Справочник по конфигурации ¶

Содержание

Формат конфигурационных файлов ¶

Конфигурация TCS задается в файлах формата YAML.

Конфигурация хранится локально, либо обновляется посредством централизованного хранилища конфигурации (etcd или хранилище на основе Tarantool).

TCS использует конфигурационный механизм Tarantool, где поддерживается слияние конфигураций разных уровней. На уровне groups задаются настройки кластера (группы серверов). Далее на вложенных уровнях задаются индивидуальные настройки для каждого набора реплик и для каждого экземпляра. Получается следующая иерархия уровней:

groups:
  [name]:
    replicasets:
      [name]:
        instances:
          [name]:

где:

groups.[name] – содержит настройки кластера (группы) из одного или нескольких наборов реплик.
groups.[name].replicasets – содержит настройки для каждого набора реплик.
groups.[name].replicasets.[name].instances – содержит настройки для каждого экземпляра в наборе реплик.

Имена групп, наборов реплик и экземпляров могут быть любыми.

В конфигурационных файлах TCS можно задавать:

Любые конфигурационные параметры, которые поддерживаются в Tarantool Enterprise Edition 3.5.

Примечание

В данном справочнике описаны только те параметры Tarantool, которые часто требуются при настройке TCS на практике. Полный список всех параметров Tarantool см. в документации.
Параметры ролей, специфичных для TCS.

config ¶

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

etcd (параметры config.etcd.*)
хранилище на основе Tarantool (параметры config.storage.*)

Если конфигурация хранится локально, то эти параметры указывать не нужно.

См. подробнее в документации Tarantool.

Пример для etcd:

config:
  etcd:
    prefix: /tcs
    endpoints:
    - http://localhost:2379
    http:
      request:
        timeout: 1

config.etcd.prefix
config.etcd.endpoints
config.etcd.http.request.timeout

config.etcd.prefix ¶

Префикс для конфигурации TCS в etcd. Определяет путь в etcd, где будет храниться конфигурация кластера TCS.

Тип: string

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

Обязательный: нет

config.etcd.endpoints ¶

Список идентификаторов URI для соединения с etcd.

Тип: list

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

Обязательный: да

config.etcd.http.request.timeout ¶

Максимальное время ожидания соединения с etcd (в секундах).

Тип: integer

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

Обязательный: нет

credentials ¶

Здесь задаются привилегии для ролей и учетных записей пользователей кластера. См. подробнее в документации Tarantool.

Пример:

credentials:
  users:
    replicator:
      password: "secret-cluster-cookie"
      roles: [replication]
      privileges:
        - permissions: [execute]
          functions: [failover.execute]
    admin:
      password: "secret-cluster-cookie"
      roles: [super]

credentials.users.[name].password
credentials.users.[name].roles
credentials.users.[name].priviledges.permissions
credentials.users.[name].priviledges.functions

credentials.users.[name].password ¶

Пароль учетной записи.

Тип: string

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

Обязательный: нет

credentials.users.[name].roles ¶

Роли, доступные данной учетной записи.

Можно задавать следующие роли:

super
public
replication
sharding

См. подробнее в документации Tarantool.

Тип: array

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

Обязательный: нет

credentials.users.[name].priviledges.permissions ¶

Права на действия и объекты, доступные данной учетной записи.

Можно задавать следующие права:

read
write
create
alter
drop
execute
session
usage

См. подробнее в документации Tarantool.

Тип: array

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

Обязательный: нет

credentials.users.[name].priviledges.functions ¶

Имена функций, на которые распространяются права данной учетной записи.

Тип: array

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

Обязательный: нет

iproto ¶

Здесь задаются параметры работы протокола Tarantool iproto.

Пример:

iproto:
  advertise:
    peer:
      login: "replicator"
    client: 127.0.0.0:3331
  listen:
    - uri: 0.0.0.0:3331

