Migration to Configuration V2

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

In configuration V1, there are two different mechanisms for applying configuration files:

static configuration manages storage nodes of the YDB cluster and requires manual placement of files on each cluster node;
dynamic configuration manages database nodes of the YDB cluster and is loaded into the cluster centrally using YDB CLI commands.

In configuration V2, this process is unified: a single configuration file is loaded into the system through YDB CLI commands, automatically delivered to all cluster nodes.

The State Storage and static group components of the YDB cluster are key to the cluster's correct operation. When working with configuration V1, these components are configured manually by specifying the domains_config and blob_storage_config sections in the configuration file.
In configuration V2, automatic configuration of these components is possible without specifying the corresponding sections in the configuration file.

Initial State

Migration to configuration V2 can be performed if the following conditions are met:

The YDB cluster has been updated to version 25.1 and higher.
The YDB cluster is configured with a configuration V1 file config.yaml, located in the node file system and connected through the ydbd --yaml-config argument.
The cluster configuration file contains the domains_config and blob_storage_config sections for configuring State Storage and static group respectively.

Checking the Current Configuration Version

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

You should continue following this instruction only if the nodes are running on configuration version V1. If all nodes already have version V2 enabled, migration is not required.

Instructions for Migration to Configuration V2

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

Check for the presence of a dynamic configuration file in the cluster. To do this, run the ydb admin cluster config fetch command:
```
ydb -e grpc://<node.ydb.tech>:2135 admin cluster config fetch > config.yaml
```
If no such configuration exists in the cluster, the command will output the message:
```
No config returned.
```
If a file is found, you should use it and skip the next step of this instruction.
If there is no dynamic configuration file in the cluster, run the dynamic configuration file generation command ydb admin cluster config generate. The file will be generated based on the static configuration file located on the cluster nodes.
```
ydb -e grpc://<node.ydb.tech>:2135 admin cluster config generate > config.yaml
```
Add the following field to the config.yaml file obtained in step 1 or 2:
```
feature_flags:
    ...
    switch_to_config_v2: true
```
More details
Enabling this flag means that the DS Controller tablet, not the Console tablet, is now responsible for configuration storage and operations. This switches the main cluster configuration management mechanism.
Place the config.yaml file on all cluster nodes, replacing the previous configuration file with it.
Create a directory for the YDB node to work with configuration on each node. If running multiple cluster nodes on one host, create separate directories for each node. Initialize the directory by running the ydb admin node config init command on each node. In the --from-config parameter, specify the path to the config.yaml file placed on the nodes earlier.
```
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
```
More details
In the future, the system will independently save the current configuration in the specified directories.
Restart all cluster nodes using the rolling-restart procedure, adding the ydbd --config-dir option when starting the node with the path to the directory specified, and removing the ydbd --yaml-config option.
Manual

Using systemd
When starting manually, add the --config-dir option to the ydbd server command, without specifying the --yaml-config option:
```
ydbd server --config-dir /opt/ydb/config-dir
```
When using systemd, add the --config-dir option to the ydbd server command in the systemd configuration file, and also remove the --yaml-config option:
```
ExecStart=/opt/ydb/bin/ydbd server --config-dir /opt/ydb/config-dir
```
After updating the systemd file, run the following command to apply the changes:
```
sudo systemctl daemon-reload
```
Load the previously obtained configuration file config.yaml into the system using the ydb admin cluster config replace command:
```
ydb -e grpc://<node.ydb.tech>:2135 cluster config replace -f config.yaml
```
The command will request confirmation to perform the operation This command may damage your cluster, do you want to continue? [y/N], in response to this request you need to agree and enter y.

More details
After executing the command, the configuration file will be loaded into the internal storage of the DS Controller tablet and saved in the directories specified in the --config-dir option on each node. From this moment, any configuration change on existing nodes is performed using special commands of the YDB CLI. Also, when starting a node, the current configuration will be automatically loaded from the configuration directory.
Get the current cluster configuration using ydb admin cluster config fetch:
```
ydb -e grpc://<node.ydb.tech>:2135 admin cluster config fetch > config.yaml
```
The config.yaml file should match the configuration files distributed across the cluster nodes, except for the metadata.version field, which should be one unit higher compared to the version on the cluster nodes.
Add the following block to config.yaml in the config section:
```
self_management_config:
  enabled: true
```
More details
This section is responsible for enabling the distributed configuration mechanism in the cluster. Configuration storage and any operations on it will be performed through this mechanism.
Load the updated configuration file into the cluster using ydb admin cluster config replace:
```
ydb -e grpc://<node.ydb.tech>:2135 cluster config replace -f config.yaml
```
Restart all storage nodes of the cluster using the rolling restart procedure.
If there is a config.domains_config.security_config section in the config.yaml file, move it one level up — to the config section.
Remove the config.blob_storage_config and config.domains_config sections from the config.yaml file.
Load the updated configuration file into the cluster:
```
ydb -e grpc://<node.ydb.tech>:2135 cluster config replace -f config.yaml
```
More details
After loading the configuration, the YDB cluster will be switched to automatic configuration management mode for State Storage and static group using the distributed configuration mechanism.

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. On all cluster nodes, the Configuration version should be equal to v2.

Result

As a result of the performed actions, the cluster will be migrated to configuration V2 mode. Unified configuration management is performed using special commands of the YDB CLI, static group and State Storage are managed automatically by the system.

Was the article helpful?

Migration

Migration to configuration V1