Установка TCF вручную поверх кластеров Tarantool DB

Сценарий установки доступен начиная с версии Tarantool DB 2.2.0. Поддерживаемые операционные системы описаны в разделе Требования к инфраструктуре для TCF.

В этом руководстве приведена инструкция по ручной установке отказоустойчивой системы из двух кластеров Tarantool DB 2.х с использованием Tarantool Clusters Federation (TCF). В руководстве кластеры развернуты вручную с помощью консольной утилиты tt CLI. В качестве хранилища конфигурации и состояния кластеров используется хранилище на основе Tarantool (Tarantool-based configuration storage). Подробная информация по настройке среды TCF + TDB приведена в соответствующем разделе.

В инструкции для примера созданы два кластера – Tarantool Cluster 1 и Tarantool Cluster 2.

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

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

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

1. На каждом из кластеров создан спейс writers со следующим форматом:

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

   Эти спейсы созданы в Tarantool DB при первоначальной миграции так называется изменение схемы базы данных и данных в ней, возникающее во время разработки. Чтобы межкластерная репликация работала корректно, спейсы, созданные в этих кластерах, должны быть идентичными.

2. Добавлены данные в спейс на одном кластере.

3. Проверено, что данные появились в спейсе на другом кластере.

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

• Подготовка архивов для установки
• Настройка хранилища состояния кластеров
• Настройка и запуск кластеров
• Настройка и запуск репликации данных с активного кластера на пассивный
• Проверка репликации с Tarantool Cluster 1 на Tarantool Cluster 2

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

• сборку TCF в разделе tcf/release. Архив имеет название вида tcf-<tcf_version>.tar.gz, где <tcf_version> – версия TCF не ниже 0.5.0;

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

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

Для распаковки TGZ-архивов выполните следующие шаги:

1. Загрузите на сервер дистрибутив Tarantool DB.

2. Распакуйте архив с Tarantool DB. По умолчанию распаковка выполняется в директорию tarantooldb:

    
   $ tar -xzf tarantooldb-2.2.0.linux.x86_64.tar.gz

3. Добавьте директорию tarantooldb в список директорий переменной PATH:

    
   $ export PATH=~/tarantooldb:$PATH

4. Загрузите на сервер дистрибутив TCF.

5. Распакуйте архив с TCF. По умолчанию распаковка выполняется в текущую директорию:

    
   $ tar -xzf tcf-0.9.0.tar.gz

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

1. Перейдите в интерфейс командной строки, создайте директорию config-env для хранилища конфигурации TCF и создайте в ней новое окружение для консольной утилиты tt. Директория config-env должна быть создана в домашней директории на одном уровне с директорией tarantoodb.

    
   $ mkdir config-env$ cd config-env/$ tt init

2. Перейдите в директорию окружения instances.enabled, созданную автоматически при выполнении команды tt init. Создайте внутри директорию configstorage, а затем перейдите в нее.

    
   $ cd instances.enabled/$ mkdir configstorage$ cd configstorage/

3. В директории configstorage подготовьте файл source.yaml с конфигурацией хранилища конфигурации на основе Tarantool. Пример конфигурации для набора реплик с 3 экземплярами хранилища, экземпляры в этой конфигурации принимают входящие запросы на порты 3301–3303:

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

   В файле конфигурации в секции credentials.users заданы следующие пользователи:

   • replicator – пользователь для соединения узлов хранилища конфигурации друг с другом;
   • dbadmin – администратор БД;
   • tcm_config_storage – пользователь для подключения TCM к узлам хранилища конфигурации;
   • tarantool_config_storage – пользователь для подключения экземпляров кластера к узлам хранилища конфигурации.

4. В директории configstorage подготовьте файл instances.yaml, содержащий список узлов (экземпляров хранилища). Для примера конфигурации выше список будет таким:

    
   instance001:instance002:instance003:

5. Запустите настроенное хранилище состояний:

    
   $ tt start configstorage

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

    
   • Starting an instance [configstorage:instance001]...• Starting an instance [configstorage:instance002]...• Starting an instance [configstorage:instance003]...

