Add Russian CMS docs YDBDOCS-124 (#2097)

8 files changed, 109 insertions, 10 deletions

diff --git a/ydb/docs/en/core/maintenance/manual/node_restarting.md b/ydb/docs/en/core/maintenance/manual/node_restarting.md
index c66e883d6e..3b743bb52d 100644
--- a/ydb/docs/en/core/maintenance/manual/node_restarting.md
+++ b/ydb/docs/en/core/maintenance/manual/node_restarting.md
@@ -26,9 +26,9 @@ To make sure that the process is stoppable, follow these steps.
     sudo service ydbd start
    ```
 
-## Replacing equipment {#replace_hardware}
+## Replacing equipment {#replace-hardware}
 
-Before replacing equipment, make sure that the YDB process is [stoppable](#restart_process).
+Before replacing equipment, make sure that the {{ ydb-short-name }} process is [stoppable](#restart_process).
 If the replacement is going to take a long time, first move all the VDisks from this node and wait until replication is complete.
 After replication is complete, you can safely shut down the node.
 
diff --git a/ydb/docs/ru/core/administration/upgrade.md b/ydb/docs/ru/core/administration/upgrade.md
index e7625656c6..e3bbe56b89 100644
--- a/ydb/docs/ru/core/administration/upgrade.md
+++ b/ydb/docs/ru/core/administration/upgrade.md
@@ -7,7 +7,7 @@
 Базовым сценарием является обновление исполняемого файла и последовательный рестарт каждого узла:
 
 1. Обновление и рестарт storage узлов;
-1. Обновление и рестар динамических узлов.
+1. Обновление и рестарт динамических узлов.
 
 Процесс остановки и запуска описан на странице [Безопасные рестарт и выключение узлов](../maintenance/manual/node_restarting.md).
 Узлы {{ ydb-short-name }} следует обновлять последовательно по одному, после каждого шага контролировать состояние кластера через [{{ ydb-short-name }} Monitoring](../maintenance/embedded_monitoring/ydb_monitoring.md) - на вкладке `Storage` не должно быть пулов в состоянии `Degraded` (как на примере ниже). В противном случае обновление необходимо остановить.
diff --git a/ydb/docs/ru/core/cluster/index.md b/ydb/docs/ru/core/cluster/index.md
index 82996d7958..5f19cf2118 100644
--- a/ydb/docs/ru/core/cluster/index.md
+++ b/ydb/docs/ru/core/cluster/index.md
@@ -8,3 +8,4 @@
 * [{#T}](../devops/manual/system-views.md).
 * [{#T}](../administration/monitoring.md).
 * [{#T}](../administration/upgrade.md).
+* [{#T}](../maintenance/maintenance-without-outages.md).
diff --git a/ydb/docs/ru/core/cluster/toc_i.yaml b/ydb/docs/ru/core/cluster/toc_i.yaml
index 5e6770c937..1285a09c5e 100644
--- a/ydb/docs/ru/core/cluster/toc_i.yaml
+++ b/ydb/docs/ru/core/cluster/toc_i.yaml
@@ -39,3 +39,5 @@ items:
     href: ../maintenance/manual/dynamic-config-volatile-config.md
   - name: Изменение конфигураций через CMS
     href: ../maintenance/manual/cms.md
+- name: Обслуживание кластера без потери доступности
+  href: ../maintenance/maintenance-without-outages.md
diff --git a/ydb/docs/ru/core/concepts/cluster/_includes/distributed_storage/distributed_storage_interface.md b/ydb/docs/ru/core/concepts/cluster/_includes/distributed_storage/distributed_storage_interface.md
index bdd8301bf6..c2a8b87e9e 100644
--- a/ydb/docs/ru/core/concepts/cluster/_includes/distributed_storage/distributed_storage_interface.md
+++ b/ydb/docs/ru/core/concepts/cluster/_includes/distributed_storage/distributed_storage_interface.md
@@ -21,7 +21,7 @@
 
 При чтении указывается идентификатор блоба, который может быть произвольным, но желательно ранее записанным.
 
-### Группы
+### Группы {#storage-groups}
 
 Запись блобов производится в логическую сущность, называемую *группой*. На каждом узле для каждой группы, в которую осуществляется запись, создается специальный актор, который называется DS proxy. Этот актор отвечает за выполнение всех операций, связанных с группой. Создание этого актора производится автоматически через сервис NodeWarden, о котором речь пойдет ниже.
 
diff --git a/ydb/docs/ru/core/maintenance/maintenance-without-outages.md b/ydb/docs/ru/core/maintenance/maintenance-without-outages.md
new file mode 100644
index 0000000000..cbc8a99d7d
--- /dev/null
+++ b/ydb/docs/ru/core/maintenance/maintenance-without-outages.md
@@ -0,0 +1,98 @@
+# Обслуживание кластера без потери доступности
+
+Периодически кластер {{ ydb-short-name }} необходимо обслуживать, например, обновлять его версию или заменять сломавшиеся диски. Работы по обслуживанию могут привести к недоступности кластера или имеющихся баз данных из-за:
+- Превышения модели отказа затронутых [групп хранения](../concepts/databases.md#storage-groups).
+- Превышения модели отказа [State Storage](../deploy/configuration/config.md#domains-state).
+- Недостатка вычислительных ресурсов вследствие остановки слишком большого количества [динамических узлов](../concepts/cluster/common_scheme_ydb.md#nodes).
+
+Для избежания таких ситуаций в {{ ydb-short-name }} есть системная [таблетка](../concepts/cluster/common_scheme_ydb.md#tablets), которая следит за состоянием кластера — *Cluster Management System (CMS)*. CMS позволяет ответить на вопрос можно ли безопасно вывести в обслуживание узел {{ ydb-short-name }} или хост, на котором работают узлы {{ ydb-short-name }}. Для этого необходимо создать [задачу обслуживания](#maintenance-task) в CMS и указать в ней взятие эксклюзивных блокировок на узлы или хосты, которые будут задействованы в обслуживании. Компоненты кластера, на которые взяты блокировки, считаются недоступными с точки зрения CMS, и их можно безопасно обслуживать. CMS [проверит](#check-task-actions-algorithm) текущее состояние кластера и возьмет блокировки, только если работы по обслуживанию соответствуют ограничениям [режима доступности](#availability-mode) и [лимитам недоступных узлов](#unavailable-node-limits).
+
+{% note warning "Поломки во время проведения работ" %}
+
+Во время проведения работ по обслуживанию, безопасность которых гарантирована CMS, в кластере могут произойти поломки, не связанные с этими работами. Если в результате поломок доступность кластера оказалась под угрозой, то завершение работ в срочном порядке может помочь снизить риск потери доступности.
+
+{% endnote %}
+
+## Задача обслуживания {#maintenance-task}
+
+*Задача обслуживания* представляет собой набор *действий*, которые пользователь просит выполнить CMS для возможности проведения безопасного обслуживания.
+
+Поддерживаемые действия:
+- Взятие эксклюзивной блокировки на компонент кластера — узел или хост.
+
+В задаче действия делятся на группы. Действия из одной группы выполняются атомарно. На данный момент группы могут состоять только из одного действия.
+
+Если в момент запроса действие выполнить нельзя, CMS сообщает причину и время, когда стоит *обновить* задачу, и переводит действие в состояние *ожидания (pending)*. При обновлении задачи CMS повторно пытается выполнить ожидающие действия.
+
+У *выполненных (performed)* действий есть дедлайн, после которого они считаются *завершенными (completed)* и прекращают иметь эффект на кластер. Например, снимается эксклюзивная блокировка. Действие можно досрочно завершить.
+
+{% note info "Затянувшиеся работы" %}
+
+Если работы по обслуживанию кластера продолжают проводиться после завершения действий, которые были выполнены для безопасного проведения этих работ, то это расценивается как поломка в кластере.
+
+{% endnote %}
+
+Завершенные действия автоматически удаляются из задачи.
+
+### Режим доступности {#availability-mode}
+
+В задаче обслуживания необходимо указать режим доступности кластера, который должен соблюдаться при проверке возможности выполнения действий. Поддерживаются следующие режимы:
+- **Strong** — режим, минимизирующий риск потери доступности.
+    - Допускается не более одного недоступного [VDisk](../concepts/cluster/distributed_storage.md#storage-groups) в каждой из затрагиваемых групп хранения.
+    - Допускается не более одного недоступного кольца State Storage.
+- **Weak** — режим, не позволяющий превысить модель отказа.
+    - Допускается не более двух недоступных VDisk-ов для затрагиваемых групп хранения со схемой [block-4-2](../administration/production-storage-config.md#reliability).
+    - Допускается не более четырех недоступных VDisk-ов, три из которых должны находиться в одном датацентре, для затрагиваемых групп хранения со схемой [mirror-3-dc](../administration/production-storage-config.md#reliability). 
+    - Допускается не более `(nto_select - 1) / 2` недоступных колец State Storage.
+- **Force** — принудительный режим, модель отказа игнорируется. Не рекомендуется к использованию.
+
+### Приоритет {#priority}
+
+У задачи обслуживания можно указать приоритет. Меньшее значение означает более высокий приоритет.
+
+Действия задачи не могут быть выполнены до завершения всех конфликтующих действий из задач с более высоким приоритетом. Задачи с одинаковым приоритетом не имеют преимущества друг перед другом.
+
+## Лимиты недоступных узлов {#unavailable-node-limits}
+
+В конфигурации CMS можно настроить лимиты на количество недоступных узлов для базы данных (тенанта) или для кластера в целом. Поддерживаются относительные и абсолютные лимиты.
+
+По умолчанию допускается не более 10% недоступных узлов для каждой базы данных и кластера в целом.
+
+## Алгоритм проверки действий задачи {#check-task-actions-algorithm}
+
+Для того, чтобы проверить можно ли выполнить действия задачи обслуживания, CMS последовательно идет по каждой группе действий в задаче и проверяет действие из группы:
+- Если объектом действия является хост, то CMS проверяет можно ли выполнить действие со всеми узлами, запущенными на хосте. 
+- Если объектом действия является узел, то CMS проверяет:
+    - Есть ли блокировка на данном узле.
+    - Можно ли взять блокировку на данный узел в соответствии с лимитами недоступных узлов.
+    - Можно ли взять блокировки на все VDisk-и данного узла в соответствии с режимом доступности.
+    - Можно ли взять блокировку на кольцо State Storage данного узла в соответствии с режимом доступности.
+    - Можно ли взять блокировку на данный узел в соответствии с лимитом недоступных узлов, на которых могут запускаться кластерные системные таблетки.
+    
+Если проверки прошли успешно, то действие можно выполнить и на проверенные узлы берется временная блокировка. После чего CMS рассматривает следующую группу действий. Временные блокировки позволяют понять, конфликтуют ли запрошенные в разных группах действия между собой. После полного завершения проверки временные блокировки снимаются.
+
+## Примеры {#examples}
+
+Утилита [ydbops](https://github.com/ydb-platform/ydbops) использует CMS для проведения обслуживания кластера без потери доступности. Также CMS можно использовать напрямую через [gRPC API](https://github.com/ydb-platform/ydb/blob/main/ydb/public/api/grpc/draft/ydb_maintenance_v1.proto).
+
+### Вывести узел для обслуживания {#node-maintenance}
+
+{% note info "Функциональность в разработке" %}
+
+Функциональность ожидается в ближайших версиях ydbops.
+
+{% endnote %}
+
+Для выведения узла для обслуживания можно воспользоваться командой:
+```
+$ ydbops node maintenance --host <node_fqdn>
+```
+При выполнении этой команды ydbops возьмет эксклюзивную блокировку на узел в CMS.
+
+### Rolling restart {#rolling-restart}
+
+Чтобы выполнить rolling restart всего кластера можно воспользоваться командой:
+```
+$ ydbops restart --endpoint grpc://<cluster-fqdn> --availability-mode strong
+```
+Утилита ydbops автоматически создаст задачу обслуживания на рестарт всего кластера, используя указанный режим доступности. По ходу продвижения ydbops будет обновлять задачу обслуживания и получать эксклюзивные блокировки на узлы в CMS, пока все узлы не будут перезапущены.
diff --git a/ydb/docs/ru/core/maintenance/manual/node_restarting.md b/ydb/docs/ru/core/maintenance/manual/node_restarting.md
index 35bf492b49..fd871c0e25 100644
--- a/ydb/docs/ru/core/maintenance/manual/node_restarting.md
+++ b/ydb/docs/ru/core/maintenance/manual/node_restarting.md
@@ -1,5 +1,3 @@
-# Безопасный рестарт и выключение узлов
-
 ## Остановка/рестарт процесса ydb на узле {#restart_process}
 
 Чтобы убедиться, что процесс можно остановить, надо выполнить следующие шаги.
@@ -26,9 +24,9 @@
     sudo service ydbd start
     ```
 
-## Замена оборудования {#replace_hardware}
+## Замена оборудования {#replace-hardware}
 
-Перед заменой нужно убедиться, что процесс ydb можно [остановить](#restart_process).
+Перед заменой нужно убедиться, что процесс {{ ydb-short-name }} можно [остановить](#restart_process).
 При длительном отсутствии стоит перед этим перевезти все VDisk'и с данного узла и дождаться окончания репликации.
 После окончания репликации узел можно безопасно выключать.
 
diff --git a/ydb/public/api/protos/draft/ydb_maintenance.proto b/ydb/public/api/protos/draft/ydb_maintenance.proto
index 7a5e1cdc48..d749ab6709 100644
--- a/ydb/public/api/protos/draft/ydb_maintenance.proto
+++ b/ydb/public/api/protos/draft/ydb_maintenance.proto
@@ -65,13 +65,13 @@ enum AvailabilityMode {
     AVAILABILITY_MODE_UNSPECIFIED = 0;
 
     // In this mode allowed:
-    // - at most 1 unavailable disk in each storage group;
+    // - at most 1 unavailable disk in each affected storage group;
     // - at most 1 unavailable state storage ring.
     // For nodes tenant and cluster policies are followed.
     AVAILABILITY_MODE_STRONG = 1;
 
     // In this mode:
-    // - total number of an unavailable disks in each storage group
+    // - total number of an unavailable disks in each affected storage group
     //   shouldn't exceed number of parity parts in that group;
     // - it is allowed to disable (n_to_select - 1) / 2 state storage rings.
     // Nodes are handled as in strong mode.