Improve migration_to_v2 instruction (#42210)

2 files changed, 58 insertions, 32 deletions

diff --git a/ydb/docs/en/core/devops/configuration-management/migration/migration-to-v2.md b/ydb/docs/en/core/devops/configuration-management/migration/migration-to-v2.md
index fe6ea0b7dec..3df59325bec 100644
--- a/ydb/docs/en/core/devops/configuration-management/migration/migration-to-v2.md
+++ b/ydb/docs/en/core/devops/configuration-management/migration/migration-to-v2.md
@@ -45,7 +45,7 @@ To migrate the {{ ydb-short-name }} cluster to configuration V2, you need to per
     No config returned.
     ```
 
-    If a file is found, you should use it and skip the next step of this instruction.
+    If a file is found, you should use it and skip the next step of this instruction. Before proceeding, make sure that the file contains the settings that were stored in the static configuration file on storage nodes in configuration V1.
 
 2. If there is no dynamic configuration file in the cluster, run the dynamic configuration file generation command [ydb admin cluster config generate](../../../reference/ydb-cli/commands/configuration/cluster/generate.md). The file will be generated based on the static configuration file located on the cluster nodes.
 
@@ -53,7 +53,20 @@ To migrate the {{ ydb-short-name }} cluster to configuration V2, you need to per
     ydb -e grpc://<node.ydb.tech>:2135 admin cluster config generate > config.yaml
     ```
 
-3. Add the following field to the `config.yaml` file obtained in step 1 or 2:
+3. Check that the `config.yaml` file obtained in step 1 or 2 contains the storage node settings from the current static configuration V1. If the file was obtained from an existing dynamic configuration, these settings may be missing because in V1 dynamic configuration might not contain storage node parameters.
+
+    The goal of this step is to get a single combined configuration file that contains both parameters from the dynamic configuration and settings from the static configuration.
+
+    Move all sections and parameters that describe storage nodes, disks, State Storage, static group, and channel profiles from the static configuration file to the `config` section of the `config.yaml` file. In particular, check for the following sections and parameters if they are set in the static configuration V1:
+
+    - `hosts`;
+    - `host_configs`;
+    - `domains_config`;
+    - `blob_storage_config`;
+    - `channel_profile_config`;
+    - other related storage configuration parameters, such as `static_erasure`.
+
+4. Add the following field to the checked and updated `config.yaml` file:
 
     ```yaml
     feature_flags:
@@ -67,9 +80,9 @@ To migrate the {{ ydb-short-name }} cluster to configuration V2, you need to per
 
     {% endcut %}
 
-4. Place the `config.yaml` file on all cluster nodes, replacing the previous configuration file with it.
+5. Place the `config.yaml` file on all cluster nodes, replacing the previous configuration file with it.
 
-5. Create a directory for the {{ ydb-short-name }} 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](../../../reference/ydb-cli/commands/configuration/node/init.md) command on each node. In the `--from-config` parameter, specify the path to the `config.yaml` file placed on the nodes earlier.
+6. Create a directory for the {{ ydb-short-name }} 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](../../../reference/ydb-cli/commands/configuration/node/init.md) command on each node. In the `--from-config` parameter, specify the path to the `config.yaml` file placed on the nodes earlier.
 
     ```bash
     sudo mkdir -p /opt/ydb/config-dir
@@ -83,7 +96,7 @@ To migrate the {{ ydb-short-name }} cluster to configuration V2, you need to per
 
     {% endcut %}
 
-6. Restart all cluster nodes using the [rolling-restart](../../../maintenance/manual/node_restarting.md) 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.
+7. Restart all cluster nodes using the [rolling-restart](../../../maintenance/manual/node_restarting.md) 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.
 
     {% list tabs group=manual-systemd %}
 
@@ -111,10 +124,10 @@ To migrate the {{ ydb-short-name }} cluster to configuration V2, you need to per
 
     {% endlist %}
 
-7. Load the previously obtained configuration file `config.yaml` into the system using the [ydb admin cluster config replace](../../../reference/ydb-cli/commands/configuration/cluster/replace.md) command:
+8. Load the previously obtained configuration file `config.yaml` into the system using the [ydb admin cluster config replace](../../../reference/ydb-cli/commands/configuration/cluster/replace.md) command:
 
     ```bash
-    ydb -e grpc://<node.ydb.tech>:2135 cluster config replace -f config.yaml
+    ydb -e grpc://<node.ydb.tech>:2135 admin 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`.
@@ -125,7 +138,7 @@ To migrate the {{ ydb-short-name }} cluster to configuration V2, you need to per
 
     {% endcut %}
 
-8. Get the current cluster configuration using [ydb admin cluster config fetch](../../../reference/ydb-cli/commands/configuration/cluster/fetch.md):
+9. Get the current cluster configuration using [ydb admin cluster config fetch](../../../reference/ydb-cli/commands/configuration/cluster/fetch.md):
 
     ```bash
     ydb -e grpc://<node.ydb.tech>:2135 admin cluster config fetch > config.yaml
@@ -133,7 +146,7 @@ To migrate the {{ ydb-short-name }} cluster to configuration V2, you need to per
 
     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.
 
-9. Add the following block to `config.yaml` in the `config` section:
+10. Add the following block to `config.yaml` in the `config` section:
 
     ```yaml
     self_management_config:
@@ -146,22 +159,22 @@ To migrate the {{ ydb-short-name }} cluster to configuration V2, you need to per
 
     {% endcut %}
 
-10. Load the updated configuration file into the cluster using [ydb admin cluster config replace](../../../reference/ydb-cli/commands/configuration/cluster/replace.md):
+11. Load the updated configuration file into the cluster using [ydb admin cluster config replace](../../../reference/ydb-cli/commands/configuration/cluster/replace.md):
 
     ```bash
-    ydb -e grpc://<node.ydb.tech>:2135 cluster config replace -f config.yaml
+    ydb -e grpc://<node.ydb.tech>:2135 admin cluster config replace -f config.yaml
     ```
 
-11. Restart all [storage nodes](../../../concepts/glossary.md#storage-node) of the cluster using the [rolling restart](../../../reference/ydbops/rolling-restart-scenario.md) procedure.
+12. Restart all [storage nodes](../../../concepts/glossary.md#storage-node) of the cluster using the [rolling restart](../../../reference/ydbops/rolling-restart-scenario.md) procedure.
 
-12. If there is a `config.domains_config.security_config` section in the `config.yaml` file, move it one level up — to the `config` section.
+13. If there is a `config.domains_config.security_config` section in the `config.yaml` file, move it one level up — to the `config` section.
 
-13. Remove the `config.blob_storage_config` and `config.domains_config` sections from the `config.yaml` file.
+14. Remove the `config.blob_storage_config` and `config.domains_config` sections from the `config.yaml` file.
 
-14. Load the updated configuration file into the cluster:
+15. Load the updated configuration file into the cluster:
 
     ```bash
-    ydb -e grpc://<node.ydb.tech>:2135 cluster config replace -f config.yaml
+    ydb -e grpc://<node.ydb.tech>:2135 admin cluster config replace -f config.yaml
     ```
 
     {% cut "More details" %}
diff --git a/ydb/docs/ru/core/devops/configuration-management/migration/migration-to-v2.md b/ydb/docs/ru/core/devops/configuration-management/migration/migration-to-v2.md
index b052a743bb8..2441f749822 100644
--- a/ydb/docs/ru/core/devops/configuration-management/migration/migration-to-v2.md
+++ b/ydb/docs/ru/core/devops/configuration-management/migration/migration-to-v2.md
@@ -45,7 +45,7 @@
     No config returned.
     ```
 
-    Если файл найден, следует использовать его и пропустить следующий шаг данной инструкции.
+    Если файл найден, следует использовать его и пропустить следующий шаг данной инструкции. Перед дальнейшими шагами обязательно проверьте, что найденный файл содержит настройки, которые в конфигурации V1 находились в статическом конфигурационном файле на узлах хранения.
 
 2. В случае отсутствия файла динамической конфигурации в кластере выполнить команду генерации файла динамической конфигурации [ydb admin cluster config generate](../../../reference/ydb-cli/commands/configuration/cluster/generate.md). Файл будет сгенерирован на основе файла статической конфигурации, расположенного на узлах кластера.
 
@@ -53,7 +53,20 @@
     ydb -e grpc://<node.ydb.tech>:2135 admin cluster config generate > config.yaml
     ```
 
-3. Добавить в полученный на шаге 1 или 2 файл `config.yaml` следующее поле:
+3. Проверить, что полученный на шаге 1 или 2 файл `config.yaml` содержит настройки узлов хранения из актуальной статической конфигурации V1. Если файл был получен из существующей динамической конфигурации, эти настройки могут отсутствовать, так как в V1 динамическая конфигурация могла не содержать параметры узлов хранения.
+
+    Цель этого шага — получить единый объединенный конфигурационный файл, который содержит как параметры из динамической конфигурации, так и настройки из статической конфигурации.
+
+    Перенесите из статического конфигурационного файла в секцию `config` файла `config.yaml` все секции и параметры, которые описывают узлы хранения, диски, State Storage, статическую группу и профили каналов. В том числе проверьте наличие следующих секций и параметров, если они заданы в статической конфигурации V1:
+
+    - `hosts`;
+    - `host_configs`;
+    - `domains_config`;
+    - `blob_storage_config`;
+    - `channel_profile_config`;
+    - другие связанные параметры storage-конфигурации, например `static_erasure`.
+
+4. Добавить в проверенный и дополненный файл `config.yaml` следующее поле:
 
     ```yaml
     feature_flags:
@@ -67,9 +80,9 @@
 
     {% endcut %}
 
-4. Разместить файл `config.yaml` на всех узлах кластера, заменив им предыдущий файл конфигурации.
+5. Разместить файл `config.yaml` на всех узлах кластера, заменив им предыдущий файл конфигурации.
 
-5. Создать директорию для работы узла {{ ydb-short-name }} с конфигурацией на каждом из узлов. В случае запуска нескольких узлов кластера на одном хосте создайте отдельные директории под каждый узел. Инициализируйте директорию, выполнив команду [ydb admin node config init](../../../reference/ydb-cli/commands/configuration/node/init.md) на каждом из узлов. В параметре `--from-config` укажите путь к файлу `config.yaml`, размещённому на узлах ранее.
+6. Создать директорию для работы узла {{ ydb-short-name }} с конфигурацией на каждом из узлов. В случае запуска нескольких узлов кластера на одном хосте создайте отдельные директории под каждый узел. Инициализируйте директорию, выполнив команду [ydb admin node config init](../../../reference/ydb-cli/commands/configuration/node/init.md) на каждом из узлов. В параметре `--from-config` укажите путь к файлу `config.yaml`, размещённому на узлах ранее.
 
     ```bash
     sudo mkdir -p /opt/ydb/config-dir
@@ -83,7 +96,7 @@
 
     {% endcut %}
 
-6. Перезапустить все узлы кластера с помощью процедуры [rolling-restart](../../../maintenance/manual/node_restarting.md), добавив опцию `ydbd --config-dir` при запуске узла с указанием пути до директории, а также убрав опцию `ydbd --yaml-config`.
+7. Перезапустить все узлы кластера с помощью процедуры [rolling-restart](../../../maintenance/manual/node_restarting.md), добавив опцию `ydbd --config-dir` при запуске узла с указанием пути до директории, а также убрав опцию `ydbd --yaml-config`.
 
     {% list tabs group=manual-systemd %}
 
@@ -111,10 +124,10 @@
 
     {% endlist %}
 
-7. Загрузить полученный ранее конфигурационный файл `config.yaml` в систему с помощью команды [ydb admin cluster config replace](../../../reference/ydb-cli/commands/configuration/cluster/replace.md):
+8. Загрузить полученный ранее конфигурационный файл `config.yaml` в систему с помощью команды [ydb admin cluster config replace](../../../reference/ydb-cli/commands/configuration/cluster/replace.md):
 
     ```bash
-    ydb -e grpc://<node.ydb.tech>:2135 cluster config replace -f config.yaml
+    ydb -e grpc://<node.ydb.tech>:2135 admin cluster config replace -f config.yaml
     ```
 
     Команда запросит подтверждение на выполнение операции `This command may damage your cluster, do you want to continue? [y/N]`, в ответ на этот запрос необходимо согласиться и ввести `y`.
@@ -125,7 +138,7 @@
 
     {% endcut %}
 
-8. Получить текущую конфигурацию кластера с помощью [ydb admin cluster config fetch](../../../reference/ydb-cli/commands/configuration/cluster/fetch.md):
+9. Получить текущую конфигурацию кластера с помощью [ydb admin cluster config fetch](../../../reference/ydb-cli/commands/configuration/cluster/fetch.md):
 
     ```bash
     ydb -e grpc://<node.ydb.tech>:2135 admin cluster config fetch > config.yaml
@@ -133,7 +146,7 @@
 
     Файл `config.yaml` должен совпадать с конфигурационными файлами, разложенными по узлам кластера, за исключением поля `metadata.version`, которое должно быть больше на единицу по сравнению с версией на узлах кластера.
 
-9. Добавить в `config.yaml` в разделе `config` следующий блок:
+10. Добавить в `config.yaml` в разделе `config` следующий блок:
 
     ```yaml
     self_management_config:
@@ -146,22 +159,22 @@
 
     {% endcut %}
 
-10. Загрузить обновлённый конфигурационный файл в кластер с помощью [ydb admin cluster config replace](../../../reference/ydb-cli/commands/configuration/cluster/replace.md):
+11. Загрузить обновлённый конфигурационный файл в кластер с помощью [ydb admin cluster config replace](../../../reference/ydb-cli/commands/configuration/cluster/replace.md):
 
     ```bash
-    ydb -e grpc://<node.ydb.tech>:2135 cluster config replace -f config.yaml
+    ydb -e grpc://<node.ydb.tech>:2135 admin cluster config replace -f config.yaml
     ```
 
-11. Перезапустить все [узлы хранения](../../../concepts/glossary.md#storage-node) кластера с помощью процедуры [rolling restart](../../../reference/ydbops/rolling-restart-scenario.md).
+12. Перезапустить все [узлы хранения](../../../concepts/glossary.md#storage-node) кластера с помощью процедуры [rolling restart](../../../reference/ydbops/rolling-restart-scenario.md).
 
-12. При наличии секции `config.domains_config.security_config` в файле `config.yaml` вынести её на уровень выше — в секцию `config`.
+13. При наличии секции `config.domains_config.security_config` в файле `config.yaml` вынести её на уровень выше — в секцию `config`.
 
-13. Удалить из файла `config.yaml` секции `config.blob_storage_config` и `config.domains_config`.
+14. Удалить из файла `config.yaml` секции `config.blob_storage_config` и `config.domains_config`.
 
-14. Загрузить обновлённый конфигурационный файл в кластер:
+15. Загрузить обновлённый конфигурационный файл в кластер:
 
     ```bash
-    ydb -e grpc://<node.ydb.tech>:2135 cluster config replace -f config.yaml
+    ydb -e grpc://<node.ydb.tech>:2135 admin cluster config replace -f config.yaml
     ```
 
     {% cut "Подробнее" %}