6. Проверьте состояние запущенных узлов:

    
   $ tt status configstorageINSTANCE                   STATUS   PID    MODE  CONFIG   BOX     UPSTREAM configstorage:instance001  RUNNING  26302  RW    ready   running   --       configstorage:instance002  RUNNING  26303  RO    ready   running   --       configstorage:instance003  RUNNING  26304  RO    ready   running   --

   Указанные параметры для каждого узла должны иметь такие значения:

   • параметр STATUS – RUNNING;
   • параметр CONFIG – ready;
   • параметры BOX – running.

   tt status позволяет определить, какой из запущенных экземпляров является master-узлом. В примере экземпляр instance001 работает в режиме RW – чтения и записи (см. параметр узлов MODE). Это означает, что instance001 является master-узлом.

Повторите следующие шаги:

1. Перейдите в директорию tarantooldb и выполните в ней команду tt init. Команда создаст окружение tt, в том числе файл конфигурации tt.yaml, который используется консольной утилитой tt CLI.

2. В директории instances.enabled созданного tt-окружения создайте директории кластеров и назовите их следующим образом:

• cluster_a;
• cluster_b.

3. В директории instances.enabled/cluster_a создайте файл source.yaml. Этот файл содержит конфигурацию кластера Tarantool Cluster 1. Экземпляры в этой конфигурации принимают входящие запросы на порты 3304–3307:

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

   В файле конфигурации в секции credentials.users заданы следующие пользователи:

   • dbadmin – администратор БД;

   • replicator – используется для соединения узлов кластера друг с другом;

   • tcm_tarantool – пользователь для подключения TCM к узлам кластера;

   • storage – пользователь используется при запросах роутера к экземплярам хранилища;

   • tcf_replicator – пользователь используется для репликации между кластерами;

   • tcf_dml – пользователь предназначен для выполнения DML-операций с данными от имени сервисных компонентов TCF.

4. В директории instances.enabled/cluster_a создайте файл instances.yaml – список экземпляров, которые будут запущены в текущем окружении:

    
   router-a-001:storage-a-001:storage-a-002:storage-a-003:

5. В директории instances.enabled/cluster_b создайте файл source.yaml с конфигурацией кластера Tarantool Cluster 2. Экземпляры в этой конфигурации принимают входящие запросы на порты 3324–3327:

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

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

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

7. В каждой из директорий instances.enabled/cluster_a и instances.enabled/cluster_b соответственно создайте директорию 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.

8. Перейдите в домашнюю директорию, где хранится директория tarantooldb. Скопируйте директорию с модулями .rocks в директории instances.enabled/cluster_a и instances.enabled/cluster_b:

    
   $ sudo cp -r tarantooldb/.rocks tarantooldb/instances.enabled/cluster_a$ sudo cp -r tarantooldb/.rocks tarantooldb/instances.enabled/cluster_b

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

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

Здесь:

• http – имя и порт хоста, на котором запущен TCM. По умолчанию, TCM запускается на порту 8080;
• storage – настройки хранилища конфигурации и его узлов, настроенных и запущенных ранее;
• security – настройки безопасности TCM;
• initial-settings – кластеры, которые создаются автоматически при первом запуске TCM. В конфигурации TCM автоматически создан кластер Tarantool Cluster 1. Второй кластер (Tarantool Cluster 2) будет создан позже вручную через веб-интерфейс TCM. Кластеры используют общее хранилище конфигурации, но имеют различные префиксы – /default1 и /default2.

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

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

1. Откройте новую вкладку терминала.

2. Перейдите в директорию instances.enabled/cluster_a.

3. Выполните команду:

    
   $ tcm -c tcm.yaml

См. так же Начало работы с TCM.

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

1. Перейдите в директорию tarantooldb:

    
   $ cd tarantooldb

2. Загрузите конфигурацию кластера в централизованное хранилище из YAML-файла, используя команду tt cluster publish:

    
   $ tt cluster publish http://dbadmin:secret@127.0.0.1:3301/default1 ./instances.enabled/cluster_a/source.yaml

   Здесь:

   • http://dbadmin:secret@127.0.0.1:3301/default1 – адрес master-узла хранилища конфигурации, переданный вместе с именем и паролем администратора БД. Определить master-узел можно с помощью команды tt status configstorage – в примере это узел instance001, имеющий адрес 127.0.0.1:3301;
   • ./instances.enabled/cluster_a/source.yaml – публикуемый файл конфигурации.

