Развёртывание YDB кластера с помощью Ansible

В инструкции изложен процесс развёртывания YDB кластера на группе серверов с помощью Ansible. Рекомендуемая схема разворачивания кластера YDB для начала работы состоит из 3 серверов с 3 дисками для пользовательских дисков в каждом. Для обеспечения отказоустойчивости этим серверам желательно иметь независимую инфраструктуру: располагаться в отдельных датацентрах или зонах доступностях, либо хотя бы отдельных серверных стойках.

Для более масштабных кластеров, рекомендуется использовать от 9 серверов для отказоустойчивых кластеров (mirror-3-dc) или 8 серверов для однодатацентровых кластеров (block-4-2). В обоих этих случаях серверам достаточно иметь по одному диску для пользовательских данных, но желательно также иметь отдельный небольшой диск для операционной системы. Подробнее о моделях избыточности можно узнать из статьи Топология кластера YDB. В процессе эксплуатации кластер может быть расширен без приостановки доступа пользователей к базам данных.

Примечание

Рекомендуемые требования к серверам:

16 CPU (рассчитывается исходя из утилизации 8 CPU сторадж нодой и 8 CPU динамической нодой).
16 GB RAM (рекомендуемый минимальный объем RAM).
SSD-диски для пользовательских данных, размером от 120 GB.
Доступ по SSH.
Сетевая связность машин в кластере.
OS: Ubuntu 18+, Debian 9+.
Доступ в интернет для обновления репозиториев и скачивания нужных пакетов.

Скачать репозиторий с примерами для установки YDB на кластер можно с GitHub – git clone https://github.com/ydb-platform/ydb-ansible-examples.git. Этот репозиторий содержит: шаблоны установки YDB на кластер в поддиректориях, а также скрипты для генерации TLS-сертификатов и файлы requirements для установки необходимых Python пакетов. В этой статье будет использоваться поддиректория 3-nodes-mirror-3-dc для самого простого способа развёртывания. Также можно аналогичным образом использовать директории 8-nodes-block-4-2 или 9-nodes-mirror-3-dc, если вам доступно необходимое количество подходящих серверов.

Структура репозитория

├── 3-nodes-mirror-3-dc / 9-nodes-mirror-3-dc / 8-nodes-block-4-2
│   ├── ansible.cfg #Конфигурационный файл Ansible, который содержит настройки подключения к серверам и опции структуры проекта.
│   ├── ansible_vault_password_file #Пароль для пользователя root.
│   ├── creds #Переменные окружения, задающие имя пользователя и пароль для YDB.
│   ├── files
│   │   ├── config.yaml #Конфигурационный файл YDB.
│   ├── inventory #Директория с инвентаризационными файлами.
│   │   ├── 50-inventory.yaml #Основной инвентаризационный файл.
│   │   └── 99-inventory-vault.yaml #Зашифрованный инвентаризационный файл, содержащий пароль root пользователя от YDB.
├── README.md #Описание репозитория.
├── requirements.txt #Файл со списком зависимостей для установки Python пакетов в виртуальное окружение.
├── requirements.yaml #Файл с указателем на актуальные Ansible коллекции.
├── TLS #Директория, в которой создаётся поддиректория CA с TLS сертификатами.
│   ├── ydb-ca-nodes.txt #Список FQDN серверов для генерации TLS сертификатов
│   └── ydb-ca-update.sh #Скрипт для генерации TLS сертификатов из списка ydb-ca-nodes.txt

Для работы с проектом на локальной (промежуточной или инсталляционной) машине понадобится: Python 3 версии 3.10+ и Ansible core не ниже версии 2.15.2. Ansible можно установить и запустить глобально (устанавливается в систему) или в виртуальном окружении. Если Ansible уже установлен – можно переходить к шагу «Настройка Ansible проекта», если Ansible ещё не установлен, установите его одним из предложенных способов:

Установка Ansible в систему (глобально, Ubuntu 22.04 LTS)

Установка Ansible в виртуальное окружение Python

