Конфигурация кластера

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

Топология кластера настраивается при помощи секций topology и vshard_groups.

Секция topology содержит три главных подраздела:

• replicasets - содержит информацию о том, как экземпляры Tarantool организованы в наборы реплик, какие у узлов кластерные роли и веса при шардировании;
• servers - список всех экземпляров Tarantool;
• failover - настройки восстановления после сбоев.

Этот подраздел содержит информацию о том, как экземпляры организованы в наборы реплик.

Каждый набор реплик идентифицируется по своему номеру UUID. Для каждого приводятся следующие параметры:

• weight - вес набора реплик. По умолчанию: 0 (подключен, но пока не принимает данные). При указанном весе 0 попытки шардирования будут приводить к ошибке на роутере (vshard-router).
• master - UUID экземпляра-мастера в этом наборе реплик.
• alias - человекопонятное имя набора реплик.
• vshard_group - группа шардирования, к которой относится набор реплик. По умолчанию: default.
• roles - список кластерных ролей, включенных (true) или выключенных (false) для набора реплик.
• all_rw - являются ли все узлы в наборе реплик мастерами. По умолчанию: false.

Пример для одного набора реплик:

 
replicasets:  5e47bf8e-57f5-4166-96ba-e16f964fb82b: # UUID набора реплик    weight: 1    master:    - dee26aab-0190-461d-9121-56b96b881a59    alias: unnamed    vshard_group: default    roles:      tracing: true      ddl-manager: true      maintenance: true      watchdog: true      account_provider: true      metrics: true      common: true      core: true      failover-coordinator: true      storage: true      runner: true      vshard-router: true      connector: true      vshard-storage: true    all_rw: false

В этом подразделе приведен список всех экземпляров Tarantool. Каждый из них идентифицируется по своему номеру UUID. Для каждого указаны следующие параметры:

• uri - внутренний URI-адрес экземпляра.
• disabled - выключен ли экземпляр. По умолчанию: false.
• replicaset_uuid - UUID набора реплик, в котором состоит экземпляр.

Пример для одного экземпляра:

 
servers:  dee26aab-0190-461d-9121-56b96b881a59:    uri: localhost:3301    disabled: false    replicaset_uuid: 5e47bf8e-57f5-4166-96ba-e16f964fb82b

В этом подразделе указываются настройки восстановления после сбоев, аналогичные соответствующим настройкам Cartridge.

Пример:

 
failover:  fencing_enabled: true  failover_timeout: 20  fencing_pause: 2  mode: eventual  fencing_timeout: 10

По умолчанию подраздел отключен:

 
failover: false

В этой секции указываются группы шардирования, или vshard-группы, к каждой из которых может принадлежать один или несколько наборов реплик. Внутри такой группы данные шардируются между входящими в нее наборами реплик.

В vshard-группе могут состоять только наборы реплик с ролью storage. Один набор реплик не может состоять в двух разных vshard-группах.

Параметры групп шардирования указываются так же, как при работе с Tarantool.

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

 
default:  rebalancer_max_receiving: 100  bootstrapped: true  collect_lua_garbage: false  sync_timeout: 1  rebalancer_max_sending: 1  sched_ref_quota: 300  rebalancer_disbalance_threshold: 1  bucket_count: 30000  sched_move_quota: 1

См. также настройку времени ожидания сетевых вызовов при шардировании.

Авторизация настраивается при помощи секций auth/auth_external, ldap.

Секция auth позволяет настроить существующую систему авторизации аналогично тому, как это делается в Tarantool Cartridge. Вместо этого можно в секции auth_external указать путь к файлу с Lua-кодом, где задана нестандартная логика для авторизации входящих запросов.

Кроме того, ниже рассматривается секция pepper, где можно задать переменную, с помощью которой будут хешироваться пароли.

В этой секции можно указать путь к файлу с Lua-кодом, где пользователь может самостоятельно задать логику для авторизации входящих запросов. Код должен вернуть таблицу с параметром auth, в котором лежит функция для проверки входящих запросов в формате HTTP. Функция вернет либо nil, если доступ запрещен, либо объект, содержащий аутентификационную информацию.

Пример. Укажем путь к файлу auth.lua с логикой для авторизации входящих запросов:

 
auth_external: {__file: auth.lua}

