Конфигурация кластера в YAML (Tarantool 3.x)

Документ рассматривает параметры YAML-конфигурации кластеров Tarantool 3.x, необходимые для взаимодействия с TCF. Задать TCF-специфичные настройки кластера можно в файле конфигурации YAML, указав специальные роли. Для работы TCF используются две технологические роли в конфигурации кластера:

• roles.tcf-worker – инициализирует переключение статусов кластеров TCF (активный-пассивный), предоставляет базовое HTTP API для управления TCF. Назначается всем экземплярам типа storage и router в кластере Tarantool, которыми управляет TCF;
• roles.tcf-coordinator – координатор для работы автоматического восстановления после сбоев (autofailover). Отслеживает работоспособность кластеров и автоматически переключает активный-пассивный кластер в случае выхода из строя активного кластера. Назначается выборочным экземплярам типа storage и router в кластере Tarantool, которыми управляет TCF.

Раздел roles.tcf-worker содержит параметры управления статусами TCF (активный-пассивный), а также предоставляет базовое HTTP API для управления TCF:

• roles.tcf-worker.cluster_1
• roles.tcf-worker.cluster_2
• roles.tcf-worker.initial_status
• roles.tcf-worker.dml_users
• roles.tcf-worker.replication_user
• roles.tcf-worker.replication_password
• roles.tcf-worker.storage
• roles.tcf-worker.storage_params
• roles.tcf-worker.gateway
• roles.tcf-worker.destination
• roles.tcf-worker.authorization
• roles.tcf-worker.http
• roles.tcf-worker.status_ttl
• roles.tcf-worker.enable_system_check

Пример:

 
instances:  storage-1-msk:    roles_cfg:      roles.tcf-worker:        cluster_1: cluster_a        cluster_2: cluster_b        initial_status: active        dml_users: [ tcf-dml ]        replication_user: tcf-replicator        replication_password: secret        storage: config_storage        storage_params:          endpoints:            - uri: 127.0.0.1:3301              login: client              password: secret        gateway:          uri: "http://localhost:8080"          http_server:            ssl_cert_file: "/etc/certs/gateway.crt"            ssl_key_file: "/etc/certs/gateway.key"            ssl_ca_file: "/etc/certs/gateway.ca"        destination:          uri: "http://localhost:8080"          http_server:            ssl_cert_file: "/etc/certs/destination.crt"            ssl_key_file: "/etc/certs/destination.key"            ssl_ca_file: "/etc/certs/destination.ca"        authorization:          provider: keycloak          provider_params:            url: "https://keycloak.example.com/"            roles:              info: ORDERDB_TCF_INFO              toggle: ORDERDB_TCF_TOGGLE              admin: ORDERDB_TCF_ADMIN            client_id: "client"            client_secret_path: "/path/to/file"            realm: "myrealm"            ssl:              ca_file: "/etc/ssl/certs/keycloak-ca.pem"              cert_file: "/etc/ssl/certs/client.pem"              key_file: "/etc/ssl/private/client-key.pem"        http:          listen: localhost:8081

Имя кластера, для которого применяется конфигурация. Имя используется в качестве префикса хранилища конфигурации для хранения информации о состоянии кластера.

Тип: string

Имя соседнего кластера. Имя используется в качестве префикса хранилища конфигурации для хранения информации о состоянии кластера.

Тип: string

(config-tcf-3-0-yaml-tcf-worker-initial_status)=

Состояние, в которое кластер переходит при первом запуске с использованием TCF.

Возможные значения: active, passive

Список пользователей, доступ которым заблокирован на пассивном кластере.

После смены состояния балансировщик может не сразу получить информацию об изменении состояния и какое-то время продолжит направлять трафик на пассивный кластер. dml_users необходима, чтобы заблокировать пользователя, от имени которого приложение отправляет запросы на пассивный кластер.

Тип: array

Имя пользователя для подключения репликаторов TCF.

Тип: string

Пароль пользователя replication_user.