Обновите список пакетов apt репозитория – sudo apt update.
Обновите пакеты – sudo apt-get upgrade.
Установите пакет software-properties-common для управления источниками программного обеспечения вашего дистрибутива – sudo apt install software-properties-common.
Добавьте новый PPA в apt – sudo add-apt-repository --yes --update ppa:ansible/ansible.
Установите Ansible – sudo apt-get install ansible-core (имейте ввиду, что установка просто ansible приведёт к неподходящей устаревшей версии).
Проверьте версию Ansible core – ansible --version

Обновите список пакетов apt репозитория – sudo apt-get update.
Установите пакет venv для Python3 – sudo apt-get install python3-venv
Создайте директорию, где будет создано виртуальное окружение и куда будут скачаны плейбуки. Например, mkdir venv-ansible.
Создайте виртуальное окружение – python3 -m venv venv-ansible.
Активируйте виртуальное окружение – source venv-ansible/bin/activate. В дальнейшем все действия по работе с Ansible выполняются внутри виртуального окружения. Выйти из него можно командой deactivate.
Установите Ansible рекомендуемой версии с помощью команды pip3 install -r requirements.txt, находясь в корневой директории скачанного репозитория.
Проверьте версию Ansible core – ansible --version

Перейдите в корневой каталог загруженного репозитория и выполните команду ansible-galaxy install -r requirements.yaml – она скачает коллекции Ansible ydb_platform.ydb и community.general, которые содержат роли и плагины для установки YDB.

Настройка проекта Ansible

Редактирование инвентори-файлов

Независимо от выбранной топологии кластера (3-nodes-mirror-3-dc, 9-nodes-mirror-3-dc или 8-nodes-block-4-2), основные параметры для установки и настройки YDB содержатся в инвентори-файле 50-inventory.yaml, который находится в каталоге inventory/.

В инвентори-файле 50-inventory.yaml необходимо указать текущий список FQDN серверов, на которых будет установлен YDB. По умолчанию список выглядит следующим образом:

all:
  children:
    ydb:
      static-node-1.ydb-cluster.com:
      static-node-2.ydb-cluster.com:
      static-node-3.ydb-cluster.com:

Далее необходимо внести следующие изменения в разделе vars инвентори-файла:

ansible_user – укажите пользователя, от имени которого Ansible будет подключаться через SSH.
ansible_ssh_common_args: "-o ProxyJump=<ansible_user>@<static-node-1-IP>" – опция для подключения Ansible к серверу по IP, с которого будет установлен YDB (включая сервер ProxyJump). Используется при установке YDB с локальной машины, не входящей в частную DNS-зону.
ansible_ssh_private_key_file – измените путь до приватного SSH-ключа на фактическое: "../<ssh-private-key-name>".
Выберите один из доступных вариантов развёртывания исполняемых файлов YDB:
- ydb_version: автоматически загрузить один из официальных релизов YDB по номеру версии. Например, 23.4.11.
- ydb_git_version: автоматически скомпилировать исполняемые файлы YDB из исходного кода, загруженного из официального репозитория GitHub. Значение настройки – это имя ветки, тега или коммита. Например, main.
- ydb_archive: локальный путь к архиву с дистрибутивом YDB, загруженного или подготовленного заранее.
- ydbd_binary и ydb_cli_binary: локальные пути к исполняемым файлам сервера и клиента YDB, загруженным или подготовленным заранее.

Дополнительные изменения в инвентори-файлах

При необходимости можно изменить эти настройки, но это не обязательно в простых случаях:

ydb_cores_static – количество процессорных ядер, выделенных для статических узлов.
ydb_cores_dynamic – количество процессорных ядер, выделенных для динамических узлов.
ydb_tls_dir – укажите локальный путь к папке с заранее подготовленными TLS-сертификатами. Она должна содержать файл ca.crt и подкаталоги с именами, соответствующими именам узлов, содержащие сертификаты для каждого узла. Если параметр не указан, самоподписанные TLS-сертификаты будут сгенерированы автоматически для всего кластера YDB.

ydb_brokers – укажите список FQDN брокерных узлов. Например:

ydb_brokers:
  - static-node-1.ydb-cluster.com
  - static-node-2.ydb-cluster.com
  - static-node-3.ydb-cluster.com

Значение переменной ydb_database_groups в разделе vars имеет фиксированное значение, которое привязано к типу избыточности и не зависит от размера кластера:

