Developer’s guide¶

Встроенные роли¶

В модуль cartridge входят две встроенные роли, которые реализуют автоматический шардинг:

• vshard-router обрабатывает ресурсоемкие вычисления в vshard: направляет запросы к узлам хранения данных.

• vshard-storage работает с большим количеством транзакций в vshard: хранит подмножество набора данных и управляет им.

  Примечание

  For more information on sharding, see the vshard module documentation.

With the built-in and custom roles, you can develop applications with separated compute and transaction handling – and enable relevant workload-specific roles on different instances running on physical servers with workload-dedicated hardware.

Пользовательские роли¶

You can implement custom roles for any purposes, for example:

• определять хранимые процедуры;
• implement extra features on top of vshard;
• полностью обойтись без vshard;
• внедрить одну или несколько дополнительных служб, таких как средство уведомления по электронной почте, репликатор и т.д.

To implement a custom cluster role, do the following:

1. Take the app/roles/custom.lua file in your project as a sample. Rename this file as you wish, e.g. app/roles/custom-role.lua, and implement the role’s logic. For example:

   -- Implement a custom role in app/roles/custom-role.lua
   #!/usr/bin/env tarantool
   local role_name = 'custom-role'
   
   local function init()
   ...
   end
   
   local function stop()
   ...
   end
   
   return {
       role_name = role_name,
       init = init,
       stop = stop,
   }
   

   Here the role_name value may differ from the module name passed to the cartridge.cfg() function. If the role_name variable is not specified, the module name is the default value.

   Примечание

   Имена ролей должны быть уникальными, поскольку невозможно зарегистрировать несколько ролей с одним именем.

2. Зарегистрируйте новую роль в кластере, изменив вызов cartridge.cfg() в файле входа в приложение init.lua:

   -- Register a custom role in init.lua
   ...
   local cartridge = require('cartridge')
   ...
   cartridge.cfg({
     workdir = ...,
     advertise_uri = ...,
     roles = {'custom-role'},
   })
   ...
   

   где custom-role (пользовательская роль) – это название загружаемого Lua-модуля.

The role module does not have required functions, but the cluster may execute the following ones during the role’s life cycle:

• init() – это функция инициализации роли.

  Inside the function’s body you can call any box functions: create spaces, indexes, grant permissions, etc. Here is what the initialization function may look like:

  local function init(opts)
      -- Кластер передает Lua-таблицу 'opts', которая содержит флаг 'is_master'.
      if opts.is_master then
          local customer = box.schema.space.create('customer',
              { if_not_exists = true }
          )
          customer:format({
              {'customer_id', 'unsigned'},
              {'bucket_id', 'unsigned'},
              {'name', 'string'},
          })
          customer:create_index('customer_id', {
              parts = {'customer_id'},
              if_not_exists = true,
          })
      end
  end
  

  Примечание

  • Neither vshard-router nor vshard-storage manage spaces, indexes, or formats. You should do it within a custom role: add a box.schema.space.create() call to your first cluster role, as shown in the example above.
  • Тело функции заключено в условный оператор, который позволяет вызывать функции box только на мастерах. Это предотвращает конфликты репликации, так как данные автоматически передаются на реплики.

• stop() is the role’s termination function. Implement it if initialization starts a fiber that has to be stopped or does any job that needs to be undone on termination.

• validate_config() and apply_config() are functions that validate and apply the role’s configuration. Implement them if some configuration data needs to be stored cluster-wide.

Next, get a grip on the role’s life cycle to implement the functions you need.

Определение зависимостей для ролей¶

Можно заставить кластер применить некоторые другие роли, если включена пользовательская роль.

Например:

-- Role dependencies defined in app/roles/custom-role.lua
local role_name = 'custom-role'
...
return {
    role_name = role_name,
    dependencies = {'cartridge.roles.vshard-router'},
    ...
}

Здесь роль vshard-router будет инициализирована автоматически для каждого экземпляра, в котором включена роль custom-role.

Использование нескольких групп vshard storage¶

Для наборов реплик с ролью vshard-storage можно задавать группы. Например, группы hot и cold предназначены для независимой обработки горячих и холодных данных.

Группы указаны в конфигурации кластера:

-- Specify groups in init.lua
cartridge.cfg({
    vshard_groups = {'hot', 'cold'},
    ...
})

Если ни одна группа не указана, кластер предполагает, что все наборы реплик входят в группу default (по умолчанию).

Если включены несколько групп, каждый набор реплик с включенной ролью vshard-storage должен быть назначен в определенную группу. Эту настройку нельзя изменить впоследствии.

