Руководство разработчика

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

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

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

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

  Примечание

  Для получения дополнительной информации о шардировании см. документацию по модулю vshard.

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

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

Вы можете создавать пользовательские роли для любых целей, например:

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

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

1. Возьмите в качестве примера файл app/roles/custom.lua из проекта. Переименуйте этот файл как угодно, например app/roles/custom-role.lua, и опишите логику роли. Например:

   -- Реализуйте пользовательскую роль в app/roles/custom-role.lua
   local role_name = 'custom-role'
   
   local function init()
   ...
   end
   
   local function stop()
   ...
   end
   
   return {
       role_name = role_name,
       init = init,
       stop = stop,
   }
   

   Здесь значение role_name может отличаться от имени модуля, переданного в функцию cartridge.cfg(). Если не указать переменную role_name, то значением по умолчанию будет имя модуля.

   Примечание

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

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

   -- Зарегистрируйте пользовательскую роль в init.lua,
   ...
   local cartridge = require('cartridge')
   ...
   cartridge.cfg({
       workdir = ...,
       advertise_uri = ...,
       roles = {'custom-role'},
   })
   ...
   

   где custom-role — это название загружаемого Lua-модуля.

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

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

  В пределах тела функции можно вызывать любые функции из box: создавать спейсы, индексы, выдавать права и т.д. Вот как может выглядеть функция инициализации:

  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
  

  Примечание

  • Спейсами, индексами и форматами не управляют ни vshard-router, ни vshard-storage — это придется делать в рамках пользовательской роли, то есть добавить вызов box.schema.space.create() к первой кластерной роли, как показано в примере выше.
  • Тело функции заключено в условный оператор, который позволяет вызывать функции box только на мастерах. Это предотвращает конфликты репликации, так как данные автоматически передаются на реплики.

• stop() — это функция завершения работы роли. Ее стоит использовать, если инициализация запускает файбер, который нужно остановить, или же выполняет любую задачу, которую нужно отменить при завершении работы.

• validate_config() и apply_config() — это функции, которые валидируют и применяют настройки роли соответственно. Их стоит использовать, если какие-то настройки нужно хранить на уровне кластера.

Далее, изучите жизненный цикл ролей, чтобы реализовать необходимые функции.

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

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

Например:

-- Зависимости для ролей, определенные в 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 предназначены для независимой обработки горячих и холодных данных.

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

-- Укажите группы в init.lua
cartridge.cfg({
    vshard_groups = {'hot', 'cold'},
    ...
})

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

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

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

Наконец, обратите внимание на синтаксис для доступа к роутеру. Каждый экземпляр со включенной ролью vshard-router инициализирует несколько роутеров. Доступ к ним можно получить через роль:

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

Если роли не указаны, доступ к статическому роутеру можно получить, как и прежде (когда Tarantool Cartridge не знал о группах):

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

Тем не менее, при использовании действующего API, работающего с группами, статический роутер следует вызывать при помощи двоеточия:

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

Жизненный цикл роли и порядок выполнения функций

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

cartridge.admin.edit_replicaset('replicaset-uuid', {roles = {'vshard-router', 'custom-role'}})

Если несколько ролей одновременно включены на экземпляре, кластер сначала инициализирует встроенные роли (если они есть), а затем пользовательские (если они есть) в том порядке, в котором пользовательские роли были перечислены в cartridge.cfg().

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

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

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

В качестве эксперимента дадим кластеру некоторые задачи и посмотрим порядок выполнения функций роли:

• Присоединение экземпляра или создание набора реплик (в обоих случаях с включенной ролью):
  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-сервер.
  • Выполнять любой код, связанный с инициализацией роли.
• Функции stop() должны отменять любую задачу, которую нужно отменить при завершении работы роли.
• Функция validate_config() должна валидировать любые изменения конфигурации.
• Функция apply_config() может выполнять любой код, связанный с изменением конфигурации, например, следить за файбером expirationd.

