Руководство для начинающих | Clusters_Federation
Войти Регистрация
Download

Версия:

latest (0.3.x+)
Руководство для начинающих

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

В этом руководстве приведена инструкция по ручному разворачиванию отказоустойчивой системы из двух кластеров 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.

  1. Скопируйте архив tarantooldb-<tdb_version>.<os>.<arch>.tar.gz в домашнюю директорию и распакуйте его:

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

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

    $ export PATH=~/tarantooldb:$PATH

  3. Скопируйте архив 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

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

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

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

  2. В директории instances.enabled созданного tt-окружения создайте директории cluster1 и cluster2.

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

    credentials:
  users:
    dbadmin:
      password: secret
      roles: [super]
    peer:
      password: peer_password
      roles: ['replication']
      privileges:
      - permissions: ['execute']
        lua_call: ['box.info']
    storage:
      password: storage_password
      roles: [sharding]
   tcm_tarantool:
      password: tcm_tarantool_password
      roles: [super]
    tcf_replicator:
      password: replicator_password
      roles: [super]
    tcf_dml:
      password: dml_password
      roles: [super]
iproto:
  advertise:
    peer:
      login: peer
    sharding:
      login: storage
sharding:
  bucket_count: 3000
roles_cfg:
  roles.tcf-worker:
    cluster_1: cluster1
    cluster_2: cluster2
    initial_status: active
    dml_users: [ tcf_dml ]
    replication_user: tcf_replicator
    replication_password: replicator_password
    status_ttl: 4
    enable_system_check: true
  roles.tcf-coordinator:
    failover_timeout: 20
    health_check_delay: 2
    max_suspect_counts: 3
groups:
  routers:
    sharding:
      roles: [router]
    replicasets: 
      router-001:
        instances: 
          router-001-a:
            roles_cfg:
              roles.httpd:
                default:
                  listen: 8081
            iproto:
              listen:
              - uri: 127.0.0.1:3301
              advertise:
                client: 127.0.0.1:3301
    roles:
      - roles.tcf-worker
      - roles.tcf-coordinator
      - roles.httpd
      - roles.crud-router
    roles_cfg:
      roles.crud-router:
        stats: true
        stats_driver: metrics
        stats_quantiles: true
        stats_quantile_tolerated_error: 0.001
        stats_quantile_age_buckets_count: 5
        stats_quantile_max_age_time: 180
  storages:
    sharding:
      roles: [storage]
    replication:
      failover: manual
    replicasets: 
      storage-001:
        leader: storage-001-a
        instances: 
          storage-001-a:
            roles_cfg:
              roles.httpd:
                default:
                  listen: 8082
            iproto:
              listen:
                - uri: 127.0.0.1:3302
              advertise:
                client: 127.0.0.1:3302
          storage-001-b:
            roles_cfg:
              roles.httpd:
                default:
                  listen: 8083
            iproto:
              listen:
                - uri: 127.0.0.1:3303
              advertise:
                client: 127.0.0.1:3303
          storage-001-c:
            roles_cfg:
              roles.httpd:
                default:
                  listen: 8084
            iproto:
              listen:
                - uri: 127.0.0.1:3304
              advertise:
                client: 127.0.0.1:3304
    roles:
      - roles.tcf-worker
      - roles.httpd
      - roles.crud-storage
      - roles.expirationd
    roles_cfg:
      roles.expirationd: []

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

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

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

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

    • tcm_tarantool – пользователь для подключения TCM к экземплярам Tarantool Cluster 1;

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

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

      Примечание

      Начиная с TCF 0.5.0, рекомендуется явно указывать роль roles.httpd в конфигурации кластера. При этом адрес для HTTP-запросов для конкретного экземпляра задается в секции roles_cfg.roles.httpd.default.listen. В версиях до 0.5.0 такой адрес указывается в секции roles_cfg.roles.tcf-worker.http.listen.

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

    router-001-a:
