Module config

config API

object config¶

config:get([param, opts])¶

Get a configuration applied to the current or remote instance. Note the following differences between getting a configuration for the current and remote instance:

• For the current instance, get() returns its configuration considering environment variables.
• For a remote instance, get() only considers a cluster configuration and ignores environment variables.

Parameters:	param (string) – a configuration option name opts (table) – options to pass. The following options are available: instance (since 3.1.0) – the name of a remote instance whose configuration should be obtained
Return:	an instance configuration

Examples:

The example below shows how to get the full instance configuration:

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

This example shows how to get an iproto.listen option value:

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

config.get() can also be used in application code to get the value of a custom configuration option.

config:info([version])¶

Get the current instance’s state in regard to configuration.

Parameters:

version (string) – (since 3.1.0) the version of the information that should be returned. The version argument can be one of the following values: v1 (default): the meta field returned by info() includes information about the last loaded configuration v2: the meta field returned by info() includes two fields: the last field includes information about the last loaded configuration the active field includes information for the last successfully applied configuration

Return:

a table containing an instance’s state. The returned state includes the following sections: status – one of the following statuses: ready – the configuration is applied successfully check_warnings – the configuration is applied with warnings check_errors – the configuration cannot be applied due to configuration errors meta – additional configuration information alerts – warnings or errors raised on an attempt to apply the configuration

Below are a few examples demonstrating how the info() output might look.

Example: no configuration warnings or errors

In the example below, an instance’s state is ready and no warnings are shown:

app:instance001> require('config'):info('v2')
---
- status: ready
  meta:
    last: &0 []
    active: *0
  alerts: []
...

Example: configuration warnings

In the example below, the instance’s state is check_warnings. The alerts section informs that privileges to the bands space for sampleuser cannot be granted because the bands space has not been created yet:

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
...

This warning is cleared when the bands space is created.

Example: configuration errors

In the example below, the instance’s state is check_errors. The alerts section informs that the log.level configuration option has an incorrect value:

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
...

Example: configuration errors (centralized configuration storage)

In this example, the meta field includes information about a centralized storage the instance takes a configuration from:

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
...

config:instance_uri([uri_type, opts])¶

Since: 3.1.0

Get a URI of the current or remote instance.

Parameters:

uri_type (string) – a URI type. The following URI types are supported: peer – a URI used to advertise the instance to other cluster members. See also: iproto.advertise.peer. sharding – a URI used to advertise the current instance to a router and rebalancer. See also: iproto.advertise.sharding. opts (table) – options to pass. The following options are available: instance – the name of a remote instance whose URI should be obtained

Return:

a table representing an instance URI. This table might include the following fields: uri – an instance URI login – a username used to connect to this instance password – a user’s password params – URI parameters used to connect to this instance Note Note that the resulting URI object can be passed to the connect() function of the net.box module.

Example

The example below shows how to get a URI used to advertise storage-b-003 to other cluster members:

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

config:instances()¶

Since: 3.1.0

List all instances of the cluster.

Return:	a table containing information about instances. The returned table uses instance names as the keys and contains the following information for each instance: instance_name – an instance name replicaset_name – the name of a replica set the instance belongs to group_name – the name of a group the instance belongs to

Example

The example below shows how to use instances() to get the names of all instances in the cluster, create a connection to each instance using the connpool module, and log connection URIs using the log module:

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

In this example, the same actions are performed for instances from the specified replica set:

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)
    end
end

config:reload()¶

Reload the current instance’s configuration. Below are a few use cases when this function can be used:

• A configuration option value specific to this instance is changed in a cluster’s configuration.
• A new instance is added to a replica set.
• A centralized configuration with turned-off configuration reloading is updated. Learn more at Reloading configuration.

config.storage API

The config.storage API allows you to interact with a Tarantool-based centralized configuration storage.

config.storage.put(path, value)¶

Put a value by the specified path.

Parameters:	path (string) – a path to put the value by value (string) – a value to put
Return:	a table containing the following fields: revision: a revision after performing the operation
Rtype:	table

Example:

The example below shows how to read a configuration stored in the source.yaml file using the fio module API and put this configuration by the /myapp/config/all path:

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()

Example on GitHub: tarantool_config_storage

config.storage.get(path)¶

Get a value stored by the specified path or prefix.

Parameters:	path (string) – a path or prefix to get a value by; prefixes end with /
Return:	a table containing the following fields: data: a table containing the information about the value: path: a path mod_revision: the last revision at which this value was modified value:: a value revision: a revision after performing the operation
Rtype:	table

Examples:

The example below shows how to get a configuration stored by the /myapp/config/all path:

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

This example shows how to get all configurations stored by the /myapp/ prefix:

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

Example on GitHub: tarantool_config_storage

config.storage.delete(path)¶

Delete a value stored by the specified path or prefix.

Parameters:	path (string) – a path or prefix to delete the value by; prefixes end with /
Return:	a table containing the following fields: data: a table containing the information about the value: path: a path mod_revision: the last revision at which this value was modified value:: a value revision: a revision after performing the operation
Rtype:	table

Examples:

The example below shows how to delete a configuration stored by the /myapp/config/all path:

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

In this example, all configuration are deleted:

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

Example on GitHub: tarantool_config_storage

config.storage.info()¶

Get information about an instance’s connection state.

Return:	a table containing the following fields: status: a connection status, which can be one of the following: connected: if any instance from the quorum is available to the current instance disconnected: if the current instance doesn’t have a connection with the quorum
Rtype:	table

config.storage.txn(request)¶

Make an atomic request.

Parameters:	request (table) – a table containing the following optional fields: predicates: a list of predicates to check. Each predicate is a list that contains: {target, operator, value[, path]} target – one of the following string values: revision, mod_revision, value, count operator – a string value: eq, ne, gt, lt, ge, le or its symbolic equivalent, for example, ==, !=, > value – an unsigned or string value to compare path (optional) – a string value: can be a path with the mod_revision and value target or a path/prefix with the count target on_success: a list with operations to execute if all predicates in the list evaluate to true on_failure: a list with operations to execute if any of a predicate evaluates to false
Return:	a table containing the following fields: data: a table containing response data: responses: the list of responses for all operations is_success: a boolean value indicating whether the predicate is evaluated to true revision: a revision after performing the operation
Rtype:	table

Example:

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

Example on GitHub: tarantool_config_storage