Функции валидации и применения конфигурации позволяют настроить конфигурацию всего кластера, как описано в следующем разделе.

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

Вы можете:

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

  # в конфигурационном YAML-файле
  my_role:
    notify_url: "https://localhost:8080"
  

  -- в файле init.lua
  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
  

• Загружать и выгружать конфигурацию всего кластера через веб-интерфейс или с помощью API (запросы GET/PUT к конечной точке admin/config: curl localhost:8081/admin/config и curl -X PUT -d "{'my_parameter': 'value'}" localhost:8081/admin/config).

• Использовать ее в функции apply_config() в своей роли.

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

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

Конфигурация кластера представляет собой Lua-таблицу, которую можно загрузить и выгрузить в формате YAML. Если в каждом экземпляре кластера необходимо хранить какие-то данные конфигурации для конкретного приложения (например, схему базы данных, описанную с помощью языка определения данных DDL), можно использовать свой собственный API, добавив в таблицу специальный раздел. Кластер поможет вам безопасно передать настройки всем экземплярам.

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

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

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

При реализации функций валидации и применения конфигурации, которые по какой-либо причине вызывают функции box, следует принять меры предосторожности:

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

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

  -- Внутри функции validate_config():
  if type(box.cfg) == 'table' then
      -- Здесь вы можете вызывать функции из box
  end
  

• В отличие от функции валидации, apply_config() может свободно вызывать функции из box, потому что кластер применяет пользовательскую конфигурацию после автоматического вызова box.cfg().

  Тем не менее, создание спейсов, пользователей и т. д. может вызвать конфликты репликации при одновременном выполнении на мастере и на реплике. Лучше всего вызывать такие функции из box только на мастерах, а на реплики изменения отправятся автоматически.

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

  -- Внутри функции  apply_config():
  if opts.is_master then
      -- Здесь вы можете вызывать функции из box
  end
  

-- Реализация пользовательской роли

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'
    -- И используйте
end

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

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

В примере реализации можно вызвать функцию set_secret(), чтобы применить новую конфигурацию с помощью административной консоли или конечной точки HTTP, если роль ее экспортирует.

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

1. Исправляет активную конфигурацию в памяти: копирует таблицу и заменяет раздел "custom-role" в копии на раздел, который задан функцией set_secret().
2. Кластер проверяет, можно ли применить новую конфигурацию ко всем экземплярам, кроме отключенных и исключенных. Все обновляемые экземпляры должны быть исправными и в статусе alive в соответствии с требованиями модуля membership.
3. (Фаза подготовки) Кластер передает исправленную конфигурацию. Каждый экземпляр валидирует ее с помощью функции validate_config() из каждой зарегистрированной роли. В зависимости от результата валидации:
   • В случае успеха (то есть возврата значения true) экземпляр сохраняет новую конфигурацию во временный файл с именем config.prepare.yml в рабочем каталоге.
   • (Фаза отмены) В противном случае экземпляр сообщает об ошибке, а все остальные экземпляры откатывают обновление: удаляют файл, если уже подготовили его.
4. (Фаза коммита) После успешной подготовки всех экземпляров кластер фиксирует изменения. Каждый экземпляр:
   1. Создает жесткую ссылку на активную конфигурацию.
   2. Атомарно заменяет активный файл конфигурации на подготовленный файл. Атомарная замена неделима: она выполняется или не выполняется полностью — но не частично.
   3. Вызывает функцию apply_config() каждой зарегистрированной роли.

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

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

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

Когда Cartridge настраивает роли, он учитывает ассоциативный массив лидеров (консолидированный в модуле failover.lua). Ассоциативный массив лидеров составляется, когда экземпляр впервые входит в состояние ConfiguringRoles. В дальнейшем массив обновляется в соответствии с режимом восстановления после отказа.

Каждое изменение в ассоциативном массиве лидеров сопровождается переконфигурацией экземпляра. Когда массив меняется, Cartridge обновляет параметр read_only и вызывает apply_config для каждой роли. Он также устанавливает флаг is_master (который на самом деле означает is_leader, но еще не переименован в силу исторических причин).