Есть еще одно ограничение – нельзя добавлять группы динамически (такая возможность появится в будущих версиях).

Finally, mind the syntax for router access. Every instance with a vshard-router role enabled initializes multiple routers. All of them are accessible through the role:

local router_role = cartridge.service_get('vshard-router')
router_role.get('hot'):call(...)

If you have no roles specified, you can access a static router as before (when Tarantool Cartridge was unaware of groups):

local vhsard = require('vshard')
vshard.router.call(...)

However, when using the current group-aware API, you must call a static router with a colon:

local router_role = cartridge.service_get('vshard-router')
local default_router = router_role.get() -- или router_role.get('default')
default_router:call(...)

Role’s life cycle (and the order of function execution)¶

The cluster displays the names of all custom roles along with the built-in vshard-* roles in the web interface. Cluster administrators can enable and disable them for particular instances – either via the web interface or via the cluster public API. For example:

cartridge.admin.edit_replicaset('uuid-набора-реплик', {roles = {'vshard-router', 'пользователськая-роль'}})

If you enable multiple roles on an instance at the same time, the cluster first initializes the built-in roles (if any) and then the custom ones (if any) in the order the latter were listed in cartridge.cfg().

If a custom role has dependent roles, the dependencies are registered and validated first, prior to the role itself.

Кластер вызывает функции роли в следующих случаях:

• Функция init() обычно выполняется один раз: либо когда администратор включает роль, либо при перезапуске экземпляра. Как правило, достаточно один раз включить роль.
• Функция stop() – только когда администратор отключает роль, а не во время завершения работы экземпляра.
• Функция validate_config(): сначала до автоматического вызова box.cfg()` (инициализация базы данных), а затем при каждом обновлении конфигурации.
• Функция apply_config() – при каждом обновлении конфигурации.

As a tryout, let’s task the cluster with some actions and see the order of executing the role’s functions:

• Присоединение экземпляра или создание набора реплик (в обоих случаях с включенной ролью):
  1. validate_config()
  2. init()
  3. apply_config()
• Перезапуск экземпляра с включенной ролью:
  1. validate_config()
  2. init()
  3. apply_config()
• Отключение роли: stop().
• При вызове cartridge.confapplier.patch_clusterwide():
  1. validate_config()
  2. apply_config()
• При запущенном восстановлении после отказа:
  1. validate_config()
  2. apply_config()

Учитывая вышеописанное поведение:

• Функция init() может:
  • Вызывать функции box.
  • Запускать файбер, и в таком случае функция stop() должна позаботиться о завершении работы файбера.
  • Настраивать встроенный HTTP-сервер.
  • Выполнять любой код, связанный с инициализацией роли.
• The stop() functions must undo any job that needs to be undone on role’s termination.
• Функция validate_config() должна валидировать любые изменения конфигурации.
• Функция apply_config() может выполнять любой код, связанный с изменением конфигурации, например, следить за файбером expirationd.

The validation and application functions together allow you to change the cluster-wide configuration as described in the next section.

Конфигурация пользовательских ролей¶

Доступны следующие операции:

• Хранить настройки пользовательских ролей в виде разделов в конфигурации на уровне кластера, например:

  # in YAML configuration file
  my_role:
    notify_url: "https://localhost:8080"
  

  -- in init.lua file
  local notify_url = 'http://localhost'
  function my_role.apply_config(conf, opts)
    local conf = conf['my_role'] or {}
    notify_url = conf.notify_url or 'default'
  end
  

• Download and upload cluster-wide configuration using the web interface or API (via GET/PUT queries to admin/config endpoint like curl localhost:8081/admin/config and curl -X PUT -d "{'my_parameter': 'value'}" localhost:8081/admin/config).

• Utilize it in your role’s apply_config() function.

Каждый экземпляр в кластере хранит копию конфигурационного файла в своей рабочей директории (которую можно задать с помощью cartridge.cfg({workdir = ...})):

• /var/lib/tarantool/<instance_name>/config.yml для экземпляров, развернутых из RPM-пакетов, под управлением systemd.
• /home/<username>/tarantool_state/var/lib/tarantool/config.yml for instances deployed from tar+gz archives.

The cluster’s configuration is a Lua table, downloaded and uploaded as YAML. If some application-specific configuration data, e.g. a database schema as defined by DDL (data definition language), needs to be stored on every instance in the cluster, you can implement your own API by adding a custom section to the table. The cluster will help you spread it safely across all instances.

Such section goes in the same file with topology-specific and vshard-specific sections that the cluster generates automatically. Unlike the generated, the custom section’s modification, validation, and application logic has to be defined.

Самый распространенный способ заключается в том, чтобы:

• validate_config(conf_new, conf_old) для валидации изменений, сделанных в новой конфигурации (conf_new) по отношению к старой конфигурации (conf_old).
• apply_config(conf, opts) для выполнения любого кода, связанного с изменениями конфигурации. Входными данными для этой функции будут применяемая конфигурация (conf, которая и есть новая конфигурация, проверенная чуть ранее с помощью validate_config()), а также параметры (аргумент opts включает в себя описываемый ниже логический флаг is_master ).

When implementing validation and application functions that call box ones for some reason, mind the following precautions:

• Жизненный цикл роли не предполагает, что кластер автоматически вызовет box.cfg() до вызова validate_config().

  If the validation function calls any box functions (e.g., to check a format), make sure the calls are wrapped in a protective conditional statement that checks if box.cfg() has already happened:

  -- Inside the validate_config() function:
  
  if type(box.cfg) == 'table' then
  
      -- Here you can call box functions
  
  end
  

• Unlike the validation function, apply_config() can call box functions freely as the cluster applies custom configuration after the automatic box.cfg() call.

  However, creating spaces, users, etc., can cause replication collisions when performed on both master and replica instances simultaneously. The appropriate way is to call such box functions on masters only and let the changes propagate to replicas automatically.

  По выполнении apply_config(conf, opts) кластер передает флаг is_master в таблице opts, который можно использовать для заключения функций из box в защитный условный оператор, если они могут вызвать конфликт:

  -- Inside the apply_config() function:
  
  if opts.is_master then
  
      -- Here you can call box functions
  
  end
  

#!/usr/bin/env tarantool
-- Реализация пользовательской роли

local cartridge = require('cartridge')

local role_name = 'custom-role'

-- Изменение конфигурации с вводом сеттера (альтернатива HTTP PUT)
local function set_secret(secret)
    local custom_role_cfg = cartridge.confapplier.get_deepcopy(role_name) or {}
    custom_role_cfg.secret = secret
    cartridge.confapplier.patch_clusterwide({
        [role_name] = custom_role_cfg,
    })
end
-- Валидация
local function validate_config(cfg)
    local custom_role_cfg = cfg[role_name] or {}
    if custom_role_cfg.secret ~= nil then
        assert(type(custom_role_cfg.secret) == 'string', 'custom-role.secret must be a string')
    end
    return true
end
-- Применение
local function apply_config(cfg)
    local custom_role_cfg = cfg[role_name] or {}
    local secret = custom_role_cfg.secret or 'default-secret'
    -- Make use of it
end

return {
    role_name = role_name,
    set_secret = set_secret,
    validate_config = validate_config,
    apply_config = apply_config,
}

Применение конфигурации пользовательской роли¶

With the implementation showed by the example, you can call the set_secret() function to apply the new configuration via the administrative console – or an HTTP endpoint if the role exports one.

Функция set_secret() вызывает cartridge.confapplier.patch_clusterwide(), которая производит двухфазную фиксацию транзакций:

1. Исправляет активную конфигурацию в памяти: копирует таблицу и заменяет раздел "custom-role" в копии на раздел, который задан функцией set_secret().
2. The cluster checks if the new configuration can be applied on all instances except disabled and expelled. All instances subject to update must be healthy and alive according to the membership module.
3. (Фаза подготовки) Кластер передает исправленную конфигурацию. Каждый экземпляр валидирует ее с помощью функции validate_config() каждой зарегистрированной роли. В зависимости от результата валидации:
   • В случае успеха (то есть возврата значения true) экземпляр сохраняет новую конфигурацию во временный файл с именем config.prepare.yml в рабочей директории.
   • (Abort phase) Otherwise, the instance reports an error and all the other instances roll back the update: remove the file they may have already prepared.
4. (Фаза фиксации) После успешной подготовки всех экземпляров кластер фиксирует изменения. Каждый экземпляр:
   1. Создает жесткую ссылку активной конфигурации.
   2. Atomically replaces the active configuration file with the prepared one. The atomic replacement is indivisible – it can either succeed or fail entirely, never partially.
   3. Вызывает функцию apply_config() каждой зарегистрированной роли.

Если любой из этих шагов не будет выполнен, в веб-интерфейсе появится ошибка рядом с соответствующим экземпляром. Кластер не обрабатывает такие ошибки автоматически, их необходимо исправлять вручную.

Такого рода исправлений можно избежать, если функция validate_config() сможет обнаружить все проблемы конфигурации, которые могут привести к ошибкам в apply_config().

Instance configuration upon a leader change¶

When Cartridge configures roles, it takes into account the leadership map (consolidated in the failover.lua module). The leadership map is composed when the instance enters the ConfiguringRoles state for the first time. Later the map is updated according to the failover mode.

Every change in the leadership map is accompanied by instance re-configuration. When the map changes, Cartridge updates the read_only setting and calls the apply_config callback for every role. It also specifies the is_master flag (which actually means is_leader, but hasn’t been renamed yet due to historical reasons).

It’s important to say that we discuss a distributed system where every instance has its own opinion. Even if all opinions coincide, there still may be races between instances, and you (as an application developer) should take them into account when designing roles and their interaction.

Leader appointment rules¶

The logic behind leader election depends on the failover mode: disabled, eventual, or stateful.

Manual leader promotion¶

It differs a lot depending on the failover mode.

In the disabled and eventual modes, you can only promote a leader by changing the failover priority (and applying a new clusterwide configuration).

In the stateful mode, the failover priority doesn’t make much sense (except for the first appointment). Instead, you should use the promotion API (the Lua cartridge.failover_promote or the GraphQL mutation {cluster{failover_promote()}}) which pushes manual appointments to the state provider.

Stateful failover implies consistent promotion: every instance before becoming writable performs wait_lsn operation to sync with the previous one.

The information about «previous leader» (we call it vclockkeeper) is also stored in the external storage. Even when old leader is demoted, it remains a vclockkeeper until the new one succeessfully awaits and persists his vclock in the external storage.

If replication is stuck and consistent promotion isn’t possible, a user has two options: revert promotion (re-promote the old one) or force it inconsistently (all kinds of failover_promote API has force_inconsistency flag).

Failover configuration¶

These are clusterwide parameters:

• mode: «disabled» / «eventual» / «stateful».
• state_provider: «tarantool» / «etcd».
• tarantool_params: {uri = "...", password = "..."}.
• etcd2_params: {endpoints = {...}, prefix = "/", lock_delay = 10, username = "", password = ""}.

Stateboard configuration¶

Like other Cartridge instances, the stateboard supports cartridge.argprase options:

• listen
• workdir
• password
• lock_delay

Similarly to other argparse options, they can be passed via command-line arguments or via environment variables, e.g.:

.rocks/bin/stateboard --workdir ./dev/stateboard --listen 4401 --password qwerty

Fine-tuning failover behavior¶

Besides failover priority and mode, there are some other private options that influence failover operation:

• LONGPOLL_TIMEOUT (failover) – the long polling timeout (in seconds) to fetch new appointments (default: 30);
• NETBOX_CALL_TIMEOUT (failover/coordinator) – stateboard client’s connection timeout (in seconds) applied to all communications (default: 1);
• RECONNECT_PERIOD (coordinator) – time (in seconds) to reconnect to the state provider if it’s unreachable (default: 5);
• IMMUNITY_TIMEOUT (coordinator) – minimal amount of time (in seconds) to wait before overriding an appointment (default: 15).

Configuration basics¶

Конфигурация экземпляра состоит из двух наборов параметров:

• cartridge.cfg() parameters;
• box.cfg() parameters.

Задать эти параметры можно:

1. В аргументах в командной строке.
2. В переменных окружения.
3. В конфигурационном файле формата YAML.
4. В файле init.lua.

Вышеуказанный порядок определяет приоритет: аргументы в командной строке замещают переменные окружения и т.д.

Независимо от того, как вы запускаете экземпляры, необходимо задать следующие параметры cartridge.cfg() для каждого экземпляра:

• advertise_uri – либо <ХОСТ>:<ПОРТ>, либо <ХОСТ>:, либо <ПОРТ>. Используется другими экземплярами для подключения. НЕ указывайте 0.0.0.0 – это должен быть внешний IP-адрес, а не привязка сокета.
• http_port – порт, который используется, чтобы открывать административный веб-интерфейс и API. По умолчанию: 8081. Чтобы отключить, укажите "http_enabled": False.
• workdir – директория, где хранятся все данные: файлы снимка, журналы упреждающей записи и конфигурационный файл cartridge. По умолчанию: ..

Если вы запустите экземпляры, используя интерфейс командной строки cartridge или systemctl, сохраните конфигурацию в формате YAML, например:

my_app.router: {"advertise_uri": "localhost:3301", "http_port": 8080}
my_app.storage_A: {"advertise_uri": "localhost:3302", "http_enabled": False}
my_app.storage_B: {"advertise_uri": "localhost:3303", "http_enabled": False}

С помощью интерфейса командной строки cartridge вы можете передать путь к этому файлу в качестве аргумента командной строки --cfg для команды cartridge start – или же указать путь в конфигурации cartridge (в ./.cartridge.yml или ~/.cartridge.yml):

cfg: cartridge.yml
run_dir: tmp/run
apps_path: /usr/local/share/tarantool

С помощью systemctl сохраните файл в формате YAML в /etc/tarantool/conf.d/ (по умолчанию путь systemd) или в место, указанное в переменной окружения TARANTOOL_CFG.

Если вы запускаете экземпляры с помощью tarantool init.lua, необходимо также передать другие параметры конфигурации в качестве параметров командной строки и переменных окружения, например:

$ tarantool init.lua --alias router --memtx-memory 100 --workdir "~/db/3301" --advertise_uri "localhost:3301" --http_port "8080"

Internal representation of clusterwide configuration¶

In the file system, clusterwide configuration is represented by a file tree. Inside workdir of any configured instance you can find the following directory:

config/
├── auth.yml
├── topology.yml
└── vshard_groups.yml

This is the clusterwide configuration with three default config sections – auth, topology, and vshard_groups.

Due to historical reasons clusterwide configuration has two appearances:

• old-style single-file config.yml with all sections combined, and
• modern multi-file representation mentioned above.

Before cartridge v2.0 it used to look as follows, and this representation is still used in HTTP API and luatest helpers.

# config.yml
---
auth: {...}
topology: {...}
vshard_groups: {...}
...

Beyond these essential sections, clusterwide configuration may be used for storing some other role-specific data. Clusterwide configuration supports YAML as well as plain text sections. It can also be organized in nested subdirectories.

In Lua it’s represented by the ClusterwideConfig object (a table with metamethods). Refer to the cartridge.clusterwide-config module documentation for more details.

Two-phase commit¶

Cartridge manages clusterwide configuration to be identical everywhere using the two-phase commit algorithm implemented in the cartridge.twophase module. Changes in clusterwide configuration imply applying it on every instance in the cluster.

Almost every change in cluster parameters triggers a two-phase commit: joining/expelling a server, editing replica set roles, managing users, setting failover and vshard configuration.

Two-phase commit requires all instances to be alive and healthy, otherwise it returns an error.

For more details, please, refer to the cartridge.config_patch_clusterwide API reference.

Managing role-specific data¶

Beside system sections, clusterwide configuration may be used for storing some other role-specific data. It supports YAML as well as plain text sections. And it can also be organized in nested subdirectories.

Role-specific sections are used by some third-party roles, i.e. sharded-queue and cartridge-extensions.

A user can influence clusterwide configuration in various ways. You can alter configuration using Lua, HTTP or GraphQL API. Also there are luatest helpers available.

cat > config.yml << CONFIG
---
custom_section: {}
...
CONFIG

curl -v "localhost:8081/admin/config" -X PUT --data-binary @config.yml

curl -v "localhost:8081/admin/config" -o config.yml

g.cluster.main_server:graphql({query = [[
    mutation($sections: [ConfigSectionInput!]) {
        cluster {
            config(sections: $sections) {
                filename
                content
            }
        }
    }]],
    variables = {sections = {
      {
        filename = 'custom_section.yml',
        content = '---\n{}\n...',
      }
    }}
})

function create_tube(tube_name, tube_opts)
    local tubes = cartridge.config_get_deepcopy('tubes') or {}
    tubes[tube_name] = tube_opts or {}

    return cartridge.config_patch_clusterwide({tubes = tubes})
end

local function validate_config(conf)
    local tubes = conf.tubes or {}
    for tube_name, tube_opts in pairs(tubes) do
        -- validate tube_opts
    end
    return true
end

local function apply_config(conf, opts)
    if opts.is_master then
        local tubes = cfg.tubes or {}
        -- create tubes according to the configuration
    end
    return true
end

g.before_all(function()
    g.cluster = helpers.Cluster.new(...)
    g.cluster:upload_config({some_section = 'some_value'})
    t.assert_equals(
        g.cluster:download_config(),
        {some_section = 'some_value'}
    )
end)

Развертывание приложения в виде пакета rpm или deb¶

The choice between DEB and RPM depends on the package manager of the target OS. For example, DEB is native for Debian Linux, and RPM – for CentOS.

1. Упакуйте файлы приложения в распространяемый пакет:

   $ cartridge pack rpm ИМЯ_ПРИЛОЖЕНИЯ
   # -- ИЛИ --
   $ cartridge pack deb ИМЯ_ПРИЛОЖЕНИЯ
   

   Будет создан RPM-пакет (например, ./my_app-0.1.0-1.rpm) или же DEB-пакет (например, ./my_app-0.1.0-1.deb).

2. Загрузите пакет на необходимые серверы с поддержкой systemctl.

3. Установите:

   $ yum install ИМЯ_ПРИЛОЖЕНИЯ-ВЕРСИЯ.rpm
   # -- ИЛИ --
   $ dpkg -i ИМЯ_ПРИЛОЖЕНИЯ-ВЕРСИЯ.deb
   

4. Выполните конфигурацию экземпляров.

5. Запустите экземпляры Tarantool’а с соответствующими службами. Например, это можно сделать, используя systemctl:

   # запуск одного экземпляра
   $ systemctl start my_app
   
   # запуск нескольких экземпляров
   $ systemctl start my_app@router
   $ systemctl start my_app@storage_A
   $ systemctl start my_app@storage_B
   

6. Если это приложение с поддержкой кластеров, далее переходите к развертыванию кластера.

   Примечание

   If you’re migrating your application from local test environment to production, you can re-use your test configuration at this step:

   1. In the cluster web interface of the test environment, click Configuration files > Download to save the test configuration.
   2. In the cluster web interface of the production environment, click Configuration files > Upload to upload the saved configuration.

Развертывание архива tar+gz¶

1. Упакуйте файлы приложения в распространяемый пакет:

   $ cartridge pack tgz ИМЯ_ПРИЛОЖЕНИЯ
   

   Будет создан архив tar+gz (например, ./my_app-0.1.0-1.tgz).

2. Upload the archive to target servers, with tarantool and (optionally) cartridge-cli installed.

3. Распакуйте архив:

   $ tar -xzvf ИМЯ_ПРИЛОЖЕНИЯ-ВЕРСИЯ.tgz
   

4. Выполните конфигурацию экземпляров.

5. Запустите экземпляры Tarantool’а. Это можно сделать, используя:

   • tarantoolctl, например:

     $ tarantool init.lua # запускает одиночный экземпляр
     

   • или cartridge, например:

     # в директории приложения
     $ cartridge start # запускает все экземпляры
     $ cartridge start .router_1 # запускает один экземпляр
     
     # в среде с несколькими приложениями
     $ cartridge start my_app # запускает все экземпляры my_app
     $ cartridge start my_app.router # запускает один экземпляр
     

6. Если это приложение с поддержкой кластеров, далее переходите к развертыванию кластера.

   Примечание

   If you’re migrating your application from local test environment to production, you can re-use your test configuration at this step:

   1. In the cluster web interface of the test environment, click Configuration files > Download to save the test configuration.
   2. In the cluster web interface of the production environment, click Configuration files > Upload to upload the saved configuration.

Развертывание из исходных файлов¶

Такой метод развертывания предназначен только для локального тестирования.

1. Вытяните все зависимости в директорию .rocks:

   $ tarantoolctl rocks make

2. Выполните конфигурацию экземпляров.

3. Запустите экземпляры Tarantool’а. Это можно сделать, используя:

   • tarantoolctl, например:

     $ tarantool init.lua # запускает одиночный экземпляр
     

   • или cartridge, например:

     # в директории приложения
     cartridge start # запускает все экземпляры
     cartridge start .router_1 # запускает один экземпляр
     
     # в среде с несколькими приложениями
     cartridge start my_app # запускает все экземпляры my_app
     cartridge start my_app.router # запускает один экземпляр
     

4. Если это приложение с поддержкой кластеров, далее переходите к развертыванию кластера.

   Примечание

   If you’re migrating your application from local test environment to production, you can re-use your test configuration at this step:

   1. In the cluster web interface of the test environment, click Configuration files > Download to save the test configuration.
   2. In the cluster web interface of the production environment, click Configuration files > Upload to upload the saved configuration.

Запуск/остановка с помощью tarantool¶

С помощью tarantool можно запустить только один экземпляр:

$ tarantool init.lua # простейшая команда

Можно также задать дополнительные параметры в командной строке или в переменных окружения.

Чтобы остановить экземпляр, используйте Ctrl+C.

Запуск/остановка с помощью CLI в cartridge¶

С помощью интерфейса командной строки cartridge, можно запустить один или несколько экземпляров:

$ cartridge start [ИМЯ_ПРИЛОЖЕНИЯ[.ИМЯ_ЭКЗЕМПЛЯРА]] [параметры]

Возможные параметры:

--script FILE

Точка входа в приложение. По умолчанию:

• TARANTOOL_SCRIPT, либо
• ./init.lua, если запуск идет из директории приложения, или же
• :путь_к_приложениям/:имя_приложения/init.lua в среде с несколькими приложениями.

--apps_path PATH

Путь к директории с приложениями при запуске из среды с несколькими приложениями. По умолчанию: /usr/share/tarantool.

--run_dir DIR

Директория с файлами pid и sock. По умолчанию: TARANTOOL_RUN_DIR или /var/run/tarantool.

--cfg FILE

Конфигурациионный файл в формате YAML для экземпляров Cartridge. По умолчанию: TARANTOOL_CFG или ./instances.yml.

--foreground

Не в фоне.

Например:

cartridge start my_app --cfg demo.yml --run_dir ./tmp/run --foreground

Это запустит все экземпляры Tarantool’а, указанные в файле cfg, не в фоновом режиме с принудительным использованием переменных окружения.

Если ИМЯ_ПРИЛОЖЕНИЯ не указано, cartridge выделит его из имени файла ./*.rockspec.

Если ИМЯ_ЭКЗЕМПЛЯРА не указывается, cartridge прочитает файл cfg и запустит все указанные экземпляры:

# в директории приложения
cartridge start # запускает все экземпляры
cartridge start .router_1 # запускает отдельный экземпляр

# в среде с несколькими приложениями
cartridge start my_app # запускает все экземпляры my_app
cartridge start my_app.router # запускает отдельный экземпляр

Чтобы остановить экземпляры, выполните команду:

$ cartridge stop [ИМЯ_ПРИЛОЖЕНИЯ[.ИМЯ_ЭКЗЕМПЛЯРА]] [параметры]

Поддерживаются следующие параметры из команды cartridge start`:

• --run_dir DIR
• --cfg FILE

Запуск/остановка с помощью systemctl¶

• Чтобы запустить отдельный экземпляр:

  $ systemctl start ИМЯ_ПРИЛОЖЕНИЯ
  

  This will start a systemd service that will listen to the port specified in instance configuration (http_port parameter).

• Чтобы запустить несколько экземпляров на одном или нескольких серверах:

  $ systemctl start ИМЯ_ПРИЛОЖЕНИЯ@ЭКЗЕМПЛЯР_1
  $ systemctl start ИМЯ_ПРИЛОЖЕНИЯ@ЭКЗЕМПЛЯР_2
  ...
  $ systemctl start ИМЯ_ПРИЛОЖЕНИЯ@ЭКЗЕМПЛЯР_N
  

  где ИМЯ_ПРИЛОЖЕНИЯ@ЭКЗЕМПЛЯР_N – это имя экземпляра сервиса systemd с инкрементным числом N (уникальным для каждого экземпляра), которое следует добавить к порту 3300 для настройки прослушивания (например, 3301, 3302 и т.д.).

• Чтобы остановить все сервисы на сервере, используйте команду systemctl stop и укажите имена экземпляров по одному. Например:

  $ systemctl stop ИМЯ_ПРИЛОЖЕНИЯ@ЭКЗЕМПЛЯР_1 ИМЯ_ПРИЛОЖЕНИЯ@ЭКЗЕМПЛЯР_2 ... ИМЯ_ПРИЛОЖЕНИЯ@ЭКЗЕМПЛЯР_<N>
  

