Roles

[TarantoolBot]

Related dev. issue(s): tarantool/tarantool#9078
Related doc. issue(s): #3883, #3670

Product: Tarantool
Since: 3.0
Root document:

• roles reference
• Tarantool config storage
• Somewhere in Developing applications
• Update CRUD sample to using built-in roles #4152

SME: @ ImeevMA

Details

Two new options have been added: "roles" and "roles_cfg". The first one
is an array and the second one is a map. Each of these can be defined
per instance, replica set, group, and globally. As with almost all other
options, with the exception of those defined as 'map', the 'roles'
option for the lower scope will replace the roles for the higher scope.
Value roles_cfg however defined as "map", so it will be merged.

The "roles" option defines the roles for each instance. A role is a
program that runs when a configuration is loaded or reloaded. If a role
is defined more than once on an instance, it will still only be run
once. Three functions must be defined in the role: validate(), apply()
and stop(). Each of these functions should throw an error if it occurs.

The "roles_cfg" option specifies the configuration for each role. In
this option, the role name is the key and the role configuration is the
value.

On each run, all roles will be loaded (if necessary) in the order in
which they were specified; the configuration for each role will then be
validated using the corresponding validate() function in the same order;
and then they will all be run with apply() function in the same order.
If some roles have been removed from the instance, they will be stopped
in reverse order using the stop() function.

Example of a role structure:

local M = {}

-- Validates configuration of the role.
--
-- Called on initial configuration apply at startup and on
-- configuration reload if the role is enabled for the given instance.
--
-- The cfg argument may have arbitrary user provided value,
-- including nil.
--
-- Must raise an error if the validation fail.
function M.validate(cfg)
    -- <...>
end

-- Applies the given configuration of the role.
--
-- Called on initial configuration apply at startup and on
-- configuration reload if the role is enabled for the given instance.
--
-- The cfg argument may have arbitrary user provided value,
-- including nil.
--
-- Must raise an error if the given configuration can't be applied.
function M.apply(cfg)
    -- <...>
end

-- Stops the role.
--
-- Called on configuration reload if the role was enabled before
-- and removed now from the list of roles of the given instance.
--
-- Should cancel all background fibers and clean up hold
-- resources.
--
-- Must raise an error if this action can't be performed.
function M.stop()
    -- <...>
end

return M

Requested by @ ImeevMA in tarantool/tarantool@5288440.

Example

Config:

credentials:
  users:
    guest:
      roles: [super]

app:
  file: 'init.lua'

groups:
  routers:
    roles_cfg:
      router:
        init_size: 100
    roles: [router]
    replicasets:
      router-001:
        sharding:
          roles: [router]
        instances:
          instance-000:
            iproto:
              listen: 'localhost:3300'
              advertise:
                client: 'localhost:3300'
                sharding: 'localhost:3300'
  storages:
    roles: [storage]
    replicasets:
      storage-001:
        database:
          replicaset_uuid: 'aaaaaaaa-0000-4000-a000-000000000000'
        instances:
          instance-001:
            database:
              instance_uuid: 'aaaaaaaa-0000-4000-a000-000000000011'
              mode: rw
            sharding:
              roles: [storage]
            iproto:
              listen: 'localhost:3301'
              advertise:
                client: 'localhost:3301'
                sharding: 'localhost:3301'
          instance-002:
            database:
              instance_uuid: 'aaaaaaaa-0000-4000-a000-000000000012'
            sharding:
              roles: [storage]
            iproto:
              listen: 'localhost:3302'
              advertise:
                client: 'localhost:3302'
                sharding: 'localhost:3302'
      storage-002:
        database:
          replicaset_uuid: 'bbbbbbbb-0000-4000-a000-000000000000'
        instances:
          instance-003:
            database:
              instance_uuid: 'bbbbbbbb-0000-4000-a000-000000000021'
              mode: rw
            sharding:
              roles: [storage]
            iproto:
              listen: 'localhost:3303'
              advertise:
                client: 'localhost:3303'
                sharding: 'localhost:3303'
          instance-004:
            database:
              instance_uuid: 'bbbbbbbb-0000-4000-a000-000000000022'
            sharding:
              roles: [storage]
            iproto:
              listen: 'localhost:3304'
              advertise:
                client: 'localhost:3304'
                sharding: 'localhost:3304'

init.lua:

local fiber = require("fiber")
require('log').info("lua: example started")

local version = require('tarantool').version

assert(version:sub(1, 2) == '3.', "tarantool version have to be >= 3, got " .. version)

_G.hello = function(name)
    return "Hello "..tostring(name)
end


fiber.create(function()
    box.ctl.wait_rw(30)
    box.schema.func.create('prometheus_collect_http', {if_not_exists=true})
    box.schema.func.create('hello', {if_not_exists=true})
end)

Router code:

local vshard = require('vshard')
local crud = require('crud')
local uuid = require('uuid')
local datetime = require('datetime')
local log = require('log')
local fiber = require('fiber')

local M = {}

function M.validate(cfg)
    if cfg.init_size then
        assert(type(cfg.init_size) == "number", "init_size must be number")
        assert(cfg.init_size > 0, "init_size must be positive")
    end