Тип: string

Тип хранилища конфигурации, которое используется для хранения состояния кластеров.

Возможные значения: config_storage, etcd_v3.

Параметры хранилища конфигурации. Набор параметров зависит от выбранного типа хранилища конфигурации – config_storage или etcd_v3.

Для типа config_storage доступны следующие параметры:

• endpoints – массив узлов хранилища config_storage с возможностью указания нескольких подключений. Параметр доступен начиная с версии 0.6.0. Тип: array. Возможные параметры:
  • uri – адрес master-узла хранилища конфигурации для типа config_storage, указанный внутри каждого объекта в массиве endpoints. Тип: string;
  • login – имя пользователя для доступа к хранилищу конфигурации. Тип: string;
  • password – пароль для доступа к хранилищу конфигурации. Тип: string;
  • params – дополнительные параметры подключения к хранилищу. Возможные параметры:
    • ssl_key_file – путь к закрытому ключу. Тип: string;
    • ssl_cert_file – путь к сертификату. Тип: string;
    • ssl_ca_file – путь к корневому сертификату. Тип: string;
    • ssl_ciphers – список наборов шифров TLS, разделенных двоеточиями. Тип: string;
    • ssl_password – пароль для зашифрованного закрытого ключа SSL. Тип: string;
    • ssl_password_file – текстовый файл, содержащий пароли для зашифрованных ключей SSL. Тип: string;
• uri – адрес master-узла хранилища конфигурации для типа config_storage. Параметр удален начиная с версии 0.6.0. Тип: string, key-value;
• login – имя пользователя для доступа к хранилищу конфигурации. Параметр удален начиная с версии 0.6.0. Тип: string;
• password – пароль для доступа к хранилищу конфигурации. Параметр удален начиная с версии 0.6.0. Тип: string;
• timeout – время ожидания выполнения запроса в секундах. Тип: number. Значение по умолчанию: 1. В версии 0.7.0 параметр переименован из request_timeout в timeout;
• prefix – префикс, под которым хранится конфигурация. Параметр доступен начиная с версии 0.4.0. Тип: string;
• params – дополнительные параметры подключения к хранилищу. Набор параметров совпадает со списком опций функции Tarantool net_box.connect(). Параметр удален начиная с версии 0.6.0;
• uri.params - настройки SSL. Параметр удален начиная с версии 0.6.0. Возможные параметры:
  • ssl_key_file – путь к закрытому ключу. Тип: string;
  • ssl_cert_file – путь к сертификату. Тип: string;
  • ssl_ca_file – путь к корневому сертификату. Тип: string;
  • ssl_ciphers – список наборов шифров TLS, разделенных двоеточиями. Тип: string;
  • ssl_password – пароль для зашифрованного закрытого ключа SSL. Тип: string;
  • ssl_password_file – текстовый файл, содержащий пароли для зашифрованных ключей SSL. Тип: string.

Для типа etcd_v3 доступны следующие параметры:

• endpoints – URI экземпляров хранилища конфигурации. Тип: array;
• login – имя пользователя для доступа к хранилищу конфигурации. Тип: string;
• password – пароль для доступа к хранилищу конфигурации. Тип: string;
• prefix – префикс, под которым хранится конфигурация. Значение по умолчанию: /tcf. Параметр доступен начиная с версии 0.4.0. Тип: string;
• lock_delay – время в секундах, в течение которого блокировка остается активной после разрыва соединения. После этого она автоматически снимается. Тип: number;
• request_timeout – время в секундах, в течение которого должен выполниться запрос к etcd. Если за это время ответа нет, запрос считается неудачным. Тип: number;
• http.request.timeout – время ожидания выполнения запроса в секундах. Тип: number. Значение по умолчанию: 1;
• http.request.unix_socket – Unix-сокет для подключения к хранилищу конфигурации. Тип: string;
• ssl.ca_file – путь к корневому сертификату. Тип: string;
• ssl.ca_path – путь к директории, содержащей сертификаты. Тип: string;
• ssl.ssl_cert – путь к сертификату. Тип: string;
• ssl.ssl_key – путь к закрытому ключу. Тип: string;
• ssl.verify_host – верифицировать имя сертификата (CN) с указанным хостом. Тип: boolean;
• ssl.verify_peer – верифицировать SSL-сертификаты. Тип: boolean;
• watchers.reconnect_max_attempts – максимальное число попыток подключения к хранилищу в случае ошибок подключения. Тип: integer;
• watchers.reconnect_timeout – время ожидания между попытками подключения к хранилищу в случае ошибок подключения. Тип: number.

