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

В этом руководстве описывается процесс развёртывания YDB кластера на группе серверов с помощью Ansible. Это рекомендуемый подход для сред с физическими серверами или виртуальными машинами.

Предварительные требования

Настройка серверов

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

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

Если вы планируете использовать виртуальные машины у публичного облачного провайдера, рекомендуется следовать Развёртывание инфраструктуры для кластера YDB с помощью Terraform.

Настройка программного обеспечения

Для работы с проектом на локальной (промежуточной или установочной) машине потребуется:

• Python 3 версии 3.10+
• Ansible core версии 2.15.2 или выше
• Рабочая директория на сервере с SSH-доступом ко всем серверам кластера

Если Ansible уже установлен, можно перейти к разделу «Настройка проекта Ansible». Если Ansible ещё не установлен, установите его одним из следующих способов:

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

Установка YDB Ansible плейбуков

$ cat <<EOF > requirements.yaml
roles: []
collections:
  - name: git+https://github.com/ydb-platform/ydb-ansible
    type: git
    version: main
EOF
$ ansible-galaxy install -r requirements.yaml

$ ansible-galaxy collection install git+https://github.com/ydb-platform/ydb-ansible.git

Настройка Ansible

Создайте ansible.cfg с конфигурацией Ansible, подходящей для вашего окружения. Подробности см. в справочнике по конфигурации Ansible. Дальнейшее руководство предполагает, что поддиректория ./inventory рабочей директории настроена для использования файлов инвентаризации.

[defaults]
conditional_bare_variables = False
force_handlers = True
gathering = explicit
interpreter_python = /usr/bin/python3
inventory = ./inventory
pipelining = True
private_role_vars = True
timeout = 5
vault_password_file = ./ansible_vault_password_file
verbosity = 1
log_path = ./ydb.log

[ssh_connection]
retries = 5
timeout = 60

Создание основного файла инвентаризации

Создайте файл inventory/50-inventory.yaml, используя один из шаблонов ниже в зависимости от выбранной топологии YDB кластера:

all:
  children:
    ydb:
      # Серверы
      hosts:
        static-node-1.ydb-cluster.com:
          location:
            data_center: 'zone-a'
        static-node-2.ydb-cluster.com:
          location:
            data_center: 'zone-b'
        static-node-3.ydb-cluster.com:
          location:
            data_center: 'zone-c'
      vars:
        # Ansible
        ansible_user: ubuntu
        ansible_ssh_private_key_file: "~/ydb"

        # Система
        system_timezone: UTC
        system_ntp_servers: pool.ntp.org

        # Узлы
        ydb_version: "25.1.1"
        ydb_storage_node_cores: 8
        ydb_database_node_cores: 8

        # Хранилище
        ydb_database_storage_groups: 8
        ydb_disks:
          - name: /dev/vdb
            label: ydb_disk_1
          - name: /dev/vdc
            label: ydb_disk_2
          - name: /dev/vdd
            label: ydb_disk_3
        ydb_allow_format_drives: true # замените на false после первоначальной настройки

        # База данных
        ydb_user: root
        ydb_domain: Root
        ydb_database_name: database
        ydb_config:
          erasure: mirror-3-dc
          fail_domain_type: disk
          default_disk_type: SSD
          security_config:
            enforce_user_token_requirement: true

