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

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

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

Требования

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

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

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

• 22: сервис SSH;
• 2135, 2136: GRPC для клиент-кластерного взаимодействия;
• 19001, 19002: Interconnect для внутрикластерного взаимодействия узлов;
• 8765, 8766: HTTP интерфейс YDB Embedded UI.

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

Убедитесь в том, что системные часы на всех серверах в составе кластера синхронизированы с помощью инструментов ntpd или chrony. Желательно использовать единый источник времени для всех серверов кластера, чтобы обеспечить одинаковую обработку секунд координации (leap seconds).

Если применяемый на серверах кластера тип Linux использует syslogd для логирования, необходимо настроить ротацию файлов лога с использованием инструмента logrotate или его аналогов. Сервисы YDB могут генерировать значительный объем системных логов, в особенности при повышении уровня логирования для диагностических целей, поэтому важно включить ротацию файлов системного лога для исключения ситуаций переполнения файловой системы /var.

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

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

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

Подготовка ключей и сертификатов TLS

Защита трафика и проверка подлинности серверных узлов YDB осуществляется с использованием протокола TLS. Перед установкой кластера необходимо спланировать состав серверов, определиться со схемой именования узлов и конкретными именами, и подготовить ключи и сертификаты TLS.

Вы можете использовать существующие или сгенерировать новые сертификаты. Следующие файлы ключей и сертификатов TLS должны быть подготовлены в формате PEM:

• ca.crt - сертификат центра регистрации (Certification Authority, CA), которым подписаны остальные сертификаты TLS (одинаковые файлы на всех узлах кластера);
• node.key - секретные ключи TLS для каждого из узлов кластера (свой ключ на каждый сервер кластера);
• node.crt - сертификаты TLS для каждого из узлов кластера (соответствующий ключу сертификат);
• web.pem - конкатенация секретного ключа узла, сертификата узла и сертификата центра регистрации для работы HTTP интерфейса мониторинга (свой файл на каждый сервер кластера).

Необходимые параметры формирования сертификатов определяются политикой организации. Обычно сертификаты и ключи для YDB формируются со следующими параметрами:

• ключи RSA длиною 2048 или 4096 бит;
• алгоритм подписи сертификатов SHA-256 с шифрованием RSA;
• срок действия сертификатов узлов не менее 1 года;
• срок действия сертификата центра регистрации не менее 3 лет.

Необходимо, чтобы сертификат центра регистрации был помечен соответствующим образом: должен быть установлен признак CA, а также включены виды использования "Digital Signature, Non Repudiation, Key Encipherment, Certificate Sign".

Для сертификатов узлов важно соответствие фактического имени хоста (или имён хостов) значениям, указанным в поле "Subject Alternative Name". Для сертификатов должны быть включены виды использования "Digital Signature, Key Encipherment" и расширенные виды использования "TLS Web Server Authentication, TLS Web Client Authentication". Необходимо, чтобы сертификаты узлов поддерживали как серверную, так и клиентскую аутентификацию (опция extendedKeyUsage = serverAuth,clientAuth в настройках OpenSSL).

Для пакетной генерации или обновления сертификатов кластера YDB с помощью программного обеспечения OpenSSL можно воспользоваться примером скрипта, размещённым в репозитории YDB на GitHub. Скрипт позволяет автоматически сформировать необходимые файлы ключей и сертификатов для всего набора узлов кластера за одну операцию, облегчая подготовку к установке.

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

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

sudo groupadd ydb
sudo useradd ydb -g ydb

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

sudo usermod -aG disk ydb

Установите программное обеспечение YDB на каждом сервере

1. Скачайте и распакуйте архив с исполняемым файлом 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
   

2. Создайте директории для размещения программного обеспечения YDB:

   sudo mkdir -p /opt/ydb /opt/ydb/cfg
   

3. Скопируйте исполняемый файл и библиотеки в соответствующие директории:

   sudo cp -iR ydbd-stable-linux-amd64/bin /opt/ydb/
   sudo cp -iR ydbd-stable-linux-amd64/lib /opt/ydb/
   

4. Установите владельца файлов и каталогов:

   sudo chown -R root:bin /opt/ydb
   

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

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

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

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

   Внимание

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

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

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

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

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

2. Очистите диск встроенной в исполняемый файл ydbd командой:

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

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

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

Подготовьте конфигурационный файл 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. В секции blob_storage_config скорректируйте FQDN всех нод, используемых для размещения статической группы хранения:

   • для схемы mirror-3-dc необходимо указать FQDN для 9 нод;
   • для схемы block-4-2 необходимо указать FQDN для 8 нод.

5. Включите аутентификацию пользователей (опционально).

   Если вы планируете использовать в кластере 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"
   

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

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

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

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

Скопируйте ключи и сертификаты TLS на каждый сервер

Подготовленные ключи и сертификаты TLS необходимо скопировать в защищенный каталог на каждом из узлов кластера YDB. Ниже приведен пример команд для создания защищенного каталога и копирования файлов с ключами и сертификатами.

sudo mkdir -p /opt/ydb/certs
sudo cp -v ca.crt /opt/ydb/certs/
sudo cp -v node.crt /opt/ydb/certs/
sudo cp -v node.key /opt/ydb/certs/
sudo cp -v web.pem /opt/ydb/certs/
sudo chown -R ydb:ydb /opt/ydb/certs
sudo chmod 700 /opt/ydb/certs

Запустите статические узлы

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 \
    --grpcs-port 2135 --ic-port 19001 --mon-port 8765 --mon-cert /opt/ydb/certs/web.pem --node static