Параметры экземпляра Gateway.

Тип: map

Если эта опция задана, TCF-worker будет управлять состоянием Gateway: автоматически отключать Gateway на пути из пассивного кластера в активный и включать Gateway на пути из активного кластера в пассивный с помощью HTTP-адресов обработчиков запросов /api/v1/start и /api/v1/stop. При этом репликация будет односторонней. Если секция tcf-worker.gateway отсутствует, репликация будет двусторонней.

Поддерживаемые параметры:

• uri – URI для подключения к экземпляру Gateway. Тип: string;
• http_server – параметры для установки соединения к серверу. Тип: map. Поддерживаемые параметры:
  • ssl_ca_file– путь к файлу корневого сертификата, который используется для проверки подлинности клиента при установке TLS-соединения. Тип: string;
  • ssl_cert_file – путь к файлу сертификата сервера. Тип: string;
  • ssl_key_file – путь к файлу закрытого ключа сервера. Тип: string.

Пример:

 
roles_cfg:  roles.tcf-worker:    gateway:      uri: "http://localhost:8080"      http_server:        ssl_cert_file: "/etc/certs/gateway.crt"        ssl_key_file: "/etc/certs/gateway.key"        ssl_ca_file: "/etc/certs/gateway.ca"  # ...

Параметры экземпляра Destination.

Тип: map

Опция tcf-worker.destination делает возможным плавное переключение без потери данных (graceful toggle), если при отправке запроса на HTTP-адрес обработчика /api/v1/status приходит ответ с HTTP-кодом 200 и в теле ответа содержится статус connected (соединение установлено) или streaming (репликация активна).

Поддерживаемые параметры:

• uri – URI для подключения к экземпляру Gateway. Тип: string;
• http_server – параметры для установки соединения к серверу. Тип: map. Поддерживаемые параметры:
  • ssl_ca_file – путь к файлу корневого сертификата, который используется для проверки подлинности клиента при установке TLS-соединения. Тип: string;
  • ssl_cert_file – путь к файлу сертификата сервера. Тип: string;
  • ssl_key_file – путь к файлу закрытого ключа сервера. Тип: string.

Пример:

 
roles_cfg:  roles.tcf-worker:    destination:      uri: "http://localhost:8080"      http_server:        ssl_cert_file: "/etc/certs/destination.crt"        ssl_key_file: "/etc/certs/destination.key"        ssl_ca_file: "/etc/certs/destination.ca"  # ...

Доступно с версии 0.9.0.

Параметры авторизации для HTTP API TCF-worker.

Тип: map

Поддерживаемые параметры:

• provider – имя провайдера. На текущий момент поддерживается только значение keycloak. Тип: string;
• provider_params – параметры провайдера Keycloak. Тип: map. Поддерживаемые параметры:
  • url – URL сервера Keycloak. Тип: string;
  • ssl – параметры TLS для HTTP API Keycloak. Тип: map. Поддерживаемые параметры:
    • ca_file – путь к файлу корневого сертификата, который используется для проверки подлинности клиента при установке TLS-соединения. Тип: string;
    • cert_file – путь к файлу сертификата сервера. Тип: string;
    • key_file – путь к файлу закрытого ключа сервера. Тип: string;
  • roles – список с соответствием ролей из Keycloak и правил авторизации для TCF-worker. Тип: map. Поддерживаемые параметры:
    • info – чтение статусов кластеров и метрик. Дает доступ к HTTP-адресам обработчиков запросов: /tcf/status, /tcf/is_active, /tcf/clusters (TCF-worker) и /api/v1/status (Destination). Значение по умолчанию: TCF_INFO. Тип: string;
    • toggle – управление репликацией. Дает доступ ко всем адресам обработчиков запросов, кроме /api/v1/rebootstrap (Destination). Значение по умолчанию: TCF_TOGGLE. Тип: string;
    • admin – полный доступ ко всем адресам обработчиков запросов, включая /api/v1/rebootstrap. Значение по умолчанию: TCF_ADMIN. Тип: string;
  • client_id – имя сервисного клиента. Тип: string;
  • client_secret_path – путь к файлу с секретом клиента. Тип: string. Для повышения безопасности необходимо создать текстовый файл с секретом внутри;
  • realm – имя области realm, в которой создан сервисный клиент. Тип: string.

Компоненты Gateway и Destination предоставляют HTTP API, к которому TCF-worker делает запросы. Для таких внутренних запросов используются параметры client_id, client_secret_path и realm. Чтобы эти запросы работали корректно:

1. Заполните поля roles.tcf-worker.gateway или roles.tcf-worker.destination в конфигурации TCF-worker.

2. Создайте конфиденциального клиента с включенным сервис-аккаунтом serviceAccountsEnabled=true. Клиент должен иметь роль toggle или admin. Через этого клиента будут выписываться токены для обращения TCF-worker к компонентам Gateway/Destination.

3. Добавьте параметры authorization.provider_params.client_id, authorization.provider_params.client_secret_path и authorization.provider_params.realm в конфигурацию TCF-worker.

Узнайте также про настройку обнаружения отзыва токена для Gateway и Destination.

Пример:

 
roles_cfg:  roles.tcf-worker:    authorization:      provider: keycloak      provider_params:        url: "https://keycloak.example.com/"        roles:          info: ORDERDB_TCF_INFO          toggle: ORDERDB_TCF_TOGGLE          admin: ORDERDB_TCF_ADMIN        client_id: "client"        client_secret_path: "/path/to/file"        realm: "myrealm"        ssl:          ca_file: "/etc/ssl/certs/keycloak-ca.pem"          cert_file: "/etc/ssl/certs/client.pem"          key_file: "/etc/ssl/private/client-key.pem"

Настройки HTTP-соединения. Поддерживаемые параметры:

• roles.tcf-worker.http.listen – endpoint для HTTP API TCF-координаторов. Тип: string.

(config-tcf-3-0-yaml-tcf-worker-status_ttl)=

Время (в секундах), через которое может произойти автоматическое переключение состояния кластеров.

Тип: number

Значение по умолчанию: 4

Включить сервис проверки доступности файловой системы.

Тип: boolean

Значение по умолчанию: true

Раздел roles.tcf-coordinator содержит параметры координатора для работы автоматического восстановления после сбоев (autofailover):

• roles.tcf-coordinator.failover_timeout
• roles.tcf-coordinator.health_check_delay
• roles.tcf-coordinator.max_suspect_counts

Пример:

 
instances:  router-msk:    roles_cfg:      roles.tcf-coordinator:        failover_timeout: 20        health_check_delay: 2        max_suspect_count: 3

Время (в секундах) захвата флага активным координатором. Если активный координатор вышел из строя и в активном кластере не осталось доступных координаторов, будет произведено переключение статусов кластеров.

Тип: number

Значение по умолчанию: 20

Периодичность (в секундах) опроса проверки состояния кластера координатором. Каждая последующая неудачная проверка увеличивает счетчик suspect_counts на 1. См. также max_suspect_count.

Тип: number

Значение по умолчанию: 3

Максимальное значение счетчика suspects_counts, после которого координатор складывает полномочия и производится переключение состояния кластеров. См. также health_check_delay.

Тип: number

Значение по умолчанию: 3