Перейти к содержанию

Экземпляры

Команды управления экземплярами - tt instance start, stop, restart, kill, status, logs, logrotate, check, clean и connect - работают с экземплярами приложения на этом хосте. tt connect - это tt instance connect, а tt data play принимает те же цели.

Пара файлов

Приложение запускается по паре файлов:

  • instances.yaml, описание: что именно работает на этом хосте;
  • config.yaml, конфигурация кластера, с которой запускается Tarantool 3 (tarantool -c).

Пара берётся целиком из одного каталога:

  • шаблон приложения, .templates/<name>/: default, если в --template не указан другой. Проект всегда работает по шаблону, как и установленное приложение, у которого нет пары хоста.
  • пара хоста, <root>/etc/<app>/, для приложения, установленного в область установки пользователя или системы. Если она есть, она имеет преимущество над шаблонами и лежит отдельно от установленной версии, поэтому сохраняется при обновлении. При наличии пары хоста флаг --template отвергается.

Повреждённая пара считается ошибкой и никогда не служит поводом откатиться на другую.

Описание

instances.yaml сопоставляет имена экземпляров с записями:

storage-001:
storage-002:
  restart: on-failure
gateway:
  binary: ./bin/gateway
legacy:
  script: init.lua

Запись бывает трёх видов:

  • Экземпляр Tarantool, настроенный конфигурацией кластера: запись без binary и script, например storage-001. Она должна входить в топологию config.yaml; в топологии могут быть и другие экземпляры, работающие на других хостах.
  • Экземпляр Tarantool со своим собственным скриптом: запись со script, настраиваемая через box.cfg в скрипте, как работали приложения tt 2.x. См. Run a box.cfg application.
  • Внешний процесс: запись с binary - программа не на Tarantool, которая запускается, останавливается и показывается рядом с экземплярами Tarantool. См. Run an external process.

Запись "*", в кавычках, обозначает каждый экземпляр топологии config.yaml, не названный другими записями; каждый такой экземпляр - это экземпляр Tarantool с полями из "*". Собственная запись заменяет "*" для своего экземпляра целиком. Экземпляры, которые задаёт "*", запускаются по порядку своих имён.

Шаблон, состоящий только из config.yaml, запускает всю свою топологию точно так же, как запись "*": {}. Паре хоста описание необходимо: оно указывает, что именно работает на этом хосте, тогда как остальная часть кластера может работать на других.

Описанию, состоящему только из экземпляров со скриптами и внешних процессов, config.yaml не нужен. Файл config.yaml, содержащий лишь config.etcd или config.storage, подтягивает остальную конфигурацию кластера из этого хранилища.

Все поля описаны в справочнике.

Цели

Команды управления экземплярами принимают цели:

  • <app>:<instance>, <app>:* или их список через запятую;
  • без цели: все экземпляры текущего проекта.

<app> - это текущий проект, если он назван так же, а иначе - приложение, установленное в область установки системы. Флаг --scope project|user|system выбирает область установки напрямую, и в область установки пользователя попадают только так. Имя <app> без указания экземпляра отвергается: забытое имя экземпляра не должно останавливать все экземпляры сразу.

$ tt instance start                               # все экземпляры проекта
$ tt instance start myapp:storage-001 --scope user
$ tt instance stop myapp:* --yes
$ tt instance logs myapp:storage-001 --follow

Запуск

tt instance start запускает каждый экземпляр в фоне под процессом-наблюдателем (watchdog) tt. Watchdog перезапускает экземпляр после его самостоятельного выхода, если это предписано полем restart: no (по умолчанию), on-failure или always.

С флагом --foreground tt вместо этого остаётся на переднем плане: для systemd, контейнера или терминала. Каждый экземпляр по-прежнему работает под собственным процессом-наблюдателем, который его не перезапускает, поэтому команды tt instance stop, kill, logrotate и status работают с ним из другого терминала. Вывод экземпляров поступает в их журналы и в стандартный вывод tt с префиксом имени экземпляра, когда их несколько. Сигналы SIGINT, SIGTERM и SIGQUIT, отправленные tt, останавливают каждый экземпляр. tt завершает работу, когда завершились все они: с кодом 0, если они успели вовремя остановиться; с кодом 137, если какой-то экземпляр не уложился в свой stop_timeout и был принудительно завершён; в остальных случаях - с кодом первого экземпляра, завершившегося с отличным кодом.

Остановка посылает экземпляру его сигнал stop_signal, по умолчанию SIGTERM, и принудительно завершает его по истечении stop_timeout, по умолчанию 30 секунд.

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

Где находятся файлы

Экземпляр приложения <app> хранит свои файлы под корнем области установки этого приложения:

Каталог Содержимое
<root>/var/lib/<app>/<instance>/ данные: *.snap, *.xlog, vinyl; рабочий каталог внешнего процесса
<root>/var/log/<app>/<instance>/ tt.log: вывод экземпляра и его процесса-наблюдателя
<root>/var/run/<app>/<instance>/ tt.pid процесса-наблюдателя, tarantool.pid, сокет консоли tarantool.control; process.pid внешнего процесса

В проекте <root> - это .tarantool/. Экземпляр Tarantool работает в каталоге приложения: в проекте либо в установленной версии. tt передаёт ему эти пути через переменные окружения TT_*_DEFAULT, поэтому конфигурация кластера может указывать другие пути.

tt instance clean удаляет данные и журнал неработающих экземпляров.

Подтверждения и коды возврата

stop, restart, kill и clean запрашивают подтверждение, которое флаг --yes (-y) пропускает. Подтверждение запрашивается только в терминале: в скрипте или конвейере команда, требующая подтверждения, завершается с кодом 1, если ей не передан флаг --yes.

Если команда действует на несколько экземпляров, она продолжает работу, когда один из них сбоит. Она завершается с кодом 3, если сбой произошёл лишь для части экземпляров; с кодом 1, если сбой произошёл для всех экземпляров; и с кодом самой ошибки, если экземпляр был только один. См. Exit codes.

Под systemd

tt service systemd создаёт unit-файлы systemd, которые запускают экземпляры приложения области установки системы; после этого команды управления экземплярами отказываются запускать или останавливать эти экземпляры в обход unit-файлов. См. Run instances under systemd.