Развёртывание 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 и до 2.18
• Рабочая директория на сервере с 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: latest
EOF
$ ansible-galaxy install -r requirements.yaml

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

Создание директорий для работы

mkdir deployment
cd deployment
mkdir inventory
mkdir files

Создание конфигурационного файла 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
verbosity = 1
log_path = ./ydb.log
vault_password_file = ./ansible_vault_password_file

[ssh_connection]
retries = 5
timeout = 60
ssh_args = -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -o ControlMaster=auto -o ControlPersist=60s -o ControlPath=/tmp/ssh-%h-%p-%r -o ServerAliveCountMax=3 -o ServerAliveInterval=10

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

Создайте файл inventory/50-inventory.yaml со следующим содержимым:

  all:
  children:
    ydb:
    #Серверы
      hosts:
        static-node-1.ydb-cluster.com:
        static-node-2.ydb-cluster.com:
        static-node-3.ydb-cluster.com:

      vars:
        # Ansible
        ansible_user: имя_пользователя
        ansible_ssh_private_key_file: "/путь/к/вашему/id_rsa"

        # Система
        system_timezone: UTC
        system_ntp_servers: [time.cloudflare.com, time.google.com, ntp.ripe.net, pool.ntp.org]
        
        # Узлы
        ydb_config: "{{ ansible_config_file | dirname }}/files/config.yaml"
        ydb_version: "25.1.4.7"

        # Хранилище
        ydb_cores_static: 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
        ydb_skip_data_loss_confirmation_prompt: false
        ydb_enforce_user_token_requirement: true
        ydb_request_client_certificate: true
        ydb_pool_kind: ssd
        ydb_database_groups: 8
        ydb_cores_dynamic: 8
        ydb_dynnodes:
          - { instance: 'a', offset: 0 }
          - { instance: 'b', offset: 1 }
        ydb_brokers:
          - static-node-1.ydb-cluster.com
          - static-node-2.ydb-cluster.com
          - static-node-3.ydb-cluster.com
        
        # База данных
        ydb_user: root
        ydb_domain: Root
        ydb_dbname: database

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

1. Имена серверов. Замените static-node-*.ydb-cluster.com в all.children.ydb.hosts и all.children.vars.ydb_brokers на реальные FQDN.
2. Настройка SSH доступа. Укажите пользователя ansible_user и путь к приватному ключу ansible_ssh_private_key_file, которые Ansible будет использовать для подключения к вашим серверам.
3. Пути к блочным устройствам в файловой системе. В секции all.children.ydb.vars.ydb_disks шаблон предполагает, что /dev/vda предназначен для операционной системы, а следующие диски, такие как /dev/vdb, — для слоя хранения YDB. Метки дисков создаются плейбуками автоматически, и их имена могут быть произвольными.
4. Версия системы. В параметре ydb_version укажите номер версии YDB, которую нужно установить. Список доступных версий вы найдёте на странице загрузок.

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

• ydb_domain. Это будет первый компонент пути для всех объектов схемы в кластере. Например, вы можете поместить туда название своей компании, регион кластера и т.д.
• ydb_database_name. Это будет второй компонент пути для всех объектов схемы в базе данных. Например, вы можете поместить туда название сценария использования или проекта.

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

Создайте файл ansible_vault_password_file с содержимым:

password

Этот файл содержит пароль, который Ansible будет использовать для автоматического шифрования и расшифровки конфиденциальных данных, например, файлов с паролями пользователей. Благодаря этому пароли не хранятся в открытом виде в репозитории. Подробнее о работе механизма Ansible Vault можно прочитать в официальной документации.

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

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

Зашифруйте этот файл с помощью команды ansible-vault encrypt inventory/99-inventory-vault.yaml.

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