3. Запустите кластер:

    
   $ tt start cluster_a

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

    
   $ tt status cluster_a

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

    
   $ tt bootstrap vshard cluster_a

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

    
   $ tt migrations publish http://dbadmin:secret@127.0.0.1:3301/default1 ./instances.enabled/cluster_a/migrations

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

    
   $ tt migrations apply http://dbadmin:secret@127.0.0.1:3301/default1 --tarantool-username=admin --tarantool-password=secret

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

1. Перейдите в директорию tarantooldb:

    
   $ cd tarantooldb

2. Загрузите конфигурацию кластера в централизованное хранилище из YAML-файла, используя команду tt cluster publish:

    
   $ tt cluster publish http://dbadmin:secret@127.0.0.1:3301/default2 ./instances.enabled/cluster_b/source.yaml

   Здесь:

   • http://dbadmin:secret@http://127.0.0.1:3301/default2 – адрес master-узла хранилища конфигурации, переданный вместе с именем и паролем администратора БД. Определить master-узел можно с помощью команды tt status configstorage – в примере это узел instance001, имеющий адрес 127.0.0.1:3301;
   • ./instances.enabled/cluster_b/source.yaml – публикуемый файл конфигурации.

3. Запустите кластер:

    
   $ tt start cluster_b

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

    
   $ tt status cluster_b

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

    
   $ tt bootstrap vshard cluster_b

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

    
   $ tt migrations publish http://dbadmin:secret@127.0.0.1:3301/default2 ./instances.enabled/cluster_b/migrations

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

    
   $ tt migrations apply http://dbadmin:secret@127.0.0.1:3301/default2 --tarantool-username=admin --tarantool-password=secret

Перед запуском пассивного кластера необходимо создать этот кластер в TCM и настроить его конфигурацию. Для этого:

1. Для входа в TCM откройте в браузере адрес http://localhost:8080. Логин и пароль для входа:

   • Username: admin;
   • Password: secret.

2. В TCM перейдите на вкладку Clusters и нажмите кнопку Add.

3. На первом экране настройки (General) введите имя нового кластера в поле Name. Имя кластера может быть любое, в примере используется имя Tarantool Cluster 2.

4. Перейдите во вкладку Config storage connection, нажав кнопку Next.

5. Во вкладке Config storage connection укажите следующие значения:

• в поле Provider – tarantool;

• в поле Prefix – /default2;

• в поле Endpoints укажите узлы хранилища конфигурации:

   
  127.0.0.1:3301127.0.0.1:3302127.0.0.1:3303

• в поле Username – tcm_config_storage;

• в поле Password – tcm_config_storage_password.

6. Переключитесь на третий экран настройки (Tarantool connection), нажав кнопку Next.

7. На третьем экране настройки (Tarantool connection) укажите следующие значения:

• в поле Username – tcm_tarantool;
• в поле Password – tcm_tarantool_password.

8. Нажмите кнопку Add, чтобы сохранить новые настройки кластера.

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

1. В TCM выберите нужный кластер (Tarantool Cluster 1 или Tarantool Cluster 2) над вкладкой Stateboard в выпадающем списке Clusters. Всё настроено правильно, если на вкладке Stateboard все узлы в кластере подсвечены зеленым цветом.

2. Чтобы проверить примененную миграцию, перейдите на вкладку Tuples. При успешной миграции в списке появится спейс writers.

3. Чтобы проверить текущее состояние кластеров, перейдите на вкладку TCF. Видно, что Tarantool Cluster 1 перешел в активное состояние, а Tarantool Cluster 2 – в пассивное.

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

    
   $ tt connect 127.0.0.1:3327 -u tcf_dml -p secret• 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)

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

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

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

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

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

3. Запустите 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

4. Проверить статус 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:

1. В TCM над вкладкой Stateboard выберите кластер Tarantool Cluster 1 в выпадающем списке Clusters.

2. Подключитесь к узлу хранилища. Для этого нажмите на набор реплик replicaset001, выберите экземпляр storage-a-001 и в открывшемся окне перейдите на вкладку Terminal (TT Connect).

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

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

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

5. Переключитесь на Tarantool Cluster 2 и перейдите на вкладку Tuples.

6. Выберите в списке спейс writers и проверьте, что в открывшейся вкладке также появился кортеж Haruki Murakami.