Важно отметить, что речь идет о распределенной системе, где у каждого экземпляра есть свое собственное мнение. Даже если все мнения совпадают, экземпляры все равно могут быть в состоянии гонки, и вам (как разработчику приложения) следует учитывать их при проектировании ролей и их взаимодействия.

Правила назначения лидера

Логика выбора лидера зависит от режима восстановления после отказа: disabled, eventual или stateful.

 cartridge.cfg({
    ...
    enable_synchro_mode = true,
})

Продвижение лидера вручную

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

В режимах disabled и eventual продвинуть лидера можно только путем изменения приоритета восстановления после отказа (и применения новой конфигурации на уровне кластера).

В режиме stateful приоритет восстановления после отказа не имеет особого смысла (кроме первого назначения). Вместо этого следует использовать API для продвижения (cartridge.failover_promote в Lua или mutation {cluster{failover_promote()}} в GraphQL), который передает данные о продвижении поставщику состояния.

Режим stateful подразумевает последовательное продвижение: прежде чем разрешить запись, каждый экземпляр выполняет операцию wait_lsn для синхронизации с предыдущим.

Информация о предыдущем лидере (мы называем его vclockkeeper) также хранится на внешнем хранилище. Даже после смещения старого лидера он остается vclockkeeper до тех пор, пока новый лидер успешно ждет и сохраняет vclock на внешнем хранилище.

Если репликация застряла и последовательное продвижение невозможно, у пользователя есть два варианта: отменить продвижение (снова продвинуть старого лидера) или вызвать недопустимое состояние (во всех видах API failover_promote есть флаг для вызова недопустимого состояния force_inconsistency).

Последовательное продвижение не работает для наборов реплик с установленным флагом all_rw и для наборов реплик из одного экземпляра. В этих случаях экземпляр даже не пытается запросить vclockkeeper и выполнить wait_lsn. Но координатор все равно назначает нового лидера, если текущий будет недоступен.

In the Raft failover mode, the user can also use the promotion API: cartridge.failover_promote in Lua or mutation {cluster{failover_promote()}} in GraphQL, which calls box.ctl.promote on the specified instances. Note that box.ctl.promote starts fair elections, so some other instance may become the leader in the replicaset.

Unelectable nodes

You can restrict the election of a particular node in the stateful failover mode by GraphQL or Lua API. An «unelectable» node can’t become a leader in a replicaset. It could be useful for nodes that could only be used for election process and for routers that shouldn’t store the data.

In edit_topology:

{
   "replicasets": [
     {
         "alias": "storage",
         "uuid": "aaaaaaaa-aaaa-0000-0000-000000000000",
         "join_servers": [
             {
                 "uri": "localhost:3301",
                 "uuid": "aaaaaaaa-aaaa-0000-0000-000000000001",
                 "electable": false
             }
         ],
         "roles": []
     }
   ]
 }

In Lua API:

-- to make nodes unelectable:
require('cartridge.lua-api.topology').api_topology.set_unelectable_servers(uuids)
-- to make nodes electable:
require('cartridge.lua-api.topology').api_topology.set_electable_servers(uuids)

You can also make a node unelectable in WebUI:

If everything is ok, you will see a crossed-out crown to the left of the instance name.

Фенсинг

Ни режим eventual, ни режим stateful не защищают набор реплик от появления нескольких лидеров, когда сеть разделена. А фенсинг (изоляция узла, fencing) защищает, обеспечивая соблюдение требования о наличии не более одного лидера в наборе реплик.

Fencing operates as a fiber that occasionally checks connectivity with the state provider and with replicas. Fencing fiber runs on vclockkeepers; it starts right after consistent promotion succeeds. Replicasets which don’t need consistency (single-instance and all_rw) don’t defend, though.

Чтобы фенсинг сработал, должны выполняться такие условия: потеря кворума поставщика состояния и потеря хотя бы одной реплики. В противном случае, если либо поставщик состояния доступен, либо все реплики работают, файбер фенсинга ждет и не вмешивается в их работу.

