Модуль config

Начиная с: 3.0.0

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

С помощью ролей config.storage можно настроить централизованное хранилище конфигурации на базе Tarantool и взаимодействовать с этим хранилищем через API модуля config.

Для загрузки модуля config используйте директиву require():

 
local config = require('config')

Затем можно обратиться к его API:

 
config:reload()

Ниже приведен перечень функций модуля config.

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

• Для текущего экземпляра get() возвращает его конфигурацию с учетом переменных окружения.
• Для удаленного экземпляра get() учитывает только конфигурацию кластера и игнорирует переменные окружения.

Параметры:

• param (string) — имя параметра конфигурации
• opts (table) — передаваемые параметры. Доступны следующие параметры:
  • instance (начиная с 3.1.0) – имя удаленного экземпляра, конфигурацию которого требуется получить

Возвращает

конфигурация экземпляра

Примеры:

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

 
app:instance001> require('config'):get()---- fiber:    io_collect_interval: null    too_long_threshold: 0.5    top:      enabled: false  # Other configuration values  # ...

В этом примере показано, как получить значение параметра iproto.listen:

 
app:instance001> require('config'):get('iproto.listen')---- - uri: 127.0.0.1:3301...

config.get() можно также использовать в коде приложения для получения значения пользовательского параметра конфигурации.

Получение состояния текущего экземпляра в контексте конфигурации.

Параметры:

• version (string) — (начиная с 3.1.0) версия возвращаемой информации. Аргумент version может принимать одно из следующих значений:
  • v1 (по умолчанию): поле meta, возвращаемое info(), содержит информацию о последней загруженной конфигурации
  • v2: поле meta, возвращаемое info(), содержит два поля:
    • поле last содержит информацию о последней загруженной конфигурации
    • поле active содержит информацию о последней успешно примененной конфигурации

Возвращает

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

• status – один из следующих статусов:
  • ready – конфигурация успешно применена
  • check_warnings – конфигурация применена с предупреждениями
  • check_errors – конфигурация не может быть применена из-за ошибок в конфигурации
• meta – дополнительная информация о конфигурации
• alerts – предупреждения или ошибки, возникшие при попытке применить конфигурацию
• hierarchy – (начиная с 3.3.0) таблица, отображающая имена группы, набора реплик и самого экземпляра. Эти имена берутся непосредственно из опции CLI --name (или переменной окружения TT_INSTANCE_NAME) и конфигурации кластера. Это означает, что они всегда присутствуют при использовании YAML-конфигурации, независимо от состояния базы данных (обновлена ли она, доступна ли для записи или нет).

Ниже приведено несколько примеров, демонстрирующих возможный вывод info().

Пример: без предупреждений или ошибок конфигурации

В примере ниже состояние экземпляра — ready, предупреждения отсутствуют:

 
app:instance001> require('config'):info('v2')---- status: ready  meta:    last: &0    active: *0  alerts:  hierarchy:    group: group-001    replicaset: replicaset-001    instance: instance-001...

Пример: предупреждения конфигурации

В примере ниже состояние экземпляра — check_warnings. Раздел alerts сообщает, что привилегии на спейс bands для пользователя sampleuser не могут быть предоставлены, так как спейс bands еще не создан:

 
app:instance001> require('config'):info('v2')---- status: check_warnings  meta:    last: &0    active: *0  alerts:  - type: warn    message: box.schema.user.grant("sampleuser", "read,write", "space", "bands") has      failed because either the object has not been created yet, a database schema      upgrade has not been performed, or the privilege write has failed (separate      alert reported)    timestamp: 2024-07-03T18:09:18.826138+0300  hierarchy:    group: group-001    replicaset: replicaset-001    instance: instance-001...

Это предупреждение очищается при создании спейса bands.

Пример: ошибки конфигурации

В примере ниже состояние экземпляра — check_errors. Раздел alerts сообщает, что параметр конфигурации log.level имеет некорректное значение:

 
app:instance001> require('config'):info('v2')---- status: check_errors  meta:    last:    active:  alerts:  - type: error    message: '[cluster_config] log.level: Got 8, but only the following values are      allowed: 0, fatal, 1, syserror, 2, error, 3, crit, 4, warn, 5, info, 6, verbose,      7, debug'    timestamp: 2024-07-03T18:13:19.755454+0300  hierarchy:    group: group-001    replicaset: replicaset-001    instance: instance-001...

Пример: ошибки конфигурации (централизованное хранилище конфигурации)

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

 
app:instance001> require('config'):info('v2')---- status: check_errors  meta:    last:      etcd:        mod_revision:          /myapp/config/all: 5        revision: 5    active:      etcd:        mod_revision:          /myapp/config/all: 2        revision: 4  alerts:  - type: error    message: 'etcd source: invalid config at key "/myapp/config/all": [cluster_config]      groups.group001.replicasets.replicaset001.instances.instance001.log.level: Got      8, but only the following values are allowed: 0, fatal, 1, syserror, 2, error,      3, crit, 4, warn, 5, info, 6, verbose, 7, debug'    timestamp: 2024-07-03T15:22:06.438275Z  hierarchy:    group: group001    replicaset: replicaset001    instance: instance001...

Начиная с: 3.1.0

Получение URI текущего или удаленного экземпляра.

Параметры:

• uri_type (string) — тип URI. Поддерживаются следующие типы URI:
  • peer – URI, используемый для объявления экземпляра другим членам кластера. См. также: iproto.advertise.peer.
  • sharding – URI, используемый для объявления текущего экземпляра роутеру и ребалансировщику. См. также: iproto.advertise.sharding.
• opts (table) — передаваемые параметры. Доступны следующие параметры:
  • instance – имя удаленного экземпляра, URI которого требуется получить

Возвращает