iproto.advertise.peer.login
iproto.advertise.client
iproto.listen.uri

iproto.advertise.peer.login ¶

Имя учетной записи, которая используется для подключения к данному экземпляру.

См. подробнее в документации Tarantool.

Тип: string

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

Обязательный: нет

iproto.advertise.client ¶

Идентификатор URI с номером порта или доменный Unix-сокет, на котором экземпляр Tarantool виден клиентским приложениям.

Нельзя указывать адрес 0.0.0.0/[::] и номер порта 0.

См. подробнее в документации Tarantool.

Тип: string

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

Обязательный: нет

iproto.listen.uri ¶

Идентификатор URI для обработки входящих запросов.

См. подробнее в документации Tarantool.

Тип: string

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

Обязательный: да

memtx ¶

Здесь задаются параметры для работы движка Tarantool MemTX.

Пример:

memtx:
  memory: 2147483648

memtx.memory

memtx.memory ¶

Максимальный объем памяти, доступный для работы движка Tarantool MemTX (в байтах).

Тип: integer

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

Обязательный: нет

roles ¶

Здесь задается список ролей, которые может потребоваться назначить экземплярам кластера.

Можно задавать следующие роли:

tcs_roles/storage – хранилище данных
tcs_roles/scheduler – маршрутизатор запросов
tcs_roles/coordinator – координатор обработки сбоев
tcs_roles/stateboard – менеджер аварийного переключения
tcs_roles/cpu – сборщик метрик ЦПУ
roles.metrics-export – сборщик метрик кластера

Пример:

groups:
  storages:
    roles:
      [
        tcs_roles/storage,
        tcs_roles/stateboard,
        roles.metrics-export,
      ]

roles_cfg ¶

Здесь задаются настройки для каждой из ролей, перечисленных в параметре roles.

Пример:

roles_cfg:
  roles.metrics-export:
    http:
      - listen: 0.0.0.0:8081
        endpoints:
          - path: /metrics
            format: prometheus
  tcs_roles/storage:
    arrow_flight_sql:
      listen: 0.0.0.0:50051
      credentials:
        username: tcs
        password: tcs
    http:
      enabled: true
      listen: 0.0.0.0:7777
      credentials:
        username: tcs
        password: tcs

Параметры репликации ¶

Эти параметры задаются на соответствующем уровне конфигурации:

в groups.[name].replicasets (для всех наборов реплик);
в groups.[name].replicasets.[name] (для конкретного набора реплик).

Пример:

groups:
  storages:
    replicasets:
      replicaset1:
        replication:
          failover: manual
        leader: instance11
      replicaset2:
        replication:
          failover: manual
        leader: instance21

replication.failover
leader

replication.failover ¶

Вид аварийного переключения в случае сбоя экземпляра в наборе реплик:

manual – ручной
supervised – автоматический (требует запуска отдельного экземпляра Tarantool, который выступает в качестве координатора обработки сбоев)

Для автоматического режима также можно указать дополнительные параметры:

failover:
  call_timeout: 1
  connect_timeout: 1
  lease_interval: 10
  probe_interval: 1
  renew_interval: 10
  stateboard:
    keepalive_interval: 15
    renew_interval: 3

Для значений параметров должна соблюдаться следующая формула:

lease_interval > probe_interval + renew_interval

Описания параметров см. в документации Tarantool.

Тип: string

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

Обязательный: нет

leader ¶

Имя экземпляра, который является лидером репликации в данном наборе реплик.

Тип: string

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

Обязательный: да

Параметры ролей ¶

Список ролей для кластера TCS задается в параметре roles.

Параметры конкретной роли задаются в role_cfg на соответствующем уровне конфигурации, например:

в groups.[name] – для данной роли на всех экземплярах кластера;
в groups.[name].replicasets.[name].instances.[name] – для данной роли в рамках конкретного экземпляра.

Роль tcs_roles/cpu ¶

