Использование узлов-обработчиков¶

Пререквизиты¶

Для выполнения примера требуются:

• установленные Docker-образы Tarantool DB, Prometheus и Grafana;

• приложение Docker Compose;

• утилита etcdctl;

• компилятор Go;

• исходные файлы примера tdb_worker.

  Примечание

  Есть два способа получить исходные файлы примера:

  • Архив с полной документацией Tarantool DB, полученный по почте или скачанный в личном кабинете tarantool.io. Пример архива: tarantooldb-documentation-3.0.0.tar.gz. Пример tdb_worker расположен в таком архиве в директории ./doc/examples/tdb_worker/.

  • Отдельный архив tdb_worker.tar.gz, скачанный c сайта Tarantool.

Запуск стенда¶

Перейдите в директорию примера tdb_worker:

cd ./doc/examples/tdb_worker/

Запустите стенд:

make start

Запущенный стенд состоит из:

• кластера Tarantool DB (2 роутера, 2 набора реплик по 3 хранилища);

• кластера etcd из 3 узлов для хранения конфигурации;

• 1 Tarantool Cluster Manager (TCM);

• средств мониторинга – Prometheus, Grafana.

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

• Username: admin

• Password: secret

Используемые файлы¶

В руководстве используются следующие файлы примера tdb_worker:

• cluster/config.yml — конфигурация и топология кластера;

• cluster/docker-compose.yml — описание узлов кластера Tarantool DB;

• docker-compose-worker.yml — описание узлов-обработчиков;

• main.go — исходный код обработчика;

• http-server-1-config.yml — конфигурация первого обработчика;

• http-server-2-config.yml — конфигурация второго обработчика.

Сборка обработчика¶

Исходный код обработчика хранится в файле main.go в примере tdb_worker.

Для сборки обработчика выполните команду ниже:

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o bin/http-server ./main.go

Конфигурация узлов-обработчиков хранится в файлах http-server-1-config.yml, http-server-2-config.yml и загружается в хранилище конфигурации (в примере это etcd) при запуске стенда.

Прочитать её можно так:

ETCDCTL_API=3 etcdctl get --prefix '/tdb-workers/'

Сама конфигурация выглядит так:

/tdb-workers/tdb/instances/127.0.0.1/http-server-1
type: nontarantool
instrumentation: # параметры мониторинга
    url:            worker-1:9080
    metrics_url:    /metrics
    metrics_format: "prometheus"
    liveness_url:   /alive
    info_url:       /info
    binary:         ./bin/http-server
config: # произвольная конфигурация обработчика
    addr:                       0.0.0.0:10000
    tarantool_cluster_prefix:   /tdb/config/all
    tarantool_user:             admin
    tarantool_pass:             secret-cluster-cookie

Описание конфигурации приведено в соответствующем разделе справочника.

У каждого обработчика конфигурация хранится по отдельному ключу:

• /tdb-workers/tdb — префикс для хранения конфигураций экземпляров обработчиков;

• 127.0.0.1 — адрес хоста обработчика (ansible host);

• http-server-1 — имя обработчика.

Префикс для конфигурации обработчиков можно задать через веб-интерфейс TCM. Для этого:

1. В TCM перейдите на вкладку Clusters и нажмите на кнопку вызова меню … (Actions) справа от нужного кластера (в примере это кластер Tarantool DB Cluster).

2. В выпадающем меню выберите пункт Edit и перейдите на вкладку настроек Config storage connection, нажав кнопку Next.

3. На вкладке Config storage connection введите название префикса в поле Workers prefix.

Запуск обработчика¶

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

• TDB_WORKER_NAME=http-server-1 — имя обработчика. Тип: string;

• TDB_WORKER_HOST_NAME=127.0.0.1 — название хоста, на котором расположен обработчик. Тип: string.

• TDB_WORKER_CONFIG_ETCD_PREFIX=/tdb-workers/tdb/instances — путь префикса в централизованном хранилище конфигурации etcd, который указывает расположение конфигурации обработчиков. Тип: string.

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

• TDB_WORKER_CONFIG_ETCD_USERNAME — имя пользователя для подключения к централизованному хранилищу конфигурации etcd. Тип: string. Значение по умолчанию: "";

• TDB_WORKER_CONFIG_ETCD_PASSWORD — пароль для подключения к централизованному хранилищу конфигурации etcd. Тип: string. Значение по умолчанию: "";

• TDB_WORKER_CONFIG_ETCD_ENDPOINTS=http://etcd1:2379 — список узлов централизованного хранилища конфигурации для подключения, узлы указываются через запятую. Тип: array;

Также можно указать опции SSL-подключения:

• TDB_WORKER_CONFIG_ETCD_SSL_VERIFY_PEER – наличие проверки peer-сертификата etcd. Тип: boolean. Значение по умолчанию: false;

• TDB_WORKER_CONFIG_ETCD_SSL_VERIFY_HOST – наличие проверки master-сертификата etcd. Тип: boolean. Значение по умолчанию: false;

• TDB_WORKER_CONFIG_ETCD_SSL_CA_PATH – путь к доверенному CA-сертификату, используемому для установки соединения с etcd. Тип: string;

• TDB_WORKER_CONFIG_ETCD_SSL_CERT – путь к клиентскому SSL-сертификату, используемому для установки соединения с etcd. Тип: string;

• TDB_WORKER_CONFIG_ETCD_SSL_KEY – путь к клиентскому SSL-ключу, используемому для установки соединения с etcd. Тип: string.