Содержание auth.lua определяется пользователем самостоятельно. Например, в файле может быть указана такая логика обработки:

 
– Функция авторизует пользователя по HTTP-заголовкуlocal function auth(request)local header = request.headers['custom_token']if header == nil then    return nil, "no header"endif header == 'error-injection' then    error('error-injection')endif header == 'invalid-answer' then    return 'invalid-answer'endif header == 'invalid-decision' then    return {        decision = 'invalid-decision',    }endif header == 'invalid-token' then    return {        decision = 'reject',        reason = 'invalid token',    }endif header == 'fallback-token' then    return {        decision = 'fallback',    }endif header == 'custom-response' then    return {        decision = 'reject',        status_code = 418,        reason = 'Hello, world!',        headers = {            ['custom'] = 'header',        }    }endreturn {    decision = 'accept',    account = {        is_user = true,        email = 'example@tarantool.org',        role_id = 1,    },}endreturn {    auth = auth,}

В этой секции указываются параметры авторизации внешних пользователей и систем через LDAP:

• domain - доменное имя, которое используется в доменном логине пользователя (user@domain).

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

• hosts - адрес подключения к серверу LDAP.

• use_active_directory - параметр, определяющий использование Active Directory (служба каталогов Microsoft). Значение по умолчанию: false.

  Если установлено значение true, используйте адрес электронной почты для входа в систему и атрибут Active Directory userprincipalname=email в качестве фильтра, где email - адрес электронной почты пользователя. Часть с именем пользователя в email будет распознана одинаково независимо от регистра (aBc@mail.ru и AbC@mail.ru - это один и тот же пользователь).

• use_tls - параметр, определяющий использование TLS. Значение по умолчанию: false.

• search_timeout - время ожидания ответа от сервера LDAP в секундах. Значение по умолчанию: 2.

• options - настройки LDAP. Параметр опционален. Доступные настройки:

  • LDAP_OPT_DEBUG_LEVEL - уровень отладки клиентской библиотеки.
  • LDAP_OPT_PROTOCOL_VERSION - версия протокола LDAP.
  • LDAP_OPT_X_TLS_CACERTDIR- путь к директории с корневыми сертификатами.
  • LDAP_OPT_X_TLS_CACERTFILE - полный путь к файлу корневого сертификата.
  • LDAP_OPT_X_TLS_NEWCTX - создание нового контекста библиотеки TLS.
  • LDAP_OPT_X_TLS_REQUIRE_CERT - стратегия проверки сертификатов. Принимает целое значение от 0 до 4, где:
    • 0 - LDAP_OPT_X_TLS_NEVER,
    • 1 - LDAP_OPT_X_TLS_HARD,
    • 2 - LDAP_OPT_X_TLS_DEMAND,
    • 3 - LDAP_OPT_X_TLS_ALLOW,
    • 4 - LDAP_OPT_X_TLS_TRY.

  Подробное описание этих настроек LDAP приведено на странице ldap_get_option().

• roles - описание ролей, которые будут назначаться пользователю в зависимости от групп LDAP, в которых он состоит. Вложенные параметры:

  • role - роль, назначенная пользователю или внешнему приложению для авторизованного доступа и действий в системе (читать подробнее про роли).
  • domain_groups - LDAP-группы, которые соответствуют указанной выше роли. В параметрах групп указываются:
    • cn (common name) - общее имя.
    • ou (organization unit name) - организационное подразделение или группа пользователей.
    • dc (domain component) - компонент домена.

  Если пользователь состоит сразу в нескольких LDAP-группах, он получает разрешения на действия из всех ролей, назначенных для этих групп.

Пример

В примере заданы настройки для:

• LDAP-группы tarantool с ролью admin;
• LDAP-группы svcaccts с ролью supervisor.

Для них указаны основные параметры авторизации, отключен Active Directory и отключен TLS:

 
ldap:  - domain: 'my.domain.ru'    organizational_units: ['tarantool']    hosts:      - server.my.domain.ru:389    use_tls: false    use_active_directory: false    search_timeout: 2    options:      - LDAP_OPT_DEBUG_LEVEL: 3    roles:      - domain_groups:          - 'cn=tarantool,ou=groups,dc=my,dc=domain,dc=ru'        role: 'admin'  - domain: 'my.domain.ru'    organizational_units: ['svcaccts']    hosts:      - server.my.domain.ru:389    use_tls: false    use_active_directory: false    search_timeout: 2    roles:      - domain_groups:          - 'cn=svcaccts,ou=groups,dc=my,dc=domain,dc=ru'        role: 'supervisor'

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

