Конфигурация

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

Существует два подхода к конфигурации Tarantool:

• Начиная с версии 3.0: в формате YAML.

  YAML-конфигурация позволяет описать полную топологию кластера и задать все параметры конфигурации. Можно использовать локальную конфигурацию в YAML-файле для каждого экземпляра или хранить данные конфигурации в надежном централизованном хранилище.

• В версии 2.11 и ранее: в коде с помощью API box.cfg.

  В этом случае конфигурация задается в Lua-скрипте инициализации.

YAML-конфигурация описывает полную топологию кластера Tarantool. Топология кластера включает следующие элементы, начиная с нижнего уровня:

 
groups:  group001:    replicasets:      replicaset001:        instances:          instance001:            # ...          instance002:            # ...

• instances

  Экземпляр представляет один запущенный экземпляр Tarantool. Он хранит данные или может выступать в роли маршрутизатора для обработки CRUD-запросов в шардированном кластере.

• replicasets

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

• groups

  Группа позволяет организовывать наборы реплик. Например, в шардированном кластере одна группа может содержать экземпляры хранилищ, а другая — маршрутизаторы, используемые для обработки CRUD-запросов.

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

В этом разделе приведен обзор настройки Tarantool в YAML-файле.

В примере ниже показана конфигурация отдельного экземпляра Tarantool:

 
# yaml-language-server: $schema=https://download.tarantool.org/tarantool/schema/config.schema.jsongroups:  group001:    replicasets:      replicaset001:        instances:          instance001:            iproto:              listen:              - uri: '127.0.0.1:3301'

• Секция instances включает только один экземпляр с именем instance001. Параметр iproto.listen.uri задает адрес для прослушивания входящих запросов.

• Секция replicasets содержит один набор реплик с именем replicaset001.

• Секция groups содержит одну группу с именем group001.

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

• Экземпляр

  Чтобы применить определенные параметры конфигурации к конкретному экземпляру, задайте эти параметры только для данного экземпляра. В примере ниже iproto.listen применяется только к instance001.

 
groups:  group001:    replicasets:      replicaset001:        instances:          instance001:            iproto:              listen:              - uri: '127.0.0.1:3301'

• Набор реплик

  В этом примере iproto.listen действует для всех экземпляров в replicaset001.

 
groups:  group001:    replicasets:      replicaset001:        iproto:          listen:          - uri: '127.0.0.1:3301'        instances:          instance001: { }

• Группа

  В этом примере iproto.listen действует для всех экземпляров в group001.

 
groups:  group001:    iproto:      listen:      - uri: '127.0.0.1:3301'    replicasets:      replicaset001:        instances:          instance001: { }

• Глобальный уровень

  В этом примере iproto.listen применяется ко всем экземплярам кластера.

 
iproto:  listen:  - uri: '127.0.0.1:3301'groups:  group001:    replicasets:      replicaset001:        instances:          instance001: { }

Области конфигурации выше перечислены в порядке приоритета — от высшего к низшему. Например, если один и тот же параметр задан на уровне экземпляра и на глобальном уровне, значение экземпляра имеет приоритет над глобальным значением.

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

 
credentials:  users:    replicator:      password: 'topsecret'      roles: [replication]iproto:  advertise:    peer:      login: replicatorreplication:  failover: manualgroups:  group001:    replicasets:      replicaset001:        leader: instance001        instances:          instance001:            iproto:              listen:              - uri: '127.0.0.1:3301'          instance002:            iproto:              listen:              - uri: '127.0.0.1:3302'          instance003:            iproto:              listen:              - uri: '127.0.0.1:3303'

• credentials (глобальный уровень)

  Эта секция используется для создания пользователя replicator и назначения ему указанной роли. Эти параметры применяются глобально ко всем экземплярам.

• iproto (глобальный уровень, экземпляр)

  Секция iproto задана как на глобальном уровне, так и на уровне экземпляра. Параметр iproto.advertise.peer задает параметры, используемые экземпляром для подключения к другому экземпляру в качестве реплики, например, URI, логин и пароль или SSL-параметры. В примере выше параметр включает только login. URI берется из iproto.listen, заданного на уровне экземпляра.

• replication (глобальный уровень)

  Глобальный параметр replication.failover задает ручную отказоустойчивость для всех наборов реплик.

• leader (набор реплик)

Параметр <replicaset-name>.leader задает мастер-экземпляр для replicaset001.

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

Роли могут быть встроенными ролями Tarantool, ролями из сторонних Lua-модулей или пользовательскими ролями, разработанными как часть кластерного приложения. В этом разделе описывается, как включать и настраивать роли. О разработке пользовательских ролей см. Прикладные роли.

Чтобы включить или отключить роль для конкретного экземпляра или набора экземпляров, используйте параметр конфигурации roles. В примере ниже показано включение роли roles.crud-router, предоставляемой модулем CRUD, с помощью параметра roles:

 
roles: [ roles.crud-router ]app:  module: routersharding:  roles: [ router ]replicasets:  router-a:    instances:      router-a-001:        iproto:          listen:          - uri: '127.0.0.1:3301'          advertise:            client: '127.0.0.1:3301'