Роль tcs_roles/cpu выполняет функции сборщика метрик ЦПУ.

Конфигурационные параметры у этой роли отсутствуют.

Роль tcs_roles/stateboard ¶

Роль tcs_roles/stateboard выполняет функции актуализации статуса экземпляра и продления разрешения (lease) на стороне etcd.

Пример:

roles_cfg:
  tcs_roles/stateboard:
    lease_ttl: 5
    lease_renew_interval: 1
    state_renew_interval: 1

lease_ttl
lease_renew_interval
state_renew_interval

lease_ttl¶

Время (в секундах), в течение которого разрешение (lease) остается валидным на стороне etcd в случае, если разрешение не было обновлено.

Тип: integer

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

Обязательный: нет

lease_renew_interval¶

Частота (в секундах), с которой обновляется разрешение (lease) в etcd.

Тип: integer

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

Обязательный: нет

state_renew_interval¶

Частота (в секундах), с которой текущий статус экземпляра отсылается в etcd.

Тип: integer

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

Обязательный: нет

Роль tcs_roles/storage ¶

Роль tcs_roles/storage выполняет функции хранилища данных.

Пример:

roles_cfg:
  tcs_roles/storage:
    enable_sharding: false
    max_concurrent_queries: 10000
    rv_update_ms: 3
    rv_gc_ms: 100
    arrow_flight_sql:
      listen: 0.0.0.0:50051
      advertise:
        client: 127.0.0.1:50051
        sharding:
          uri: 127.0.0.1:50051
      credentials:
        username: tcs
        password: tcs
    http:
      enabled: true
      listen: 0.0.0.0:7777
      advertise:
        client:
          127.0.0.1:7777
        sharding:
          uri: 127.0.0.1:7777
      credentials:
        username: tcs
        password: tcs
    transport: tls
    tls_version: ["TLSv1.2", "TLSv1.3"]
    tls_cert_file: certs/cert.pem
    tls_ca_file: certs/ca.pem
    tls_key_file: certs/key.pem
    tls_ciphers: 'GOST2012-MAGMA-MAGMAOMAC:GOST2012-KUZNYECHIK-KUZNYECHIKOMAC:LEGACY-GOST2012-GOST8912-GOST8912:IANA-GOST2012-GOST8912-GOST8912:GOST2001-GOST89-GOST89'
    tls_ciphersuites: ''

enable_sharding¶

Включен ли режим шардирования в наборе реплик хранилищ.

Тип: boolean

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

Обязательный: нет

max_concurrent_queries¶

Количество запросов, которые хранятся и исполняются параллельно.

Тип: integer

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

Обязательный: нет

rv_gc_ms¶

Интервал в миллисекундах для удаления устаревших представлений для чтения (read view).

Тип: integer

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

Обязательный: нет

rv_update_ms¶

Интервал в миллисекундах для обновления представления для чтения (read view).

Тип: integer

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

Обязательный: нет

arrow_flight_sql.listen¶

Идентификатор URI с номером порта для соединений по SQL-протоколу Apache Arrow Flight. Это технический адрес общего назначения, без каких-либо конкретных целей.

Тип: integer

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

Обязательный: да

arrow_flight_sql.credentials.username¶

Логин для соединений по SQL-протоколу Apache Arrow Flight.

Тип: string

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

Обязательный: да

arrow_flight_sql.credentials.password¶

Пароль для соединений по SQL-протоколу Apache Arrow Flight.

Тип: string

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

Обязательный: да

arrow_flight_sql.session_expiration_secs¶

Максимальная длительность сессии в секундах для соединений по SQL-протоколу Apache Arrow Flight.

Значение этого параметра (по умолчанию – 8 часов) имеет смысл увеличивать, если в рамках сессии подразумевается выполнение какого-то особо длительного процесса, который может потребовать больше 8 часов (к примеру, заливка данных ETL).

Тип: integer

