Развертывание кластера YDB на виртуальных или физических серверах

Этот документ описывает способ развернуть мультитенантный кластер YDB на нескольких физических или виртуальных серверах.

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

Требования

У вас должен быть ssh доступ на все сервера. Это необходимо для установки артефактов и запуска исполняемого файла YDB. Сетевая конфигурация должна разрешать TCP соединения по следующим портам (по умолчанию):

  • 2135, 2136 - grpc для клиент-кластерного взаимодействия;
  • 19001, 19002 - Interconnect для внутрикластерного взаимодействия нод;
  • 8765, 8766 - http интерфейс для мониторинга кластера.

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

Выберите серверы и диски, которые будут использоваться для хранения данных:

  • Используйте схему отказоустойчивости block-4-2 для развертывания кластера в одной зоне доступности (AZ). Чтобы переживать отказ 2 нод используйте не менее 8 нод.
  • Используйте схему отказоустойчивости mirror-3-dc для развертывания кластера в трех зонах доступности (AZ). Чтобы переживать отказ 1 AZ и 1 ноды в другом AZ используйте не менее 9 нод. Количество нод в каждой AZ должно быть одинаковым.

Запускайте каждую статическую ноду на отдельном сервере.

Подробнее требования к оборудованию описаны в разделе Системные требования и рекомендации.

Создайте системного пользователя и группу, от имени которого будет работать YDB

На каждом сервере, где будет запущен YDB выполните:

sudo groupadd ydb
sudo useradd ydb -g ydb

Для того, чтобы сервис YDB имел доступ к блочным дискам для работы, необходимо добавить пользователя, под которым будет запущен процесс, в группу disk:

sudo usermod -aG disk ydb

Подготовьте и отформатируйте диски на каждом сервере

Важно

Мы не рекомендуем использовать для хранения данных диски, которые используются другими процессами (в том числе операционной системой).

Для эффективной работы YDB рекомендуется использовать физические (не виртуальные) диски объемом более 800 ГБ как блочные устройства.

Минимальный объем диска должен быть не менее 80 ГБ, при меньшем объеме узел YDB не сможет использовать устройство. Корректная и бесперебойная работа с дисками минимального объема не гарантируется. Использовать такие диски рекомендуется исключительно в ознакомительных целях.

Важно

Конфигурации с дисками объемом меньше 800 ГБ или с любыми видами виртуализации системы хранения нельзя использовать для сервисов, находящихся в промышленной эксплуатации, а также для тестирования производительности системы.

  1. Создайте раздел на выбранном диске:

    Внимание

    Следующая операция удалит все разделы на указанных дисках! Убедитесь, что вы указали диски, на которых нет других данных!

    sudo parted /dev/nvme0n1 mklabel gpt -s
    sudo parted -a optimal /dev/nvme0n1 mkpart primary 0% 100%
    sudo parted /dev/nvme0n1 name 1 ydb_disk_ssd_01
    sudo partx --u /dev/nvme0n1
    

    После выполнения в системе появится диск с лейблом /dev/disk/by-partlabel/ydb_disk_ssd_01.

    Если вы планируете использовать более одного диска на каждом сервере, укажите для каждого свой уникальный лейбл вместо ydb_disk_ssd_01. Эти диски необходимо будет использовать в конфигурационных файлах далее.

  2. Скачайте и распакуйте архив с исполняемым файлом ydbd и необходимыми для работы YDB библиотеками:

    mkdir ydbd-stable-linux-amd64
    curl -L https://binaries.ydb.tech/ydbd-stable-linux-amd64.tar.gz | tar -xz --strip-component=1 -C ydbd-stable-linux-amd64
    
  3. Создайте директории для запуска:

    sudo mkdir -p /opt/ydb/bin /opt/ydb/cfg /opt/ydb/lib
    sudo chown -R ydb:ydb /opt/ydb
    
  4. Скопируйте исполняемый файл, библиотеки и конфигурационный файл в соответствующие директории:

    sudo cp -i ydbd-stable-linux-amd64/bin/ydbd /opt/ydb/bin/
    sudo cp -i ydbd-stable-linux-amd64/lib/libaio.so /opt/ydb/lib/
    sudo cp -i ydbd-stable-linux-amd64/lib/libiconv.so /opt/ydb/lib/
    sudo cp -i ydbd-stable-linux-amd64/lib/libidn.so /opt/ydb/lib/
    
  5. Отформатируйте диск встроенной командой:

    sudo LD_LIBRARY_PATH=/opt/ydb/lib /opt/ydb/bin/ydbd admin bs disk obliterate /dev/disk/by-partlabel/ydb_disk_ssd_01
    

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

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

