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

Что нового в tt 3

tt 3 – это переработанный tt 2.x. Главное в нём:

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

tt 3 работает только с Tarantool 3. Если вы переходите с tt 2.x, прочитайте раздел Переход с tt 2.x.

Без конфигурационного файла

В tt 3 нет файла tt.yaml. Объект, с которым работает команда, определяется каталогом, из которого её запустили:

  • Внутри проекта tt находит его корень, поднимаясь от текущего каталога вверх. Поэтому команды работают из любого подкаталога проекта.
  • Вне проекта область установки (scope) задаётся флагом:
  • --scope user – приложения и бинарные файлы текущего пользователя;
  • --scope system – приложения и бинарные файлы всей системы.

У каждой области установки свой корневой каталог, но структура каталогов внутри одинаковая.

Приложение – это пакет

Пакет описывается двумя файлами в корне проекта:

  • app.manifest.toml – манифест. В нём указаны имя пакета, подходящие версии Tarantool и tt, зависимости (обычные и для разработки), компоненты, из которых собирается пакет, и продукты, в которые он упаковывается.
  • app.manifest.lock – локфайл. В нём зафиксированы точные версии всех зависимостей, прямых и транзитивных. Благодаря этому сборка одного и того же коммита везде устанавливает одинаковые версии.

Пример работы с пакетом:

tt new
tt package add checks '>=3.0.0'
tt package build
tt test
  • tt new создаёт заготовку манифеста.
  • tt package add, remove, update, resolve и deps управляют зависимостями. Команды меняют манифест на месте и сохраняют комментарии в нём.
  • Локфайл обновляется только явной командой. С флагом --locked устаревший локфайл считается ошибкой – это удобно в CI.
  • tt package build устанавливает зависимости в .rocks/ и собирает компоненты:
  • модули на Lua;
  • нативные модули – с помощью c, lua-c, cargo, zig, cmake, make или shell. Нативный модуль можно написать на Rust или на Zig;
  • программы для внешних процессов – с помощью go, cargo, zig, cmake, make или shell. Один компонент может собирать и модуль, и программу.
  • Версия пакета берётся из файла VERSION или из ближайшего тега git. В коде её можно получить так: require('<name>.version').version.
  • tt run запускает Tarantool проекта в текущем каталоге. Аргументы начиная с имени скрипта передаются скрипту без изменений.
  • tt test собирает пакет и запускает его тесты с помощью luatest. Если luatest не указан в манифесте, tt установит его сам.

Подробнее – в разделах Пакеты и Первый пакет.

Самодостаточные архивы

tt package pack упаковывает приложение в архив <name>-<version>-<os>-<arch>.tt (формат tar.zst). Архив воспроизводимый: один и тот же коммит всегда даёт побайтно одинаковый архив.

По умолчанию в архив входит всё, что нужно приложению: зависимости, шаблоны экземпляров, а также Tarantool, tt и TCM нужных версий. Поэтому для tt package install доступ к сети не нужен.

$ tt package pack
.../kv-api/_build/pack/kv-api-1.1.0-linux-amd64.tt
$ tt package install --scope system _build/pack/kv-api-1.1.0-linux-amd64.tt

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

  • Архив устанавливается как новая версия приложения, и <root>/apps/<name> атомарно переключается на неё.
  • Каждое приложение работает на версии Tarantool из своего локфайла. Поэтому на одном хосте могут работать приложения на разных версиях Tarantool.
  • Флаг --upgrade устанавливает более новую версию. Запущенные экземпляры продолжают работать на старой версии до tt instance restart.
  • Данные и конфигурация хоста хранятся отдельно от версий приложения, поэтому сохраняются при обновлении и удалении.

При установке в проект архив становится гостевым пакетом: его rock-модули подключаются к проекту.

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

Выбор rock-серверов

tt берёт список rock-серверов из первого заданного источника в таком порядке:

  1. флаг --registry;
  2. переменная окружения TT_REGISTRIES;
  3. секция [platform].registries манифеста;
  4. встроенный список.

Какой список используется сейчас, показывает tt registry list.

  • Rock-сервер может быть адресом HTTP(S) или локальным каталогом.
  • tt package search ищет модули сразу на всех серверах.
  • tt package download скачивает rock-модули в каталог, который сам может служить rock-сервером. Так можно подготовить зеркало для сборки без доступа к сети.
  • tt rocks работает на go-luarocks – реализации LuaRocks на Go.

Подробнее – в разделе Rock-серверы.

Экземпляры: одно описание для трёх видов

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

  • instances.yaml – какие экземпляры работают на этом хосте;
  • config.yaml – конфигурация кластера Tarantool 3.

Эти файлы лежат в .templates/<name>/ проекта или установленной версии приложения. Копии для конкретного хоста кладутся в <root>/etc/<app>/.

Пример instances.yaml:

"*":                       # каждый экземпляр из топологии config.yaml
  restart: on-failure