storage-001-a:
storage-001-b:
storage-001-c:

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

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

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

    credentials:
  users:
    dbadmin:
      password: secret
      roles: [super]
    peer:
      password: peer_password
      roles: ['replication']
      privileges:
      - permissions: ['execute']
        lua_call: ['box.info']
    storage:
      password: storage_password
      roles: [sharding]
   tcm_tarantool:
      password: tcm_tarantool_password
      roles: [super]
    tcf_replicator:
      password: replicator_password
      roles: [super]
    tcf_dml:
      password: dml_password
      roles: [super]
iproto:
  advertise:
    peer:
      login: peer
    sharding:
      login: storage
sharding:
  bucket_count: 3000
roles_cfg:
  roles.tcf-worker:
    cluster_1: cluster2
    cluster_2: cluster1
    initial_status: passive
    dml_users: [ tcf_dml ]
    replication_user: tcf_replicator
    replication_password: replicator_password
    status_ttl: 4
    enable_system_check: true
  roles.tcf-coordinator:
    failover_timeout: 20
    health_check_delay: 2
    max_suspect_counts: 3
groups:
  routers:
    sharding:
      roles: [router]
    replicasets: 
      router-001:
        instances: 
          router-001-a:
            roles_cfg:
              roles.httpd:
                default:
                  listen: 18081
            iproto:
              listen:
              - uri: 127.0.0.1:13301
              advertise:
                client: 127.0.0.1:13301
    roles:
      - roles.tcf-worker
      - roles.tcf-coordinator
      - roles.httpd
      - roles.crud-router
    roles_cfg:
      roles.crud-router:
        stats: true
        stats_driver: metrics
        stats_quantiles: true
        stats_quantile_tolerated_error: 0.001
        stats_quantile_age_buckets_count: 5
        stats_quantile_max_age_time: 180
  storages:
    sharding:
      roles: [storage]
    replication:
      failover: manual
    replicasets: 
      storage-001:
        leader: storage-001-a
        instances: 
          storage-001-a:
            roles_cfg:
              roles.httpd:
                default:
                  listen: 18082
            iproto:
              listen:
                - uri: 127.0.0.1:13302
              advertise:
                client: 127.0.0.1:13302
          storage-001-b:
            roles_cfg:
              roles.httpd:
                default:
                  listen: 18083
            iproto:
              listen:
                - uri: 127.0.0.1:13303
              advertise:
                client: 127.0.0.1:13303
          storage-001-c:
            roles_cfg:
              roles.httpd:
                default:
                  listen: 18084
            iproto:
              listen:
                - uri: 127.0.0.1:13304
              advertise:
                client: 127.0.0.1:13304
    roles:
      - roles.tcf-worker
      - roles.httpd
      - roles.crud-storage
      - roles.expirationd
    roles_cfg:
      roles.expirationd: []

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

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

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

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

  9. В директории 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:

mode: production
cluster:
  connection-rate-limit: 512
  tarantool-timeout: 10s
  tarantool-ping-timeout: 5s
  tt-command: tt
  refresh-state-period: 5s
  refresh-state-timeout: 4s
  discovery-period: 4s
  sharding-index: bucket_id
  skew-time: 30s
security:
  bootstrap-password: secret
http:
  host: 127.0.0.1
  port: 8080
  show-stack-trace: False
  trace: False
  network: tcp
  tls:
    enabled: False
    cert-file:
    key-file:
    server-name:
    min-version: 0
    max-version: 0
    curve-preferences: []
    cipher-suites: []
log:
  default:
    show-stack-trace: False
    add-source: False
    level: INFO
    format: struct
    output: stdout
    file:
      name: /var/log/tarantool/cluster-manager/tcm.log
      maxsize: 1073741824
      maxage: 0
      maxbackups: 10
      compress: True
addon:
  enabled: False
  addons-dir:
  max-upload-size: 104857600
  dev-addons-dir: []