В незащищенном режиме трафик между нодами кластера, а также между клиентом и кластером использует нешифрованное соединение. Используйте данный режим для тестовых задач.

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

  1. Скачайте пример конфига для соответствующей модели отказа вашего кластера:

    • block-4-2 - для однодатацентрового кластера.
    • mirror-3dc - для cross-DC кластера из 9 нод.
    • mirror-3dc-3nodes - для cross-DC кластера из 3 нод.
  2. В секции host_configs укажите все диски и их тип на каждой из нод кластера. Возможные варианты типов дисков:

    • ROT: rotational, HDD диски.
    • SSD: SSD или NVMe диски.
    host_configs:
    - drive:
      - path: /dev/disk/by-partlabel/ydb_disk_ssd_01
        type: SSD
      host_config_id: 1
    
  3. В секции hosts укажите FQDN всех нод, их конфигурацию и расположение по датацентрам (data_center) и стойкам (rack):

    hosts:
    - host: node1.ydb.tech
      host_config_id: 1
      walle_location:
        body: 1
        data_center: 'zone-a'
        rack: '1'
    - host: node2.ydb.tech
      host_config_id: 1
      walle_location:
        body: 2
        data_center: 'zone-b'
        rack: '1'
    - host: node3.ydb.tech
      host_config_id: 1
      walle_location:
        body: 3
        data_center: 'zone-c'
        rack: '1'
    
  4. Включите аутентификацию пользователей (опционально).

    Если вы планируете использовать в кластере YDB возможности аутентификации и разграничения доступа пользователей, добавьте в секцию domains_config следующие дополнительные параметры:

    domains_config:
      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"
    

В защищенном режиме трафик между нодами кластера, а также между клиентом и кластером шифруется протоколом TLS.

Примечание

