diff --git a/ydb/docs/ru/core/maintenance/manual/dynamic-config.md b/ydb/docs/ru/core/maintenance/manual/dynamic-config.md index 11172ef6942d..a27fe6077525 100644 --- a/ydb/docs/ru/core/maintenance/manual/dynamic-config.md +++ b/ydb/docs/ru/core/maintenance/manual/dynamic-config.md @@ -1,4 +1,4 @@ -## Динамическая конфигурация кластера +# Динамическая конфигурация кластера Динамическая конфигурация позволяет запускать динамические [узлы](../../concepts/glossary.md#node), сконфигурировав их централизованно, без необходимости раскладывать файлы по узлам вручную. {{ ydb-short-name }} выступает в роли системы управления конфигурациями, предоставляя инструменты для надёжного хранения, версионирования и доставки конфигурации, а так же [DSL (Domain Specific Language)](./dynamic-config-selectors.md) для переопределения её частей для определённых групп узлов. Конфигурация представляет собой YAML документ. Он является расширенной версией статической конфигурации: @@ -6,30 +6,23 @@ * добавлено поле `metadata`, необходимое для валидации и версионирования; * добавлены поля `allowed_labels` и `selector_config` для гранулярного переопределения настроек. -Эта конфигурация загружается в кластер, где надёжно сохраняется и доставляется до каждого динамического узла при его старте. [Определенные настройки](#dynamic-kinds) обновляются на лету, без перезапуска узлов. С помощью динамической конфигурации можно централизованно решить следующие задачи: +Эта конфигурация загружается в кластер, где надёжно сохраняется и доставляется до каждого динамического узла при его старте. [Некоторые настройки](#dynamic-kinds) обновляются на лету, без перезапуска узлов. С помощью динамической конфигурации можно централизованно решить следующие задачи: -* переключение настроек журналирования компонентов как для всего кластера, так и для отдельных групп узлов; -* включать экспериментальную функциональность (feature flags) на отдельных базах; -* изменить настройки акторной системы на отдельно узле или на групе узлов; -* и т.д. +* переключать настройки журналирования компонентов как для всего кластера, так и для отдельных баз данных или групп узлов; +* включать экспериментальную функциональность (feature flags) на отдельных базах данных; +* изменять настройки акторной системы на конкретной базе данных, отдельном узле или на группе узлов. -### Подготовка к использованию динамической конфигурации {#preparation} - -{% note info %} - -После включения поддержки динамической конфигурации в кластере {{ ydb-short-name }} устаревшая функция управления конфигурацией через CMS будет недоступна. - -{% endnote %} +## Подготовка к использованию динамической конфигурации {#preparation} Перед началом использования динамической конфигурации в кластере необходимо провести подготовительные работы: -1. В кластере должна быть включена авторизация регистрации узлов баз данных. +1. В кластере должна быть включена [авторизация узлов баз данных](../../reference/configuration/node_authorization.md) при их регистрации. -1. Если ранее в кластере использовалось [управление конфигурацией через CMS](cms.md), то необходимо выгрузить существующие настройки к формату YAML. Для этого необходимо выполнить следующую команду: +1. Если ранее в кластере использовалось [управление конфигурацией через CMS](cms.md), то необходимо выгрузить существующие настройки в формате YAML. Для этого необходимо выполнить следующую команду: ```bash ./ydbd -s grpcs://:2135 --ca-file ca.crt --token-file ydbd-token \ - admin console configs dump-yaml > dynconfig.yaml + admin console configs dump-yaml > dynconfig.yaml ``` Предварительно необходимо получить токен аутентификации с помощью команды `ydb auth get-token`, по аналогии с [процедурой инициализации кластера](../../devops/manual/initial-deployment.md#initialize-cluster). @@ -40,6 +33,7 @@ * добавить секцию `metadata` по образцу из [примера конфигурации](#example); * в секцию `config` добавить параметр `yaml_config_enabled: true`. * При отсутствии ранее выполненных через CMS настроек используется [минимальное наполнение](#example) файла динамической конфигурации. + * Если в кластере используется шифрование [интерконнекта акторной системы](../../concepts/glossary.md#actor-system-interconnect), следует добавить в секцию `config` используемые [настройки TLS для интерконнекта](../../reference/configuration/tls.md#interconnect). 1. Сформированный файл динамической конфигурации необходимо применить на кластер: @@ -48,7 +42,13 @@ {{ ydb-cli }} admin config replace -f dynconfig.yaml ``` -### Примеры конфигурации {#example} +{% note info %} + +После включения поддержки динамической конфигурации в кластере {{ ydb-short-name }} устаревшая функция управления конфигурацией через CMS будет недоступна. + +{% endnote %} + +## Примеры конфигурации {#example} Пример минимальной динамической конфигурации для однодатацентрового кластера: @@ -81,9 +81,78 @@ 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 # Получить конфигурацию кластера @@ -97,9 +166,9 @@ 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. @@ -107,7 +176,7 @@ vim dynconfig.yaml 4. Файл надёжно сохраняется в кластере [таблеткой](../../concepts/glossary.md#tablet) Console. 5. Обновления файла рассылаются по узлам кластера. -#### Обновление конфигурации с точки зрения узла кластера +### Обновление конфигурации с точки зрения узла кластера 1. Каждый узел при старте запрашивает полную конфигурацию. 2. Получив конфигурацию, узел [генерирует конечную конфигурацию](./dynamic-config-selectors.md#selectors-resolve) для своего набора [лейблов](./dynamic-config-selectors.md#selectors-intro). @@ -117,11 +186,11 @@ vim dynconfig.yaml Пункты 1,2 выполняются только для динамических узлов кластера. -#### Версионирование конфигурации +### Версионирование конфигурации Данный механизм позволяет избежать конкурентной модификации конфигурации и сделать её обновление идемпотентным. При получении запроса на модификацию конфигурации сервер сравнивает версию полученной модификации с сохраненной. Если версия меньше на единицу, то конфигурации сравниваются — если они одинаковы, значит пользователь пытается загрузить конфигурацию повторно, пользователь получает ОК, а конфигурация на кластере не обновляется. Если версия равна текущей на кластере, то конфигурация заменяется на новую, при этом поле версии увеличивается на единицу. Во всех остальных случаях пользователь получает ошибку. -### Динамически обновляемые настройки {#dynamic-kinds} +## Динамически обновляемые настройки {#dynamic-kinds} Часть настроек системы обновляется без перезапуска узлов. Для их изменения достаточно загрузить новую конфигурацию и дождаться её распространения по кластеру. @@ -137,7 +206,7 @@ vim dynconfig.yaml В будущем список может быть расширен. -### Ограничения +## Ограничения * Использование более 30 различных [лейблов](./dynamic-config-selectors.md) в [селекторах](./dynamic-config-selectors.md) может привести к задержкам при валидации конфигурации в десятки секунд, т.к. {{ ydb-short-name }} необходимо проверить валидность каждой возможной конечной конфигурации. При этом количество значений одного лейбла влияет намного меньше. -* Использование объемных файлов (более 500KiB для кластера в 1000 узлов), конфигурации может привести к росту сетевого трафика в кластере при обновлении конфигурации. Объем трафика прямо пропорционален количеству нод и объему конфигурации. +* Использование объемных файлов (более 500KiB для кластера в 1000 узлов) конфигурации может привести к росту сетевого трафика в кластере при обновлении конфигурации. Объем трафика прямо пропорционален количеству нод и объему конфигурации. diff --git a/ydb/docs/ru/core/maintenance/manual/node_authorization.md b/ydb/docs/ru/core/maintenance/manual/node_authorization.md deleted file mode 100644 index 4e8ab0e38649..000000000000 --- a/ydb/docs/ru/core/maintenance/manual/node_authorization.md +++ /dev/null @@ -1,76 +0,0 @@ -# Авторизация узлов при регистрации в кластере - -Функция авторизации узлов обеспечивает проверку подлинности узлов баз данных при их регистрации в состав кластера {{ ydb-short-name }}. Использование авторизации узлов рекомендовано для всех кластеров {{ ydb-short-name }}, поскольку позволяет избежать нежелательной ситуации, когда потенциальный злоумышленник может запустить собственный экземпляр узла базы данных, и получить тем самым доступ к данным соответствующей базы данных. - -Далее описаны действия необходимые для для того, чтобы задействовать авторизацию регистрации узлов. - -## Подготовка сертификатов узлов - -При подготовке сертификатов узлов необходимо обеспечить единые правила заполнения поля "Subject" (Субъект). При проверке сертификата в процессе регистрации узла {{ ydb-short-name }} убеждается в наличии у подключающегося узла доверенного сертификата, и проверяет заполнение полей поля "Subject" на соответствие требованиям, устанавливаемым в статической конфигурации {{ ydb-short-name }}. - -Предлагаемый [пример скрипта](https://github.com/ydb-platform/ydb/blob/main/ydb/deploy/tls_cert_gen/) для генерации самоподписанных сертификатов узлов {{ ydb-short-name }} обеспечивает заполнение поля "Subject" значением `O=YDB` для всех сертификатов узлов. Приведенные далее примеры настроек подготовлены для сертификатов с именно таким заполнением поля "Subject". - -## Включение режима авторизации узлов - -Для включения обязательной авторизации узлов баз данных в файл [статической конфигурации кластера](../../reference/configuration/) необходимо добавить следующие блоки настроек: - -1. На корневом уровне конфигурации добавить блок `client_certificate_authorization`, в которой указать требования к заполнению поля "Subject" доверенных сертификатов подключаемых узлов, например: - - ```yaml - client_certificate_authorization: - request_client_certificate: true - client_certificate_definitions: - - member_groups: ["registerNode@cert"] - subject_terms: - - short_name: "O" - values: ["YDB"] - ``` - - В случае успешной проверки сертификата и при условии соответствия заполнения компонентов поля "Subject" сертификата установленным в блоке `subject_terms` требованиям, подключению будут присвоены субъекты доступа, перечисленные в параметре `member_groups`. Для отделения таких субъектов доступа от других разновидностей групп и учетных записей к их наименованию добавляется суффикс `@cert`. - -1. В блок `domains_config / security_config` добавить элемент `register_dynamic_node_allowed_sids`, в котором указать список субъектов доступа, для которых разрешена регистрация узлов баз данных. По техническим причинам в этом элементе также должен присутствовать субъект доступа `root@builtin`. Пример: - - ```yaml - domains_config: - ... - security_config: - enforce_user_token_requirement: true - monitoring_allowed_sids: - ... - administration_allowed_sids: - ... - viewer_allowed_sids: - ... - register_dynamic_node_allowed_sids: - - "root@builtin" # требуется по техническим причинам - - "registerNode@cert" - ``` - -1. В блоке `grpc_config` должны быть установлены параметры TLS-защиты трафика, а также обеспечена активация по умолчанию сервиса `legacy`, пример: - - ```yaml - grpc_config: - ssl_port: 2135 - cert: "/opt/ydb/certs/node.crt" - key: "/opt/ydb/certs/node.key" - ca: "/opt/ydb/certs/ca.crt" - services_enabled: - - legacy - ``` - - В приведенном выше фрагменте конфигурации установлен номер GRPCS-порта, имена файлов ключа и сертификата узла, а также имя файла сертификата используемого доверенного центра сертификации. - - В большинстве случаев номер порта и пути к файлам ключей и сертификатов переопределяется аргументами командной строки запуска сервиса YDB, пример: - - ```bash - /opt/ydb/bin/ydbd server --tcp --yaml-config /opt/ydb/cfg/ydbd-static.yaml \ - --node static --grpcs-port 2135 --ic-port 19001 --mon-port 8765 \ - --ca /opt/ydb/certs/ca.crt --cert /opt/ydb/certs/node.crt --key /opt/ydb/certs/node.key \ - --grpc-ca /opt/ydb/certs/ca.crt --grpc-cert /opt/ydb/certs/node.crt --grpc-key /opt/ydb/certs/node.key \ - --mon-cert /opt/ydb/certs/web.pem - ``` - -## Параметры запуска узлов баз данных - -После включения в кластере {{ ydb-short-name }} режима обязательной авторизации узлов при подключении узла базы данных будет требоваться подтверждение подлинности с помощью TLS-сертификата. - diff --git a/ydb/docs/ru/core/reference/configuration/node_authorization.md b/ydb/docs/ru/core/reference/configuration/node_authorization.md new file mode 100644 index 000000000000..c2d0b3bdcd23 --- /dev/null +++ b/ydb/docs/ru/core/reference/configuration/node_authorization.md @@ -0,0 +1,49 @@ +# Авторизация узлов при регистрации в кластере + +Функция авторизации узлов обеспечивает проверку подлинности узлов баз данных при их регистрации в состав кластера {{ ydb-short-name }}. Использование авторизации узлов рекомендовано для всех кластеров {{ ydb-short-name }}, поскольку позволяет избежать ситуаций несанкционированного доступа к данным через включение в кластер контролируемых злоумышленником узлов. + +Далее описаны действия, необходимые для включения функции авторизации узлов. + +## Включение TLS для трафика gRPC и подготовка сертификатов узлов + +Перед включением функции авторизации узлов необходимо [настроить шифрование трафика gRPC](./tls.md#grpc) с использованием протокола TLS. + +При подготовке сертификатов узлов для кластера, в котором планируется использовать функцию авторизации узлов, необходимо обеспечить единые правила заполнения поля "Subject" сертификатов. При проверке сертификата в процессе регистрации узла {{ ydb-short-name }} убеждается в наличии у подключающегося узла доверенного сертификата, и проверяет заполнение поля "Subject" на соответствие требованиям, устанавливаемым в статической конфигурации {{ ydb-short-name }}. Поле "Subject" может состоять из нескольких компонентов (например `O` - организация, `OU` - подразделение в составе организации, `C` - страна, `CN` - имя собственное субъекта), и проверки могут быть настроены в отношении одного или нескольких компонентов. + +Предлагаемый [пример скрипта](https://github.com/ydb-platform/ydb/blob/main/ydb/deploy/tls_cert_gen/) для генерации самоподписанных сертификатов узлов {{ ydb-short-name }} обеспечивает заполнение поля "Subject" значением `O=YDB` для всех сертификатов узлов. Приведенные далее примеры настроек подготовлены для сертификатов с именно таким заполнением поля "Subject". + +## Включение режима авторизации узлов + +Для включения обязательной авторизации узлов баз данных в файл [статической конфигурации кластера](./index.md) необходимо добавить следующие блоки настроек: + +1. На корневом уровне конфигурации добавить блок `client_certificate_authorization`, в которой указать требования к заполнению поля "Subject" доверенных сертификатов подключаемых узлов, например: + + ```yaml + client_certificate_authorization: + request_client_certificate: true + client_certificate_definitions: + - member_groups: ["registerNode@cert"] + subject_terms: + - short_name: "O" + values: ["YDB"] + ``` + + В случае успешной проверки сертификата и при условии соответствия заполнения компонентов поля "Subject" сертификата установленным в блоке `subject_terms` требованиям, подключению будут присвоены субъекты доступа, перечисленные в параметре `member_groups`. Для отделения таких субъектов доступа от других разновидностей групп и учетных записей к их наименованию добавляется суффикс `@cert`. + +1. В блок `domains_config / security_config` добавить элемент `register_dynamic_node_allowed_sids`, в котором указать список субъектов доступа, для которых разрешена регистрация узлов баз данных. По техническим причинам в этом списке также должен присутствовать субъект доступа `root@builtin`. Пример: + + ```yaml + domains_config: + ... + security_config: + enforce_user_token_requirement: true + monitoring_allowed_sids: + ... + administration_allowed_sids: + ... + viewer_allowed_sids: + ... + register_dynamic_node_allowed_sids: + - "root@builtin" # требуется по техническим причинам + - "registerNode@cert" + ``` diff --git a/ydb/docs/ru/core/reference/configuration/toc_p.yaml b/ydb/docs/ru/core/reference/configuration/toc_p.yaml index c26f18897f87..aa858c404861 100644 --- a/ydb/docs/ru/core/reference/configuration/toc_p.yaml +++ b/ydb/docs/ru/core/reference/configuration/toc_p.yaml @@ -1,3 +1,5 @@ items: - name: TLS - href: tls.md \ No newline at end of file + href: tls.md +- name: Авторизация узлов баз данных + href: node_authorization.md