[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 \
    --grpcs-port 2135 --ic-port 19001 --mon-port 8765 \
    --mon-cert /opt/ydb/certs/web.pem --node static
LimitNOFILE=65536
LimitCORE=0
LimitMEMLOCK=3221225472

[Install]
WantedBy=multi-user.target

sudo systemctl start ydbd-storage

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

Операция инициализации кластера осуществляет настройку набора статических узлов, перечисленных в конфигурационном файле кластера, для хранения данных YDB.

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

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

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

export LD_LIBRARY_PATH=/opt/ydb/lib
/opt/ydb/bin/ydbd -f token-file --ca-file ca.crt -s grpcs://`hostname -f`:2135 \
    admin blobstorage config init --yaml-file  /opt/ydb/cfg/config.yaml
echo $?

export LD_LIBRARY_PATH=/opt/ydb/lib
/opt/ydb/bin/ydbd --ca-file ca.crt -s grpcs://`hostname -f`:2135 \
    admin blobstorage config init --yaml-file  /opt/ydb/cfg/config.yaml
echo $?

При успешном выполнении инициализации кластера выведенный на экран код завершения команды инициализации кластера должен быть нулевым.

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

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

Для выполнения административной команды создания базы данных потребуется файл сертификата центра регистрации ca.crt, аналогично описанному выше порядку выполнения действий по инициализации кластера.

При создании базы данных устанавливается первоначальное количество используемых групп хранения, определяющее доступную пропускную способность ввода-вывода и максимальную емкость хранения. Количество групп хранения может быть при необходимости увеличено после создания базы данных.

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

export LD_LIBRARY_PATH=/opt/ydb/lib
/opt/ydb/bin/ydbd -f token-file --ca-file ca.crt -s grpcs://`hostname -s`:2135 \
    admin database /Root/testdb create ssd:1
echo $?

export LD_LIBRARY_PATH=/opt/ydb/lib
/opt/ydb/bin/ydbd --ca-file ca.crt -s grpcs://`hostname -s`:2135 \
    admin database /Root/testdb create ssd:1
echo $?

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

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

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

Запустите динамические узлы

sudo su - ydb
cd /opt/ydb
export LD_LIBRARY_PATH=/opt/ydb/lib
/opt/ydb/bin/ydbd server --grpcs-port 2136 --grpc-ca /opt/ydb/certs/ca.crt \
    --ic-port 19002 --ca /opt/ydb/certs/ca.crt \
    --mon-port 8766 --mon-cert /opt/ydb/certs/web.pem \
    --yaml-config  /opt/ydb/cfg/config.yaml --tenant /Root/testdb \
    --node-broker grpcs://<ydb1>:2135 \
    --node-broker grpcs://<ydb2>:2135 \
    --node-broker grpcs://<ydb3>:2135

[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 \
    --grpcs-port 2136 --grpc-ca /opt/ydb/certs/ca.crt \
    --ic-port 19002 --ca /opt/ydb/certs/ca.crt \
    --mon-port 8766 --mon-cert /opt/ydb/certs/web.pem \
    --yaml-config  /opt/ydb/cfg/config.yaml --tenant /Root/testdb \
    --node-broker grpcs://<ydb1>:2135 \
    --node-broker grpcs://<ydb2>:2135 \
    --node-broker grpcs://<ydb3>:2135
LimitNOFILE=65536
LimitCORE=0
LimitMEMLOCK=32212254720

[Install]
WantedBy=multi-user.target

sudo systemctl start ydbd-testdb

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

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

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

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

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

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

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

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

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

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

   ydb --ca-file ca.crt -e grpcs://<node.ydb.tech>:2136 -d /Root/testdb --user root \
       yql -s 'CREATE USER user1 PASSWORD "passw0rd"'
   

4. Установите права учетных записей, включив их во встроенные группы:

   ydb --ca-file ca.crt -e grpcs://<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.

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

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

2. Создайте тестовую строковую (test_row_table) или колоночную таблицу (test_column_table):

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

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

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

Проверка доступа ко встроенному web-интерфейсу

Для проверки доступа ко встроенному web-интерфейсу YDB достаточно открыть в Web-браузере страницу с адресом https://<node.ydb.tech>:8765, где <node.ydb.tech> - FQDN сервера, на котором запущен любой статический узел YDB.

В Web-браузере должно быть настроено доверие в отношении центра регистрации, выпустившего сертификаты для кластера YDB, в противном случае будет отображено предупреждение об использовании недоверенного сертификата.

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

Особенности установки YDB в незащищенном режиме

Описанная выше процедура установки предусматривает развёртывание YDB в стандартном защищенном режиме.

Незащищённый режим работы YDB предназначен для решения тестовых задач, преимущественно связанных с разработкой и тестированием программного обеспечения YDB. В незащищенном режиме:

• трафик между узлами кластера, а также между приложениями и кластером использует незашифрованные соединения;
• не используется аутентификация пользователей (включение аутентификации при отсутствии шифрования трафика не имеет смысла, поскольку логин и пароль в такой конфигурации передавались бы через сеть в открытом виде).

Установка YDB для работы в незащищенном режиме производится в порядке, описанном выше, со следующими исключениями:

1. При подготовке к установке не требуется формировать сертификаты и ключи TLS, и не выполняется копирование сертификатов и ключей на узлы кластера.

2. Из конфигурационных файлов кластерных узлов исключается подсекция security_config в секции domains_config, а также целиком исключаются секции interconnect_config и grpc_config.

3. Используются упрощенный вариант команд запуска статических и динамических узлов кластера: исключаются опции с именами файлов сертификатов и ключей, используется протокол grpc вместо grpcs при указании точек подключения.

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

5. Команда инициализации кластера выполняется в следующей форме:

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

6. Команда создания базы данных выполняется в следующей форме:

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

7. При обращении к базе данных из YDB CLI и приложений используется протокол grpc вместо grpcs, и не используется аутентификация.