Аналогично можно включить роль roles.crud-storage, чтобы экземпляры работали в качестве CRUD-хранилищ:

 
roles: [ roles.crud-storage ]  app:    module: storage  sharding:    roles: [ storage ]  replication:    failover: manual  replicasets:    storage-a:      leader: storage-a-001      instances:        storage-a-001:          iproto:            listen:            - uri: '127.0.0.1:3302'            advertise:              client: '127.0.0.1:3302'        storage-a-002:          iproto:            listen:            - uri: '127.0.0.1:3303'            advertise:              client: '127.0.0.1:3303'    storage-b:      leader: storage-b-001      instances:        storage-b-001:          iproto:            listen:            - uri: '127.0.0.1:3304'            advertise:              client: '127.0.0.1:3304'        storage-b-002:          iproto:            listen:            - uri: '127.0.0.1:3305'            advertise:              client: '127.0.0.1:3305'routers:  roles: [ roles.crud-router ]  app:    module: router  sharding:    roles: [ router ]  replicasets:    router-a:      instances:        router-a-001:          iproto:            listen:            - uri: '127.0.0.1:3301'            advertise:              client: '127.0.0.1:3301'

Пример на GitHub: sharded_cluster_crud

Параметр roles_cfg позволяет задать конфигурацию для каждой роли. В этом параметре имя роли является ключом, а конфигурация роли — значением.

В примере ниже показано, как включить статистику по вызываемым операциям, задав конфигурацию роли roles.crud-router:

 
roles:- roles.crud-router- roles.metrics-exportroles_cfg:  roles.crud-router:    stats: true    stats_driver: metrics    stats_quantiles: true

Пример на GitHub: sharded_cluster_crud_metrics

Как и большинство параметров конфигурации, роли и их конфигурации можно задавать на разных уровнях. С учетом того, что параметр roles имеет тип array, а roles_cfg — тип map, существуют особенности применения конфигурации:

• Для roles роль экземпляра имеет приоритет над ролями, заданными на другом уровне. В примере ниже instance001 имеет только role3:

   
  # ...replicaset001:  roles: [ role1, role2 ]  instances:    instance001:      roles: [ role3 ]

  Подробнее о порядке приоритета для разных областей применения конфигурации см. в configuration_scopes.

• Для roles_cfg применяются следующие правила:

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

    В примере ниже role1.greeting равно 'Hi':

     
    # ...replicaset001:  roles_cfg:    role1:      greeting: 'Hello'  instances:    instance001:      roles: [ role1 ]      roles_cfg:        role1:          greeting: 'Hi'

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

    В примере ниже instance001 имеет role1.greeting со значением 'Hi' и role2.farewell со значением 'Bye':

     
    # ...replicaset001:  roles_cfg:    role1:      greeting: 'Hi'  instances:    instance001:      roles: [ role1, role2 ]      roles_cfg:        role2:          farewell: 'Bye'

Метки позволяют добавлять пользовательские атрибуты в конфигурацию кластера. Метка — это произвольная пара key: value со строковыми ключом и значением.

 
labels:  dc: 'east'  production: 'false'

Метки можно задавать в любой области конфигурации. Экземпляр получает метки из всех областей, к которым он принадлежит. Секция labels в области группы или набора реплик применяется ко всем экземплярам группы или набора реплик. Чтобы переопределить эти метки на уровне экземпляра или добавить специфичные для экземпляра метки, задайте еще одну секцию labels в области экземпляра.

 
labels:  dc: 'east'  production: 'false'

Пример на GitHub: labels

Чтобы получить доступ к меткам экземпляра из кода приложения, вызовите функцию config:get():

 
myapp:instance001> require('config'):get('labels')---- production: 'true'  rack: '10'  dc: east...

Метки можно использовать для направления вызовов функций к экземплярам, соответствующим определенным критериям, с помощью модуля connpool.

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

• instance_name
• replicaset_name
• group_name

Чтобы сослаться на эти переменные в файле конфигурации, заключите их в двойные фигурные скобки с пробелами. В примере ниже {{ instance_name }} заменяется на instance001.

 
groups:  group001:    replicasets:      replicaset001:        instances:          instance001:            snapshot:              dir: ./var/{{ instance_name }}/snapshots            wal:              dir: ./var/{{ instance_name }}/wals

В результате пути к снимкам состояния и журналам предзаписи различаются для разных экземпляров.

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

Условные части задаются в секции конфигурации conditional на глобальном уровне. Она включает одну или несколько подсекций if. Каждая подсекция if определяет условия и части конфигурации, которые применяются к экземплярам, удовлетворяющим этим условиям.

В примере ниже показана секция conditional для обновления кластера с Tarantool 3.0.0 до Tarantool 3.1.0:

• Пользовательская метка upgraded имеет значение true на экземплярах, работающих под управлением Tarantool 3.1.0 или более поздней версии. На более старых версиях она имеет значение false.