Для типа избыточности block-4-2 значение ydb_database_groups равно семи.
Для типа избыточности mirror-3-dc значение ydb_database_groups равно восьми.

Значения переменных system_timezone и system_ntp_servers зависят от свойств инфраструктуры, на которой развёртывается YDB кластер. По умолчанию в system_ntp_servers указан набор NTP-серверов без учёта географического расположения инфраструктуры, на которой будет развёртываться YDB кластер. Мы настоятельно рекомендуем использовать локальный NTP-сервер для on-premise инфраструктуры и следующие NTP-серверы для облачных провайдеров:

Yandex Cloud

AWS

Azure

Alibaba

system_timezone: Europe/Moscow
system_ntp_servers: [0.ru.pool.ntp.org, 1.ru.pool.ntp.org, ntp0.NL.net, ntp2.vniiftri.ru, ntp.ix.ru, ntps1-1.cs.tu-berlin.de] Подробнее о настройках NTP-серверов Yandex Cloud.

system_timezone: USA/<region_name>
system_ntp_servers: [169.254.169.123, time.aws.com] Подробнее о настройках NTP-серверов AWS.

О том, как настраивается синхронизация времени на виртуальных машинах Azure, можно прочесть в данной статье.

Специфика подключения к NTP-серверам в Alibaba описана в этой статье.

Изменения других секций конфигурационного файла 50-inventory.yaml не требуются.

Изменение пароля пользователя root

Далее можно изменить стандартный пароль root пользователя YDB, который содержится в зашифрованном инвентаризационном файле 99-inventory-vault.yaml и файле ansible_vault_password_file.txt. Для изменения пароля укажите новый пароль в файле ansible_vault_password_file.txt и продублируйте его в файле 99-inventory-vault.yaml в формате:

all:
  children:
    ydb:
      vars:
        ydb_password: <new-password>

Для шифрования 99-inventory-vault.yaml выполните команду ansible-vault encrypt inventory/99-inventory-vault.yaml.

После изменения инвентаризационных файлов можно переходить к подготовке конфигурационного файла YDB.

Подготовка конфигурационного файла YDB

Конфигурационный файл YDB содержит настройки нод YDB и располагается в поддиректории /files/config.yaml. С подробным описанием секций настройки конфигурационного файла YDB можно ознакомиться в статье Статическая конфигурация кластера.

Дефолтный конфигурационный файл YDB уже содержит почти все необходимые настройки для развёртывания кластера. Необходимо заменить стандартные FQDN хостов на актуальные FQDN в разделах hosts и blob_storage_config:

Раздел hosts:

...
hosts:
  - host: static-node-1.ydb-cluster.com #FQDN ВМ
    host_config_id: 1
    walle_location:
      body: 1
      data_center: 'zone-a'
      rack: '1'
...

Раздел blob_storage_config:

...
- fail_domains:
  - vdisk_locations:
    - node_id: static-node-1.ydb-cluster.com #FQDN ВМ
      pdisk_category: SSD
      path: /dev/disk/by-partlabel/ydb_disk_1
...

Остальные секции и настройки конфигурационного файла остаются без изменений.

Развёртывание кластера YDB

Примечание

Минимальное количество серверов в кластере YDB – восемь серверов для модели избыточности block-4-2 и девять серверов для модели избыточности mirror-3-dc.

Репозиторий содержит два готовых набора шаблонов для развёртывания кластера YDB из восьми (модель избыточности block-4-2) и девяти серверов (mirror-3-dc). Любой из предложенных вариантов может быть масштабирован на любое нужное количество серверов с учётом ряда технических требований.

Для подготовки собственного шаблона можно воспользоваться следующей инструкцией:

Создайте копию директории с готовым примером (9-nodes-mirror-3-dc или 8-nodes-block-4-2).
Укажите FQDN серверов в файле TLS/ydb-ca-nodes.txt и выполните скрипт ydb-ca-update.sh для генерации наборов TLS сертификатов.
Внесите изменения в инвентаризационные файлы шаблона в соответствии с инструкцией.
Внесите изменения в конфигурационный файл YDB в соответствии с инструкцией.
Выполните команду ansible-playbook ydb_platform.ydb.initial_setup, находясь в директории клонированного шаблона.

