Первоначальное развёртывание YDB EM

В этом руководстве описан процесс первоначального развёртывания YDB Enterprise Manager (далее — YDB EM) с помощью Ansible. По завершении вы получите работающий экземпляр YDB EM, подключённый к существующему кластеру YDB.

Перед началом работы

Требования

Для развёртывания YDB EM необходимо:

1. Работающий кластер YDB. YDB EM подключается к существующему кластеру для управления его ресурсами; без кластера работа EM невозможна. В этом кластере будет автоматически создана служебная база данных для хранения метаинформации YDB EM. Подробнее о развёртывании кластера — в разделе Способы развёртывания YDB.

2. Параметры подключения к базе данных YDB, которая будет использоваться для хранения метаданных YDB EM:

   • Эндпоинт (например, grpcs://ydb-node01.ru-central1.internal:2135).
   • Имя пользователя и пароль для получения токена авторизации. Пользователь должен обладать правами на модификацию схемы, запись и чтение данных. Если кластер YDB настроен на аутентификацию через LDAP, используйте учётную запись из соответствующего каталога.

3. Хост для компонентов Gateway и Control Plane — один сервер (физический или виртуальный), на который будут установлены серверные компоненты YDB EM. Это может быть любой из хостов кластера YDB или отдельная машина.

4. Ansible на управляющей машине (с которой выполняется установка). Рекомендуется ansible-core 2.14–2.18, подробнее см. Развёртывание YDB кластера с помощью Ansible.

5. SSH-доступ с управляющей машины ко всем серверам, на которые будут установлены компоненты YDB EM (хост Gateway/CP и хосты кластера для агентов).

Сетевые требования

Сетевая конфигурация должна разрешать TCP-соединения по следующим портам (значения по умолчанию):

Загрузка пакета

Скачайте пакет YDB EM на управляющую машину (с которой будет выполняться установка через Ansible). Актуальный номер версии и ссылку на архив уточняйте в информации о последнем релизе:

Распакуйте скачанный архив в рабочую директорию (замените <VERSION> на актуальную версию):

tar -xf ydb-em-<VERSION>-stable-linux-amd64.tar.xz

Содержимое пакета:

Установка Ansible-коллекций

Установите Ansible-коллекцию для YDB, если она ещё не установлена:

ansible-galaxy collection install collections/ydb_platform-ydb-*.tar.gz

Установите Ansible-коллекцию для YDB EM:

ansible-galaxy collection install collections/ydb_platform-ydb_em-*.tar.gz

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

Распаковка шаблонов конфигурации

Пакет YDB EM содержит готовые шаблоны конфигурации Ansible — файлы инвентаря, плейбуки и директории для размещения бинарных файлов и сертификатов. Распакуйте этот архив:

tar -xf examples.tar.gz

В результате появится директория examples/, которая будет использоваться как рабочая директория для установки.

Размещение файлов

1. Скопируйте бинарные файлы из директории bin/ пакета в директорию examples/files/:

   cp bin/ydb-em-gateway bin/ydb-em-cp bin/ydb-em-agent examples/files/
   

2. Разместите TLS-сертификаты в директории examples/files/certs/. Используйте те же сертификаты, что и для узлов кластера YDB (сертификат CA, сертификаты и ключи узлов):

   cp /path/to/your/certs/* examples/files/certs/
   

Настройка инвентаря Ansible

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

• examples/inventory/50-inventory.yaml — общие параметры: SSH-подключение, подключение к YDB, настройки Control Plane.
• examples/inventory/90-inventory.yaml — описание серверов (какие хосты используются для каких компонентов).
• examples/inventory/99-inventory-vault.yaml — конфиденциальные данные (пароли).

Настройка списка хостов

Откройте файл examples/inventory/90-inventory.yaml и настройте две группы хостов.

Группа ydb_em — хосты для серверных компонентов YDB EM (Gateway и Control Plane). Достаточно одного хоста — это может быть любой из хостов кластера YDB или отдельный сервер:

ydb_em:
  hosts:
    ydb-node01.ru-central1.internal:

Группа ydbd_dynamic — хосты кластера YDB, на которые будет установлен Agent. Agent нужен на каждом хосте, где работают динамические узлы YDB, — именно через агентов YDB EM управляет процессами узлов. Как правило, сюда включаются все хосты кластера:

ydb:
  children:
    ydbd_dynamic:
      hosts:
        ydb-node01.ru-central1.internal:
            ydb_em_agent_cpu: 4
            ydb_em_agent_memory: 8
            location: db-dc-1
        ydb-node02.ru-central1.internal:
            ydb_em_agent_cpu: 4
            ydb_em_agent_memory: 16
            location: db-dc-2
        ydb-node03.ru-central1.internal:
            location: db-dc-3
    ydb_em:
      hosts:
        ydb-node01.ru-central1.internal:

Для каждого хоста в группе ydbd_dynamic можно указать дополнительные параметры. Если параметры не указаны, будут использованы значения по умолчанию. Уточнить настройки ресурсов можно позже через веб-интерфейс YDB EM.

Настройка SSH-подключения

В файле examples/inventory/50-inventory.yaml проверьте параметры SSH-подключения с управляющей машины к целевым серверам:

# Удалённый пользователь с правами sudo
ansible_user: ansible

# Настройки для подключения через Bastion/Jump host (JUMP_IP)
# ansible_ssh_common_args: "-o ProxyJump=ansible@{{ lookup('env','JUMP_IP') }} -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no"

# Общие настройки SSH
ansible_ssh_common_args: "-o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no"

# Приватный ключ для подключения
ansible_ssh_private_key_file: "~/.ssh/id_ed25519"

ansible_ssh_common_args: "-o StrictHostKeyChecking=yes"

Настройка подключения к базе данных YDB

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

# Эндпоинт подключения к YDB
ydb_em_db_connection_endpoint: "grpcs://ydb-node01.ru-central1.internal:2135"
# Корневой домен
ydb_em_db_connection_db_root: "/Root"
# Имя базы данных
ydb_em_db_connection_db: "db"
# Пользователь YDB
ydb_user: root

Пароль пользователя YDB задаётся в файле examples/inventory/99-inventory-vault.yaml:

all:
  children:
    ydb:
      vars:
        ydb_password: <пароль>

ansible-vault encrypt examples/inventory/99-inventory-vault.yaml

Настройка подключения к Control Plane

В файле examples/inventory/50-inventory.yaml укажите эндпоинт подключения к YDB EM Control Plane:

# Эндпоинт должен указывать на хост из группы ydb_em
ydb_em_cp_connection_endpoint: "grpcs://ydb-node01.ru-central1.internal:8787"

Этот параметр используется в конфигурации Gateway и Agent для подключения к Control Plane.

Запуск установки

После завершения настройки конфигурации перейдите в директорию examples и выполните установку одним из способов:

Автоматическая установка

Запустите скрипт автоматической установки:

cd examples
./install.sh

Скрипт автоматически выполнит все необходимые шаги по развёртыванию компонентов YDB EM.

Ручной запуск Ansible

Также можно выполнить установку вручную, запустив плейбук Ansible:

ansible-playbook ydb_platform.ydb_em.initial_setup

ansible-playbook ydb_platform.ydb_em.initial_setup --ask-vault-pass

Проверка установки

После успешного завершения установки откройте веб-интерфейс YDB EM в браузере:

https://<FQDN хоста из группы ydb_em>:8789/ui/clusters

Например:

https://ydb-node01.ru-central1.internal:8789/ui/clusters

В веб-интерфейсе должна отобразиться страница со списком кластеров YDB.

Устранение неполадок

Не удаётся подключиться к веб-интерфейсу

1. Убедитесь, что порт 8789 доступен с вашей машины:

   curl -k https://<FQDN>:8789/ui/clusters
   

2. Проверьте статус сервиса YDB EM Gateway на целевом хосте:

   sudo systemctl status ydb-em-gateway
   

3. Проверьте логи сервиса:

   sudo journalctl -u ydb-em-gateway -n 100
   

Агент не подключается к Control Plane

1. Убедитесь, что порт 8787 доступен между узлами кластера и хостом Control Plane.

2. Проверьте статус сервиса YDB EM Agent на узле:

   sudo systemctl status ydb-em-agent
   

3. Проверьте корректность TLS-сертификатов и эндпоинта Control Plane в конфигурации агента.

Ошибки подключения к базе данных YDB

1. Убедитесь, что эндпоинт, имя базы данных, пользователь и пароль указаны корректно.

2. Проверьте сетевую доступность порта 2135 на узле YDB с хоста YDB EM.

3. Проверьте логи YDB EM Control Plane:

   sudo journalctl -u ydb-em-cp -n 100