Для TBCS используются схожие параметры, но с другим префиксом.

• TDB_WORKER_CONFIG_STORAGE_PREFIX

• TDB_WORKER_CONFIG_STORAGE_ENDPOINTS

Узнать больше про настройку etcd и TBCS можно в документации платформы Tarantool.

Если зайти в TCM по адресу http://localhost:8081, на вкладке Stateboard вы увидите секцию с обработчиками: Сейчас эти узлы отключены, поэтому они подсвечены серым цветом. Если нажать на такой узел, в открывшемся окне будет видно, что узел имеет статус no-connection:

Запустите узлы-обработчики:

docker compose -f docker-compose-worker.yml up -d worker-1 worker-2

Проверьте логи:

docker compose -f docker-compose-worker.yml logs

В логах должны появиться следующие строки:

worker-1-1  | http-server-1 /tdb-workers/tdb/instances/127.0.0.1
worker-1-1  | 2026-01-29T11:36:39Z INFO /home/user/tarantooldb/doc/examples/tdb_worker/main.go:213 "starting http server" addr=0.0.0.0:10000
worker-1-1  | 2026-01-29T11:36:39Z INFO /home/user/tarantooldb/doc/examples/tdb_worker/main.go:194 "starting instrumentation server" addr=worker-1:9080
worker-2-1  | http-server-2 /tdb-workers/tdb/instances/127.0.0.1
worker-2-1  | 2026-01-29T11:36:39Z INFO /home/user/tarantooldb/doc/examples/tdb_worker/main.go:213 "starting http server" addr=0.0.0.0:10001
worker-2-1  | 2026-01-29T11:36:39Z INFO /home/user/tarantooldb/doc/examples/tdb_worker/main.go:194 "starting instrumentation server" addr=worker-2:9081

В TCM обработчики будут отображаться так:

Обработчик запускает два простых HTTP‑сервера:

• сервер для доступа к спейсу bands;

• сервер для мониторинга и интеграции с TCM.

Добавьте новые кортежи в спейс bands:

curl -X POST http://127.0.0.1:10000/api/bands -d '{"id":1,"band_name":"name", "year":2024}'
curl -X POST http://127.0.0.1:10001/api/bands -d '{"id":2,"band_name":"name-2", "year":2025}'

Теперь прочитайте записанные кортежи:

curl http://127.0.0.1:10000/api/bands/1
curl http://127.0.0.1:10000/api/bands/2

Ответ:

{"id":1,"band_name":"name","year":2024}
{"id":2,"band_name":"name-2","year":2025}

Взаимодействие с кластером Tarantool DB¶

Обработчик использует библиотеку go‑discovery, которая позволяет реагировать на изменения конфигурации кластера и динамически обновлять группу соединений. Это позволяет добавлять и удалять узлы без перезапуска обработчика.

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

1. Создание группы соединений для подключения к кластеру Tarantool DB:

   // Create pool for tarantool DB cluster.
   pool, err := pool.NewPool(
       dial.NewNetDialerFactory(
           workerCfg.Config.TarantoolUser,
           workerCfg.Config.TarantoolPass,
           tarantool.Opts{
               Timeout: 5 * time.Second,
           },
       ),
       pool.NewRoundRobinBalancer(),
   )
   

2. Подписка на изменения конфигурации (узлы с ролью roles.crud‑router):

   // The scheduler will watch for updates from etcd.
   etcdWatcher := scheduler.NewEtcdWatch(
       clientv3,
       workerCfg.Config.TarantoolClusterPrefix,
   )
   defer etcdWatcher.Stop()
   
   disc := discoverer.NewFilter(
       // The base discoverer gets a list of instance configurations from
       // etcd.
       discoverer.NewEtcd(clientv3,
           strings.TrimSuffix(
               workerCfg.Config.TarantoolClusterPrefix,
               "/config/all",
           ),
       ),
   )
   
   // The Subscriber will send instance configurations into the pool
   // on updates.
   etcdSubscriber := subscriber.NewFilter(
       subscriber.NewSchedule(etcdWatcher, disc),
       // etcdSubscriber will track new crud-routers in cluster configuration
       filter.RolesContain{
           Roles: []string{"roles.crud-router"},
       },
   )
   

Подробная информация приведена в документации библиотеки go‑discovery.

Мониторинг состояния обработчика и интеграция с TCM¶

Обработчик предоставляет три адреса обработчика запроса (endpoints) для отслеживания своего состояния и интеграции с TCM:

• /healthcheck – проверка работоспособности узла обработчика;

• /metrics – метрики экземпляра обработчик;

• /info – общая информация об обработчике.

Задавать эти адреса обработчика запроса необязательно, но они позволяют TCM взаимодействовать с узлами-обработчиками. Хранение конфигурации в централизованном хранилище конфигурации, формат конфигурации и указание таких адресов обработчика запроса позволяют успешно интегрировать экземпляры обработчиков в поставку вместе с Tarantool DB.

curl http://127.0.0.1:9080/metrics | head -n 5
curl http://127.0.0.1:9081/metrics | head -n 5

curl http://127.0.0.1:9080/info

{
  "version": "1.0.0",
  "uptime_seconds": 362349.44,
  "memory_usage_bytes": 209213124,
  "extra_info": {
    "env": "staging",
    "my_custom": "foo-bar"
  }
}

Остановка стенда¶

Для остановки стенда выполните в локальном терминале команды ниже:

make stop
docker compose -f docker-compose-worker.yml down