Application roles

Providing a role configuration

A custom role can be configured in the same way as roles provided by Tarantool or third-party Lua modules. You can learn more from Enabling and configuring roles.

This example shows how to enable and configure the greeter role, which is implemented in the next section:

instance001:
  roles: [ greeter ]
  roles_cfg:
    greeter:
      greeting: 'Hi'

The role configuration provided in roles_cfg can be accessed when validating and applying this configuration.

Tarantool includes the experimental.config.utils.schema built-in module that provides tools for managing user-defined configurations of applications (app.cfg) and roles (roles_cfg). The examples below show its basic usage.

Given that a role is a Lua module, a role name is passed to require() to obtain the module. When developing an application, you can place a file with the role code next to the cluster configuration file.

Creating a custom role

return {
    validate = function() -- ... -- end,
    apply = function() -- ... -- end,
    stop = function() -- ... -- end,
    dependencies = { -- ... -- },
}

local greeter_schema = schema.new('greeter', schema.record({
    greeting = schema.scalar({
        type = 'string',
        allowed_values = { 'Hi', 'Hello' }
    })
}))

local function validate(cfg)
    greeter_schema:validate(cfg)
end

local function apply(cfg)
    log.info("%s from the 'greeter' role!", greeter_schema:get(cfg, 'greeting'))
end

local function stop()
    log.info("The 'greeter' role is stopped")
end

return {
    validate = validate,
    apply = apply,
    stop = stop,
}

-- byeer.lua --
local log = require('log').new("byeer")

return {
    dependencies = { 'greeter' },
    validate = function() end,
    apply = function() log.info("Bye from the 'byeer' role!") end,
    stop = function() end,
}

instance001:
  roles: [ greeter, byeer ]

local function init()
    -- ... --
end

init()

box.watch('box.status', function()
    -- creating a space
    -- ...
end)

Roles life cycle

A role’s life cycle includes the stages described below.

1. Loading roles

   On each run, all roles are loaded in the order they are specified in the configuration. This stage takes effect when a role is enabled or an instance with this role is restarted. At this stage, a role executes the initialization code.

   A role cannot be started if it has dependencies that are not specified in a configuration.

   Примечание

   Dependencies do not affect the order in which roles are loaded. However, the validate(), apply(), and stop() functions are executed taking dependencies into account. Learn more in Executing functions for dependent roles.

2. Stopping roles

   This stage takes effect during a configuration reload when a role is removed from the configuration for a given instance. Note that all stop() calls are performed before any validate() or apply() calls. This means that old roles are stopped first, and only then new roles are started.

3. Validating a role’s configurations

   At this stage, a configuration for each role is validated using the corresponding validate() function in the same order in which they are specified in the configuration.

4. Applying a role’s configurations

   At this stage, a configuration for each role is applied using the corresponding apply() function in the same order in which they are specified in the configuration.

All role’s functions report an unrecoverable error by throwing an error object. If an error is thrown in any phase, applying a configuration is stopped. If starting or stopping a role throws an error, no roles are stopped or started afterward. An error is caught and shown in config:info() in the alerts section.

role1
role2
role3
    └─── role4
             └─── role5

roles: [ role1, role2, role3, role4, role5 ]

role1 -> role2 -> role5 -> role4 -> role3

roles: [ role1 ]

role3 -> role4 -> role5 -> role2

Example: Role without a configuration

The example below shows how to enable the custom greeter role for instance001:

instance001:
  roles: [ greeter ]

The implementation of this role looks as follows:

-- greeter.lua --
return {
    validate = function() end,
    apply = function() require('log').info("Hi from the 'greeter' role!") end,
    stop = function() end,
}

Example on GitHub: application_role

Example: Role with a configuration

The example below shows how to enable the custom greeter role for instance001 and specify the configuration for this role:

instance001:
  roles: [ greeter ]
  roles_cfg:
    greeter:
      greeting: 'Hi'

The implementation of this role looks as follows:

-- greeter.lua --
local log = require('log').new("greeter")
local schema = require('experimental.config.utils.schema')

local greeter_schema = schema.new('greeter', schema.record({
    greeting = schema.scalar({
        type = 'string',
        allowed_values = { 'Hi', 'Hello' }
    })
}))

local function validate(cfg)
    greeter_schema:validate(cfg)
end

local function apply(cfg)
    log.info("%s from the 'greeter' role!", greeter_schema:get(cfg, 'greeting'))
