Configuration | Tarantool
Concepts Configuration

Configuration

Tarantool provides the ability to configure the full topology of a cluster and set parameters specific for concrete instances, such as connection settings, memory used to store data, logging, and snapshot settings. Each instance uses this configuration during startup to organize the cluster.

There are two approaches to configuring Tarantool:

  • Since version 3.0: In the YAML format.

    YAML configuration allows you to provide the full cluster topology and specify all configuration options. You can use local configuration in a YAML file for each instance or store configuration data in one reliable place using etcd.

  • In version 2.11 and earlier: In code using the box.cfg API.

    In this case, configuration is provided in a Lua initialization script.

    Note

    Starting with the 3.0 version, configuring Tarantool in code is considered a legacy approach.

YAML configuration describes the full topology of a Tarantool cluster. A cluster’s topology includes the following elements, starting from the lower level:

groups:
  group001:
    replicasets:
      replicaset001:
        instances:
          instance001:
            # ...
          instance002:
            # ...
  • instances

    An instance represents a single running Tarantool instance. It stores data or might act as a router for handling CRUD requests in a sharded cluster.

  • replicasets

    A replica set is a pack of instances that operate on same data sets. Replication provides redundancy and increases data availability.

  • groups

    A group provides the ability to organize replica sets. For example, in a sharded cluster, one group can contain storage instances and another group can contain routers used to handle CRUD requests.

You can flexibly configure a cluster’s settings on different levels: from global settings applied to all groups to parameters specific for concrete instances.

This section provides an overview on how to configure Tarantool in a YAML file.

The example below shows a sample configuration of a single Tarantool instance:

groups:
  group001:
    replicasets:
      replicaset001:
        instances:
          instance001:
            iproto:
              listen:
              - uri: '127.0.0.1:3301'
  • The instances section includes only one instance named instance001. The iproto.listen.uri option sets an address used to listen for incoming requests.
  • The replicasets section contains one replica set named replicaset001.
  • The groups section contains one group named group001.

This section shows how to control a scope the specified configuration option is applied to. Most of the configuration options can be applied to a specific instance, replica set, group, or to all instances globally.

  • Instance

    To apply specific configuration options to a concrete instance, specify such options for this instance only. In the example below, iproto.listen is applied to instance001 only.

    groups:
      group001:
        replicasets:
          replicaset001:
            instances:
              instance001:
                iproto:
                  listen:
                  - uri: '127.0.0.1:3301'
    
  • Replica set

    In this example, iproto.listen is in effect for all instances in replicaset001.

    groups:
      group001:
        replicasets:
          replicaset001:
            iproto:
              listen:
              - uri: '127.0.0.1:3301'
            instances:
              instance001: { }
    
  • Group

    In this example, iproto.listen is in effect for all instances in group001.

    groups:
      group001:
        iproto:
          listen:
          - uri: '127.0.0.1:3301'
        replicasets:
          replicaset001:
            instances:
              instance001: { }
    
  • Global

    In this example, iproto.listen is applied to all instances of the cluster.

    iproto:
      listen:
      - uri: '127.0.0.1:3301'
    
    groups:
      group001:
        replicasets:
          replicaset001:
            instances:
              instance001: { }
    

Note

The Configuration reference contains information about scopes to which each configuration option can be applied.

The example below shows how specific configuration options work in different configuration scopes for a replica set with a manual failover. You can learn more about configuring replication from Replication tutorials.

credentials:
  users:
    replicator:
      password: 'topsecret'
      roles: [replication]

iproto:
  advertise:
    peer:
      login: replicator

replication:
  failover: manual

groups:
  group001:
    replicasets:
      replicaset001:
        leader: instance001
        instances:
          instance001:
            iproto:
              listen:
              - uri: '127.0.0.1:3301'
          instance002:
            iproto:
              listen:
              - uri: '127.0.0.1:3302'
          instance003:
            iproto:
              listen:
              - uri: '127.0.0.1:3303'
  • credentials (global)

    This section is used to create the replicator user and assign it the specified role. These options are applied globally to all instances.

  • iproto (global, instance)

    The iproto section is specified on both global and instance levels. The iproto.advertise.peer option specifies the parameters used by an instance to connect to another instance as a replica, for example, a URI, a login and password, or SSL parameters . In the example above, the option includes login only. An URI is taken from iproto.listen that is set on the instance level.

  • replication (global)

    The replication.failover global option sets a manual failover for all replica sets.

  • leader (replica set)

    The <replicaset-name>.leader option sets a master instance for replicaset001.

Using Tarantool as an application server, you can run your own Lua applications. In the app section, you can load the application and provide a custom application configuration in the cfg section.

In the example below, the application is loaded from the myapp.lua file placed next to the YAML configuration file:

app:
  file: 'myapp.lua'
  cfg:
    greeting: 'Hello'

groups:
  group001:
    replicasets:
      replicaset001:
        instances:
          instance001:
            iproto:
              listen:
              - uri: '127.0.0.1:3301'

To get a value of the custom greeting property in the application code, use the config:get() function provided by the config module.

-- myapp.lua --
local log = require('log').new("myapp")
local config = require('config')
log.info("%s from app, %s!", config:get('app.cfg.greeting'), box.info.name)

As a result of starting the instance001, a log should contain the following line:

main/103/interactive/myapp I> Hello from app, instance001!

The app section can be placed in any configuration scope. As an example use case, you can provide different applications for storages and routers in a sharded cluster:

groups:
  storages:
    app:
      module: storage
      # ...
  routers:
    app:
      module: router
      # ...

Learn more about using Tarantool as the application server from Developing applications with Tarantool.

In a configuration file, you can use the following predefined variables that are replaced with actual values at runtime:

  • instance_name
  • replicaset_name
  • group_name

To reference these variables in a configuration file, enclose them in double curly braces with whitespaces. In the example below, {{ instance_name }} is replaced with instance001.

groups:
  group001:
    replicasets:
      replicaset001:
        instances:
          instance001:
            snapshot:
              dir: ./var/{{ instance_name }}/snapshots
            wal:
              dir: ./var/{{ instance_name }}/wals

As a result, the paths to snapshots and write-ahead logs differ for different instances.

For each configuration parameter, Tarantool provides two sets of predefined environment variables:

  • TT_<CONFIG_PARAMETER>. These variables are used to substitute parameters specified in a configuration file. This means that these variables have a higher priority than the options specified in a configuration file.
  • TT_<CONFIG_PARAMETER>_DEFAULT. These variables are used to specify default values for parameters missing in a configuration file. These variables have a lower priority than the options specified in a configuration file.

For example, TT_IPROTO_LISTEN and TT_IPROTO_LISTEN_DEFAULT correspond to the iproto.listen option. TT_SNAPSHOT_DIR and TT_SNAPSHOT_DIR_DEFAULT correspond to the snapshot.dir option. To see all the supported environment variables, execute the tarantool command with the --help-env-list option.

$ tarantool --help-env-list

Below are a few examples that show how to set environment variables of different types, like string, number, array, or map:

  • String. In this example, TT_LOG_LEVEL is used to set a logging level to CRITICAL:

    $ export TT_LOG_LEVEL='crit'
    
  • Number. In this example, a logging level is set to CRITICAL using a corresponding numeric value:

    $ export TT_LOG_LEVEL=3
    
  • Array. The examples below show how to set the TT_SHARDING_ROLES variable that accepts an array value. Arrays can be passed in two ways: using a simple

    $ export TT_SHARDING_ROLES=router,storage
    

    … or JSON format:

    $ export TT_SHARDING_ROLES='["router", "storage"]'
    

    The simple format is applicable only to arrays containing scalar values.

  • Map. To assign map values to environment variables, you can also use simple or JSON formats. In the example below, TT_LOG_MODULES sets different logging levels for different modules using a simple format:

    $ export TT_LOG_MODULES=module1=info,module2=error
    

    In the next example, TT_APP_CFG is used to specify the value of a custom configuration property for a loaded application using a JSON format:

    $ export TT_APP_CFG='{"greeting":"Hi"}'
    

    The simple format is applicable only to maps containing scalar values.

  • Array of maps. In the example below, TT_IPROTO_LISTEN is used to specify a listening host and port values:

    $ export TT_IPROTO_LISTEN=['{"uri":"127.0.0.1:3311"}']
    

    You can also pass several listening addresses:

    $ export TT_IPROTO_LISTEN=['{"uri":"127.0.0.1:3311"}','{"uri":"127.0.0.1:3312"}']
    

Note

There are also special TT_INSTANCE_NAME and TT_CONFIG environment variables that can be used to start the specified Tarantool instance with configuration from the given file.

Enterprise Edition

Storing configuration in etcd is supported by the Enterprise Edition only.

Tarantool enables you to store configuration data in one reliable place using etcd. To achieve this, you need to:

  1. Provide a local YAML configuration with an etcd endpoint address and key prefix in the config section:
config:
  etcd:
    endpoints:
    - http://localhost:2379
    prefix: /example
  1. Publish a cluster’s configuration to an etcd server.

Learn more from the following guide: Storing configuration in etcd.

Tarantool configuration options are applied from multiple sources with the following precedence, from highest to lowest:

If the same option is defined in two or more locations, the option with the highest precedence is applied.

This section gives an overview of some useful configuration options. All the available options are documented in the Configuration reference.

To configure an address used to listen for incoming requests, use the iproto.listen option. The example below shows how to set a listening IP address for instance001 to 127.0.0.1:3301:

instance001:
  iproto:
    listen:
    - uri: '127.0.0.1:3301'

You can learn more from the Connections topic.

The credentials section allows you to create users and grant them the specified privileges. In the example below, a dbadmin user with the specified password is created:

credentials:
  users:
    dbadmin:
      password: 'T0p_Secret_P@$$w0rd'

To learn more, see the Credentials section.

The memtx.memory option specifies how much memory Tarantool allocates to actually store data.

memtx:
  memory: 100000000

When the limit is reached, INSERT or UPDATE requests fail with ER_MEMORY_ISSUE.

The snapshot.dir and wal.dir options can be used to configure directories for storing snapshots and write-ahead logs. For example, you can place snapshots and write-ahead logs on different hard drives for better reliability.

instance001:
  snapshot:
    dir: '/media/drive1/snapshots'
  wal:
    dir: '/media/drive2/wals'

To learn more about the persistence mechanism in Tarantool, see the Persistence section. Read more about snapshot and WAL configuration: Persistence.

Found what you were looking for?
Feedback