Миграция на конфигурацию V2

Данный документ содержит инструкцию по миграции с конфигурации V1 на конфигурацию V2.

В конфигурации V1 существует два различных механизма применения конфигурационных файлов:

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

В конфигурации V2 этот процесс унифицирован: единый конфигурационный файл загружается в систему через команды YDB CLI, автоматически доставляясь на все узлы кластера.

Компоненты State Storage и статической группы кластера YDB являются ключевыми для корректной работы кластера. При работе с конфигурацией V1 данные компоненты настраиваются вручную через задание секций domains_config и blob_storage_config в конфигурационном файле.
В конфигурации V2 возможна автоматическая конфигурация этих компонентов без указания соответствующих секций в конфигурационном файле.

Исходное состояние

Миграция на конфигурацию V2 может быть осуществлена в случае выполнения следующих условий:

Кластер YDB обновлён до версии 25.1 и выше.
Кластер YDB сконфигурирован с файлом конфигурации V1 config.yaml, расположенным в файловой системе узлов и подключённым через аргумент ydbd --yaml-config.
В конфигурационном файле кластера заданы разделы domains_config и blob_storage_config для настройки State Storage и статической группы соответственно.

Проверка текущей версии конфигурации

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

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

Инструкция по миграции на конфигурацию V2

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

Проверить наличие файла динамической конфигурации в кластере. Для этого необходимо выполнить команду ydb admin cluster config fetch:
```
ydb -e grpc://<node.ydb.tech>:2135 admin cluster config fetch > config.yaml
```
В случае отсутствия такой конфигурации в кластере команда выдаст сообщение:
```
No config returned.
```
Если файл найден, следует использовать его и пропустить следующий шаг данной инструкции.
В случае отсутствия файла динамической конфигурации в кластере выполнить команду генерации файла динамической конфигурации ydb admin cluster config generate. Файл будет сгенерирован на основе файла статической конфигурации, расположенного на узлах кластера.
```
ydb -e grpc://<node.ydb.tech>:2135 admin cluster config generate > config.yaml
```
Добавить в полученный на шаге 1 или 2 файл config.yaml следующее поле:
```
feature_flags:
    ...
    switch_to_config_v2: true
```
Подробнее
Включение данного флага означает, что за хранение конфигурации и операции над ней теперь отвечает таблетка DS Controller, а не таблетка Console. Это переключает основной механизм управления конфигурацией кластера.
Разместить файл config.yaml на всех узлах кластера, заменив им предыдущий файл конфигурации.
Создать директорию для работы узла YDB с конфигурацией на каждом из узлов. В случае запуска нескольких узлов кластера на одном хосте создайте отдельные директории под каждый узел. Инициализируйте директорию, выполнив команду ydb admin node config init на каждом из узлов. В параметре --from-config укажите путь к файлу config.yaml, размещённому на узлах ранее.
```
sudo mkdir -p /opt/ydb/config-dir
sudo chown -R ydb:ydb /opt/ydb/config-dir
ydb admin node config init --config-dir /opt/ydb/config-dir --from-config /opt/ydb/cfg/config.yaml
```
Подробнее
В дальнейшем система самостоятельно будет сохранять актуальную конфигурацию в указанные директории.
Перезапустить все узлы кластера с помощью процедуры rolling-restart, добавив опцию ydbd --config-dir при запуске узла с указанием пути до директории, а также убрав опцию ydbd --yaml-config.
Вручную

С использованием systemd
При ручном запуске добавьте опцию --config-dir к команде ydbd server, не указывая опцию --yaml-config:
```
ydbd server --config-dir /opt/ydb/config-dir
```
При использовании systemd добавьте опцию --config-dir к команде ydbd server в конфигурационный файл systemd, а также удалите опцию --yaml-config:
```
ExecStart=/opt/ydb/bin/ydbd server --config-dir /opt/ydb/config-dir
```
После обновления файла systemd выполните следующую команду, чтобы применить изменения:
```
sudo systemctl daemon-reload
```
Загрузить полученный ранее конфигурационный файл config.yaml в систему с помощью команды ydb admin cluster config replace:
```
ydb -e grpc://<node.ydb.tech>:2135 cluster config replace -f config.yaml
```
Команда запросит подтверждение на выполнение операции This command may damage your cluster, do you want to continue? [y/N], в ответ на этот запрос необходимо согласиться и ввести y.

Подробнее
После выполнения команды конфигурационный файл загрузится во внутреннее хранилище таблетки DS Controller и сохранится в директориях, указанных в опции --config-dir на каждом узле. С этого момента любое изменение конфигурации на существующих узлах выполняется с помощью специальных команд YDB CLI. Также при запуске узла актуальная конфигурация будет автоматически загружаться из конфигурационной директории.
Получить текущую конфигурацию кластера с помощью ydb admin cluster config fetch:
```
ydb -e grpc://<node.ydb.tech>:2135 admin cluster config fetch > config.yaml
```
Файл config.yaml должен совпадать с конфигурационными файлами, разложенными по узлам кластера, за исключением поля metadata.version, которое должно быть больше на единицу по сравнению с версией на узлах кластера.
Добавить в config.yaml в разделе config следующий блок:
```
self_management_config:
  enabled: true
```
Подробнее
Данная секция отвечает за включение механизма распределённой конфигурации в кластере. Хранение конфигурации и любые операции над ней будут осуществляться через данный механизм.
Загрузить обновлённый конфигурационный файл в кластер с помощью ydb admin cluster config replace:
```
ydb -e grpc://<node.ydb.tech>:2135 cluster config replace -f config.yaml
```
Перезапустить все узлы хранения кластера с помощью процедуры rolling restart.
При наличии секции config.domains_config.security_config в файле config.yaml вынести её на уровень выше — в секцию config.
Удалить из файла config.yaml секции config.blob_storage_config и config.domains_config.
Загрузить обновлённый конфигурационный файл в кластер:
```
ydb -e grpc://<node.ydb.tech>:2135 cluster config replace -f config.yaml
```
Подробнее
После загрузки конфигурации кластер YDB будет переведён в режим автоматического управления конфигурацией State Storage и статической группой с помощью механизма распределённой конфигурации.

Убедиться в успешном завершении миграции можно, проверив версию конфигурации на узлах кластера одним из способов, описанных в статье Проверка версии конфигурации. На всех узлах кластера версия Configuration version должна быть равна v2.

Результат

В результате проделанных действий кластер будет переведён на режим конфигурации V2. Управление единой конфигурацией осуществляется с помощью специальных команд YDB CLI, статическая группа и State Storage управляются системой автоматически.

Была ли статья полезна?

Миграции

На конфигурацию V1