Когда фенсинг срабатывает, он локально фиктивно назначает лидера на nil. Следовательно, экземпляр будет доступен только для чтения. Возврат статуса лидера возможен только при восстановлении кворума; подключение реплики не будет обязательным условием, чтобы вернуть статус лидера. Экземпляр может снова стать лидером в соответствии с правилами последовательного переключения, если только какой-либо другой экземпляр еще не был назначен новым лидером.

Raft failover supports fencing too. Check election_fencing_mode parameter of box.cfg{}

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

Параметры конфигурации на уровне кластера:

• mode: «disabled» / «eventual» / «stateful» / «raft».
• state_provider: «tarantool» / «etcd».
• failover_timeout – время (в секундах) до перевода члена кластера в статусе suspect в статус dead и запуска восстановления после отказа (по умолчанию: 20).
• tarantool_params: {uri = "...", password = "..."}.
• etcd2_params: {endpoints = {...}, prefix = "/", lock_delay = 10, username = "", password = ""}.
• fencing_enabled: true / false (по умолчанию: false).
• fencing_timeout – время до срабатывания фенсинга после неудачной проверки (по умолчанию: 10).
• fencing_pause – время на выполнение проверки (по умолчанию: 2).
• leader_autoreturn: true / false (default: false).
• autoreturn_delay – the time before failover will try to return leader in replicaset to the first instance in failover_priority list (default: 300).
• check_cookie_hash – enable check that nobody else uses this stateboard.

Должно быть так: failover_timeout > fencing_timeout >= fencing_pause.

mutation {
  cluster { failover_params(
    mode: "stateful"
    failover_timeout: 20
    state_provider: "etcd2"
    etcd2_params: {
        endpoints: ["http://127.0.0.1:4001"]
        prefix: "etcd-prefix"
    }) {
        mode
        }
    }
}

Конфигурация stateboard

Как и другие экземпляры Cartridge, stateboard поддерживает параметры cartridge.argprase:

• listen
• workdir
• password
• lock_delay

Как и другие параметры argparse, их можно передавать как аргументы командной строки или переменные окружения, например:

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

Настройка поведения при восстановлении после отказа

Помимо приоритета и режима восстановления после отказа, есть еще несколько закрытых параметров, которые влияют на восстановление после отказа:

• LONGPOLL_TIMEOUT (failover) – время ожидания длинного запроса (в секундах) для получения данных о назначении лидера (по умолчанию: 30);
• NETBOX_CALL_TIMEOUT (failover/coordinator) – время ожидания соединения клиента stateboard (в секундах), применяется ко всем соединениям (по умолчанию: 1);
• RECONNECT_PERIOD (coordinator) – время (в секундах) для повторного соединения с поставщиком состояния, если он недоступен (по умолчанию: 5);
• IMMUNITY_TIMEOUT (coordinator) – минимальное время (в секундах) до переназначения лидера (по умолчанию: 15).

Основы конфигурации

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

• параметры cartridge.cfg();
• параметры box.cfg().

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

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

С помощью 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"

Внутреннее представление конфигурации на уровне кластера

В файловой системе конфигурация на уровне кластера показана в виде дерева файлов. В workdir любого сконфигурированного экземпляра можно найти каталог:

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

Это конфигурация на уровне кластера с тремя разделами config по умолчанию: auth, topology и vshard_groups.

Исторически сложилось так, что есть два вида кластерной конфигурация:

• один файл config.yml старого образца, в котором находятся все разделы, и
• представленное выше современное представление из нескольких файлов.

Так конфигурация выглядела до версии Cartridge 2.0 и до сих используется в таком виде в HTTP API и вспомогательных утилитах luatest:

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

Помимо основных разделов, в конфигурации на уровне кластера можно хранить некоторые другие данные для конкретной роли. Конфигурация на уровне кластера поддерживает YAML, а также обычные текстовые разделы. Используя вложенные подкаталоги, можно упорядочить разделы.