When running instances with systemctl, keep these practices in mind:

• You can specify instance configuration in a YAML file.

  This file can contain these options; see an example here).

  Save this file to /etc/tarantool/conf.d/ (the default systemd path) or to a location set in the TARANTOOL_CFG environment variable (if you’ve edited the application’s systemd unit file). The file name doesn’t matter: it can be instances.yml or anything else you like.

  Here’s what systemd is doing further:

  • obtains app_name (and instance_name, if specified) from the name of the application’s systemd unit file (e.g. APP_NAME@default or APP_NAME@INSTANCE_1);
  • sets default console socket (e.g. /var/run/tarantool/APP_NAME@INSTANCE_1.control), PID file (e.g. /var/run/tarantool/APP_NAME@INSTANCE_1.pid) and workdir (e.g. /var/lib/tarantool/<APP_NAME>.<INSTANCE_NAME>). Environment=TARANTOOL_WORKDIR=${workdir}.%i

  Finally, cartridge looks across all YAML files in /etc/tarantool/conf.d for a section with the appropriate name (e.g. app_name that contains common configuration for all instances, and app_name.instance_1 that contain instance-specific configuration). As a result, Cartridge options workdir, console_sock, and pid_file in the YAML file cartridge.cfg become useless, because systemd overrides them.

