Основные задачи¶

Добавление экземпляров Scheduler¶

Добавление новых экземпляров Scheduler может понадобиться, когда системе не хватает пропускной способности роутеров или мощности SQL-вычислений.

Для добавления нового экземпляра с помощью инсталлятора Ansible Tarantool Enterprise:

1. Добавьте экземпляры в инвентарь TCS.

2. Вызовите метод install_scheduler, чтобы установить и запустить новые экземпляры. При необходимости задайте параметр limit:

      docker run --network host -it --rm \
          -v ${PATH_TO_PRIVATE_KEY}:/ansible/.ssh/id_private_key:Z \
          -v ${PATH_TO_INVENTORY}:/ansible/inventories/hosts.yml:Z \
          -e SUPER_USER_NAME=${SUPER_USER_NAME} \
          ansible-tarantool-enterprise:latest \
          ansible-playbook -i /ansible/inventories/hosts.yml \
          --extra-vars '{
              "ansible_ssh_private_key_file":"/ansible/.ssh/id_private_key",
              "super_user":"'${SUPER_USER_NAME}'",
              "tarantool_shared_become_user":"tarantool",
          }' \
          playbooks/tcs/install_scheduler.yml --limit ${LIMIT}
   

Настройка шардирования¶

Для настройки шардирования в кластере TCS укажите следующие параметры в конфигурации TCS:

1. Настройте конфигурацию шардов (наборов реплик, состоящих из экземпляров Storage, между которыми будут распределяться данные).

   Для этого нужно указать следующие параметры:

   • блок параметров для как минимум 2 шардов (раздел groups:aggregators:replicasets, параметры leader и instances);

     • можно использовать 1 шард, если вставка будет происходить через экземпляр Scheduler, используя его ADBC/JDBC интерфейс, в таком случае необходимо указать блок параметров только для этого шарда;

   • общее имя группы для всех шардов (параметр tarantool_group_name в конфигурации каждого экземпляра Storage, который входит в состав шардов).

   Например:

all:
  groups:
    aggregators:
      replicasets:
        tcs_storages_r01:
          leader: tcs-r01-s01
          instances:
             tcs-r01-s01:
             tcs-r01-s02:
        tcs_storages_r02:
          leader: tcs-r02-s01
          instances:
             tcs-r02-s01:
             tcs-r02-s02:

  children:
    aggregators:
      tcs_storages_r01:
        hosts:
          tcs-r01-s01:
          tcs-r01-s02:
        vars:
          replicaset_alias: tcs_storages_r01
          tarantool_group_name: aggregators

      tcs_storages_r02:
        hosts:
          tcs-r02-s01:
          tcs-r02-s02:
        vars:
          replicaset_alias: tcs_storages_r02
          tarantool_group_name: aggregators

1. Настройте сервис Arrow Flight SQL на всех экземплярах Storage, которые участвуют в шардировании.

   Для этого нужно указать следующие параметры (раздел roles_cfg:tcs:aggregator):

   • параметры соединения в разделе arrow_flight_sql: listen, credentials, session_timeout_secs;

   • параметр arrow_flight_sql_api в разделе features.

   Например:

roles_cfg:
  tcs:
    aggregator:
      features:
        - arrow_flight_sql_api
      arrow_flight_sql:
        listen: 0.0.0.0:50051
        credentials:
          login: tcs
          password: tcs
        session_timeout_secs: 28800

3. Включите поддержку шардирования на всех экземплярах Scheduler, которые есть в кластере TCS.

   Для этого в конфигурации каждого экземпляра Scheduler нужно указать параметр sharding_api в списке features.

   Например:

all:
  groups:
    tcs_scheduler:
      hosts:
        tcs-scheduler-01:
          http_listen: '0.0.0.0:7778'
          with_metrics: true
          config_storage: etcd
          group: aggregators
          etcd:
            prefix: /tcs
            endpoints:
              - 'http://0.0.0.0:2379'
          features:
            - sharding_api

4. Укажите ключ шардирования для всех шардируемых таблиц.

   Для этого в разделе groups:aggregators:roles_cfg:app/aggregator_role:tcs:tables нужно для каждой шардируемой таблицы задать раздел sharding с параметрами:

   • method – метод построения ключа (в текущей версии поддерживается только значение hash);

   • column_name – имя колонки для построения ключа шардирования.

   Например:

groups:
  aggregators:
    roles_cfg:
      app/aggregator_role:
        tcs:
          tables:
            tcs.public.attributes:
              sharding:
                method: hash
                column_name: Attribute1
            tcs.public.clients:
              ttl: 9999999
              timestamp: time
              sharding:
                method: hash
                column_name: id