end

function M.bootstrap_f(cfg)
    for i = 1,10 do
        local rc, err = vshard.router.bootstrap()
        log.info("Attempt to bootstrap vshard cluster")
        log.info(rc)
        if rc == nil then
            if string.find(tostring(err), "is already bootstrapped") ~=nil then
                break
            end
            log.info(err)
        end
        if rc ~= nil then
            break
        end
        fiber.sleep(1)
    end
    if cfg.init_size then
        for i = 1, cfg.init_size do
            crud.insert('sales', {
                uuid.new(),
                box.NULL,
                ("product_%s"):format(i % 100),
                ("buyer_%s"):format(i % 10),
                i,
                true,
                datetime.new{timestamp=os.time()}
            })
        end


        for i = 1, cfg.init_size do
            crud.replace('counter', {
                i,
                box.NULL,
                i,
                i,
            })
        end
        for i = 1, cfg.init_size do 
            crud.replace('complex', {
                i, 
                "BBBB", 
                box.NULL, 
                false, 
                false, i, 30, i + 1.1111,
                {"string1",  "string2",  "string3" }, 
                "Something", 
                "Category", 
                uuid.new(),
                "Key2", 
                datetime.new{timestamp=os.time()}
            })
        end
    end
end



function M.apply(cfg)
    M.bootstrap_fiber = fiber.create(M.bootstrap_f, cfg)
    
    crud.init_router()
end

function M.stop()
    crud.stop_router()
end

return M

Storage code:

local crud = require('crud')

local M = {}

function M.validate()
end

function M.apply()
    crud.init_storage()
    if box.info.ro ~= true then
        box.schema.space.create('sales', {if_not_exists=true})

        box.space.sales:format({
            {name='id', type='uuid'},
            {name='bucket_id', type='unsigned'},
            {name='product_id', type='string'},
            {name='buyer_id', type='string'},
            {name='price', type='double'},
            {name='direct', type='boolean'},
            {name='time', type='datetime'},
        })
        box.space.sales:create_index('primary',{ parts = {{'id'}}, if_not_exists=true})
        box.space.sales:create_index('bucket_id', {
            parts={{'bucket_id'}}, unique=false, if_not_exists=true,
        })


        box.schema.space.create('counter', {if_not_exists=true})

        box.space.counter:format({
            {name='id1', type='unsigned'},
            {name='bucket_id', type='unsigned'},
            {name='id2', type='unsigned'},
            {name='id3', type='unsigned'},
        })
        box.space.counter:create_index('primary',{ parts = {{'id1'}}, if_not_exists=true})
        box.space.counter:create_index('bucket_id', {
            parts={{'bucket_id'}}, unique=false, if_not_exists=true,
        })


        box.schema.space.create('complex', {if_not_exists=true})
        box.space.complex:format({
            {name='key1', type='integer'},
            {name='val', type='string'},
            {name="bucket_id", type="unsigned"},
            {name='flag', type='boolean'},
            {name='flag sort', type='boolean', is_nullable=true},
            {name='integer_number', type='integer'},
            {name='age', type='unsigned'},
            {name='int_or_float', type='number'},
            {name="arr", type='array'},
            {name='something', type='scalar'},
            {name='minstr', type='string'},
            {name='id', type='uuid'},
            {name='key2', type='string'},
            {name='time', type='datetime'},
        })
        box.space.complex:create_index('pkey', {parts={{field='key1', type='integer'}, {field='key2', type='string'}}, if_not_exists=true})
    
        box.space.complex:create_index('secondary', {parts={{field='key1', type='integer'}, {field='flag', type='boolean'}, {field='int_or_float', type='number'}}, if_not_exists=true})
    
        box.space.complex:create_index('otherindex', {parts={{field='something', type='scalar'}, {field='flag', type='boolean'}, {field='int_or_float', type='number'}}, if_not_exists=true})
    
        box.space.complex:create_index('ageindex', {parts={{field='something', type='scalar'}}, unique=false, if_not_exists=true})
    
        box.space.complex:create_index('agefifers', {parts={{field='something', type='scalar'}, {field='integer_number', type='integer'}}, if_not_exists=true})
    
        box.space.complex:create_index('nullableTrue', {parts={{field='something', type='scalar'}, {field='flag sort', type='boolean', is_nullable=true} }, if_not_exists=true, unique=false})
    
        box.space.complex:create_index('ageArray', {parts={{field='arr', type="string", path="[*]"}, {field='integer_number', type='integer'}}, if_not_exists=true, unique=false})
    
        box.space.complex:create_index('bucket_id', {
            parts={{'bucket_id'}}, unique=false, if_not_exists=true,
        })
    end
end

function M.stop()
    crud.stop_storage()
end

return M

[Totktonada]

Epic: #3544.

[andreyaksenov]

• Configuring roles: https://www.tarantool.io/en/doc/latest/concepts/configuration/#configuration-application-roles
• Developing custom roles: https://www.tarantool.io/en/doc/latest/how-to/app/app_roles/