• The default tool for querying logs is journalctl. For example:

  # show log messages for a systemd unit named APP_NAME.INSTANCE_1
  $ journalctl -u APP_NAME.INSTANCE_1
  
  # show only the most recent messages and continuously print new ones
  $ journalctl -f -u APP_NAME.INSTANCE_1
  

  If really needed, you can change logging-related box.cfg options in the YAML configuration file: see log and other related options.

Error objects in Lua¶

Error classes help to locate the problem’s source. For this purpose, an error object contains its class, stack traceback, and a message.

local errors = require('errors')
local DangerousError = errors.new_class("DangerousError")

local function some_fancy_function()

    local something_bad_happens = true

    if something_bad_happens then
        return nil, DangerousError:new("Oh boy")
    end

    return "success" -- not reachable due to the error
end

print(some_fancy_function())

nil DangerousError: Oh boy
stack traceback:
    test.lua:9: in function 'some_fancy_function'
    test.lua:15: in main chunk

For uniform error handling, errors provides the :pcall API:

local ret, err = DangerousError:pcall(some_fancy_function)
print(ret, err)

nil DangerousError: Oh boy
stack traceback:
    test.lua:9: in function <test.lua:4>
    [C]: in function 'xpcall'
    .rocks/share/tarantool/errors.lua:139: in function 'pcall'
    test.lua:15: in main chunk