Управление кластером с помощью ATE¶

Инсталлятор Ansible Tarantool Enterprise предоставляет следующие сценарии по управлению кластером (см. соответствующие разделы в документации по инсталлятору Ansible Tarantool Enterprise):

• Tarantool 3.0: Отправка конфигурации в etcd (сценарий применим ко всем компонентам кластера)

• Запуск экземпляр(ов) (сценарий не применим к экземплярам Scheduler)

• Остановка экземпляра(ов) (сценарий не применим к экземплярам Scheduler)

• Перезагрузка экземпляра(ов) (сценарий не применим к экземплярам Scheduler)

• Перезапуск экземпляров Scheduler

• Автоматическое резервирование (сценарий не применим к экземплярам Scheduler)

• Автоматическое восстановление (сценарий не применим к экземплярам Scheduler)

Управление кластером с помощью TCM¶

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

• Создание/остановка кластера и изменение его конфигурации:

  • Переключение лидера в наборах реплик;

  • Изменение некоторых других настроек кластера, с простоем и в runtime;

  • Исключение экземпляра из кластера.

• Управление пользователями и ролями в кластере:

  • Управление пользователями Tarantool;

  • Изменение паролей пользователей Tarantool Enterprise.

• Контролируемое аварийное переключение узлов кластера;

• Восстановление и пересоздание экземпляров;

• Проверка работоспособности кластера;

• Просмотр журналов аудита.

См. документацию по Tarantool Cluster Manager.

Примеры: конфигурация Aggregator (один экземпляр)¶

tarantool_column_store.s1-1:
  advertise_uri: localhost:3301
  http_port: 8081
  memtx_memory: 2147483648 # 2gb
  log: ''
  aggregator:
    transport: tls
    tls_cert_file: certs/cert.pem
    tls_key_file: certs/key.pem

    features:
      - grpc_api

tarantool_column_store.s1-1:
  advertise_uri: localhost:3301
  http_port: 8081
  memtx_memory: 2147483648 # 2gb
  log: ''
  aggregator:
    transport: tls
    tls_cert_file: certs/cert.pem
    tls_ca_file: certs/ca.pem
    tls_key_file: certs/key.pem

    features:
      - grpc_api

tarantool_column_store.s1-1:
  advertise_uri: localhost:3301
  http_port: 8081
  memtx_memory: 2147483648 # 2gb
  log: ''
  aggregator:
    transport: tls
    tls_cert_file: certs/cert.pem
    tls_key_file: certs/key.pem
    tls_ciphers: 'GOST2012-MAGMA-MAGMAOMAC:GOST2012-KUZNYECHIK-KUZNYECHIKOMAC:LEGACY-GOST2012-GOST8912-GOST8912:IANA-GOST2012-GOST8912-GOST8912:GOST2001-GOST89-GOST89'
    tls_ciphersuites: ''

    features:
      - grpc_api

Примеры: конфигурация Scheduler¶

listen: 0.0.0.0:7777
transport: tls
tls_cert_file: certs/cert.pem
tls_key_file: certs/key.pem

nodes:
  - admin_iproto_endpoint: master:3301
    admin_http_endpoint: master:8081
    api_http_endpoint: master:7777

listen: 0.0.0.0:7777
transport: tls
tls_cert_file: certs/cert.pem
tls_ca_file: certs/ca.pem
tls_key_file: certs/key.pem

nodes:
  - admin_iproto_endpoint: master:3301
    admin_http_endpoint: master:8081
    api_http_endpoint: master:7777

listen: 0.0.0.0:7777
transport: tls
tls_cert_file: certs/cert.pem
tls_key_file: certs/key.pem
tls_ciphers: 'GOST2012-MAGMA-MAGMAOMAC:GOST2012-KUZNYECHIK-KUZNYECHIKOMAC:LEGACY-GOST2012-GOST8912-GOST8912:IANA-GOST2012-GOST8912-GOST8912:GOST2001-GOST89-GOST89'
tls_ciphersuites: ''

nodes:
  - admin_iproto_endpoint: master:3301
    admin_http_endpoint: master:8081
    api_http_endpoint: master:7777

Настройка поддержки драйверов JDBC/ADBC для экземпляра Storage¶

Для того чтобы включить поддержку драйверов JDBC/ADBC для экземпляров Storage, в конфигурации TCS нужно указать следущие параметры для каждого экземпляра:

• Параметр arrow_flight_sql_api в разделе features (groups/aggregators/replicasets/replicaset<N>/instances/instance<N>/roles_cfg/tcs/aggregator/features). По умолчанию: не задан.

• Параметры соединения в разделе arrow_flight_sql (groups/aggregators/replicasets/replicaset<N>/instances/instance<N>/roles_cfg/tcs/aggregator/arrow_flight_sql):

  • listen – номер порта. По умолчанию: 50051.

  • (обязательно) credentials – логин и пароль (параметры login и password).

  • session_timeout_secs – максимальная длительность сессии (в секундах). По умолчанию: 28800 (8 часов).

Пример:

groups:
  aggregators:
    replicasets:
      replicaset1:
        replication:
          failover: manual
        leader: instance1
        instances:
          instance1:
            roles_cfg:
              tcs:
                aggregator:
                  http_listen: 0.0.0.0:7776
                  http_listen_streaming: 0.0.0.0:8776
                  features:
                    - arrow_flight_sql_api
                  arrow_flight_sql:
                    listen: 0.0.0.0:50052
                    credentials:
                      login: tcs
                      password: tcs
                    session_timeout_secs: 28800
          instance2:
            roles_cfg:
              tcs:
                aggregator:
                  http_listen: 0.0.0.0:7777
                  http_listen_streaming: 0.0.0.0:8777
                  features:
                    - arrow_flight_sql_api
                  arrow_flight_sql:
                    listen: 0.0.0.0:50053
                    credentials:
                      login: tcs
                      password: tcs
                    session_timeout_secs: 28800

Для обоих экземпляров Storage в replicaset1 указаны:

• параметр arrow_flight_sql_api;

• разные номера портов в listen, поскольку экземпляры запущены на одном хосте.

Настройка поддержки драйверов JDBC/ADBC для экземпляра Scheduler¶

Поддержка драйверов JDBC/ADBC для экземпляров Scheduler доступна только в режиме шардированной работы, даже если в конфигурации кластера задан только 1 шард.

Для того чтобы перевести экземпляр Scheduler в режим шардированной работы, в его настройках нужно указать:

features:
  - sharding_api

Подробнее о переводе Scheduler в шардированный режим работы см. в разделе Настройка шардирования.

В настройках экземпляра Scheduler нужно включить поддержку arrow_flight_sql_api:

arrow_flight_sql:
  listen: 0.0.0.0:50051
  session_timeout_s: 3840
with_metrics: true
config_storage: etcd
etcd:
  prefix: /tcs
  endpoints:
    - http://localhost:2379
group: aggregators
replicaset: replicaset1
features:
  - experimental_api
  - sharding_api
authentication:
  etcd_auth_prefix: "/auth"
  system_user:
    username: tcs
    password: tcs

Параметр session_timeout_s необязателен. Он указывает время жизни сессии в секундах, создаваемой для подключения. По умолчанию значение параметра равно 3840, что равняется 8 часам. Если в рамках сессии подразумевается выполнение какого-то особо длительного процесса, который может потребовать больше 8 часов, к примеру, заливка данных ETL, то в таком случае имеет смысл переопределить значение параметра session_timeout_s в большую сторону.

Блок параметров authentication содержит аутентификационные данные учетной записи пользователя tcs. Эти данные необходимы для выполнения подключения по протоколу Arrow Flight SQL. Для подключения по протоколу HTTP API эти данные указывать не обязательно.

После включения этих настроек можно подключаться к таким экземплярам Scheduler с помощью коннекторов ADBC или JDBC и выполнять запросы SELECT и INSERT.

Запросы INSERT будут шардированы. Это значит, что если в запросе указан ключ шардирования, то строки будут распределяться по шардам в соответствии с тем, на какой шард указывает ключ шардирования каждой конкретной строки. Если ключ шардирования не указан, то все вставляемые строки будут отправляться на один шард — на первый в топологии.

Применение обновления¶

1. Обновить версию TCS до требуемой.

2. Выполнить команду следующего вида на мастер-экземпляре Storage (а при настроенном шардировании – на мастер-экземпляре Storage каждого набора реплик):

   require('migrations.<имя_скрипта>').apply()
   

   Примечание

   Имя скрипта миграции указывается без расширения .lua.

Откат обновления¶

1. Выполнить команду следующего вида на мастер-экземпляре Storage (а при настроенном шардировании – на мастер-экземпляре Storage каждого набора реплик):

   require('migrations.<имя_скрипта>').revert()
   

   Примечание

   Имя скрипта миграции указывается без расширения .lua.

2. Откатить версию TCS при необходимости.

Полная инструкция¶

