Обновлена 27 ноября 2025 г. в 14:21

Руководство для начинающих

В этом руководстве приведена инструкция по ручному разворачиванию отказоустойчивой системы из двух кластеров Tarantool DB 2.х с использованием Tarantool Clusters Federation (TCF). Узнать больше об архитектуре и элементах TCF вы можете на странице Архитектура.

В руководстве кластеры развернуты вручную с помощью утилиты tt CLI. Пример запуска кластеров Tarantool DB с TCF через Docker Compose можно найти в документации Tarantool DB.

Руководство включает следующие шаги:

Во время прохождения руководства будут запущены:

хранилище конфигурации etcd – для хранения конфигурации кластеров и их состояния;
активный кластер Tarantool DB (Tarantool Cluster 1), состоящий из 1 роутера и 1 набора реплик из 3 хранилищ;
пассивный кластер Tarantool DB (Tarantool Cluster 2), состоящий из 1 роутера и 1 набора реплик из 3 хранилищ;
веб-интерфейс Tarantool Cluster Manager (TCM);
TCF Gateway – для отправки изменений с Tarantool Cluster 1 на Tarantool Cluster 2;
TCF Destination – для применения изменений, пришедших с Tarantool Cluster 1 на Tarantool Cluster 2.

Подготовка архивов для развертывания

TCF и Tarantool DB распространяются в виде TGZ-архивов. Скачайте следующие файлы в личном кабинете tarantool.io:

сборку TCF в разделе tcf/release. Архив имеет название вида tcf-<tcf_version>.tar.gz, где <tcf_version>– версия TCF не ниже 0.9.0;
сборку Tarantool DB в разделе tarantooldb/release/for_deploy/. Архив имеет название вида tarantooldb-<tdb_version>.<os>.<arch>.tar.gz, где <tdb_version>– версия Tarantool DB не ниже 2.0.0.

Если у вас нет доступа к личному кабинету, свяжитесь с нами через форму обратной связи или напишите на sales@tarantool.io.

Скопируйте архив tarantooldb-<tdb_version>.<os>.<arch>.tar.gz в домашнюю директорию и распакуйте его:
```
$ tar -xzf tarantooldb-2.2.1.linux.x86_64.tar.gz
```
Добавьте директорию tarantooldb в список директорий переменной PATH:
```
$ export PATH=~/tarantooldb:$PATH
```
Скопируйте архив tcf-<tcf_version>.tar.gz в домашнюю директорию и распакуйте его:
```
$ tar -xzf tcf-0.9.0.tar.gz
```

Установка и запуск etcd

Перед разворачиванием кластеров Tarantool DB и TCF установите etcd. Подробнее о настройке хранилища конфигурации и состояния можно узнать в соответствующем разделе.

Запустите etcd с флагами --listen-client-urls и --advertise-client-urls:


$ etcd --listen-client-urls http://127.0.0.1:2379 \       --advertise-client-urls http://127.0.0.1:2379

Настройка и запуск кластеров

Создание приложения

Перейдите в директорию tarantooldb и выполните в ней команду tt init. Команда создаст окружение tt, в том числе файл конфигурации tt.yaml, который используется утилитой tt CLI.
В директории instances.enabled созданного tt-окружения создайте директории cluster1 и cluster2.
В директории instances.enabled/cluster1 создайте файл source.yaml. Этот файл содержит конфигурацию Tarantool Cluster 1. Экземпляры в этой конфигурации принимают входящие запросы на порты 3301–3304:

Листинг примера

В файле конфигурации в секции credentials.users заданы следующие пользователи:
- dbadmin – администратор TCF;
- peer – пользователь для репликации внутри кластера;
- storage – пользователь используется при запросах роутера к экземплярам хранилища;
- tcm_tarantool – пользователь для подключения TCM к экземплярам Tarantool Cluster 1;
- tcf_replicator – пользователь используется для репликации между кластерами;
- tcf_dml – пользователь предназначен для выполнения DML-операций с данными от имени сервисных компонентов TCF.
В директории instances.enabled/cluster1 создайте файл instances.yaml – список экземпляров, которые будут запущены в текущем окружении:
```
router-001-a:storage-001-a:storage-001-b:storage-001-c:
```

В директории instances.enabled/cluster1 создайте файл config.yaml. Этот файл содержит конфигурацию централизованного хранилища etcd.


config:  etcd:    endpoints:      - http://127.0.0.1:2379    prefix: /cluster1    http:      request:        timeout: 3

В директории instances.enabled/cluster2 создайте файл source.yaml с конфигурацией кластера B. Экземпляры в этой конфигурации принимают входящие запросы на порты 13301-13304:

Листинг примера

В директории instances.enabled/cluster2 создайте файл instances.yaml:


router-001-b:storage-001-b:storage-002-b:storage-003-c:

В директории instances.enabled/cluster2 создайте файл config.yaml.


config:  etcd:    endpoints:      - http://127.0.0.1:2379    prefix: /cluster2    http:      request:        timeout: 3

В директории instances.enabled создайте директорию migrations/scenario. В этой директории создайте файл миграции 001_migration.lua:

local helpers = require('tt-migrations.helpers')
local function apply_scenario()
    local space = box.schema.space.create('writers')
    space:format({
        {name = 'id', type = 'number'},
        {name = 'bucket_id', type = 'number'},
        {name = 'name', type = 'string'},
        {name = 'age', type = 'number'},
    })
    space:create_index('primary', {parts = {'id'}})
    space:create_index('bucket_id', {parts = {'bucket_id'}})
    helpers.register_sharding_key('writers', {'id'})
end
return {
    apply = {
        scenario = apply_scenario,
    },
}

В миграции создается шардированный спейс writers с ключом шардирования id и первичным индексом primary.

Настройка и запуск Tarantool Cluster Manager

В качестве веб-интерфейса кластеров Tarantool DB используется Tarantool Cluster Manager, или TCM. Tarantool Cluster Manager – это инструмент для настройки и отслеживания кластеров Tarantool EE и управления ими. Подробная информация о TCM приведена в документации Tarantool.

Задать настройки для запуска TCM можно в файле конфигурации. Для этого создайте файл tcm.yaml в директории instances.enabled/cluster1:

Листинг примера

Здесь:

http – имя и порт хоста, на котором запущен TCM. По умолчанию, TCM запускается на порту 8080;
storage – настройки хранилища конфигурации и узлов etcd, linkto(/ru/getting_started#configure-etcd)[text=настроенных и запущенных ранее]};
security – настройки безопасности TCM;
initial-settings – кластеры, которые создаются автоматически при первом запуске TCM. В конфигурации TCM автоматически созданы кластеры Tarantool Cluster 1 и Tarantool Cluster 2. Кластеры используют общий etcd, но имеют различные префиксы – /cluster1 и /cluster2.

Полная информация об опциях конфигурации TCM приведена в документации TCM.

Чтобы запустить TCM с конфигурацией из файла:

Откройте новую вкладку терминала.
Перейдите в директорию instances.enabled/cluster1.
Запустите TCM:
```
$ tcm -c tcm.yaml
```

Узнать больше: Начало работы с TCM.

Запуск активного кластера

Запустите активный кластер (Tarantool Cluster 1). Для этого:

Перейдите в директорию tarantooldb:
```
$ cd tarantooldb
```
Загрузите конфигурацию кластера в централизованное хранилище из YAML-файла, используя команду tt cluster publish:
```
$ tt cluster publish http://127.0.0.1:2379/cluster1 ./instances.enabled/cluster1/source.yaml
```
Здесь:
- http://127.0.0.1:2379/cluster1 – адрес etcd;
- ./instances.enabled/cluster1/source.yaml – публикуемый файл конфигурации.
Запустите кластер:
```
$ tt start cluster1
```

Проверьте статус кластера:


$ tt status cluster1

Результат будет выглядеть следующим образом:


INSTANCE                STATUS   PID     MODE  CONFIG  BOX      UPSTREAM cluster1:router-001-a   RUNNING  502612  RW    ready   running    --        cluster1:storage-001-a  RUNNING  502613  RW    ready   running    --        cluster1:storage-001-b  RUNNING  502614  RO    ready   running    --        cluster1:storage-001-c  RUNNING  502611  RO    ready   running    --

Запустите модуль шардирования vshard:


$ tt replicaset vshard bootstrap cluster1

Результат будет выглядеть следующим образом:


• Discovery application...  Orchestrator:      centralized config Replicasets state: bootstrapped  • router-001 Failover: off Master:   single • router-001-a localhost:3301 rw • storage-001 Failover: manual Master:   single • storage-001-a localhost:3302 rw • storage-001-b localhost:3303 read • storage-001-c localhost:3304 read  • Bootstrapping vshard      • Done.

Загрузите миграции в кластер:


$ tt migrations publish http://127.0.0.1:2379/cluster1 ./instances.enabled/cluster1/migrations

Примените загруженные миграции:


$ tt migrations apply http://127.0.0.1:2379/cluster1 --tarantool-username=dbadmin --tarantool-password=secret

Результат будет выглядеть следующим образом:


• router-001:               •     001_migration.lua: successfully applied • storage-001:              •     001_migration.lua: successfully applied

Запуск пассивного кластера

Запустите пассивный кластер (Tarantool Cluster 2). Для этого:

Перейдите в директорию tarantooldb:
```
$ cd tarantooldb
```
Загрузите конфигурацию кластера в централизованное хранилище из YAML-файла, используя команду tt cluster publish:
```
$ tt cluster publish http://127.0.0.1:2379/cluster2 ./instances.enabled/cluster2/source.yaml
```
Здесь:
- http://127.0.0.1:2379/cluster2 – адрес etcd;
- ./instances.enabled/cluster2/source.yaml – публикуемый файл конфигурации.
Запустите кластер:
```
$ tt start cluster2
```

Проверьте статус кластера:


$ tt status cluster2

Результат будет выглядеть следующим образом:


INSTANCE                STATUS   PID     MODE  CONFIG  BOX      UPSTREAMcluster2:router-001-b   RUNNING  502898  RW    ready   running    --       cluster2:storage-001-b  RUNNING  502899  RW    ready   running    --       cluster2:storage-002-b  RUNNING  502896  RO    ready   running    --       cluster2:storage-003-c  RUNNING  502897  RO    ready   running    --

Запустите модуль шардирования vshard:


$ tt replicaset vshard bootstrap cluster2

Результат будет выглядеть следующим образом:


• Discovery application...  Orchestrator:      centralized config Replicasets state: bootstrapped  • router-001 Failover: off Master:   single • router-001-b 127.0.0.1:13301 rw • storage-001 Failover: manual Master:   single • storage-001-b 127.0.0.1:13302 rw • storage-002-b 127.0.0.1:13303 read • storage-003-c 127.0.0.1:13304 read  • Bootstrapping vshard      • Done.

Загрузите миграции в кластер:


$ tt migrations publish http://127.0.0.1:2379/cluster2 ./instances.enabled/cluster2/migrations

Примените загруженные миграции:


$ tt migrations apply http://127.0.0.1:2379/cluster2 --tarantool-username=dbadmin --tarantool-password=secret

Результат будет выглядеть следующим образом:


• router-001:              • 001_migration.lua: successfully applied• storage-001:             • 001_migration.lua: successfully applied

Проверка работы кластеров

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

Для входа в TCM откройте в браузере адрес http://localhost:8080. Логин и пароль для входа:
- Username: admin;
- Password: secret.
В TCM выберите нужный кластер (Tarantool Cluster 1 или Tarantool Cluster 2) над вкладкой Stateboard в выпадающем списке Clusters. Всё настроено правильно, если на вкладке Stateboard все узлы в кластере подсвечены зеленым цветом.
Чтобы проверить примененную миграцию, перейдите на вкладку Tuples. При успешной миграции в списке появится спейс writers.
Чтобы проверить текущее состояние кластеров, перейдите на вкладку TCF.

Также проверьте с помощью команды tt connect, что пассивный кластер заблокирован для пользователя tcf_dml:


$ tt connect 127.0.0.1:13301 -u tcf_dml -p dml_password• Connecting to the instance...⨯ failed to run interactive console: failed to create new console: failed to connect: failed to authenticate: DML is blocked, cluster is passive (ClientError, code 0x1ff)

Конфигурирование и запуск репликаторов данных

Настройка репликаторов

Чтобы сконфигурировать репликаторы данных (компоненты Gateway и Destination) для репликации с кластера Tarantool Cluster 1 на кластер Tarantool Cluster 2, в директории с распакованным архивом TCF создайте файл config_a_b.yaml и вставьте следующую конфигурацию:

Листинг примера

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

Запуск репликатора Tarantool Cluster 1 -> Tarantool Cluster 2

Запустите TCF Gateway для отправки изменений с Tarantool Cluster 1 на Tarantool Cluster 2:


$ ./tcf-gateway --config config_a_b.yaml

Запустите TCF Destination для применения изменений, пришедших с Tarantool Cluster 1 на Tarantool Cluster 2:


$ ./tcf-destination --config config_a_b.yaml

Когда компонент TCF Destination будет готов к работе, вывод результатов работы команды может выглядеть так:


2025-02-27T17:43:38+03:00 INFO src/pkg/ttpusher/pusher.go:427 "CDC State successfully fetched" Pusher=General/Subscribe

Проверить статус TCF Gateway необходимо после запуска компонента Destination. Когда компонент Gateway готов к работе, вывод результатов работы команды может выглядеть так:


2025-02-27T17:42:53+03:00 INFO src/internal/gateway/server.go:512 Connected "Replica set"=e0f5488a-00c5-4c53-9b3a-ec052610357b Host=localhost:13303 From="&{VClock:[0 3117] OwnerID:0 ConfirmedVClock:[]}"

Проверка репликации Tarantool Cluster 1 -> Tarantool Cluster 2

Чтобы проверить успешную репликацию данных с Tarantool Cluster 1 на Tarantool Cluster 2:

Перейдите в веб-интерфейс ТСМ.
В TCM над вкладкой Stateboard выберите кластер Tarantool Cluster 1 в выпадающем списке Clusters.
Подключитесь к узлу-роутеру. Для этого нажмите на router-001, выберите экземпляр router-001-b и в открывшемся окне перейдите на вкладку Terminal (TT Connect).

Добавьте в созданный ранее спейс writers новый кортеж:

crud.insert_object('writers', {
    id = 1,
    name = 'Haruki Murakami',
    age = 75
}, {
    noreturn = true
})

Проверьте, что в спейсе появились данные. Для этого перейдите на вкладку Tuples и выберите в списке спейс writers. В открывшейся вкладке видно, что в спейс добавлен новый кортеж Haruki Murakami.
Переключитесь на Tarantool Cluster 2 и перейдите на вкладку Tuples.
Выберите в списке спейс writers и проверьте, что в открывшейся вкладке также появился кортеж Haruki Murakami.

Не нашли ответа?Напишите нам