План выполнения сценария установки YDB

Последовательность выполнения ролей и их краткое описание:

Роль packages настраивает репозитории, управляет предпочтениями и конфигурациями APT, а также исправляет неконфигурированные пакеты и устанавливает необходимые программные пакеты в зависимости от версии дистрибутива.
Роль system устанавливает системные настройки, включая конфигурацию часов и временной зоны, синхронизацию времени через NTP с помощью systemd-timesyncd, настройку systemd-journald для управления журналами, конфигурацию загрузки модулей ядра и оптимизацию параметров ядра через sysctl, а также настройку производительности процессора с использованием cpufrequtils.
Роль ydb выполняет задачи по проверке необходимых переменных, установке базовых компонентов и зависимостей, настройке системных пользователей и групп, развертыванию и конфигурированию YDB, включая управление сертификатами TLS и обновление конфигурационных файлов.
Роль ydb-static отвечает за подготовку и запуск статических нод YDB, включая проверку необходимых переменных и секретов, форматирование и подготовку дисков, создание и запуск systemd unit для узла хранения, а также инициализацию хранилища и управление доступом к базе данных. Ознакомиться с systemd unit сторадж ноды можно по ссылке.
Роль ydb-dynamic настраивает и управляет динамическими узлами YDB, включая проверку необходимых переменных, создание конфигурационных файлов и systemd unit файлов для каждого динамического узла, запуск этих узлов, получение токена для доступа к YDB, создание базы данных в YDB. Шаблон файла systemd unit динамической ноды находится по ссылке.

Подробное пошаговое описание установки YDB

Роль packages. Задачи:

check dpkg audit – проверка состояния dpkg с помощью команды dpkg --audit и сохранение результатов команды в переменной dpkg_audit_result. Задача завершится с ошибкой, если команда dpkg_audit_result.rc вернет значение отличное от 0 или 1.
run the equivalent of "apt-get clean" as a separate step – очистка кеша apt, аналогично команде apt-get clean.
run the equivalent of "apt-get update" as a separate step – обновление кеша apt, аналогично команде apt-get update.
fix unconfigured packages – исправление неконфигурированных пакетов с помощью команды dpkg --configure --pending.
set vars_for_distribution_version variables – установка переменных для конкретной версии дистрибутива.
setup apt repositories – настройка репозиториев apt из заданного списка.
setup apt preferences – настройка предпочтений apt (содержание переменных указано в roles/packages/vars/distributions/<distributive name>/<version>/main.yaml).
setup apt configs– настройка конфигураций apt.
flush handlers – принудительный запуск всех накопленных обработчиков (хендлеров). В данном случае запускается хендлер, который обновляет кеш apt.
install packages – установка пакетов apt с учетом заданных параметров и времени валидности кеша.

Ссылки на списки пакетов, которые будут установлены для Ubuntu 22.04 или Astra Linux 1.7:

Список пакетов для Ubuntu 22.04;
Список пакетов для Astra Linux 1.7.

Роль system. Задачи:

configure clock – блок задач настройки системных часов:
- assert required variables are defined – проверка переменной system_timezone на существование. Эта проверка гарантирует, что необходимая переменная доступна для следующей задачи в блоке.
- set system timezone – установка системного часового пояса. Часовой пояс задаётся значением переменной system_timezone, а аппаратные часы (hwclock) устанавливаются на UTC. После выполнения задачи отправляется уведомление для перезапуска службы cron.
- flush handlers – принудительное выполнение накопленных обработчиков директивой meta. Будет произведен рестарт следующих процессов: timesyncd, journald, cron, cpufrequtils, и выполнена команда sysctl -p.
configure systemd-timesyncd – блок задач настройки systemd-timesyncd:
- assert required variables are defined - утверждает, что количество NTP серверов (system_ntp_servers) больше одного, если переменная system_ntp_servers определена. Если переменная system_ntp_servers не определена, выполнение блока задач configure systemd-timesyncd будет пропущено, включая проверку количества NTP серверов и настройку systemd-timesyncd.
- create conf.d directory for timesyncd - создаёт директорию /etc/systemd/timesyncd.conf.d, если переменная system_ntp_servers определена.
- configure systemd-timesyncd - создаёт конфигурационный файл /etc/systemd/timesyncd.conf.d/ydb.conf для службы systemd-timesyncd с основным и резервными NTP серверами. Задача будет выполнена, если переменная system_ntp_servers определена. После выполнения задачи отправляется уведомление для перезапуска службы timesyncd.
- flush handlers - вызываются накопленные обработчики. Выполняется обработчик restart timesyncd, который выполняет перезапуск сервиса systemd-timesyncd.service.
- start timesyncd - запуск и активация службы systemd-timesyncd.service. Далее служба будет стартовать автоматически при загрузке системы.
configure systemd-journald – блок задач по настройке сервиса systemd-journald:
- create conf.d directory for journald - создание директории /etc/systemd/journald.conf.d для хранения конфигурационных файлов systemd-journald.
- configure systemd-journald - создание конфигурационного файла в /etc/systemd/journald.conf.d/ydb.conf для systemd-journald, в котором указывается секция Journal с опцией ForwardToWall=no. Параметр ForwardToWall=no в конфигурации systemd-journald означает, что журнал сообщений (логи) системы не будет перенаправляться как сообщения "wall" всем вошедшим в систему пользователям. После выполнения задачи отправляется уведомление для перезапуска службы journald.
- flush handlers - вызывает накопленные хендлеры. Будет выполнен хендлер restart journald, который перезапустит сервис systemd-journald.
- start journald - запуск и активация службы systemd-journald.service. Далее служба будет стартовать автоматически при загрузке системы.
configure kernel – блок задач конфигурирования ядра:
- configure /etc/modules-load.d dir - создание директории /etc/modules-load.d с правами владельца и группы для пользователя root и разрешениями 0755.
- setup conntrack module - копирование строки nf_conntrack в файл /etc/modules-load.d/conntrack.conf для загрузки модуля nf_conntrack при старте системы.
- load conntrack module - загрузка модуля nf_conntrack в текущей сессии.
- setup sysctl files - применяет шаблоны для создания конфигурационных файлов в /etc/sysctl.d/ для различных системных настроек (таких, как настройки безопасности, сети и файловой системы). Список файлов включает 10-console-messages.conf, 10-link-restrictions.conf и другие. После выполнения этой задачи отправляется уведомление для применения изменений в настройках ядра.
- flush handlers - вызывает накопленные хендлеры. Будет вызван хендлер apply kernel settings, который выполнит команду sysctl -p для применения параметров ядра, указанных в файле /etc/sysctl.conf или в других файлах в каталоге /etc/sysctl.d/.
configure cpu governor – блок задач настройки режима управления частотой процессора:
- install cpufrequtils - установка пакета cpufrequtils из apt. В задаче установлены параметры проверки кеша apt и таймаут выполнения задачи в 300 секунд, чтобы ускорить выполнения задачи и избежать бесконечного цикла ожидания обновления пакетов apt.
- use performance cpu governor - создание файла /etc/default/cpufrequtils с содержимым "GOVERNOR=performance", что устанавливает режим работы CPU governor в "performance" (Отключения режима энергосбережения при простое ядер CPU). После выполнения задачи отправляется уведомление для перезапуска службы cpufrequtils.
- disable ondemand.service - отключение сервиса ondemand.service, если он присутствует в системе. Сервис останавливается, его автоматический запуск отключается, и он маскируется (предотвращается его запуск). После выполнения задачи отправляется уведомление для перезапуска cpufrequtils.
- flush handlers - вызывает накопленные хендлеры. Будет вызван хендлер restart cpufrequtils, который перезапустит сервис cpufrequtils.
- start cpufrequtils - запуск и активация службы cpufrequtils.service. Далее служба будет стартовать автоматически при загрузке системы.

Роль ydbd. Задачи:

check if required variables are defined – проверка, что переменные ydb_archive, ydb_config, ydb_tls_dir определены. Если какая-либо из них не определена, Ansible выведет соответствующее сообщение об ошибке и остановит выполнение плейбука.
set vars_for_distribution variables – установка переменных из указанного файла в переменной vars_for_distribution_file во время выполнения плейбука. Задача управляет набором переменных, зависящих от конкретного дистрибутива Linux.
ensure libaio is installed – проверка, что пакет libaio установлен.
install custom libidn from archive – установка пользовательской версии библиотеки libidn из архива.
create certs group – создание системной группы certs.
create ydb group – создание системной группы ydb.
create ydb user – создание системного пользователя ydb с домашней директорией.
install YDB server binary package from archive – установка YDB из скаченного архива.
create YDB audit directory – создание поддиректории audit в директории установки YDB.
setup certificates – блок задач по установки сертификатов безопасности:
- create YDB certs directory – создание поддиректории certs в директории установки YDB.
- copy the TLS ca.crt – копирование корневого сертификата ca.crt на сервер.
- copy the TLS node.crt – копирование TLS-сертификата node.crt из директории сгенерированных сертификатов.
- copy the TLS node.key – копирование TLS-сертификата node.key из директории сгенерированных сертификатов.
- copy the TLS web.pem – копирование TLS pem ключа web.pem из директории сгенерированных сертификатов.
copy configuration file – копирование конфигурационного файла config.yaml на сервер.
add configuration file updater script – копирование скрипта update_config_file.sh на сервер.

Роль ydbd_static. Задачи:

check if required variables are defined – проверка, что переменные ydb_cores_static, ydb_disks, ydb_domain, ydb_user определены. Если хотя бы одна из этих переменных не определена, задача завершится с ошибкой, и будет выведено соответствующее сообщение об ошибке для каждой переменной, которая не была определена.
check if required secrets are defined – проверка определения секретной переменной ydb_password. Если эта переменная не определена, задача завершится с ошибкой, и будет выведено сообщение об ошибке.
create static node configuration file – создание конфигурационного файла статической ноды путём запуска скопированного скрипта update_config_file.sh и передачи в него конфигураций ydbd-config.yaml, ydbd-config-static.yaml.
create static node systemd unit – создание файла ydbd-storage.service для статического узла на основе шаблона. После выполнения задачи отправляется уведомление для перезапуска службы systemd.
flush handlers – выполнение накопленных хендлеров. Выполняется перезапуск всех служб systemd.
format drives confirmation block – блок задач по форматированию дисков и прерывания выполнения плейбука в случае отказа пользователя от подтверждения. В терминал будет выведен запрос на подтверждение форматирования подключенного к серверу диска. Варианты ответа: yes – продолжить выполнение плейбука с форматированием диска. Любое другое значение, будет восприниматься как отказ от форматирования. По умолчанию диски форматируется автоматически без запроса разрешения у пользователя, так как переменные ydb_allow_format_drives и ydb_skip_data_loss_confirmation_prompt равны true. Если нужно запросить подтверждение от пользователя, то нужно изменить значение переменной ydb_skip_data_loss_confirmation_prompt на false в инвентаризационном файле 50-inventory.yaml.
prepare drives – задача по форматированию подключенных дисков. Вызывается плагин drive_prepare – это специально разработанный Ansible-модуль для установки YDB, который входит в состав поставки коллекции YDB и располагается в директории .../.ansible/collections/ansible_collections/ydb_platform/ydb/plugins/action/drive_prepare.py. Модуль выполнит форматирование подключенного к серверу диска, указанного в переменной ydb_disks. Форматирование будет произведено если переменная ydb_allow_format_drives имеет значение true.
start storage node – запуск процесса сторадж ноды с помощью systemd. В случае возникновения любых ошибок запуска сервиса исполнение плейбука будет прервано.
get ydb token – запрос токена YDB для выполнения команды инициализации стораджа. Токен сохраняется в переменной ydb_credentials. В задаче вызывается модуль get_token из директории .../.ansible/collections/ansible_collections/ydb_platform/ydb/plugins/modules. В случае возникновение любых ошибок на данном шаге выполнение плейбука будет прервано.
wait for ydb discovery to start working locally – вызывается модуль wait_discovery, который выполняет запрос ListEndpoints к YDB для проверки работоспособности базовых подсистем кластера. Если подсистемы работают исправно – можно выполнять команды инициализации стороджа и создания базы данных.
init YDB storage if not initialized – инициализация хранилища в случае если оно еще не создано. В задаче вызывается плагин init_storage, который выполняет команду инициализации хранилища с помощью grpcs-запроса к статической ноде на порт 2135. Результат выполнения команды сохраняется в переменной init_storage.
wait for ydb healthcheck switch to "GOOD" status – ожидание получения статуса GOOD от системы проверки состояния YDB. В задаче вызывается плагин wait_healthcheck, который выполняет команду проверке состояния YDB.
set cluster root password – установка пароля для root пользователя YDB. В задаче выполняется плагин set_user_password, который выполняет grpcs запрос к YDB и устанавливает заранее заданный пароль для root пользователя YDB. Пароль задаётся переменной ydb_password в инвентаризационном файле /examples/9-nodes-mirror-3-dc/inventory/99-inventory-vault.yaml в зашифрованном виде.