limits:
  users-count: 1000
  clusters-count: 10
  roles-count: 100
  webhooks-count: 200
  user-secrets-count: 10
  user-websessions-count: 10
  linked-cluster-users: 10
feature:
  ttgraph: False
  column-store: False
  tqe: False
  api-token: False
  tcf: True
storage:
  provider: etcd
  etcd:
    prefix: /tcm
    endpoints:
      - http://127.0.0.1:2379
initial-settings:
  clusters:
    - name: Tarantool Cluster 1
      id: 00000000-0000-0000-0000-000000000000
      storage-connection:
        provider: etcd
        etcd-connection:
          prefix: /cluster1
          endpoints:
            - http://127.0.0.1:2379
      tarantool-connection:
        username: tcm_tarantool
        password: tcm_tarantool_password
    - name: Tarantool Cluster 2
      storage-connection:
        provider: etcd
        etcd-connection:
          prefix: /cluster2
          endpoints:
            - http://127.0.0.1:2379
      tarantool-connection:
        username: tcm_tarantool
        password: tcm_tarantool_password

Здесь:

  • http – имя и порт хоста, на котором запущен TCM. По умолчанию, TCM запускается на порту 8080;

  • storage – настройки хранилища конфигурации и узлов etcd, настроенных и запущенных ранее;

  • security – настройки безопасности TCM;

  • initial-settings – кластеры, которые создаются автоматически при первом запуске TCM. В конфигурации TCM автоматически созданы кластеры Tarantool Cluster 1 и Tarantool Cluster 2. Кластеры используют общий etcd, но имеют различные префиксы – /cluster1 и /cluster2.

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

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

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

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

  3. Запустите TCM:

    $ tcm -c tcm.yaml

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

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

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

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

    $ cd tarantooldb

  2. Загрузите конфигурацию кластера в централизованное хранилище из 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 – публикуемый файл конфигурации.

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

    $ tt start cluster1

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

    $ 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    --

  5. Запустите модуль шардирования 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.

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

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

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

    $ 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). Для этого:

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

    $ cd tarantooldb

  2. Загрузите конфигурацию кластера в централизованное хранилище из 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 – публикуемый файл конфигурации.

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

    $ tt start cluster2

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

    $ tt status cluster2

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

    INSTANCE                STATUS   PID     MODE  CONFIG  BOX      UPSTREAM
cluster2: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    --

  5. Запустите модуль шардирования 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.

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

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

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

    $ 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

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

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

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

    • Username: admin;

    • Password: secret.

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

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

  4. Чтобы проверить текущее состояние кластеров, перейдите на вкладку TCF.

  5. Также проверьте с помощью команды 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 и вставьте следующую конфигурацию:

  gateway:
    grpc_server:
      host: 127.0.0.1
      port: 10080
    http_server:
      host: 127.0.0.1
      port: 8000
    replica_type: anonymous
    max_cpu: 4
    stream_instances:
      - uri: 127.0.0.1:3302
        user: tcf_replicator
        password: replicator_password
      - uri: 127.0.0.1:3303
        user: tcf_replicator
        password: replicator_password
      - uri: 127.0.0.1:3304
        user: tcf_replicator
        password: replicator_password
  destination:
    metrics_enabled: true
    http_server:
      host: 127.0.0.1
      port: 8001
    gateways:
      - host: 127.0.0.1
        port: 10080
    buffer_size: 10000
    vshard_routers:
      hosts:
        - 127.0.0.1:13301
      user: tcf_replicator
      password: replicator_password
    start_retry_delay: 200
    max_retry_delay: 1500
    retry_attempts: 10
    max_cpu: 4

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

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

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

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

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

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

  1. Перейдите в веб-интерфейс ТСМ.

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

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

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

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

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

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

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

Нашли ответ на свой вопрос?
Обратная связь
Архитектура
Руководство по установке
Single-page version