stateboard: new service for reporting instance states

Related dev. issue(s): tarantool/tarantool-ee#1229

Product: Tarantool
Since: 3.5
Audience/target: Tarantool EE developers
Root document: configuration reference, Platform > Monitoring (new) > Stateboard
SME: @georgiy-belyanin

Details

New stateboard service

Enterprise-edition only.

Tarantool may report its state to a remote key-value storages like
etcd or Tarantool config.storage using the stateboard service.

The reported state is a YAML that contains the following fields.

• hostname (string): hostname.
• pid (integer): Tarantool process ID.
• mode ('ro' or 'rw'): instance mode (see box.info.ro).
• ro_reason (string): the reason why the instance is read-only (see
  box.info.ro_reason).
• status (string): instance status (see box.info.status for
  possible values and their description).

The stateboard service can be enabled by configuring a centralized configuration storage and specifying stateboard.enabled: true in the Tarantool configuration.

Using Tarantool-based storage as a stateboard.

After setting up a Tarantool config.storage cluster and providing connection options in the
config.storage section the stateboard may be enabled as follows.

config:
  storage:
    endpoints:
      - uri: '127.0.0.1:4401'
        login: sampleuser
        password: '123456'
      - uri: '127.0.0.1:4402'
        login: sampleuser
        password: '123456'
      - uri: '127.0.0.1:4403'
        login: sampleuser
        password: '123456'
    prefix: /myapp
    timeout: 3
    reconnect_after: 5

stateboard:
  enabled: true

When using such configuration instances would report their state in
/myapp/state/by-name/{{ instance_name }} in YAML format. You may
access this state from other Tarantool instances using
the config.storage client API.

local config = require('config')
local yaml = require('yaml')

local endpoints = config:get('config.storage.endpoints')
local prefix = config:get('config.storage.prefix')

-- Connect to the config.storage cluster configured in the
-- `config.storage` section.
local client = config.storage_client.connect(endpoints)

local instance1_path = prefix .. '/state/by-name/instance-001'
-- Fetch the information instance-001 reports
local instance1_yaml = client:get(instance_path).data[1].value
local instance1_state = yaml.decode(instance1_yaml)

-- `instance1_state` is a table with this keys.
-- {
--     status = 'running',
--     mode = 'rw',
--     hostname = 'user',
--     pid = 1000
-- }

Using etcd as a stateboard.

Tarantool can report its state to etcd. After configuring a etcd cluster and Tarantool instances to use
it using the config.etcd section.

config:
  etcd:
    endpoints:
    - http://localhost:2379
    prefix: /myapp
    username: sampleuser
    password: '123456'
    http:
      request:
        timeout: 3

stateboard:
  enabled: true

In that case the instance state would be reported in /myapp/state/by-name/{{ instance_name }}. It can be accessed using various etcd
clients, e.g. etcdctl:

$ etcdctl get /myapp/state/by-name/instance-001
---
status: running
mode: rw
hostname: user
pid: 1000
...

For information on configuring the stateboard see the configuration
reference on the stateboard section.

There are a new configuration options related to the stateboard.

A new configuration section called stateboard for defining stateboard
parameters has been added. It's available only in Tarantool Enterprise.

The options are described as follows.

stateboard

These options define configuration parameters related to the stateboard
service allowing Tarantool instances to report their state into some
extra key-value storage (e.g. etcd or Tarantool config.storage).

The provided information includes:
An instance with an enabled stateboard reports its status to
<prefix>/state/by-name/{{ instance_name }} where prefix is received
from the config.*.prefix option. The provided information is in YAML
format with the following fields:

• hostname (string): hostname
• pid (integer): Tarantool process ID
• mode ('ro' or 'rw'): instance mode (see box.info.ro).
• status (string): instance status (see box.info.status for
  possible values and their description).

See Tarantool stateboard for more information on the stateboard.

stateboard.enabled

Enable or disable the stateboard service.

stateboard.keepalive_interval

A time interval (in seconds) that specifies how long a transient state
information is stored.

stateboard.renew_interval

A time interval (in seconds) that specifies how often a Tarantool instance
writes its state information to the stateboard.

Definition of done

• Write a description on how to setup a stateboard
• Describe stateboard configuration options