Migration to Configuration V1

This document contains instructions for migrating from configuration V2 to configuration V1.

Initial State

Migration to configuration V1 is only possible if the cluster uses configuration V2. This can be achieved:

• as a result of migration to configuration V2
• during initial deployment of the cluster

You can determine the current configuration version on nodes using several methods described in the article Checking Configuration Version. Before starting the migration, ensure that the cluster is running on configuration V2.

Instructions for Migration to Configuration V1

To migrate the YDB cluster to configuration V1, you need to perform the following steps:

1. Get the current cluster configuration using the ydb admin cluster config fetch command:

   ydb -e grpc://<node.ydb.tech>:2135 admin cluster config fetch --for-v1-migration > config.yaml
   

   More details

   The --for-v1-migration argument specifies that the full cluster configuration will be retrieved, including State Storage and static group configuration parameters.

2. Modify the config.yaml configuration file by changing the self_management_config.enabled parameter value from true to false:

   self_management_config:
     enabled: false
   

   More details

   This section is responsible for managing the distributed configuration mechanism. Setting enabled: false disables this mechanism. Further management of State Storage and static group configuration will be performed manually through the domains_config and blob_storage_config sections respectively in the configuration file (these sections were obtained in the previous step when using the --full flag).

3. Load the updated configuration file into the cluster using ydb admin cluster config replace:

   ydb -e grpc://<node.ydb.tech>:2135 admin cluster config replace -f config.yaml
   

4. Restart all cluster nodes using the rolling restart procedure.

   More details

   After restarting the nodes, the cluster will be switched to manual State Storage and static group management mode, but will still use a unified configuration file delivered through the BSController tablet. Node configuration at startup will still be read from the directory specified in the ydbd --config-dir option and saved there.

5. Get the current cluster configuration using ydb admin cluster config fetch:

   ydb -e grpc://<node.ydb.tech>:2135 admin cluster config fetch > config.yaml
   

   More details

   The obtained configuration will not contain the domains_config and blob_storage_config sections, as they are managed manually and should not be part of the dynamic configuration.

6. Place the obtained config.yaml file (this will be your static configuration V1) in the file system of each cluster node.

7. Restart all cluster nodes using the rolling-restart procedure, specifying the path to the static configuration file through the ydbd --yaml-config option and removing the ydbd --config-dir option:

   Manual

   Using systemd

   When starting manually, add the --yaml-config option to the ydbd server command, without specifying the --config-dir option:

   ydbd server --yaml-config /opt/ydb/cfg/config.yaml
   

   When using systemd, add the --yaml-config option to the ydbd server command in the systemd configuration file, and also remove the --config-dir option:

   ExecStart=/opt/ydb/bin/ydbd server --yaml-config /opt/ydb/config/config.yaml
   

   After updating the systemd file, run the following command to apply the changes:

   sudo systemctl daemon-reload
   

You can verify the successful completion of the migration by checking the configuration version on the cluster nodes using one of the methods described in the article Checking Configuration Version. All cluster nodes should use configuration v1.

Result

As a result of the performed actions, the cluster will be migrated to configuration V1 mode. The configuration consists of two parts: static and dynamic, static group and State Storage management is performed manually.