Роль ydbd_dynamic. Задачи:

check if required variables are defined – проверка наличия установленных переменных (ydb_domain,ydb_pool_kind, ydb_cores_dynamic, ydb_brokers, ydb_dbname, ydb_dynnodes) и вывод ошибки в случае отсутствия любой из переменных.
create dynamic node configuration file – создание конфигурационного файла для динамических нод.
create dynamic node systemd unit – создание сервиса для systemd динамических нод. После выполнения задачи отправляется уведомление для перезапуска службы systemd.
flush handlers – выполнение накопившихся хендлеров. Будет выполнен рестарт systemd.
start dynamic nodes – запуск процесса динамических нод с помощью systemd.
get ydb token – получение токена для создания базы данных.
create YDB database – создание базы данных. В задаче выполняется плагин create_database, который выполняет запрос создания БД к YDB.
wait for ydb discovery to start working locally – повторно вызывается модуль wait_discovery для проверки работоспособности базовых подсистем кластера.

Подключение к кластеру

После развёртывания кластера YDB, каждый сервер по умолчанию будет принимать соединения на следующих портах:

Порты статического узла

На каждом сервере кластера запускается по одному статическому узлу. В systemd он называетсяydbd-storage. Статический узел принимает входящие соединения на следующих портах:

Порт	Описание
2135	Порт для основного API YDB, основанного на защищённом gRPC соединении поверх TLS.
19001	Порт для интерконнекта акторной системы YDB.
8765	HTTPS-порт для встроенного интерфейса, отображения метрик и других вспомогательных команд.
5432	Порт для режима совместимости с PostgreSQL.

Порты динамических узлов

По умолчанию при развёртывании кластера через Ansible на каждом сервере запускается по два динамических узла. В systemd они называются ydbd-database-a и ydbd-database-b. Они принимают входящие соединения на следующих портах:

Название динамического узла	Порт	Описание
`ydbd-database-a`	2136	Порты для основного API YDB, основанного на защищённом gRPC соединении поверх TLS.
`ydbd-database-b`	2137
`ydbd-database-a`	19002	Порты для интерконнекта акторной системы YDB.
`ydbd-database-b`	19003	Порты для интерконнекта акторной системы YDB.
`ydbd-database-a`	8766	HTTPS-порты для встроенного интерфейса, отображения метрик и других вспомогательных команд.
`ydbd-database-b`	8767

В результате выполнения плейбука будет создан кластер YDB, на котором развёрнута база данных под названием database, а также пользователь с именем root и максимальными правами доступа. Работать с кластером можно с помощью YDB CLI, посылая API-вызовы на порт 2135, через Embedded UI, который работает на порту 8765, а также в режиме PostgreSQL-совместимости через порт 5432. Также для подключения к Embedded UI можно настроить SSH-туннелирование. Для этого на локальной машине выполните команду ssh -L 8765:localhost:8765 -i <ssh private key> <user>@<first ydb static node ip>. После успешного установления соединения можно перейти по URL localhost:8765:

ydb-web-ui

Мониторинг состояния кластера

После успешного создания кластера YDB проверить его состояние можно с помощью Embedded UI – http://localhost:8765/monitoring/cluster/tenants:

ydb-cluster-check

В разделе отражены следующие параметры кластера YDB, которые показывают состояние кластера:

Tablets – список запущенных таблеток. Все индикаторы состояния таблеток должны быть зелёного цвета.
Nodes – количество и состояние запущенных статических и динамических нод в кластере. Индикатор состояния нод должен быть зелёным, а пропорция созданных и запущенных нод должна быть равной. Например, 27/27 для кластера из девяти нод.
Индикаторы показателей Load (количество используемой RAM) и Storage (количество используемого дискового пространства) должны быть зелёными.

Проверить состояние сторадж группы можно в разделе storage – http://localhost:8765/monitoring/cluster/storage:

ydb-storage-gr-check

Индикаторы VDisks должны быть зелёными, а статус state (находится в всплывающей подсказке при наведении на индикатор VDisk) должен быть Ok. Подробнее о показателях состояния кластера и мониторинге можно прочитать в статье YDB Monitoring.

Тестирование кластера

Протестировать кластер можно с помощью встроенных в YDB CLI нагрузочных тестов. Для этого скачайте на машину, на которой установлен Ansible, YDB CLI версии 2.5.0. Например, с помощью wget: wget https://storage.yandexcloud.net/yandexcloud-ydb/release/2.5.0/linux/amd64/ydb.

Сделайте скачанный бинарный файл исполняемым – chmod +x ydb и создайте профиль подключения к YDB:

./ydb \
  config profile create <profile name> \
  -d /Root/database \
  -e grpcs://<FQDN node>:2135 \
  --ca-file <path to generated certs>/CA/certs/ca.crt \
  --user root \
  --password-file <path to vault password file>/ansible_vault_password_file

Параметры команды и их значения:

config profile create – команда создания профиля подключения. Задаётся имя профиля. Более детальную информацию о том, как создавать и изменять профили, можно найти в статье Создание и изменение профиля.
-e – эндпоинт (endpoint), строка в формате protocol://host:port. Можно указать FQDN любой ноды кластера и не указывать порт. По умолчанию будет использован 2135 порт.
--ca-file – путь к корневому сертификату для подключения к базе по grpcs. Сертификат создаётся скриптом ydb-ca-update.sh в директории TLS и располагается по пути TLS/CA/certs/ относительно корня репозитория ydb-ansible-examples.
--user – пользователь для подключения к БД. По умолчанию при выполнении плейбука ydb_platform.ydb.initial_setup создаётся пользователь root.
--password-file – путь к файлу с паролем. В каждой папке с шаблоном развёртывания YDB кластера находится файл ansible_vault_password_file, который содержит пароль пользователя root.

Проверить, создался ли профиль, можно командой ./ydb config profile list – будет выведен список профилей. После создания профиля его нужно активировать командой ./ydb config profile activate <profile name>. Проверить, что профиль был активирован, можно повторным выполнением команды ./ydb config profile list – активный профиль будет иметь отметку (active).

Теперь можно выполнить YQL запрос ./ydb yql -s 'select 1;', который вернёт в терминал результат выполнения команды select 1 в табличной форме. После проверки соединения можно создать тестовую таблицу командой:
./ydb workload kv init --init-upserts 1000 --cols 4. Будет создана тестовая таблица kv_test, состоящая из 4 столбцов и 1000 строк. Проверить, что таблица kv_test создалась и заполнилась тестовыми данными, можно командой ./ydb yql -s 'select * from kv_test limit 10;'.

В терминал будет выведена таблица из 10 строк. Теперь можно выполнять тестирование производительности кластера. В статье Key-Value нагрузка описаны 5 видов нагрузок (upsert, insert, select, read-rows, mixed) и параметры их выполнения. Пример выполнения тестовой нагрузки upsert с параметром вывода времени выполнения запроса --print-timestamp и стандартными параметрами исполнения: ./ydb workload kv run upsert --print-timestamp.

В терминал будет выведен отчёт следующего вида:

Window Txs/Sec Retries Errors  p50(ms) p95(ms) p99(ms) pMax(ms)        Timestamp
1          727 0       0       11      27      71      116     2024-02-14T12:56:39Z
2          882 0       0       10      21      29      38      2024-02-14T12:56:40Z
3          848 0       0       10      22      30      105     2024-02-14T12:56:41Z
...

После завершения тестов удалить таблицу kv_test можно командой: ./ydb workload kv clean. Подробнее об опциях создания тестовой таблицы и тестах можно прочесть в статье Key-Value нагрузка.