1. Зайдите на сервер TCS с экземплярами Storage по SSH.

2. Переключитесь на пользователя tarantool:

   sudo su tarantool
   

3. Установите переменную окружения для работы с SystemD в userspace:

   export XDG_RUNTIME_DIR=/run/user/$(id -u)
   

   Объяснение: Это нужно для выполнения команд утилит SystemD (systemctl, journalctl) в userspace.

   Рекомендация: Чтобы не выполнять экспорт каждый раз, можно добавить команду export XDG_RUNTIME_DIR=/run/user/$(id -u) в файл $HOME/.profile.

4. Посмотрите список сервисов пользователя tarantool:

   systemctl --user list-units --type=service
   

   Пример вывода:

   tarantool@tcs-testing-1:~$ systemctl --user list-units --type=service
     UNIT                               LOAD   ACTIVE SUB     DESCRIPTION
     tarantool-cluster-manager.service  loaded active running Tarantool Cluster Manager
     tcs-scheduler@scheduler-01.service loaded active running Tarantool Column Store scheduler API service
   ● tcs@i-01.service                   loaded failed failed  Tarantool application tcs@i-01 #сервис инстанса стораджа
   

   В примере выше:

   • tcs@i-01.service – полное название сервиса для экземпляра с именем i-01;

   • tcs – название приложения Tarantool.

   В директории $HOME/.config/systemd/user находятся:

   • Шаблонный сервис для всех экзепляров tcs@.service;

   • Символическая ссылка на шаблонный сервис tcs@i-01.service.

5. Откройте шаблонный сервис для экземпляров Storage:

   vim $HOME/.config/systemd/user/tcs@.service
   

6. В шаблонном сервисе посмотрите путь до исполняемого файла tarantool:

   [Service]
   Type=simple
   ExecStart="/app/tarantool/tcs/bin/tcs.%i/tarantool --name %i" # запоминаем этот путь
   Restart=on-failure RestartSec=2
   

   Объяснение:

   При автоматическом развертывании TCS исполняемые файлы размещаются в разных местах в зависимости от:

   • указанных в настройках путей для размещения файлов;

   • названия приложения (app_name);

   • других параметров конфигурации.

   Вместо того чтобы пытаться угадать правильный путь к исполняемому файлу Tarantool при настройке службы (в параметре ExecStart), лучше сразу посмотреть точное расположение файла в конфигурационном файле службы vim ~/.config/systemd/user/tcs@.service.

7. Выполните команду systemctl --user edit название_сервиса_storage для того, чтобы начать редактирование (во временном буфере) файла с перезаписью опций в шаблонном сервисе:

   systemctl --user edit tcs@i-01
   

8. Добавьте перезапись опции ExecStart из секции [Service]. В новом ExecStart указан запуск процесса через утилиту numactl с нужными опциями:

   [Service]
   ExecStart=
   ExecStart=numactl --cpunodebind=0 --membind=0 /app/tarantool/tcs/bin/tcs.%i/tarantool --name %i
   

   ВАЖНО: обязательно нужно указать сначала пустой ExecStart, чтобы в дальнейшем не возникло ошибки при применении новой конфигурации.

9. Сохраните файл.

   Объяснение: Это действие создаст директорию $HOME/.config/systemd/user/название_сервиса.d и файл override.conf в этой директории.

   Рекомендация: Чтобы в качестве редактора использовался vim (если он уже не используется по умолчанию), можно установить переменную окружения SYSTEMD_EDITOR=vim.

10. Выполните команду для перезагрузки конфигурации systemD:

systemctl --user daemon-reload

11. Перезапустите экземпляр:

systemctl --user restart tcs@i-01

Примечание: Перезапустить экземпляр можно также через ATE.

12. После перезапуска можно проверить привязку к NUMA-зоне, найдя ее в файле /proc/${PID}/numa_maps.

Краткая инструкция¶

# Зайти под пользователем tarantool:
sudo su tarantool
# Установить переменную для работы с SystemD в userspace:
export XDG_RUNTIME_DIR=/run/user/$(id -u)
# Посмотреть, какие есть сервисы:
systemctl --user list-units --type=service
# Запустить редактирование интересующего сервиса:
systemctl --user edit название_интересующего_сервиса
# Добавить в файл:
[Service]
ExecStart=
ExecStart=numactl --cpunodebind=0 --membind=0 /app/tarantool/tcs/bin/tcs.%i/tarantool --name %i
# Перезагрузить конфигурацию systemD:
systemctl --user daemon-reload
# Перезапустить экземпляр
systemctl --user restart название_сервиса