Значение по умолчанию: 28800 (8 часов)

Обязательный: да

arrow_flight_sql.advertise.client¶

Идентификатор URI с номером порта или доменный Unix-сокет, на котором экземпляр хранилища виден клиентским приложениям в соединениях по SQL-протоколу Apache Arrow Flight.

Нельзя указывать адрес 0.0.0.0/[::] и номер порта 0.

Тип: string

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

Обязательный: нет

arrow_flight_sql.advertise.sharding.uri¶

Идентификатор URI с номером порта для связи экземпляров Scheduler с данным экземпляром хранилища по SQL-протоколу Apache Arrow Flight.

Этот параметр используется для всех режимов работы кластера:

в режиме проксирования (mode: proxy) – для перенаправления запросов от клиентов на экземпляры хранилищ;
в режиме шардирования (mode: sharded) – для связи экземпляра Scheduler с экземплярами Storage в шарде.

Тип: string

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

Обязательный: нет

http.enabled¶

Включены ли входящие соединения по протоколу HTTP для всех HTTP-адресов (/sql, /insert, /metrics).

См. также параметр transport.

Тип: boolean

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

Обязательный: нет

http.listen¶

URI с номером порта для передачи метрик TCS. См. подробнее в разделе Настройка портов для мониторинга.

Тип: string

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

Обязательный: да, если указан параметр http.enabled = true

http.advertise.client¶

Идентификатор URI с номером порта или доменный Unix-сокет, на котором экземпляр хранилища виден клиентским приложениям в соединениях по протоколу HTTP.

Нельзя указывать адрес 0.0.0.0/[::] и номер порта 0.

Тип: string

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

Обязательный: нет

http.advertise.sharding.uri¶

Идентификатор URI с номером порта для связи экземпляров Scheduler с данным экземпляром хранилища по протоколу HTTP.

Этот параметр используется для всех режимов работы кластера.

Тип: string

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

Обязательный: нет

http.credentials.username¶

Логин для соединений по протоколу HTTP.

Тип: string

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

Обязательный: да

http.credentials.password¶

Пароль для соединений по протоколу HTTP.

Тип: string

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

Обязательный: да

transport¶

Протокол приема входящих сообщений:

plain (по умолчанию) – входящие сообщения будут приниматься по HTTP.
tls – входящие сообщения будут приниматься по HTTPS. Если указано это значение, то обязательно должны быть указаны tls_cert_file и tls_key_file.

См. также параметр http.enabled.

Тип: string

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

Обязательный: нет

tls_version¶

Поддерживаемые версии протокола TLS. Можно указать "TLSv1.2" и/или "TLSv1.3". Если версии не заданы, то считается, что заданы обе версии.

См. также параметры tls_ciphers и tls_ciphersuites.

Тип: array

Значение по умолчанию: ["TLSv1.2", "TLSv1.3"]

Обязательный: нет

tls_cert_file¶

Путь к TLS-сертификату в формате PEM.

Тип: string

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

Обязательный: да, если используется TLS

tls_ca_file¶

Путь к TLS-сертификату удостоверяющего центра в формате PEM.

Тип: string

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

Обязательный: да, если используется самоподписанный сертификат

tls_key_file¶

Путь к приватному ключу от сертификата.

Тип: string

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

Обязательный: да, если используется TLS

tls_ciphers¶

Список шифров для версий TLS до 1.2. Шифры разделяются символом :.

Этот параметр нельзя указывать, если не задана версия TLS 1.2 (см. параметр tls_version).

Тип: list

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

Обязательный: нет

tls_ciphersuites¶

Список шифров для TLS 1.3. Шифры разделяются символом :.

Этот параметр нельзя указывать, если не задана версия TLS 1.3 (см. параметр tls_version).

Тип: list

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

Обязательный: нет

Роль roles.metrics-export ¶

Роль roles.metrics-export выполняет функции сборщика метрик кластера.

