Comparing YDB Cluster Configurations: V1 and V2
In YDB, there are two main approaches to cluster configuration management: V1 and V2. Starting from YDB version 25.1, configuration V2 is supported, which unifies YDB cluster management, allows working with configuration entirely through YDB CLI, and also automates the most complex aspects of configuration (managing static group and State Storage).
Tip
New YDB clusters are recommended to be deployed using configuration V2. If a cluster was deployed using configuration V1, it will still use it after updating to YDB version 25.1 or higher. After such an update, it is recommended to plan and perform migration to V2, because support for V1 will be discontinued in future versions of YDB. For the instructions on how to determine the configuration version of the cluster, see Checking Configuration Version.
This article describes the key differences between these two approaches.
| Characteristic | Configuration V1 | Configuration V2 |
|---|---|---|
| Configuration structure | Separate: static and dynamic. | Unified configuration. |
| File management | Static: manual file placement on each node. Dynamic: centralized upload via CLI. |
Unified: centralized upload via CLI, automatic delivery to all nodes. |
| Delivery and application mechanism | Static: read and applied from a local file at startup. Dynamic: through Console tablet. |
Fully automatic via the distributed configuration mechanism. |
| State Storage and static group management | Manual: mandatory domains_config and blob_storage_config sections in static configuration. |
Automatic: managed by the distributed configuration system. |
| Recommended for YDB versions | All versions before 25.1.1. | Version 25.1 and above. |
Configuration V1
Configuration V1 of a YDB cluster consists of two parts:
- Static configuration: manages key node parameters, including State Storage and static group configuration (
domains_configandblob_storage_configsections respectively). Requires manual placement of the same configuration file on each cluster node. The path to the configuration is specified when starting the node using the--yaml-configoption. - Dynamic configuration: manages other cluster parameters. Loaded centrally using the
ydb admin config replacecommand and distributed to database nodes.
If your cluster is running on configuration V1, it is recommended to perform migration to configuration V2.
Configuration V2
Starting from YDB version 25.1, configuration V2 is supported. Key features:
- Unified configuration file: the entire cluster configuration is stored and managed as a single entity.
- Centralized management: configuration is loaded to the cluster using the
ydb admin cluster config replacecommand and automatically delivered to all nodes by the YDB cluster itself through the distributed configuration mechanism. - Early validation: the configuration file is validated before delivering it to cluster nodes, not when restarting the server process.
- Automatic State Storage and static group management: V2 supports automatic configuration, which allows skipping these sections in the configuration file.
- Storage on nodes: the current configuration is automatically saved by each node in a special directory (specified by the
--config-diroption when startingydbd) and used during subsequent restarts.
Using configuration V2 is recommended for all YDB clusters version 25.1 and above.