• Два параметра compat, появившиеся в версии 3.1.0, заданы для экземпляров с Tarantool 3.1.0. На более старых версиях они вызвали бы ошибку.

 
conditional:  - if: tarantool_version < 3.1.0    labels:      upgraded: 'false'  - if: tarantool_version >= 3.1.0    labels:      upgraded: 'true'    compat:      box_error_serialize_verbose: 'new'      box_error_unpack_type_and_code: 'new'

Пример на GitHub: conditional

В секциях if можно использовать одну переменную — tarantool_version. Она содержит номер версии Tarantool в формате из трех чисел и сравнивается со значениями того же формата с помощью операторов сравнения >, <, >=, <=, == и !=. Сложные условия можно записывать с помощью логических операторов || (ИЛИ) и && (И). Для задания приоритета операторов можно использовать круглые скобки ().

 
conditional:  - if: (tarantool_version > 3.2.0 || tarantool_version == 3.1.3) && tarantool_version <= 3.99.0    -- < ... >

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

Пример:

 
conditional:  - if: tarantool_version >= 3.0.0    labels:        version: '3.0' # applies to versions >= 3.0.0 and < 3.1.0  - if: tarantool_version >= 3.1.0    labels:        version: '3.1+' # applies to versions >= 3.1.0

Для каждого параметра конфигурации Tarantool предоставляет два набора предопределенных переменных окружения:

• TT_<CONFIG_PARAMETER>. Эти переменные используются для подстановки параметров, заданных в файле конфигурации. Это означает, что данные переменные имеют более высокий приоритет, чем параметры, заданные в файле конфигурации.

• TT_<CONFIG_PARAMETER>_DEFAULT. Эти переменные используются для задания значений по умолчанию для параметров, отсутствующих в файле конфигурации. Эти переменные имеют более низкий приоритет, чем параметры, заданные в файле конфигурации.

Например, TT_IPROTO_LISTEN и TT_IPROTO_LISTEN_DEFAULT соответствуют параметру iproto.listen. TT_SNAPSHOT_DIR и TT_SNAPSHOT_DIR_DEFAULT соответствуют параметру snapshot.dir. Чтобы просмотреть все поддерживаемые переменные окружения, выполните команду tarantool с параметром --help-env-list.

 
$ tarantool --help-env-list

Ниже приведено несколько примеров, показывающих, как задавать переменные окружения разных типов: строка, число, массив или ассоциативный массив(map).

В этом примере TT_LOG_LEVEL используется для задания уровня логирования CRITICAL:

 
$ export TT_LOG_LEVEL='crit'

В этом примере уровень логирования CRITICAL задается с помощью соответствующего числового значения:

 
$ export TT_LOG_LEVEL=3

В примерах ниже показано, как задать переменную TT_SHARDING_ROLES, принимающую значение типа массив. Массивы можно передавать двумя способами: в простом формате ...

 
$ export TT_SHARDING_ROLES=router,storage

... или формате JSON:

 
$ export TT_SHARDING_ROLES='["router", "storage"]'

Простой формат применим только к массивам, содержащим скалярные значения.

Чтобы присвоить переменным окружения значения типа ассоциативный массив (map), также можно использовать простой или JSON формат. В примере ниже TT_LOG_MODULES задает разные уровни логирования для разных модулей в простом формате:

 
$ export TT_LOG_MODULES=module1=info,module2=error

В следующем примере TT_ROLES_CFG используется для задания значения пользовательской конфигурации [роли]((#configuration_application) в JSON формате:

 
$ export TT_ROLES_CFG='{"greeter":{"greeting":"Hello"}}'

Простой формат применим только к ассоциативным массивам (maps), содержащим скалярные значения.

В примере ниже TT_IPROTO_LISTEN используется для задания значений хоста и порта прослушивания:

 
$ export TT_IPROTO_LISTEN=['{"uri":"127.0.0.1:3311"}']

Также можно передать несколько адресов прослушивания:

 
$ export TT_IPROTO_LISTEN=['{"uri":"127.0.0.1:3311"}','{"uri":"127.0.0.1:3312"}']

Tarantool позволяет хранить данные конфигурации в одном месте с использованием хранилища на базе Tarantool или etcd. Для этого необходимо:

1. Настроить централизованное хранилище конфигурации.

2. Опубликовать конфигурацию кластера в хранилище.

3. Настроить подключение к хранилищу, предоставив локальную YAML-конфигурацию с адресом конечной точки (endpoint) и префиксом ключа в секции config:

 
config:  etcd:    endpoints:    - http://localhost:2379    prefix: /myapp    username: sampleuser    password: '123456'    http:      request:        timeout: 3

 
config:  etcd:    endpoints:    - http://localhost:2379    prefix: /myapp

Подробнее см. в руководстве: Centralized configuration storages.

Параметры конфигурации Tarantool применяются из нескольких источников со следующим приоритетом, от высшего к низшему:

• Переменные окружения TT_*.
• Конфигурация из локального YAML-файла.
• Централизованная конфигурация.
• Переменные окружения TT_*_DEFAULT.

Если один и тот же параметр задан в двух или более источниках, применяется параметр с наивысшим приоритетом.