Вы можете использовать существующие TLS сертификаты. Важно, чтобы сертификаты поддерживали как серверную, так и клиентскую аутентификацию (extendedKeyUsage = serverAuth,clientAuth)

  1. Создайте ключ и сертификат для центра сертификации (CA):

    1. Создайте директории secure, в которой будет храниться ключ CA, и certs для сертификатов и ключей нод:

      mkdir secure
      mkdir certs
      
    2. Создайте конфигурационный файл ca.cnf со следующим содержимым:

      [ ca ]
      default_ca = CA_default
      
      [ CA_default ]
      default_days = 365
      database = index.txt
      serial = serial.txt
      default_md = sha256
      copy_extensions = copy
      unique_subject = no
      
      [ req ]
      prompt=no
      distinguished_name = distinguished_name
      x509_extensions = extensions
      
      [ distinguished_name ]
      organizationName = YDB
      commonName = YDB CA
      
      [ extensions ]
      keyUsage = critical,digitalSignature,nonRepudiation,keyEncipherment,keyCertSign
      basicConstraints = critical,CA:true,pathlen:1
      
      [ signing_policy ]
      organizationName = supplied
      commonName = optional
      
      [ signing_node_req ]
      keyUsage = critical,digitalSignature,keyEncipherment
      extendedKeyUsage = serverAuth,clientAuth
      
      # Used to sign client certificates.
      [ signing_client_req ]
      keyUsage = critical,digitalSignature,keyEncipherment
      extendedKeyUsage = clientAuth
      
    3. Создайте CA ключ:

      openssl genrsa -out secure/ca.key 2048
      

      Сохраните этот ключ отдельно, он необходим для выписывания сертификатов. При его утере вам необходимо будет перевыпустить все сертификаты.

    4. Создайте частный Certificate Authority (CA) сертификат:

      openssl req -new -x509 -config ca.cnf -key secure/ca.key -out ca.crt -days 365 -batch
      
  2. Создайте ключи и сертификаты для нод кластера:

    1. Создайте конфигурационный файл node.conf со следующим содержимым:

      # OpenSSL node configuration file
      [ req ]
      prompt=no
      distinguished_name = distinguished_name
      req_extensions = extensions
      
      [ distinguished_name ]
      organizationName = YDB
      
      [ extensions ]
      subjectAltName = DNS:<node>.<domain>
      
    2. Создайте ключ сертификата:

      openssl genrsa -out node.key 2048
      
    3. Создайте Certificate Signing Request (CSR):

      openssl req -new -sha256 -config node.cnf -key certs/node.key -out node.csr -batch
      
    4. Создайте сертификат ноды:

      openssl ca -config ca.cnf -keyfile secure/ca.key -cert certs/ca.crt -policy signing_policy \
      -extensions signing_node_req -out certs/node.crt -outdir certs/ -in node.csr -batch
      

      Создайте аналогичные пары сертификат-ключ для каждой ноды.

    5. Создайте на каждой ноде директирии для сертификатов:

      sudo mkdir /opt/ydb/certs
      sudo chown -R ydb:ydb /opt/ydb/certs
      sudo chmod 0750 /opt/ydb/certs
      
    6. Скопируйте сертификаты и ключи ноды в каталог инсталляции:

      sudo -u ydb cp certs/ca.crt certs/node.crt certs/node.key /opt/ydb/certs/
      
  3. Подготовьте конфигурационный файл YDB:

    1. Скачайте пример конфига для соответствующей модели отказа вашего кластера:

      • block-4-2 - для однодатацентрового кластера.
      • mirror-3dc - для cross-DC кластера из 9 нод.
      • mirror-3dc-3nodes - для cross-DC кластера из 3 нод.
    2. В секции host_configs укажите все диски и их тип на каждой из нод кластера. Возможные варианты типов дисков:

      • ROT: rotational, HDD диски.
      • SSD: SSD или NVMe диски.
      host_configs:
      - drive:
        - path: /dev/disk/by-partlabel/ydb_disk_ssd_01
          type: SSD
        host_config_id: 1
      
    3. В секции hosts укажите FQDN всех нод, их конфигурацию и расположение по датацентрам (data_center) и стойкам (rack):

      hosts:
      - host: node1.ydb.tech
        host_config_id: 1
        walle_location:
          body: 1
          data_center: 'zone-a'
          rack: '1'
      - host: node2.ydb.tech
        host_config_id: 1
        walle_location:
          body: 2
          data_center: 'zone-b'
          rack: '1'
      - host: node3.ydb.tech
        host_config_id: 1
        walle_location:
          body: 3
          data_center: 'zone-c'
          rack: '1'
      
    4. Включите аутентификацию пользователей (опционально).

      Если вы планируете использовать в кластере YDB возможности аутентификации и разграничения доступа пользователей, добавьте в секцию domains_config следующие дополнительные параметры:

      domains_config:
        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"
      
  4. Включите режим шифрования трафика в конфигурационном файле YDB.

    В секциях interconnect_config и grpc_config укажите путь до файлов сертификата, ключа и CA сертификата:

    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"
    

Сохраните конфигурационный файл YDB под именем /opt/ydb/cfg/config.yaml на каждом узле кластера.

Более подробная информация по созданию конфигурации приведена в статье Конфигурация кластера.

Запустите статические ноды

Запустите на каждой ноде YDB storage:

sudo su - ydb
cd /opt/ydb
export LD_LIBRARY_PATH=/opt/ydb/lib
/opt/ydb/bin/ydbd server --log-level 3 --syslog --tcp --yaml-config /opt/ydb/cfg/config.yaml  \
--grpc-port 2135 --ic-port 19001 --mon-port 8765 --node static

Создайте на каждой ноде конфигурационный файл /etc/systemd/system/ydbd-storage.service со следующим содержимым:

[Unit]
Description=YDB storage node
After=network-online.target rc-local.service
Wants=network-online.target
StartLimitInterval=10
StartLimitBurst=15

