Merge da1f81e into 1e8be6b

ydb-platform · Dec 23, 2024 · 54f22be · 54f22be
2 parents 1e8be6b + da1f81e
commit 54f22be
Show file tree

Hide file tree

Showing 4 changed files with 184 additions and 65 deletions.
diff --git a/ydb/docs/build.sh b/ydb/docs/build.sh
@@ -36,10 +36,10 @@ echo "Output directory: $DIR"
 
 if ! yfm -i . -o $DIR --allowHTML  --apply-presets; then
   echo
-  echo "================================"
-  echo "YFM build completed with ERRORS!"
-  echo "================================"
-  echo "It may be necessary to use the latest version of npm. Run the command `nvm use v22.9.0` to update it."
+  echo '================================'
+  echo 'YFM build completed with ERRORS!'
+  echo '================================'
+  echo 'It may be necessary to use the latest version of npm. Run the command `nvm use v22.9.0` to update it.'
   exit 1
 fi
 

diff --git a/ydb/docs/ru/core/maintenance/manual/dynamic-config.md b/ydb/docs/ru/core/maintenance/manual/dynamic-config.md
@@ -1,19 +1,54 @@
-## Динамическая конфигурация кластера
+# Динамическая конфигурация кластера
 
 Динамическая конфигурация позволяет запускать динамические [узлы](../../concepts/glossary.md#node), сконфигурировав их централизованно, без необходимости раскладывать файлы по узлам вручную. {{ ydb-short-name }} выступает в роли системы управления конфигурациями, предоставляя инструменты для надёжного хранения, версионирования и доставки конфигурации, а так же [DSL (Domain Specific Language)](./dynamic-config-selectors.md) для переопределения её частей для определённых групп узлов. Конфигурация представляет собой YAML документ. Он является расширенной версией статической конфигурации:
 
 * описание конфигурации вынесено в поле `config`;
 * добавлено поле `metadata`, необходимое для валидации и версионирования;
 * добавлены поля `allowed_labels` и `selector_config` для гранулярного переопределения настроек.
 
-Эта конфигурация загружается в кластер, где надёжно сохраняется и доставляется до каждого динамического узла при его старте. [Определенные настройки](#dynamic-kinds) обновляются на лету, без перезапуска узлов. С помощью динамической конфигурации можно централизованно решить следующие задачи:
+Эта конфигурация загружается в кластер, где надёжно сохраняется и доставляется до каждого динамического узла при его старте. [Некоторые настройки](#dynamic-kinds) обновляются на лету, без перезапуска узлов. С помощью динамической конфигурации можно централизованно решить следующие задачи:
 
-* переключение настроек журналирования компонентов как для всего кластера, так и для отдельных групп узлов;
-* включать экспериментальную функциональность (feature flags) на отдельных базах;
-* изменить настройки акторной системы на отдельно узле или на групе узлов;
-* и т.д.
+* переключать настройки журналирования компонентов как для всего кластера, так и для отдельных баз данных или групп узлов;
+* включать экспериментальную функциональность (feature flags) на отдельных базах данных;
+* изменять настройки акторной системы на конкретной базе данных, отдельном узле или на группе узлов.
 
-### Примеры конфигурации {#example}
+## Подготовка к использованию динамической конфигурации {#preparation}
+
+Перед началом использования динамической конфигурации в кластере необходимо провести подготовительные работы:
+
+1. Включите в кластере [авторизацию узлов баз данных](../../reference/configuration/node_authorization.md) при их регистрации.
+
+1. Если ранее в кластере использовалось [управление конфигурацией через CMS](cms.md), то выгрузите существующие настройки в формате YAML. Для этого выполните следующую команду:
+
+    ```bash
+    ./ydbd -s grpcs://<node1.ydb.tech>:2135 --ca-file ca.crt --token-file ydbd-token \
+         admin console configs dump-yaml > dynconfig.yaml
+    ```
+
+    Предварительно необходимо получить токен аутентификации с помощью команды `ydb auth get-token`, по аналогии с [процедурой инициализации кластера](../../devops/manual/initial-deployment.md#initialize-cluster).
+
+1. Сформируйте первоначальный файл динамической конфигурации:
+
+   * При наличии ранее выполненных через CMS настроек (экспортированных на предыдущем шаге) за основу берется полученный на предыдущем шаге файл, в котором требуется:
+      * добавить секцию `metadata` по образцу из [примера конфигурации](#example);
+      * в секцию `config` добавить параметр `yaml_config_enabled: true`.
+   * При отсутствии ранее выполненных через CMS настроек используется [минимальное наполнение](#example) файла динамической конфигурации.
+   * Если в кластере используется шифрование [интерконнекта акторной системы](../../concepts/glossary.md#actor-system-interconnect), следует добавить в секцию `config` используемые [настройки TLS для интерконнекта](../../reference/configuration/tls.md#interconnect).
+
+1. Примените сформированный файл динамической конфигурации на кластер:
+
+    ```bash
+    # Применить конфигурационный файл dynconfig.yaml на кластер
+    {{ ydb-cli }} admin config replace -f dynconfig.yaml
+    ```
+
+{% note info %}
+
+После включения поддержки динамической конфигурации в кластере {{ ydb-short-name }} устаревшая функция управления конфигурацией через CMS будет недоступна.
+
+{% endnote %}
+
+## Примеры конфигурации {#example}
 
 Пример минимальной динамической конфигурации для однодатацентрового кластера:
 
@@ -22,69 +57,102 @@
 # Поле управляется сервером
 metadata:
   # Имя кластера из параметра cluster_uuid, выставляемом при установке кластера, или "", если параметр не выставлен
-  cluster: unknown
-  # Идентификатор конфигурационного файла, всегда возрастает на 1 и начинается с 1.
+  cluster: ""
+  # Идентификатор конфигурационного файла, всегда возрастает на 1 и начинается с 0.
   # Увеличивается автоматически при загрузке новой конфигурации на сервер.
-  version: 1
+  version: 0
 # Основная конфигурация кластера, все значения из него применяются по-умолчанию, пока не переопределены селекторами.
 # Содержание аналогично статической конфигурации кластера
 config:
 # должен быть всегда выставлен в true для использования yaml конфигурации
   yaml_config_enabled: true
-# конфигурация актор-системы, т.к. по-умолчанию данная секция используется только дин-нодами
-# выставлена конфигурация именно для ни
+# конфигурация актор-системы - поскольку по-умолчанию данная секция используется
+# только узлами БД, выставлена конфигурация именно для них
   actor_system_config:
 # автоматический подбор конфигурации для ноды на основе типа и количества доступных ядер
     use_auto_config: true
-# HYBRID || COMPUTE || STORAGE — тип ноды
+# HYBRID || COMPUTE || STORAGE — тип ноды, для узлов БД всегда COMPUTE
     node_type: COMPUTE
-# число ядер
-    cpu_count: 4
-# конфигурация корневого домена кластера {{ ydb-short-name }}
-  domains_config:
-    domain:
-    - name: Root
-      storage_pool_types:
-      - kind: ssd
-        pool_config:
-          box_id: 1
-          erasure_species: none
-          kind: ssd
-          pdisk_filter:
-          - property:
-            - type: SSD
-          vdisk_kind: Default
-      explicit_mediators: [72075186232426497, 72075186232426498, 72075186232426499]
-      explicit_coordinators: [72075186232360961, 72075186232360962, 72075186232360963]
-      explicit_allocators: [72075186232492033, 72075186232492034, 72075186232492035]
-    state_storage:
-    - ssid: 1
-      ring:
-        nto_select: 5
-        node: [1, 2, 3, 4, 5, 6, 7, 8]
-    hive_config:
-    - hive_uid: 1
-      hive: 72057594037968897
-# конфигурация профилей каналов таблеток
-  channel_profile_config:
-    profile:
-    - profile_id: 0
-      channel:
-      - &default_channel
-        erasure_species: block-4-2
-        pdisk_category: 1
-        vdisk_category: Default
-      - *default_channel
-      - *default_channel
+# количество выделенных ядер
+    cpu_count: 14
 allowed_labels: {}
 selector_config: []
 ```
 
 Подробнее параметры конфигурации описаны на странице [{#T}](../../reference/configuration/index.md).
 
-По умолчанию конфигурация кластера является пустой и имеет версию 1. При применении новой конфигурации версия загружаемой конфигурации сравнивается и автоматически увеличивается на единицу.
+Первоначально установленная динамическая конфигурация кластера получает номер версии 1. При применении новой конфигурации версия хранимой конфигурации сравнивается с указанной в YAML-документе и автоматически увеличивается на единицу.
+
+Пример более сложной динамической конфигурации с установкой типовых глобальных параметров, а также особых параметров для одной из баз данных:
+
+```yaml
+---
+metadata:
+  kind: MainConfig
+  cluster: ""
+  version: 1
+config:
+  yaml_config_enabled: true
+  table_profiles_config:
+    table_profiles:
+    - name: default
+      compaction_policy: default
+      execution_policy: default
+      partitioning_policy: default
+      storage_policy: default
+      replication_policy: default
+      caching_policy: default
+    compaction_policies:
+    - name: default
+    execution_policies:
+    - name: default
+    partitioning_policies:
+    - name: default
+      auto_split: true
+      auto_merge: true
+      size_to_split: 2147483648
+    storage_policies:
+    - name: default
+      column_families:
+      - storage_config:
+          sys_log:
+            preferred_pool_kind: ssd
+          log:
+            preferred_pool_kind: ssd
+          data:
+            preferred_pool_kind: ssd
+    replication_policies:
+    - name: default
+    caching_policies:
+    - name: default
+  interconnect_config:
+    encryption_mode: REQUIRED
+    path_to_certificate_file: "/opt/ydb/certs/node.crt"
+    path_to_private_key_file: "/opt/ydb/certs/node.key"
+    path_to_ca_file: "/opt/ydb/certs/ca.crt"
+allowed_labels:
+  node_id:
+    type: string
+  host:
+    type: string
+  tenant:
+    type: string
+selector_config:
+- description: Custom settings for testdb
+  selector:
+    tenant: /cluster1/testdb
+  config:
+    shared_cache_config:
+      memory_limit: 34359738368
+    feature_flags: !inherit
+      enable_views: true
+    actor_system_config:
+      use_auto_config: true
+      node_type: COMPUTE
+      cpu_count: 14
+```
 
-### Обновление динамической конфигурации
+## Обновление динамической конфигурации
 
 ```bash
 # Получить конфигурацию кластера
@@ -98,17 +166,17 @@ vim dynconfig.yaml
 Дополнительные возможности конфигурирования описаны на страницах [селекторы](./dynamic-config-selectors.md) и [временная конфигурация](./dynamic-config-volatile-config.md).
 Все команды для работы с конфигурацией описаны в разделе [{#T}](../../reference/ydb-cli/configs.md).
 
-### Механизм работы
+## Механизм работы
 
-#### Обновление конфигурации c точки зрения администратора
+### Обновление конфигурации c точки зрения администратора
 
 1. Конфигурационный файл загружается пользователем при помощи [grpc-вызова](https://github.com/ydb-platform/ydb/blob/5251c9ace0a7617c25d50f1aa4d0f13e3d56f985/ydb/public/api/grpc/draft/ydb_dynamic_config_v1.proto#L22) или [{{ ydb-short-name }} CLI](../../reference/ydb-cli/index.md) в кластер.
 2. Файл проверяется на валидность, проверяются базовые ограничения, корректность версии, корректность имени кластера, корректность конфигураций полученных после преобразования DSL.
 3. Версия конфигурации в файле увеличивается на единицу.
 4. Файл надёжно сохраняется в кластере [таблеткой](../../concepts/glossary.md#tablet) Console.
 5. Обновления файла рассылаются по узлам кластера.
 
-#### Обновление конфигурации с точки зрения узла кластера
+### Обновление конфигурации с точки зрения узла кластера
 
 1. Каждый узел при старте запрашивает полную конфигурацию.
 2. Получив конфигурацию, узел [генерирует конечную конфигурацию](./dynamic-config-selectors.md#selectors-resolve) для своего набора [лейблов](./dynamic-config-selectors.md#selectors-intro).
@@ -118,11 +186,11 @@ vim dynconfig.yaml
 
 Пункты 1,2 выполняются только для динамических узлов кластера.
 
-#### Версионирование конфигурации
+### Версионирование конфигурации
 
 Данный механизм позволяет избежать конкурентной модификации конфигурации и сделать её обновление идемпотентным. При получении запроса на модификацию конфигурации сервер сравнивает версию полученной модификации с сохраненной. Если версия меньше на единицу, то конфигурации сравниваются — если они одинаковы, значит пользователь пытается загрузить конфигурацию повторно, пользователь получает ОК, а конфигурация на кластере не обновляется. Если версия равна текущей на кластере, то конфигурация заменяется на новую, при этом поле версии увеличивается на единицу. Во всех остальных случаях пользователь получает ошибку.
 
-### Динамически обновляемые настройки {#dynamic-kinds}
+## Динамически обновляемые настройки {#dynamic-kinds}
 
 Часть настроек системы обновляется без перезапуска узлов. Для их изменения достаточно загрузить новую конфигурацию и дождаться её распространения по кластеру.
 
@@ -138,7 +206,7 @@ vim dynconfig.yaml
 
 В будущем список может быть расширен.
 
-### Ограничения
+## Ограничения
 
 * Использование более 30 различных [лейблов](./dynamic-config-selectors.md) в [селекторах](./dynamic-config-selectors.md) может привести к задержкам при валидации конфигурации в десятки секунд, т.к. {{ ydb-short-name }} необходимо проверить валидность каждой возможной конечной конфигурации. При этом количество значений одного лейбла влияет намного меньше.
-* Использование объемных файлов (более 500KiB для кластера в 1000 узлов), конфигурации может привести к росту сетевого трафика в кластере при обновлении конфигурации. Объем трафика прямо пропорционален количеству нод и объему конфигурации.
+* Использование объемных файлов (более 500KiB для кластера в 1000 узлов) конфигурации может привести к росту сетевого трафика в кластере при обновлении конфигурации. Объем трафика прямо пропорционален количеству нод и объему конфигурации.