В этой секции настраивается авторизация внешних пользователей и систем через внешние провайдеры аутентификации (auth providers). Поддерживается встроенный тип провайдера keycloak: он проверяет JWT-токены, выданные внешним OpenID Connect (OIDC) провайдером (в частности, Keycloak), и сопоставляет группы пользователя с ролями TDG.

В секции можно задать несколько провайдеров keycloak — по одному на каждый идентификатор издателя токена (issuer). У каждого провайдера задаются уникальное имя (name), тип провайдера (type) и настройки провайдера (options). Если провайдеров несколько, для каждого провайдера также должен быть задан свой уникальный непустой идентификатор issuer.

Когда провайдеров несколько, TDG выбирает провайдера по непроверенному полю iss токена. Токен, выданный для другой настроенной области, проходит мимо предыдущего провайдера дальше по цепочке. Токен, у которого issuer совпадает, но проверка подписи не прошла, отклоняется и не может быть принят последующим провайдером. Два провайдера с одинаковым issuer считаются неоднозначными и отклоняются. Унаследованный пользовательский верификатор без issuer поддерживается, только если он единственный провайдер Keycloak.

 
auth_providers:  - name: keycloak-main    type: keycloak    options:      issuer: https://keycloak.example.com/realms/tdg      audience: [tdg-api]      groups_claim: realm_access.roles      roles:        - role: admin          groups:            - tdg-admins        - role: data-reader          groups:            - tdg-analysts            - tdg-support

• name (string) - уникальное имя провайдера, используется как идентификатор. Имя должно начинаться с буквы или _ и содержать только буквы, цифры, _ и -;
• type (string) - тип провайдера. Поддерживается встроенный тип keycloak. Пользовательский тип провайдера можно зарегистрировать с помощью Lua-функции account_provider.external_auth.register_provider_type(name, provider_type);
• options - опции провайдера:
  • issuer (string) - идентификатор издателя токена (URL области Keycloak). Значение поля iss токена должно точно совпадать с ним. Используется также как базовый адрес для документа OIDC discovery. Обязательный параметр;
  • audience (array) - идентификаторы, под которыми TDG известен в Keycloak. Всегда задаётся списком, даже для одного значения: audience: [tdg-api]. Токен принимается, если его поле aud содержит хотя бы одно из этих значений (сам aud может быть строкой или массивом). Обязательный параметр;
  • authorized_parties (array) - клиенты Keycloak, которым разрешено обращаться к TDG; значения сравниваются с полем azp токена (в нём Keycloak указывает id клиента, которому выдан токен). Опциональный параметр;
  • header_types (array) - допустимые значения заголовка JOSE typ. Для области Keycloak, настроенной на выдачу токена доступа типа OAuth, укажите header_types: [at+jwt]. Сравнение без учёта регистра. Опциональный параметр;
  • claim_types (array) - допустимые значения специфичного для Keycloak поля typ в payload JWT. Значение по умолчанию: [Bearer]. Если задано значение по умолчанию, принимаются только токены доступа Keycloak, а ID-токены того же клиента отклоняются. Чтобы принимать токен с любым значением поля typ (или без него), укажите для опции значение claim_types: []. Сравнение идет без учёта регистра;
  • roles (array) - правила сопоставления групп Keycloak с ролями TDG. Обязательный параметр. Нужно задать не менее одного правила. Поддерживаемые правила:
    • role (string) - имя системной или пользовательской роли TDG (например admin, supervisor или user), которая назначается пользователю;
    • groups - непустой массив групп (значения поля groups_claim), которые соответствуют указанной выше роли. Достаточно одного совпадения. Пользователю назначаются все роли, чьи правила совпали;
  • groups_claim (string) - имя поля (claim) JWT, в котором хранятся группы пользователя. Вложенность задаётся точками, например realm_access.roles. Точку в имени ключа можно экранировать символом \. Значение по умолчанию: groups;
  • clock_skew (number) - допустимая погрешность часов в секундах при проверке времени действия токена между TDG и Keycloak. Значение по умолчанию: 0;
  • max_token_age (number) - максимальное время жизни токена в секундах, отсчитывается от поля iat. Ограничивает время жизни токена на стороне TDG. Если параметр задан, токен без iat отклоняется. Опциональный параметр;
  • token_verifier (string) - имя верификатора, которым проверяется подпись токена. Значение по умолчанию: oidc_jwks.