[Service]
Restart=always
RestartSec=1
User=ydb
PermissionsStartOnly=true
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=ydbd
SyslogFacility=daemon
SyslogLevel=err
Environment=LD_LIBRARY_PATH=/opt/ydb/lib
ExecStart=/opt/ydb/bin/ydbd server --log-level 3 --syslog --tcp --yaml-config  /opt/ydb/cfg/config.yaml --grpc-port 2135 --ic-port 19001 --mon-port 8765 --node static
LimitNOFILE=65536
LimitCORE=0
LimitMEMLOCK=3221225472

[Install]
WantedBy=multi-user.target

Запустите на каждой ноде YDB storage:

sudo systemctl start ydbd-storage

Инициализируйте кластер

Действия по инициализации кластера зависят от того, включен ли в конфигурационном файле YDB режим аутентификации пользователей.

На одной из нод кластера выполните команды:

export LD_LIBRARY_PATH=/opt/ydb/lib
/opt/ydb/bin/ydbd admin blobstorage config init --yaml-file  /opt/ydb/cfg/config.yaml
echo $?

Код завершения команды должен быть нулевым.

Для выполнения административных команд (включая инициализацию кластера, создание баз данных, управление дисками и другие) в кластере со включённым режимом аутентификации пользователей необходимо предварительно получить аутентификационный токен с использованием клиента YDB CLI версии 2.0.0 или выше. Клиент YDB CLI следует установить на любом компьютере, имеющем сетевой доступ к узлам кластера (например, на одном из узлов кластера), в соответствии с инструкцией по установке.

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

ydb -e grpc://<node1.ydb.tech>:2135 -d /Root \
    --user root --no-password auth get-token --force >token-file

В качестве сервера для подключения (параметр -e или --endpoint) может быть указан любой из серверов кластера.

Если была включена защита трафика с использованием TLS, то вместо протокола grpc в команде выше следует использовать его защищенный вариант grpcs, и дополнительно указать путь к файлу с сертификатом CA в параметре --ca-file. Например:

ydb -e grpcs://<node1.ydb.tech>:2135 -d /Root --ca-file /opt/ydb/certs/ca.crt \
     --user root --no-password auth get-token --force >token-file

При успешном выполнении указанной выше команды аутентификационный токен будет записан в файл token-file. Этот файл необходимо будет скопировать на ноду кластера, на которой в дальнейшем вы собираетесь выполнять команды инициализации кластера и создания базы данных. Далее на этой ноде кластера выполните команды:

export LD_LIBRARY_PATH=/opt/ydb/lib
/opt/ydb/bin/ydbd -f token-file admin blobstorage config init --yaml-file  /opt/ydb/cfg/config.yaml
echo $?

Код завершения команды должен быть нулевым.

Создайте базу данных

Для работы с таблицами необходимо создать как минимум одну базу данных и поднять процесс, обслуживающий эту базу данных (динамическую ноду):

LD_LIBRARY_PATH=/opt/ydb/lib /opt/ydb/bin/ydbd admin database /Root/testdb create ssd:1

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

Вариант команды создания базы данных с указанием файла токена:

LD_LIBRARY_PATH=/opt/ydb/lib /opt/ydb/bin/ydbd -f token-file admin database /Root/testdb create ssd:1

В приведенных выше примерах команд используются следующие параметры:

  • /Root - имя корневого домена, должно соответствовать настройке domains_config.domain.name в файле конфигурации кластера;
  • testdb - имя создаваемой базы данных;
  • ssd:1 - имя пула хранения и номер блока в пуле. Имя пула обычно означает тип устройств хранения данных и должно соответствовать настройке storage_pool_types.kind внутри элемента domains_config.domain файла конфигурации.

Запустите динамическую ноду базы данных

Запустите динамическую ноду YDB для базы /Root/testdb:

sudo su - ydb
cd /opt/ydb
export LD_LIBRARY_PATH=/opt/ydb/lib
/opt/ydb/bin/ydbd server --grpc-port 2136 --ic-port 19002 --mon-port 8766 --yaml-config  /opt/ydb/cfg/config.yaml \
--tenant /Root/testdb --node-broker <node1.ydb.tech>:2135 --node-broker <node2.ydb.tech>:2135 --node-broker <node3.ydb.tech>:2135

Где <nodeN.ydb.tech> - FQDN серверов, на которых запущены статические ноды.