end

local function stop()
    log.info("The 'greeter' role is stopped")
end

return {
    validate = validate,
    apply = apply,
    stop = stop,
}

Example on GitHub: application_role_cfg

Example: HTTP API

The example below shows how to enable and configure the http-api custom role:

instance001:
  roles: [ http-api ]
  roles_cfg:
    http-api:
      host: '127.0.0.1'
      port: 8080

The implementation of this role looks as follows:

-- http-api.lua --
local httpd
local json = require('json')
local schema = require('experimental.config.utils.schema')

local function validate_host(host, w)
    local host_pattern = "^(%d+)%.(%d+)%.(%d+)%.(%d+)$"
    if not host:match(host_pattern) then
        w.error("'host' should be a string containing a valid IP address, got %q", host)
    end
end

local function validate_port(port, w)
    if port <= 1 or port >= 65535 then
        w.error("'port' should be between 1 and 65535, got %d", port)
    end
end

local listen_address_schema = schema.new('listen_address', schema.record({
    host = schema.scalar({
        type = 'string',
        validate = validate_host,
        default = '127.0.0.1',
    }),
    port = schema.scalar({
        type = 'integer',
        validate = validate_port,
        default = 8080,
    }),
}))

local function validate(cfg)
    listen_address_schema:validate(cfg)
end

local function apply(cfg)
    if httpd then
        httpd:stop()
    end
    local cfg_with_defaults = listen_address_schema:apply_default(cfg)
    local host = listen_address_schema:get(cfg_with_defaults, 'host')
    local port = listen_address_schema:get(cfg_with_defaults, 'port')
    httpd = require('http.server').new(host, port)
    local response_headers = { ['content-type'] = 'application/json' }
    httpd:route({ path = '/band/:id', method = 'GET' }, function(req)
        local id = req:stash('id')
        local band_tuple = box.space.bands:get(tonumber(id))
        if not band_tuple then
            return { status = 404, body = 'Band not found' }
        else
            local band = { id = band_tuple['id'],
                           band_name = band_tuple['band_name'],
                           year = band_tuple['year'] }
            return { status = 200, headers = response_headers, body = json.encode(band) }
        end
    end)
    httpd:route({ path = '/band', method = 'GET' }, function(req)
        local limit = req:query_param('limit')
        if not limit then
            limit = 5
        end
        local band_tuples = box.space.bands:select({}, { limit = tonumber(limit) })
        local bands = {}
        for _, tuple in pairs(band_tuples) do
            local band = { id = tuple['id'],
                           band_name = tuple['band_name'],
                           year = tuple['year'] }
            table.insert(bands, band)
        end
        return { status = 200, headers = response_headers, body = json.encode(bands) }
    end)
    httpd:start()
end

local function stop()
    httpd:stop()
end

local function init()
    require('data'):add_sample_data()
end

init()

return {
    validate = validate,
    apply = apply,
    stop = stop,
}

Example on GitHub: application_role_http_api

API Reference

validate([cfg])¶

Validate a role’s configuration. This function is called on instance startup or when the configuration is reloaded for the instance with this role. Note that the validate() function is called regardless of whether the role’s configuration or any field in a cluster’s configuration is changed.

validate() should throw an error if the validation fails.

Параметры:	cfg – a role’s role configuration to be validated. This parameter provides access to configuration options defined in roles_cfg.<role_name>. To get values of configuration options placed outside roles_cfg.<role_name>, use config:get().

See also: Validating a role configuration

apply([cfg])¶

Apply a role’s configuration. apply() is called after validate() is executed for all the enabled roles. As the validate() function, apply() is called on instance startup or when the configuration is reloaded for the instance with this role.

apply() should throw an error if the specified configuration can’t be applied.

Примечание

Note that apply() is not invoked if an instance switches to read-write mode when replication.failover is set to election or supervised. You can check an instance state by subscribing to the box.status event using box.watch().

Параметры:	cfg – a role’s role configuration to be applied. This parameter provides access to configuration options defined in roles_cfg.<role_name>. To get values of configuration options placed outside roles_cfg.<role_name>, use config:get().

See also: Applying a role configuration

stop()¶

Stop a role. This function is called on configuration reload if the role is removed from roles for the given instance.

See also: Stopping a role

dependencies¶

(Optional) Define a role’s dependencies.

Rtype:	table

See also: Role dependencies