Пример:

roles_cfg:
  roles.metrics-export:
    http:
      - listen: 0.0.0.0:8081
        endpoints:
          - path: /metrics
            format: prometheus

http.listen
http.endpoints.path
http.endpoints.format

http.listen¶

URI с номером порта для передачи метрик Tarantool. См. подробнее в разделе Настройка портов для мониторинга.

Тип: string

Значение по умолчанию: '0.0.0.0:8081'

Обязательный: нет

http.endpoints.path¶

Постфикс для HTTP-адреса (endpoint) для передачи метрик, например /metrics. Значение обязательно должно начинаться с символа /.

Тип: string

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

Обязательный: да

http.endpoints.format¶

Формат передачи метрик. Можно задавать следующие значения:

prometheus
json

Тип: string

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

Обязательный: да

Роль tcs_roles/scheduler ¶

Роль tcs_roles/scheduler выполняет функции маршрутизации запросов между внешними пользователями и экземплярами хранилищ.

Примеры:

в кластере без шардирования:

roles_cfg:
  tcs_roles/scheduler:
    mode:
      proxy:
        target_replicaset: storage-replicaset1
    http:
      listen: 0.0.0.0:7780
      credentials:
        username: tcs
        password: tcs

в шардированном кластере:

roles_cfg:
  tcs_roles/scheduler:
    mode:
      sharded:
        bucket_count: 1000
    arrow_flight_sql:
      listen: 0.0.0.0:50057
      credentials:
        username: tcs
        password: tcs
    http:
      listen: 0.0.0.0:7783
      credentials:
        username: tcs
        password: tcs

mode.*
mode.proxy.target_replicaset
mode.sharded.bucket_count
arrow_flight_sql.*
http.*

mode.*¶

Режим работы экземпляров Scheduler в кластере:

proxy – режим проксирования; в этом случае нужно также указать параметр mode.proxy.target_replicaset.
sharded – режим шардирования; в этом случае нужно также указать параметр mode.sharded.bucket_count.

mode.proxy.target_replicaset¶

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

Этот параметр указывается только для режима mode: proxy.

Тип: string

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

Обязательный: да, если указан режим mode: proxy

mode.sharded.bucket_count¶

Количество бакетов для шардирования данных. Значение должно быть значительно (на 2-3 порядка) больше числа шардов.

Этот параметр указывается только для режима mode: sharded.

Тип: string

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

Обязательный: да, если указан режим mode: sharded

arrow_flight_sql.*¶

См. аналогичную группу параметров для роли tcs_roles/storage:

arrow_flight_sql.listen
arrow_flight_sql.credentials.username
arrow_flight_sql.credentials.password
arrow_flight_sql.session_expiration_secs

http.*¶

См. аналогичную группу параметров для роли tcs_roles/storage:

http.enabled
http.listen
http.credentials.username
http.credentials.password

Version:

lease_ttl¶

lease_renew_interval¶

state_renew_interval¶

enable_sharding¶

max_concurrent_queries¶

rv_gc_ms¶

rv_update_ms¶

arrow_flight_sql.listen¶

arrow_flight_sql.credentials.username¶

arrow_flight_sql.credentials.password¶

arrow_flight_sql.session_expiration_secs¶

arrow_flight_sql.advertise.client¶

arrow_flight_sql.advertise.sharding.uri¶

http.enabled¶

http.listen¶

http.advertise.client¶

http.advertise.sharding.uri¶

http.credentials.username¶

http.credentials.password¶

transport¶

tls_version¶

tls_cert_file¶

tls_ca_file¶

tls_key_file¶

tls_ciphers¶

tls_ciphersuites¶

http.listen¶

http.endpoints.path¶

http.endpoints.format¶

mode.*¶

mode.proxy.target_replicaset¶

mode.sharded.bucket_count¶

arrow_flight_sql.*¶

http.*¶