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 instance
config:info() Get the current instance’s state in regard to configuration
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])

Get a configuration applied to the current instance. Optionally, you can pass a configuration option name to get its value.

Parameters:
  • param (string) – a configuration option name
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()

Get the current instance’s state in regard to 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

Examples:

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

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

    app:instance001> require('config'):info()
    ---
    - status: ready
      meta: []
      alerts: []
    ...
    
  • In the example below, the instance’s state is check_warnings. The alerts section informs that privileges to the books space for sampleuser cannot be granted because the books space has not created yet:

    app:instance001> require('config'):info()
    ---
    - status: check_warnings
      meta: []
      alerts:
      - type: warn
        message: box.schema.user.grant("sampleuser", "read,write", "space", "books") has
          failed because either the object has not been created yet, or the privilege
          write has failed (separate alert reported)
        timestamp: 2024-02-27T15:07:41.815785+0300
    ...
    

    This warning is cleared when the books space is created.

  • 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()
    ---
    - status: check_errors
      meta: []
      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-02-29T12:55:54.366810+0300
    ...
    
  • In this example, an instance’s state includes information about a centralized storage the instance takes a configuration from:

    app:instance001> require('config'):info()
    ---
    - status: ready
      meta:
        storage:
          revision: 8
          mod_revision:
            /myapp/config/all: 8
      alerts: []
    ...
    
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: a 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: a 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