таблица, представляющая URI экземпляра. Эта таблица может включать следующие поля:

• uri – URI экземпляра
• login – имя пользователя для подключения к этому экземпляру
• password – пароль пользователя
• params – параметры URI, используемые для подключения к этому экземпляру

Пример:

В примере ниже показано, как получить URI, используемый для объявления storage-b-003 другим членам кластера:

 
local config = require('config')config:instance_uri('peer', { instance = 'storage-b-003' })

Начиная с: 3.1.0

Вывод списка всех экземпляров кластера.

Возвращает

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

• instance_name – имя экземпляра
• replicaset_name – имя набора реплик, в который входит экземпляр
• group_name – имя группы, в которую входит экземпляр

Пример:

В примере ниже показано, как использовать instances() для получения имен всех экземпляров кластера, создания подключения к каждому экземпляру с помощью модуля connpool и записи URI подключений в лог с помощью модуля log:

 
local config = require('config')local connpool = require('experimental.connpool')local log = require('log')for instance_name in pairs(config:instances()) do    local conn = connpool.connect(instance_name)    log.info("Connection URI for %q: %s:%s", instance_name, conn.host, conn.port)end

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

 
local config = require('config')local connpool = require('experimental.connpool')local log = require('log')for instance_name, def in pairs(config:instances()) do    if def.replicaset_name == 'storage-b' then        local conn = connpool.connect(instance_name)        log.info("Connection URI for %q: %s:%s", instance_name, conn.host, conn.port)    endend

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

• Значение параметра конфигурации, специфичного для данного экземпляра, изменено в конфигурации кластера.
• Новый экземпляр добавлен в набор реплик.
• Обновлена централизованная конфигурация при отключенной перезагрузке конфигурации. Подробнее см. etcd_reloading_configuration.

API config.storage позволяет взаимодействовать с централизованным хранилищем конфигурации на базе Tarantool.

Запись значения по указанному пути.

Параметры:

• path (string) — путь для записи значения
• value (string) — записываемое значение

Возвращает

таблица, содержащая следующие поля:

• revision: ревизия после выполнения операции

Тип возвращаемого значения

table

Пример:

В примере ниже показано, как прочитать конфигурацию, хранящуюся в файле source.yaml, с помощью API модуля fio и записать эту конфигурацию по пути /myapp/config/all:

 
local fio = require('fio')local cluster_config_handle = fio.open('../../source.yaml')local cluster_config = cluster_config_handle:read()local response = config.storage.put('/myapp/config/all', cluster_config)cluster_config_handle:close()

Пример на GitHub: tarantool_config_storage

Получение значения, хранящегося по указанному пути или префиксу.

Параметры:

• path (string) — путь или префикс для получения значения; префиксы заканчиваются на /

Возвращает

таблица, содержащая следующие поля:

• data: таблица, содержащая информацию о значении:
  • path: путь
  • mod_revision: последняя ревизия, в которой это значение было изменено
  • value: значение
• revision: ревизия после выполнения операции

Тип возвращаемого значения

table

Примеры:

В примере ниже показано, как получить конфигурацию, хранящуюся по пути /myapp/config/all:

 
local response = config.storage.get('/myapp/config/all')

В этом примере показано, как получить все конфигурации, хранящиеся по префиксу /myapp/:

 
local response = config.storage.get('/myapp/')

Пример на GitHub: tarantool_config_storage

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

Параметры:

• path (string) — путь или префикс для удаления значения; префиксы заканчиваются на /

Возвращает

таблица, содержащая следующие поля:

• data: таблица, содержащая информацию о значении:
  • path: путь
  • mod_revision: последняя ревизия, в которой это значение было изменено
  • value: значение
• revision: ревизия после выполнения операции

Тип возвращаемого значения

table

Примеры:

В примере ниже показано, как удалить конфигурацию, хранящуюся по пути /myapp/config/all:

 
local response = config.storage.delete('/myapp/config/all')

В этом примере удаляются все конфигурации:

 
local response = config.storage.delete('/')

Пример на GitHub: tarantool_config_storage

Получение информации о состоянии подключения экземпляра.

Возвращает

таблица, содержащая следующие поля:

• status: статус подключения, который может принимать одно из следующих значений:
  • connected: если любой экземпляр из кворума доступен текущему экземпляру
  • disconnected: если текущий экземпляр не имеет подключения к кворуму

Тип возвращаемого значения

table

Выполнение атомарного запроса.

Параметры:

• request (table) — таблица, содержащая следующие необязательные параметры:

  • predicates: список предикатов для проверки. Каждый предикат — это список, содержащий:

     
    {target, operator, value[, path]}

    • target – одно из следующих строковых значений: revision, mod_revision, value, count
    • operator – строковое значение: eq, ne, gt, lt, ge, le или его символьный эквивалент, например ==, !=, >
    • value – беззнаковое или строковое значение для сравнения
    • path (необязательный) – строковое значение: может быть путем с целевым значением mod_revision и value или путем/префиксом с целевым значением count

  • on_success: список операций, выполняемых, если все предикаты в списке возвращают true

  • on_failure: список операций, выполняемых, если хотя бы один предикат возвращает false

Возвращает

таблица, содержащая следующие поля:

• data: таблица, содержащая данные ответа:
  • responses: список ответов для всех операций
  • is_success: логическое значение, указывающее, возвращает ли предикат true
• revision: ревизия после выполнения операции

Тип возвращаемого значения

table

Пример:

 
local response = config.storage.txn({    predicates = { { 'value', '==', 'v0', '/myapp/config/all' } },    on_success = { { 'put', '/myapp/config/all', 'v1' } },    on_failure = { { 'get', '/myapp/config/all' } }})

Пример на GitHub: tarantool_config_storage