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

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

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.

     Note

     Начиная с 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.