Развёртывание кластера с использованием конфигурации V2

Подготовьте окружение

Перед развёртыванием системы обязательно выполните подготовительные действия. Ознакомьтесь с документом Подготовка к развертыванию.

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

mkdir deployment
cd deployment
mkdir -p inventory/group_vars/ydb
mkdir files

Создайте конфигурационный файл Ansible

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

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

[ssh_connection]
retries = 5
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/group_vars/ydb/all.yaml и заполните его.

# 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_user: root
  ydb_dbname: db

# Хранилище
  ydb_disks:
    - name: /dev/vdb
    label: ydb_disk_1
    - name: /dev/vdc
    label: ydb_disk_2
    - name: /dev/vdd
    label: ydb_disk_3
  ydb_pool_kind: ssd
  ydb_allow_format_drives: true
  ydb_skip_data_loss_confirmation_prompt: false
  ydbops_local: true
  ydb_cores_dynamic: 2
  ydb_dynnodes:
    - {"instance": "a", offset: 1}
  ydb_cores_static:  2

# Настройки авторизации
  ydb_enforce_user_token_requirement: true

# Узлы
  ydb_version: "версия_системы"

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

1. Настройка SSH доступа. Укажите пользователя ansible_user и путь к приватному ключу ansible_ssh_private_key_file, которые Ansible будет использовать для подключения к вашим серверам.
2. Пути к блочным устройствам в файловой системе. В секции ydb_disks шаблон предполагает, что /dev/vda предназначен для операционной системы, а следующие диски, такие как /dev/vdb, — для слоя хранения YDB. Метки дисков создаются плейбуками автоматически, и их имена могут быть произвольными.
3. Версия системы. В параметре ydb_version укажите номер версии YDB, которую нужно установить. Список доступных версий вы найдёте на странице загрузок.

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

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

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

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

password

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

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

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

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

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

Создайте файл files/config.yaml и заполните его.

metadata:
  kind: MainConfig
  cluster: ""
  version: 0
config:
  yaml_config_enabled: true
  erasure: mirror-3-dc
  fail_domain_type: disk
  self_management_config:
    enabled: true
  default_disk_type: SSD
host_configs:
  - host_config_id: 1
  drive:
  - path: /dev/disk/by-partlabel/ydb_disk_ssd_01
    type: SSD
  - path: /dev/disk/by-partlabel/ydb_disk_ssd_02
    type: SSD
  - path: /dev/disk/by-partlabel/ydb_disk_ssd_03
    type: SSD
hosts:
  - host: ydb-node-zone-a.local
    host_config_id: 1
    location:
      body: 1
      data_center: 'zone-a'
      rack: '1'
  - host: ydb-node-zone-b.local
    host_config_id: 1
    location:
      body: 2
      data_center: 'zone-b'
      rack: '1'
  - host: ydb-node-zone-d.local
    host_config_id: 1
    location:
      body: 3
      data_center: 'zone-d'
      rack: '1'
actor_system_config:
  use_auto_config: true
  cpu_count: 1
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
security_config:
  enforce_user_token_requirement: true
client_certificate_authorization:
  request_client_certificate: true
  client_certificate_definitions:
  - member_groups: ["ADMINS"]
    subject_terms:
    - short_name: "O"
      values: ["YDB"]
domains_config:
  security_config:
    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  

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

• Раздел hosts:

  ...
  hosts:
    - host: ydb-node-zone-a.local
    host_config_id: 1
    location:
      body: 1
      data_center: 'zone-a'
      rack: '1'
  ...
  

• Раздел hosts_configs:

  ...
  host_configs:
  - host_config_id: 1
    drive:
    - path: /dev/disk/by-partlabel/ydb_disk_ssd_01
      type: SSD
    - path: /dev/disk/by-partlabel/ydb_disk_ssd_02
      type: SSD
    - path: /dev/disk/by-partlabel/ydb_disk_ssd_03
      type: SSD
  ...
  

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

Создайте файл inventory/ydb_inventory.yaml с содержимым:

plugin: ydb_platform.ydb.ydb_inventory
ydb_config: "files/config.yaml"

Разверните кластер 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_dbname (по умолчанию 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