`lua print(DangerousError:pcall(error, 'what could possibly go wrong?')) `

nil DangerousError: what could possibly go wrong?
stack traceback:
    [C]: in function 'xpcall'
    .rocks/share/tarantool/errors.lua:139: in function 'pcall'
    test.lua:15: in main chunk

For errors.pcall there is no difference between the return nil, err and error() approaches.

Note that errors.pcall API differs from the vanilla Lua pcall. Instead of true the former returns values returned from the call. If there is an error, it returns nil instead of false, plus an error message.

Remote net.box calls keep no stack trace from the remote. In that case, errors.netbox_eval comes to the rescue. It will find a stack trace from local and remote hosts and restore metatables.

> conn = require('net.box').connect('localhost:3301')
> print( errors.netbox_eval(conn, 'return nil, DoSomethingError:new("oops")') )
nil     DoSomethingError: oops
stack traceback:
        eval:1: in main chunk
during net.box eval on localhost:3301
stack traceback:
        [string "return print( errors.netbox_eval("]:1: in main chunk
        [C]: in function 'pcall'

However, vshard implemented in Tarantool doesn’t utilize the errors module. Instead it uses its own errors. Keep this in mind when working with vshard functions.

Data included in an error object (class name, message, traceback) may be easily converted to string using the tostring() function.