all:
  children:
    ydb:
      # Серверы
      hosts:
        static-node-1.ydb-cluster.com:
          location:
            data_center: 'zone-a'
            rack: 'rack-1'
        static-node-2.ydb-cluster.com:
          location:
            data_center: 'zone-a'
            rack: 'rack-2'
        static-node-3.ydb-cluster.com:
          location:
            data_center: 'zone-a'
            rack: 'rack-3'
        static-node-4.ydb-cluster.com:
          location:
            data_center: 'zone-b'
            rack: 'rack-4'
        static-node-5.ydb-cluster.com:
          location:
            data_center: 'zone-b'
            rack: 'rack-5'
        static-node-6.ydb-cluster.com:
          location:
            data_center: 'zone-b'
            rack: 'rack-6'
        static-node-7.ydb-cluster.com:
          location:
            data_center: 'zone-c'
            rack: 'rack-7'
        static-node-8.ydb-cluster.com:
          location:
            data_center: 'zone-c'
            rack: 'rack-8'
        static-node-9.ydb-cluster.com:
          location:
            data_center: 'zone-c'
            rack: 'rack-9'
      vars:
        # Ansible
        ansible_user: ubuntu
        ansible_ssh_private_key_file: "~/ydb"

        # Система
        system_timezone: UTC
        system_ntp_servers: pool.ntp.org

        # Узлы
        ydb_version: "25.1.1"
        ydb_storage_node_cores: 8
        ydb_database_node_cores: 8

        # Хранилище
        ydb_database_storage_groups: 8
        ydb_disks:
          - name: /dev/vdb
            label: ydb_disk_1
        ydb_allow_format_drives: true # замените на false после первоначальной настройки

        # База данных
        ydb_user: root
        ydb_domain: Root
        ydb_database_name: database
        ydb_config:
          erasure: mirror-3-dc
          default_disk_type: SSD
          security_config:
            enforce_user_token_requirement: true

all:
  children:
    ydb:
      # Серверы
      hosts:
        static-node-1.ydb-cluster.com:
          location:
            rack: 'rack-1'
        static-node-2.ydb-cluster.com:
          location:
            rack: 'rack-2'
        static-node-3.ydb-cluster.com:
          location:
            rack: 'rack-3'
        static-node-4.ydb-cluster.com:
          location:
            rack: 'rack-4'
        static-node-5.ydb-cluster.com:
          location:
            rack: 'rack-5'
        static-node-6.ydb-cluster.com:
          location:
            rack: 'rack-6'
        static-node-7.ydb-cluster.com:
          location:
            rack: 'rack-7'
        static-node-8.ydb-cluster.com:
          location:
            rack: 'rack-8'
      vars:
        # Ansible
        ansible_user: ubuntu
        ansible_ssh_private_key_file: "~/ydb"

        # Система
        system_timezone: UTC
        system_ntp_servers: pool.ntp.org

        # Узлы
        ydb_version: "25.1.1"
        ydb_storage_node_cores: 8
        ydb_database_node_cores: 8

        # Хранилище
        ydb_database_storage_groups: 8
        ydb_disks:
          - name: /dev/vdb
            label: ydb_disk_1
        ydb_allow_format_drives: true # замените на false после первоначальной настройки

        # База данных
        ydb_user: root
        ydb_domain: Root
        ydb_database_name: database
        ydb_config:
          erasure: block-4-2
          default_disk_type: SSD
          security_config:
            enforce_user_token_requirement: true

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

1. Имена серверов. Замените static-node-*.ydb-cluster.com в all.children.ydb.hosts на реальные FQDN.
2. Расположение серверов. Имена в data_center и rack в all.children.ydb.hosts.location произвольные, но они должны совпадать между серверами, только если они действительно находятся в одном датацентре (или зоне доступности) и стойке соответственно.
3. Пути к блочным устройствам в файловой системе в all.children.ydb.vars.ydb_disks. Шаблон предполагает, что /dev/vda предназначен для операционной системы, а следующие диски, такие как /dev/vdb, — для слоя хранения YDB. Метки дисков создаются плейбуками автоматически, и их имена могут быть произвольными.
4. Настройки, связанные с Ansible с префиксом all.children.ydb.ansible_, такие как имя пользователя и приватный ключ для использования с ssh. Добавьте дополнительные по мере необходимости, например ansible_ssh_common_args.

Рекомендуемые настройки для адаптации:

• ydb_domain. Это будет первый компонент пути для всех объектов схемы в кластере. Например, вы можете поместить туда название своей компании, регион кластера и т.д.
• ydb_database_name. Это будет второй компонент пути для всех объектов схемы в базе данных. Например, вы можете поместить туда название сценария использования или проекта.
• default_disk_type. Если вы используете диски NVMe или вращающиеся HDD, измените эту настройку на NVME или ROT соответственно.
• ydb_config:
  • Любые настройки YDB можно изменить через это поле, подробнее см. Параметры конфигурации кластера.
  • Плейбуки YDB автоматически устанавливают некоторые настройки YDB на основе инвентаря Ansible (например, hosts или настройки, связанные с TLS), если вы настроите их явно в ydb_config, это будет иметь приоритет.
  • Если вы предпочитаете хранить специфичные для YDB настройки отдельно от инвентаря Ansible, замените всю эту настройку строкой, содержащей путь к файлу с отдельным файлом конфигурации YDB в формате YAML.
• ydb_storage_node_cores и ydb_database_node_cores. Если ваш сервер имеет более 16 ядер CPU, увеличьте эти значения так, чтобы их сумма равнялась фактически доступному количеству ядер. Если у вас более 64 ядер на сервер, рассмотрите возможность запуска нескольких узлов базы данных на сервер, используя ydb_database_nodes_per_server. Стремитесь к $ydb\_storage\_node\_cores + ydb\_database\_nodes\_per\_server \times ydb\_database\_node\_cores = available\_cores$.

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

Далее вы можете установить пароль для начального пользователя, указанного в настройке ydb_user (по умолчанию root). Этот пользователь изначально будет иметь полные права доступа в кластере, но при необходимости это можно изменить позже. Создайте inventory/99-inventory-vault.yaml со следующим содержимым (замените <password> на фактический пароль):

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

Зашифруйте этот файл с помощью команды ansible-vault encrypt inventory/99-inventory-vault.yaml. Это потребует либо вручную ввести пароль шифрования (который может отличаться), либо настроить параметр Ansible vault_password_file. Подробнее о том, как это работает, см. в документации Ansible Vault.

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

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

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

ansible-playbook ydb_platform.ydb.initial_setup

Вскоре после начала вас попросят подтвердить полную очистку настроенных дисков. Затем завершение развёртывания может занять десятки минут в зависимости от окружения и настроек. Этот плейбук выполняет примерно те же шаги, что описаны в инструкциях для ручного развёртывания кластера YDB.

Проверка состояния кластера

На последнем этапе плейбук выполнит несколько тестовых запросов, используя настоящие временные таблицы, чтобы перепроверить, что всё действительно работает штатно. При успехе вы увидите статус ok, failed=0 для каждого сервера и результаты этих тестовых запросов (3 и 6), если вывод плейбука установлен достаточно подробным.

...

TASK [ydb_platform.ydb.ydbd_dynamic : run test queries] *******************************************************************************************************************************************************
ok: [static-node-1.ydb-cluster.com] => (item={'instance': 'a'}) => {"ansible_loop_var": "item", "changed": false, "item": {"instance": "a"}, "msg": "all test queries were successful, details: {\"count\":3,\"sum\":6}\n"}
ok: [static-node-1.ydb-cluster.com] => (item={'instance': 'b'}) => {"ansible_loop_var": "item", "changed": false, "item": {"instance": "b"}, "msg": "all test queries were successful, details: {\"count\":3,\"sum\":6}\n"}
ok: [static-node-2.ydb-cluster.com] => (item={'instance': 'a'}) => {"ansible_loop_var": "item", "changed": false, "item": {"instance": "a"}, "msg": "all test queries were successful, details: {\"count\":3,\"sum\":6}\n"}
ok: [static-node-2.ydb-cluster.com] => (item={'instance': 'b'}) => {"ansible_loop_var": "item", "changed": false, "item": {"instance": "b"}, "msg": "all test queries were successful, details: {\"count\":3,\"sum\":6}\n"}
ok: [static-node-3.ydb-cluster.com] => (item={'instance': 'a'}) => {"ansible_loop_var": "item", "changed": false, "item": {"instance": "a"}, "msg": "all test queries were successful, details: {\"count\":3,\"sum\":6}\n"}
ok: [static-node-3.ydb-cluster.com] => (item={'instance': 'b'}) => {"ansible_loop_var": "item", "changed": false, "item": {"instance": "b"}, "msg": "all test queries were successful, details: {\"count\":3,\"sum\":6}\n"}
PLAY RECAP ****************************************************************************************************************************************************************************************************
static-node-1.ydb-cluster.com : ok=167  changed=80   unreachable=0    failed=0    skipped=167  rescued=0    ignored=0
static-node-2.ydb-cluster.com : ok=136  changed=69   unreachable=0    failed=0    skipped=113  rescued=0    ignored=0
static-node-3.ydb-cluster.com : ok=136  changed=69   unreachable=0    failed=0    skipped=113  rescued=0    ignored=0