Роль также можно сопоставить по идентификатору клиента Keycloak. Этот вариант подходит для сервисного аккаунта, который аутентифицируется через Client Credentials. Задайте groups_claim: azp и перечислите ожидаемые идентификаторы клиентов в опции groups. Здесь azp — это скалярное поле авторизованной стороны, а не роль Keycloak. Используйте также authorized_parties, если к TDG могут обращаться только выбранные клиенты. Предпочитайте azp специфичному для Keycloak полю клиента сервисного аккаунта: в Keycloak 21 он был переименован из clientId в client_id, тогда как azp содержит идентификатор клиента во всех версиях. Проверено с Keycloak версий 19–26.

Параметры встроенного верификатора oidc_jwks (проверяет подпись токена по ключам из документа OIDC discovery и набора ключей JWKS):

• discovery_url (string) - адрес документа OIDC discovery, из которого получают адрес набора ключей. Значение по умолчанию: <issuer>/.well-known/openid-configuration;
• jwks_url (string) - адрес набора ключей (JWKS) для развёртываний, где discovery недоступен. Несовместим с discovery_url;
• algorithms (array) - допустимые алгоритмы подписи: RS256, RS384, RS512 (RSA) и ES256, ES384, ES512 (ECDSA). Токен, подписанный другим алгоритмом, отклоняется. По умолчанию разрешены все шесть;
• jwks_ttl (number) - срок в секундах, в течение которого локальному снимку ключей можно доверять. По его истечении авторизация останавливается. Значение по умолчанию: 3600;
• refresh_interval (number) - интервал фонового обновления ключей в секундах. Значение по умолчанию: 60;
• min_refresh_interval (number) - минимальный интервал между обновлениями ключей в секундах. Ограничивает частоту обращений к Keycloak. Значение по умолчанию: 10;
• http_timeout (number) - время ожидания выполнения HTTP-запросов к Keycloak в секундах. Значение по умолчанию: 5;
• ca_file (string) - файл CA-сертификата для проверки TLS-сертификата Keycloak;
• ca_path (string) - каталог CA-сертификатов;
• ssl_cert (string) - клиентский сертификат для взаимной TLS;
• ssl_key (string) - ключ клиентского сертификата;
• verify_peer (boolean) - если задано значение true, проверяет сертификат Keycloak. Значение по умолчанию: true;
• verify_host (boolean) - если задано значение true, проверяет имя хоста в сертификате Keycloak. Значение по умолчанию: true;
• keepalive_idle (number) - время в секундах, в течение которого соединение остаётся бездействующим, прежде чем начнутся проверки TCP keepalive. Значение по умолчанию — из настроек HTTP-клиента;
• keepalive_interval (number) - интервал в секундах между проверками TCP keepalive. Значение по умолчанию — из настроек HTTP-клиента;
• low_speed_limit (number) - скорость передачи в байтах в секунду, ниже которой запрос прерывается. Значение по умолчанию — из настроек HTTP-клиента;
• low_speed_time (number) - время в секундах, в течение которого скорость передачи может оставаться ниже low_speed_limit. Значение по умолчанию — из настроек HTTP-клиента;
• max_header_name_len (number) - максимальная поддерживаемая длина имени заголовка ответа. Значение по умолчанию — из настроек HTTP-клиента;
• follow_location (boolean) - если задано значение true, следует редиректу ответа discovery или JWKS. Значение по умолчанию — из настроек HTTP-клиента;
• unix_socket (string) - Unix-сокет, через который выполняется обращение к провайдеру идентификации;
• accept_encoding (string) - поддерживаемые кодировки ответа. Пустая строка означает, что принимаются все кодировки, которые поддерживает curl;
• verbose (boolean) - если задано значение true, выводит трассировку HTTP-клиента в stderr. Трассировка содержит заголовки и тела запросов, поэтому включайте эту опцию только при отладке. Значение по умолчанию: false;

Пользовательский верификатор можно зарегистрировать при старте с помощью Lua-функции account_provider.keycloak.register_token_verifier(name, verifier). Верификатор задаётся в виде таблицы, которая содержит функцию create(options, provider_cfg), необязательную функцию validate_config и описание capabilities (в том числе options — список объявляемых опций, и параметр accepts_opaque_tokens для верификатора, принимающего непрозрачные токены). Верификатор, который публикует свои опции в capabilities.options, проверяется на опечатки, без них проверка не выполняется.

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

Пример:

 
pepper: 2d60ec7f-e9f0-4018-b354-c54907b9423d

vshard-timeout - отдельная секция, где указывается время, в течение которого модуль vshard ожидает сетевые запросы. Это время в секундах передается в функциях vshard.router.callro() и vshard.router.callrw().

Значение по умолчанию - 2 секунды:

 
vshard-timeout: 2