В Lua конфигурация представлена в виде объекта ClusterwideConfig (таблица с метаметодами). Для получения более подробной информации обратитесь к документации модуля cartridge.clusterwide-config.

Двухфазная фиксация транзакций

Конфигурация на уровне кластера в Cartridge одинакова для всех экземпляров, что достигается использованием двухфазного алгоритма фиксации транзакций, который реализован в модуле cartridge.twophase. Изменения в конфигурации на уровне кластера подразумевают применение этих изменений к каждому экземпляру в кластере.

Почти каждое изменение параметров кластера вызывает двухфазную фиксацию: присоединение/исключение сервера, редактирование ролей наборов реплик, управление пользователями, настройка восстановления после отказа и конфигурация vshard.

Для двухфазной фиксации необходимо, чтобы все экземпляры были исправными и в статусе alive, иначе вернется ошибка.

Для получения более подробной информации, обратитесь к справочнику по API cartridge.config_patch_clusterwide.

Управление данными по конкретной роли

Помимо системных разделов, в конфигурации на уровне кластера можно хранить некоторые другие данные для конкретной роли. Конфигурация поддерживает YAML, а также обычные текстовые разделы. Используя вложенные подкаталоги, можно упорядочить разделы.

Некоторые сторонние роли (например, sharded-queue и cartridge-extensions также могут использовать такие разделы для конкретных ролей.

Конфигурацию на уровне кластера можно изменять различными способами. Вносить изменения можно с помощью API для Lua, HTTP или GraphQL. Кроме того, есть вспомогательные утилиты luatest.

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
        -- валидируйте tube_opts
    end
    return true
end

local function apply_config(conf, opts)
    if opts.is_master then
        local tubes = cfg.tubes or {}
        -- создайте tubes в соответствии с конфигурацией
    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-пакета

Выбор между DEB- и RPM-пакетами зависит от пакетного менеджера целевой ОС. DEB используется для Debian Linux и его производных, а RPM — для CentOS/RHEL и других основанных на RPM дистрибутивов Linux.

В производственной среде для управления экземплярами приложения и доступа к записям журнала рекомендуется использовать подсистему systemd.

Чтобы развернуть приложение на Tarantool Cartridge, выполните следующие шаги:

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

   $ cartridge pack rpm [APP_PATH] [--use-docker]
   $ # -- ИЛИ --
   $ cartridge pack deb [APP_PATH] [--use-docker]
   

   где

   • APP_PATH — путь к директории приложения. Значение по умолчанию — . (текущая директория).
   • --use-docker — флаг, который нужно использовать при упаковке приложения на различных листрибутивах Linux или на macOS. Он гарантирует что результирующий артефакт содержит совместимые с Linux модули и исполняемые файлы.

   В результате создается RPM- или DEB-пакет со следующим способом именования: <APP_NAME>-<VERSION>.{rpm,deb}. Например, ./my_app-0.1.0-1-g8c57dcb.rpm или ./my_app-0.1.0-1-g8c57dcb.deb. Чтобы больше узнать о формате и использовании команды cartridge pack, прочитайте ее описание.

2. Загрузите сгенерированный пакет на целевой сервер.

3. Установите приложение:

   $ sudo yum install <APP_NAME>-<VERSION>.rpm
   $ # -- ИЛИ --
   $ sudo dpkg -i <APP_NAME>-<VERSION>.deb
   

4. Настройте экземпляры приложения.

   Конфигурация хранится в файле /etc/tarantool/conf.d/instances.yml. Создайте этот файл и укажите параметры экземпляров. Подробности читайте в Конфигурация экземпляров.

   Например:

   my_app:
     cluster_cookie: secret-cookie
   
   my_app.router:
     advertise_uri: localhost:3301
     http_port: 8081
   
   my_app.storage-master:
     advertise_uri: localhost:3302
     http_port: 8082
   
   my_app.storage-replica:
     advertise_uri: localhost:3303
     http_port: 8083
   

   Примечание

   Не указывайте среди этих настроек рабочие директории экземпляров. Используйте для этого переменную окружения TARANTOOL_WORKDIR в юнит-файле для каждого из соответствующих экземпляров (/etc/systemd/system/<APP_NAME>@.service).

5. Запустите экземпляры приложения с помощью команды systemctl.

   Подробности читайте на странице Запуск и остановка с помощью systemctl.

   $ sudo systemctl start my_app@router
   $ sudo systemctl start my_app@storage-master
   $ sudo systemctl start my_app@storage-replica
   

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

   Примечание

   При переносе приложения из локальной среды тестирования на рабочий сервер на этом этапе можно переиспользовать тестовые настройки:

   1. В веб-интерфейсе кластера тестовой среды нажмите Configuration files > Download, чтобы сохранить тестовую конфигурацию.
   2. В веб-интерфейсе кластера на рабочем сервере нажмите Configuration files > Upload, чтобы загрузить сохраненную конфигурацию.

Вы можете затем управлять работающими экземплярами, используя стандартные операции утилит systemd:

• systemctl — для остановки, перезапуска, проверки статуса экземпляров и т. д.;
• journalctl для работы с журналами экземпляров.

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

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

   $ cartridge pack tgz APP_NAME
   

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

2. Загрузите архив на серверы, на которых установлены tarantool и (необязательно) cartridge-cli.

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

   $ tar -xzvf APP_NAME-VERSION.tgz
   

4. Настройте экземпляр(ы). Создайте файл под названием /etc/tarantool/conf.d/instances.yml. Например:

   my_app:
    cluster_cookie: secret-cookie
   
   my_app.instance-1:
    http_port: 8081
    advertise_uri: localhost:3301
   
   my_app.instance-2:
    http_port: 8082
    advertise_uri: localhost:3302
   

   См. описание здесь.

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. Если это приложение с поддержкой кластеров, далее переходите к развертыванию кластера.

   Примечание

   При переносе приложения из локальной среды тестирования на рабочий сервер на этом этапе можно переиспользовать тестовые настройки:

   1. В веб-интерфейсе кластера тестовой среды нажмите Configuration files > Download, чтобы сохранить тестовую конфигурацию.
   2. В веб-интерфейсе кластера на рабочем сервере нажмите Configuration files > Upload, чтобы загрузить сохраненную конфигурацию.

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

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

1. Вытяните все зависимости в каталог .rocks:

   $ tt rocks make
   

2. Настройте экземпляр(ы). Создайте файл под названием /etc/tarantool/conf.d/instances.yml. Например:

   my_app:
    cluster_cookie: secret-cookie
   
   my_app.instance-1:
    http_port: 8081
    advertise_uri: localhost:3301
   
   my_app.instance-2:
    http_port: 8082
    advertise_uri: localhost:3302
   

   См. описание здесь.

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. Если это приложение с поддержкой кластеров, далее переходите к развертыванию кластера.

   Примечание

   При переносе приложения из локальной среды тестирования на рабочий сервер на этом этапе можно переиспользовать тестовые настройки:

   1. В веб-интерфейсе кластера тестовой среды нажмите Configuration files > Download, чтобы сохранить тестовую конфигурацию.
   2. В веб-интерфейсе кластера на рабочем сервере нажмите Configuration files > Upload, чтобы загрузить сохраненную конфигурацию.

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

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

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

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

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

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

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

$ cartridge start [APP_NAME[.INSTANCE_NAME]] [options]

Возможные параметры приведены на странице справки cartridge start.

Некоторые часто используемые параметры:

--script FILE

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

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

--run-dir DIR

Каталог с файлами pid и sock. По умолчанию: TARANTOOL_RUN_DIR или /var/run/tarantool.

--cfg FILE

Файл конфигурации в формате YAML для экземпляра Cartridge. По умолчанию: TARANTOOL_CFG или ./instances.yml. Файл instances.yml содержит параметры cartridge.cfg(), которые описаны в разделе о конфигурации.

Например:

$ cartridge start my_app --cfg demo.yml --run-dir ./tmp/run

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

Если APP_NAME не указано, cartridge выделит его из имени файла ./*.rockspec.

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

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

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

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

$ cartridge stop [APP_NAME[.INSTANCE_NAME]] [options]

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

• --run-dir DIR
• --cfg FILE

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

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

  $ systemctl start APP_NAME
  

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

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

  $ systemctl start APP_NAME@INSTANCE_1
  $ systemctl start APP_NAME@INSTANCE_2
  ...
  $ systemctl start APP_NAME@INSTANCE_N
  

  где APP_NAME@INSTANCE_N – это имя экземпляра сервиса systemd с инкрементным числом N (уникальным для каждого экземпляра), которое следует добавить к порту 3300 для настройки прослушивания (например, 3301, 3302 и т.д.).

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

  $ systemctl stop APP_NAME@INSTANCE_1 APP_NAME@INSTANCE_2 ... APP_NAME@INSTANCE_<N>
  

При запуске экземпляров с помощью systemctl следует помнить о следующих правилах:

• Можно задать конфигурацию экземпляра в YAML-файле.

  В этом файле могут быть эти параметры; см. пример здесь).

  Сохраните этот файл в /etc/tarantool/conf.d/ (путь по умолчанию для systemd) или в место, указанное в переменной окружения TARANTOOL_CFG (если вы отредактировали файл systemd в своем приложении). Имя файла не имеет значения — может быть instances.yml или любое другое, которое вам нравится.

  Вот что systemd делает дальше:

  • получает app_name (и instance_name, если оно указано) из имени файла systemd (например, APP_NAME@default или APP_NAME@INSTANCE_1);
  • задает значения по умолчанию для сокета консоли (например, /var/run/tarantool/APP_NAME@INSTANCE_1.control), PID-файла (например, /var/run/tarantool/APP_NAME@INSTANCE_1.pid) и параметра workdir (например, /var/lib/tarantool/<APP_NAME>.<INSTANCE_NAME>). Environment=TARANTOOL_WORKDIR=${workdir}.%i

  Наконец, cartridge ищет раздел с соответстующим названием (например, app_name, который содержит общую конфигурацию для всех экземпляров, и app_name.instance_1, который содержит конфигурацию для конкретного экземпляра) по всем YAML-файлам в /etc/tarantool/conf.d. В результате параметры Cartridge workdir, console_sock и pid_file в YAML-файле cartridge.cfg будут бесполезны, потому что systemd переопределит их.

• Для запросов по журналам по умолчанию используется journalctl. Например:

  $ # показать журнал сообщений для юнит-файла systemd с именем APP_NAME.INSTANCE_1
  $ journalctl -u APP_NAME.INSTANCE_1
  
  $ # показать только самые последние сообщения и затем продолжать выводить новые
  $ journalctl -f -u APP_NAME.INSTANCE_1
  

  Если действительно нужно, можно изменить связанные с журналированием параметры box.cfg в конфигурационном YAML-файле: см. log и другие необходимые параметры.

Объекты ошибок в Lua

Классы ошибок помогают обнаружить источник проблемы. Для этого объект ошибки содержит имя своего класса, трассировку стека и сообщение.

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" -- недостижимо из-за ошибки
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

Для равномерной обработки ошибок в errors есть API :pcall:

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

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

Для errors.pcall нет никакой разницы между return nil, err и error().

Обратите внимание, что API errors.pcall отличается от ванильного pcall в Lua. Вместо true первый возвращает значения, полученные в результате вызова. Если произошла ошибка, то вместо false вернется nil и сообщение об ошибке.

Удаленные вызовы net.box не сохраняют трассировку стека от удаленного устройства. В этом случае на помощь придет errors.netbox_eval. Он найдет трассировку стека с локального и удаленного хостов и восстановит метатаблицы.

> 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'

Тем не мене, реализованный в Tarantool vshard не использует модуль errors. Вместо этого он использует собственные ошибки. Имейте это в виду при работе с функциями vshard.

Данные, включенные в объект ошибки (имя класса, сообщение, обратная трассировка), можно легко преобразовать в строку с помощью функции tostring().

GraphQL

В реализации GraphQL в Cartridge оборачивается модуль errors, поэтому обычно ответ на ошибку выглядит следующим образом:

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

Подробнее об ошибках читайте в спецификации GraphQL.

Если вы собираетесь реализовать обработчик GraphQL, то можете добавить свое расширение таким образом:

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

Ответ будет таким:

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

HTTP

Если кратко, то объект errors представляет собой таблицу, то есть его можно быстро представить в JSON. В Cartridge это используется для обработки ошибок через 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:..."
}

Unconfigured

Если рабочая директория пуста и для экземпляра не обнаружено ни снимков данных, ни конфигурации на уровне кластера, экземпляр переходит в состояние Unconfigured.

Экземпляр начинает принимать запросы iproto (бинарный протокол Tarantool) и остается в этом состоянии до тех пор, пока пользователь не решит присоединить его к кластеру — создать набор реплик или присоединиться к существующему.

После этого экземпляр переходит в состояние BootstrappingBox.

ConfigFound

Если экземпляр обнаружил все конфигурационные файлы и снимки данных, он переходит в состояние ConfigFound. Экземпляр пока не загружает файлы и снимки, поскольку вначале необходимо загрузить и проверить конфигурацию. В случае успеха экземпляр переходит в состояние ConfigLoaded, в противном случае состояние изменится на InitError.

ConfigLoaded

Файл конфигурации был найден, загружен и проверен. Следующий шаг — конфигурация экземпляра. Если были обнаружены прошлые снимки данных, состояние экземпляра изменится на RecoveringSnapshot. В противном случае экземпляр перейдет в состояние BootstrappingBox. По умолчанию все экземпляры запускаются в режиме только для чтения и не принимают запросы до завершения загрузки или восстановления.

InitError

Ошибка инициализации экземпляра может быть вызвана следующими событиями:

• Возникла ошибка во время соединения cartridge.remote-control с бинарным портом;
• В рабочей директории (tmp/) отсутствует config.yml, хотя снимки данных есть;
• Ошибка при загрузке конфигурации с диска;
• Некорректная конфигурация: в конфигурации кластера отсутствует сервер.

BootstrappingBox

Если снимки данных или файлы конфигурации отсутствуют, выполняется настройка аргументов для box.cfg, затем выполняется сам box.cfg. Также на этом этапе происходит настройка пользователей и остановка remote-control. Экземпляр попытается начать прослушивать полнофункциональный протокол iproto. В случае неудачной попытки экземпляр изменит свое состояние на BootError. Если всё в порядке, экземпляр примет состояние ConnectingFullmesh. Если в конфигурации на уровне кластера нет набора реплик, экземпляр также перейдет в состояние BootError.

RecoveringSnapshot

Если имеются снимки данных, box.cfg начнет процесс восстановления. После этого ход действий аналогичен BootstrappingBox.

BootError

Это состояние может быть вызвано следующими событиями:

• Не удалось выполнить привязку к двоичному порту для использования iproto;
• В конфигурации на уровне кластера отсутствует сервер;
• В конфигурации на уровне кластера отсутствует набор реплик;
• Не удалось настроить репликацию.

ConnectingFullmesh

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

BoxConfigured

Это состояние следует сразу за успешной конфигурацией наборов реплик и топологии кластера. Следующим шагом будет конфигурация ролей.

ConfiguringRoles

Состояние конфигурации ролей. Экземпляр попадает в это состояние при начальной настройке, при запуске восстановления после сбоя (failover.lua) или при изменении конфигурации на уровне кластера (twophase.lua).

RolesConfigured

Роли были успешно сконфигурированы.

OperationError

Ошибка при конфигурировании ролей.