В результате выполнения плейбука ydb_platform.ydb.initial_setup будет создан кластер YDB. Он будет содержать домен с именем из настройки ydb_domain (по умолчанию Root), базу данных с именем из настройки ydb_database_name (по умолчанию database) и начального пользователя с именем из настройки ydb_user (по умолчанию root).

Дополнительные шаги

Самый простой способ исследовать только что развёрнутый кластер — использовать Embedded UI, работающий на порту 8765 каждого сервера. В вероятном случае, когда у вас нет прямого доступа к этому порту из браузера, вы можете настроить SSH-туннелирование. Для этого выполните команду ssh -L 8765:localhost:8765 -i <private-key> <user>@<any-ydb-server-hostname> на локальной машине (при необходимости добавьте дополнительные опции). После успешного установления соединения вы можете перейти по URL localhost:8765 через браузер. Браузер может попросить принять исключение безопасности. Пример того, как это может выглядеть:

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

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

• Tablets — список запущенных таблеток. Все индикаторы состояния таблеток должны быть зелёными.
• Nodes — количество и состояние узлов хранения и узлов базы данных, запущенных в кластере. Индикатор состояния узлов должен быть зелёным, а количество созданных и запущенных узлов должно быть равным. Например, 18/18 для кластера из девяти узлов с одним узлом базы данных на сервер.

Индикаторы Load (количество используемой RAM) и Storage (количество используемого дискового пространства) также должны быть зелёными.

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

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

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

Протестировать кластер можно с помощью встроенных нагрузочных тестов в YDB CLI. Для этого установите YDB CLI и создайте профиль с параметрами подключения, заменив заполнители:

ydb \
  config profile create <profile-name> \
  -d /<ydb-domain>/<ydb-database> \
  -e grpcs://<any-ydb-cluster-hostname>:2135 \
  --ca-file $(pwd)/files/TLS/certs/ca.crt \
  --user root \
  --password-file <path-to-a-file-with-password>

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

• config profile create — эта команда используется для создания профиля подключения. Вы указываете имя профиля. Более подробную информацию о том, как создавать и изменять профили, можно найти в статье Создание и изменение профиля.
• -e — конечная точка, строка в формате protocol://host:port. Вы можете указать FQDN любого узла кластера и опустить порт. По умолчанию используется порт 2135.
• --ca-file — путь к корневому сертификату для подключений к базе данных по grpcs.
• --user — пользователь для подключения к базе данных.
• --password-file — путь к файлу с паролем. Опустите это, чтобы ввести пароль вручную.

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

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

В терминал будет выведена таблица из 10 строк. Теперь можно выполнять тестирование производительности кластера. В статье Key-Value нагрузка описаны несколько типов рабочих нагрузок (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
4          901 0       0       9       20      27      42      2024-02-14T12:56:42Z
5          879 0       0       10      22      31      59      2024-02-14T12:56:43Z
...

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

См. также

• Дополнительные примеры конфигурации Ansible
• Перезапуск кластеров YDB, развёрнутых с помощью Ansible
• Обновление конфигурации кластеров YDB, развёрнутых с Ansible
• Обновление версии YDB на кластерах, развёрнутых с помощью Ansible