GraphQL¶

GraphQL implementation in Cartridge wraps the errors module, so a typical error response looks as follows:

{
    "errors":[{
        "message":"what could possibly go wrong?",
        "extensions":{
            "io.tarantool.errors.stack":"stack traceback: ...",
            "io.tarantool.errors.class_name":"DangerousError"
        }
    }]
}

Read more about errors in the GraphQL specification.

If you’re going to implement a GraphQL handler, you can add your own extension like this:

local err = DangerousError:new('I have extension')
err.graphql_extensions = {code = 403}

It will lead to the following response:

{
    "errors":[{
        "message":"I have extension",
        "extensions":{
            "io.tarantool.errors.stack":"stack traceback: ...",
            "io.tarantool.errors.class_name":"DangerousError",
            "code":403
        }
    }]
}

HTTP¶

In a nutshell, an errors object is a table. This means that it can be swiftly represented in JSON. This approach is used by Cartridge to handle errors via http:

local err = DangerousError:new('Who would have thought?')

local resp = req:render({
    status = 500,
    headers = {
        ['content-type'] = "application/json; charset=utf-8"
    },
    json = json.encode(err),
})

{
    "line":27,
    "class_name":"DangerousError",
    "err":"Who would have thought?",
    "file":".../app/roles/api.lua",
    "stack":"stack traceback:..."
}