Запустите дополнительные динноды на других серверах для обеспечения доступности базы данных.

  1. Создайте конфигурационный файл /etc/systemd/system/ydbd-testdb.service со следующим содержимым:
[Unit]
Description=YDB testdb dynamic node
After=network-online.target rc-local.service
Wants=network-online.target
StartLimitInterval=10
StartLimitBurst=15

[Service]
Restart=always
RestartSec=1
User=ydb
PermissionsStartOnly=true
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=ydbd
SyslogFacility=daemon
SyslogLevel=err
Environment=LD_LIBRARY_PATH=/opt/ydb/lib
ExecStart=/opt/ydb/bin/ydbd server --grpc-port 2136 --ic-port 19002 --mon-port 8766 --yaml-config  /opt/ydb/cfg/config.yaml --tenant /Root/testdb --node-broker <node1.ydb.tech>:2135 --node-broker <node2.ydb.tech>:2135 --node-broker <node3.ydb.tech>:2135
LimitNOFILE=65536
LimitCORE=0
LimitMEMLOCK=32212254720

[Install]
WantedBy=multi-user.target

Где <nodeN.ydb.tech> - FQDN серверов, на которых запущены статические ноды.

  1. Запустите динамическую ноду YDB для базы /Root/testdb:
sudo systemctl start ydbd-testdb
  1. Запустите дополнительные динноды на других серверах для обеспечения доступности базы данных.

Первоначальная настройка учетных записей

Если в файле настроек кластера включен режим аутентификации, то перед началом работы с кластером YDB необходимо выполнить первоначальную настройку учетных записей.

При первоначальной установке кластера YDB автоматически создается учетная запись root с пустым паролем, а также стандартный набор групп пользователей, описанный в разделе Управление доступом.

Для выполнения первоначальной настройки учетных записей в созданном кластере YDB выполните следующие операции:

  1. Установите YDB CLI, как описано в документации.

  2. Выполните установку пароля учетной записи root:

    ydb -e grpc://<node.ydb.tech>:2136 -d /Root/testdb --user root --no-password \
        yql -s 'ALTER USER root PASSWORD "passw0rd"'
    

    Вместо значения passw0rd подставьте необходимый пароль.

  3. Создайте дополнительные учетные записи:

    ydb -e grpc://<node.ydb.tech>:2136 -d /Root/testdb --user root \
        yql -s 'CREATE USER user1 PASSWORD "passw0rd"'
    
  4. Установите права учетных записей, включив их во встроенные группы:

    ydb -e grpc://<node.ydb.tech>:2136 -d /Root/testdb --user root \
        yql -s 'ALTER GROUP `ADMINS` ADD USER user1'
    

В перечисленных выше примерах команд <node.ydb.tech> - FQDN сервера, на котором запущена динамическая нода, обслуживающая базу /Root/testdb.

При выполнении команд создания учетных записей и присвоения групп клиент YDB CLI будет запрашивать ввод пароля пользователя root. Избежать многократного ввода пароля можно, создав профиль подключения, как описано в документации YDB CLI.

Если в кластере была включена защита трафика с использованием TLS, то вместо протокола grpc в команде выше следует использовать его защищенный вариант grpcs, и дополнительно указать путь к файлу с сертификатом CA в параметре --ca-file (либо сохранить в профиле подключения).

Протестируйте работу с созданной базой

  1. Установите YDB CLI, как описано в документации.

  2. Создайте тестовую таблицу test_table:

    ydb -e grpc://<node.ydb.tech>:2136 -d /Root/testdb scripting yql \
    --script 'CREATE TABLE `testdir/test_table` (id Uint64, title Utf8, PRIMARY KEY (id));'
    

    Где <node.ydb.tech> - FQDN сервера, на котором запущена динамическая нода, обслуживающая базу /Root/testdb.

    Указанную выше команду необходимо будет скорректировать, если в кластере включена защита трафика с использованием TLS или активирован режим аутентификации пользователей. Пример:

    ydb -e grpcs://<node.ydb.tech>:2136 -d /Root/testdb --ca-file ydb-ca.crt --user root scripting yql \
    --script 'CREATE TABLE `testdir/test_table` (id Uint64, title Utf8, PRIMARY KEY (id));'