Что нового в 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-серверов из первого заданного источника в таком порядке:
- флаг
--registry; - переменная окружения
TT_REGISTRIES; - секция
[platform].registriesманифеста; - встроенный список.
Какой список используется сейчас, показывает 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
Подробнее – в разделе Установка.