diff --git a/ydb/docs/build.sh b/ydb/docs/build.sh index b93f0e6c2a70..8c80809d5750 100755 --- 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 index f3510ac19dde..11172ef6942d 100644 --- a/ydb/docs/ru/core/maintenance/manual/dynamic-config.md +++ b/ydb/docs/ru/core/maintenance/manual/dynamic-config.md @@ -13,6 +13,41 @@ * изменить настройки акторной системы на отдельно узле или на групе узлов; * и т.д. +### Подготовка к использованию динамической конфигурации {#preparation} + +{% note info %} + +После включения поддержки динамической конфигурации в кластере {{ ydb-short-name }} устаревшая функция управления конфигурацией через CMS будет недоступна. + +{% endnote %} + +Перед началом использования динамической конфигурации в кластере необходимо провести подготовительные работы: + +1. В кластере должна быть включена авторизация регистрации узлов баз данных. + +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 + ``` + + Предварительно необходимо получить токен аутентификации с помощью команды `ydb auth get-token`, по аналогии с [процедурой инициализации кластера](../../devops/manual/initial-deployment.md#initialize-cluster). + +1. Необходимо сформировать первоначальный файл динамической конфигурации: + + * При наличии ранее выполненных через CMS настроек (экспортированных на предыдущем шаге) за основу берется полученный на предыдущем шаге файл, в котором требуется: + * добавить секцию `metadata` по образцу из [примера конфигурации](#example); + * в секцию `config` добавить параметр `yaml_config_enabled: true`. + * При отсутствии ранее выполненных через CMS настроек используется [минимальное наполнение](#example) файла динамической конфигурации. + +1. Сформированный файл динамической конфигурации необходимо применить на кластер: + + ```bash + # Применить конфигурационный файл dynconfig.yaml на кластер + {{ ydb-cli }} admin config replace -f dynconfig.yaml + ``` + ### Примеры конфигурации {#example} Пример минимальной динамической конфигурации для однодатацентрового кластера: @@ -22,60 +57,24 @@ # Поле управляется сервером 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: [] ``` diff --git a/ydb/docs/ru/core/maintenance/manual/node_authorization.md b/ydb/docs/ru/core/maintenance/manual/node_authorization.md new file mode 100644 index 000000000000..4e8ab0e38649 --- /dev/null +++ b/ydb/docs/ru/core/maintenance/manual/node_authorization.md @@ -0,0 +1,76 @@ +# Авторизация узлов при регистрации в кластере + +Функция авторизации узлов обеспечивает проверку подлинности узлов баз данных при их регистрации в состав кластера {{ 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-сертификата. +