Создайте файл files/config.yaml со следующим содержимым:

  storage_config_generation: 0
  static_erasure: mirror-3-dc
  host_configs:
  - drive:
    - path: /dev/disk/by-partlabel/ydb_disk_1
      type: SSD
    - path: /dev/disk/by-partlabel/ydb_disk_2
      type: SSD
    - path: /dev/disk/by-partlabel/ydb_disk_3
      type: SSD
    host_config_id: 1
  hosts:
  - host: static-node-1.ydb-cluster.com
    host_config_id: 1
    walle_location:
      body: 1
      data_center: 'zone-a'
      rack: '1'
  - host: static-node-2.ydb-cluster.com
    host_config_id: 1
    walle_location:
      body: 2
      data_center: 'zone-b'
      rack: '2'
  - host: static-node-3.ydb-cluster.com
    host_config_id: 1
    walle_location:
      body: 3
      data_center: 'zone-d'
      rack: '3'
  domains_config:
    domain:
    - name: Root
      storage_pool_types:
      - kind: ssd
        pool_config:
          box_id: 1
          erasure_species: mirror-3-dc
          kind: ssd
          geometry:
            realm_level_begin: 10
            realm_level_end: 20
            domain_level_begin: 10
            domain_level_end: 256
          pdisk_filter:
          - property:
            - type: SSD
          vdisk_kind: Default
    state_storage:
    - ring:
        node: [1, 2, 3]
        nto_select: 3
      ssid: 1
    security_config:
      enforce_user_token_requirement: true
      monitoring_allowed_sids:
      - "root"
      - "ADMINS"
      - "DATABASE-ADMINS"
      administration_allowed_sids:
      - "root"
      - "ADMINS"
      - "DATABASE-ADMINS"
      viewer_allowed_sids:
      - "root"
      - "ADMINS"
      - "DATABASE-ADMINS"
      register_dynamic_node_allowed_sids:
      - databaseNodes@cert
      - root@builtin
  blob_storage_config:
    service_set:
      groups:
      - erasure_species: mirror-3-dc
        rings:
        - fail_domains:
          - vdisk_locations:
            - node_id: static-node-1.ydb-cluster.com
              pdisk_category: SSD
              path: /dev/disk/by-partlabel/ydb_disk_1
          - vdisk_locations:
            - node_id: static-node-1.ydb-cluster.com
              pdisk_category: SSD
              path: /dev/disk/by-partlabel/ydb_disk_2
          - vdisk_locations:
            - node_id: static-node-1.ydb-cluster.com
              pdisk_category: SSD
              path: /dev/disk/by-partlabel/ydb_disk_3
        - fail_domains:
          - vdisk_locations:
            - node_id: static-node-2.ydb-cluster.com
              pdisk_category: SSD
              path: /dev/disk/by-partlabel/ydb_disk_1
          - vdisk_locations:
            - node_id: static-node-2.ydb-cluster.com
              pdisk_category: SSD
              path: /dev/disk/by-partlabel/ydb_disk_2
          - vdisk_locations:
            - node_id: static-node-2.ydb-cluster.com
              pdisk_category: SSD
              path: /dev/disk/by-partlabel/ydb_disk_3
        - fail_domains:
          - vdisk_locations:
            - node_id: static-node-3.ydb-cluster.com
              pdisk_category: SSD
              path: /dev/disk/by-partlabel/ydb_disk_1
          - vdisk_locations:
            - node_id: static-node-3.ydb-cluster.com
              pdisk_category: SSD
              path: /dev/disk/by-partlabel/ydb_disk_2
          - vdisk_locations:
            - node_id: static-node-3.ydb-cluster.com
              pdisk_category: SSD
              path: /dev/disk/by-partlabel/ydb_disk_3
  channel_profile_config:
    profile:
    - channel:
      - erasure_species: mirror-3-dc
        pdisk_category: 1   # 0=ROT, 1=SSD, 2=NVME
        storage_pool_kind: ssd
      - erasure_species: mirror-3-dc
        pdisk_category: 1
        storage_pool_kind: ssd
      - erasure_species: mirror-3-dc
        pdisk_category: 1
        storage_pool_kind: ssd
      profile_id: 0
  interconnect_config:
      start_tcp: true
      encryption_mode: OPTIONAL
      path_to_certificate_file: "/opt/ydb/certs/node.crt"
      path_to_private_key_file: "/opt/ydb/certs/node.key"
      path_to_ca_file: "/opt/ydb/certs/ca.crt"
  grpc_config:
      cert: "/opt/ydb/certs/node.crt"
      key: "/opt/ydb/certs/node.key"
      ca: "/opt/ydb/certs/ca.crt"
      services_enabled:
      - legacy
      - discovery
  auth_config:
    path_to_root_ca: /opt/ydb/certs/ca.crt
  client_certificate_authorization:
    request_client_certificate: true
    client_certificate_definitions:
        - member_groups: ["databaseNodes@cert"]
          subject_terms:
          - short_name: "O"
            values: ["YDB"]
          - short_name: "CN"
            values: ["YDB CA"]
  query_service_config:
    generic:
      connector:
        endpoint:
          host: localhost
          port: 19102
        use_ssl: false
      default_settings:
        - name: DateTimeFormat
          value: string
        - name: UsePredicatePushdown
          value: "true"
  feature_flags:
    enable_external_data_sources: true
    enable_script_execution_operations: true

Для ускорения и упрощения первичного развёртывания YDB конфигурационный файл уже содержит большинство настроек для установки кластера. Достаточно заменить стандартные хосты 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

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

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