Module config | Tarantool

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

config API  
config:get() Get a configuration applied to the current or remote instance
config:info() Get the current instance’s state in regard to configuration
config:instance_uri() Get a URI of the current or remote instance
config:instances() List all instances of the cluster
config:reload() Reload the current instance’s configuration
config.storage API  
config.storage.put() Put a value by the specified path
config.storage.get() Get a value stored by the specified path
config.storage.delete() Delete a value stored by the specified path
config.storage.info() Get information about an instance’s connection state
config.storage.txn() Make an atomic request

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:

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

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

Found what you were looking for?
Feedback