Module config

Since: 3.0.0

The config module provides the ability to work with an instance's configuration. For example, you can determine whether the current instance is up and running without errors after applying the cluster's configuration.

By using the config.storage role, you can set up a Tarantool-based centralized configuration storage and interact with this storage using the config module API.

To load the config module, use the require() directive:

 
local config = require('config')

Then, you can access its API:

 
config:reload()

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

Returns

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.

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

• 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

Returns

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

Since version 3.3.0

• hierarchy – table, showing names of the group, replicaset, and the instance itself. These names are taken directly from the --name CLI option (or the TT_INSTANCE_NAME environment variable) and the cluster configuration. This means they are always present if the YAML configuration flow is in use, disregarding the database status (whether upgraded, writable or not).

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:   hierarchy:    group: group-001    replicaset: replicaset-001    instance: instance-001...

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  hierarchy:    group: group-001    replicaset: replicaset-001    instance: instance-001...

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  hierarchy:    group: group-001    replicaset: replicaset-001    instance: instance-001...

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  hierarchy:    group: group001    replicaset: replicaset001    instance: instance001...

Since: 3.1.0

Get a URI of the current or remote instance.

• 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

Returns

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

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' })

Since: 3.1.0

List all instances of the cluster.

Returns

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

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

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

Put a value by the specified path.

Parameters:

• path (string) — a path to put the value by

• value (string) — a value to put

Returns

a table containing the following fields:

• revision: a revision after performing the operation

Return type

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

Get a value stored by the specified path or prefix.

• path (string) — a path or prefix to get a value by; prefixes end with /

Returns

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

Return type

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

Delete a value stored by the specified path or prefix.

• path (string) — a path or prefix to delete the value by; prefixes end with /

Returns

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

Return type

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

Get information about an instance's connection state.

Returns

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

Return type

table

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

Returns

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

Return type

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