legacy:
  script: init.lua         # приложение на box.cfg, как в tt 2.x
gateway:
  binary: ./bin/gateway    # сторонний процесс, не Tarantool
  args: [--port, "8080"]
  • tt одинаково запускает, останавливает, показывает статус и ведёт журналы для трёх видов экземпляров:
  • экземпляров Tarantool из конфигурации кластера;
  • приложений на box.cfg;
  • внешних процессов.
  • Каждый экземпляр работает под наблюдением tt (watchdog). Если экземпляр падает, tt перезапускает его согласно параметру restart.
  • tt instance start --foreground запускает все экземпляры на переднем плане и выводит их журналы в stdout. Этот режим предназначен для контейнеров.
  • Команды для работы с экземплярами собраны в tt instance. Цель задаётся как APP:INSTANCE, APP:* или списком.
  • tt instance status --details показывает, на какой версии Tarantool работает экземпляр и откуда она взята.
  • stop, restart, kill и clean запрашивают подтверждение только при запуске в терминале. В скриптах передавайте флаг --yes.
  • restart сначала проверяет, что все цели готовы к запуску, и только потом останавливает экземпляры.

Подробнее – в разделах Экземпляры и Кластер на ноутбуке.

Unit-файлы systemd из tt

Для приложения, установленного в область установки системы, tt создаёт unit-файлы systemd:

  • tt service systemd install <app> создаёт шаблонный unit-файл для приложения и drop-in-файл для каждого экземпляра;
  • tt service systemd generate выводит текст unit-файлов, не устанавливая их;
  • tt service systemd uninstall удаляет unit-файлы.

Команды tt instance знают, какие экземпляры запущены под systemd, и для них предлагают использовать systemctl.

Подробнее – в разделе Запуск экземпляров под systemd.

Бинарные файлы для проекта, пользователя и системы

tt binary install, switch, list и uninstall управляют версиями Tarantool Community Edition, Tarantool Enterprise Edition, tt, TCM и Enterprise SDK. Бинарные файлы можно установить в проект, для пользователя или для всей системы.

  • Tarantool Community Edition на Linux с glibc устанавливается готовым бинарным файлом: tt берёт его из релиза на GitHub и проверяет контрольные суммы. На остальных платформах Tarantool собирается из исходного кода.
  • --from-build подключает Tarantool, собранный вручную, без копирования файлов.
  • При первой установке в проект создаётся скрипт .env/activate.sh. Он добавляет бинарные файлы проекта в PATH.

Подробнее – в разделе Управление бинарными файлами.

Собственная сборка tt

tt состоит из ядра и набора модулей на Go. Команда tt binary build tt собирает собственный дистрибутив tt по файлу tt.manifest.toml:

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

Внешние модули tt загружает из каталогов в TT_CLI_MODULES_PATH. Если имя модуля совпадает с командой tt, модуль заменяет эту команду.

Подробнее – в разделах Сборка дистрибутива tt и Внешние модули.

Чтение журналов без Tarantool

Команды tt data cat и tt data play заменили tt cat и tt play. Они читают файлы .xlog, .snap и .vylog, а также файлы .run и .index движка vinyl. Чтение реализовано на Go, поэтому Tarantool на хосте не нужен.

  • Каталог с данными читается в том же порядке, в каком Tarantool восстанавливает данные: сначала самый свежий снимок, затем файлы .xlog по порядку vclock. Транзакции, которые уже вошли в снимок, пропускаются.
  • Изменения можно отфильтровать:
  • по vclock – флагами --from-vclock и --to-vclock;
  • по LSN одной реплики – флагами --from и --to.

Обе границы включаются в выборку. Транзакция никогда не разрывается. - tt data cat -o json выводит каждую запись отдельным объектом JSON на строке. Такой вывод удобно обрабатывать в скриптах. - tt data play применяет транзакции целиком, если целевая система это поддерживает. Цель задаётся как APP:INSTANCE или URI. Поддерживаются флаги --dry-run и --on-error.

Подробнее – в разделе tt data.

Удобство для скриптов

  • Все команды возвращают одинаковые коды завершения (подробнее – tt help errors):
  • 1 – ошибка, которую может исправить пользователь;
  • 2 – сбой в системе, где выполнялась команда;
  • 3 – команда выполнена частично.
  • --log-format json выводит каждую запись журнала отдельным объектом JSON. Учётные данные в URI в журнале маскируются.
  • Журнал и индикатор выполнения выводятся в stderr, поэтому в stdout попадает только результат команды.
  • tt instance status, tt registry list и команды tt package, которые выводят таблицы, поддерживают флаги -o json и -o yaml.

Установка одной командой

Чтобы установить последний релиз tt 3 на Linux или macOS с процессором Apple, выполните:

curl -fsSL https://raw.githubusercontent.com/tarantool/tt/v3/install.sh | sh

Подробнее – в разделе Установка.