telemt-api/docs/GATEWAY_RUN.md

Запуск Telemt API Gateway (Docker)

Оглавление:

1. Назначение
2. Требования
3. Минимальная конфигурация
4. Переменные окружения
5. Сборка образа
6. Запуск через Docker CLI
7. Запуск через Docker Compose
8. Проверка
9. Обновление и CI/CD
10. Устранение неполадок

Назначение

Шлюз — это один HTTP‑вход для нескольких экземпляров Telemt Control API:

• Белый список IP (CIDR): кто может обращаться к шлюзу (кроме GET /health, см. ниже).
• Маршрутизация по alias: клиент вызывает GET /api/{alias}/health, шлюз проксирует на {base_url}/v1/health у соответствующего сервера.
• Метрики Prometheus: GET /metrics (под тем же правилом whitelist, что и API).
• Доверенные прокси: если прямой TCP‑peer входит в trusted_proxies, для проверки whitelist берётся первый адрес из X-Forwarded-For или X-Real-IP.

Эндпоинты и контракт ответов бэкенда описаны в API.md.

Требования

• Установленные Docker и при необходимости Docker Compose v2.
• Для локальной сборки из исходников: Go 1.22+ (опционально, если не используете только готовый образ из registry).

Минимальная конфигурация

Скопируйте config.example.yaml в свой config.yaml и отредактируйте.

Минимальный рабочий фрагмент для разработки (без проверки IP):

listen: ":8080"
allow_all: true
servers:
  - alias: main_srv
    base_url: http://127.0.0.1:9091

Минимальный фрагмент для продакшена (только перечисленные сети/хосты):

listen: ":8080"
allow_all: false
whitelist_cidrs:
  - "203.0.113.10/32"
  - "10.0.0.0/8"
servers:
  - alias: main_srv
    base_url: http://telemt-internal:9091

Правила:

• При allow_all: false и пустом whitelist_cidrs доступ будет закрыт для всех (кроме GET /health).
• GET /health на шлюзе не проверяется по whitelist — так проще настроить Docker HEALTHCHECK и оркестраторы.
• Поле path_prefix по умолчанию равно /v1 (префикс Telemt Control API).

Опционально для бэкенда с включённым auth_header в Telemt задайте в конфиге имя переменной окружения, значение которой будет отправлено как заголовок Authorization на этот upstream:

servers:
  - alias: main_srv
    base_url: http://telemt:9091
    authorization_env: TELEMT_API_AUTH

Значение должно точно совпадать с настроенным в Telemt auth_header (см. API.md).

Переменные окружения

Переменная	Описание
CONFIG_PATH	Путь к YAML внутри контейнера. По умолчанию: /etc/telemt-gateway/config.yaml.
TELEMT_API_AUTH	Пример: секрет для authorization_env в конфиге (имя может быть любым).

Сборка образа

В каталоге репозитория:

docker build -t telemt-api-gateway:local .

Запуск через Docker CLI

Пример для Linux (подставьте путь к config.yaml; ниже — файл из текущего каталога):

docker run -d --name telemt-gateway \
  -p 8080:8080 \
  -v "$(pwd)/config.yaml:/etc/telemt-gateway/config.yaml:ro" \
  -e CONFIG_PATH=/etc/telemt-gateway/config.yaml \
  telemt-api-gateway:local

Проверка:

curl -sS -i http://127.0.0.1:8080/health
curl -sS -i http://127.0.0.1:8080/api/main_srv/health

Второй запрос проксируется на {base_url}/v1/health для alias main_srv.

Остановка и удаление:

docker stop telemt-gateway
docker rm telemt-gateway

Запуск через Docker Compose

В репозитории есть docker-compose.yml и пример config.compose.yaml с allow_all: true и base_url: http://host.docker.internal:9091 (Telemt на хосте; на Docker Desktop для Linux это обычно работает из коробки).

docker compose up -d --build
docker compose logs -f gateway
docker compose down

На Linux без host.docker.internal сделайте одно из:

• в docker-compose.yml для сервиса gateway добавьте extra_hosts: ["host.docker.internal:host-gateway"] (Docker Engine 20.10+);
• либо замените в config.compose.yaml значение base_url на IP хоста в docker‑bridge (часто 172.17.0.1) или на имя сервиса Telemt в той же сети compose.

Проверка

Сценарий	Ожидание
GET /health	200, JSON {"status":"ok"}
Разрешённый IP, корректный alias	ответ бэкенда (например 200 для /v1/health)
IP не в whitelist	403, JSON с code: forbidden
Неизвестный alias	404, JSON с code: not_found
Бэкенд недоступен	502, JSON с code: bad_gateway
GET /metrics	текст метрик Prometheus (при разрешённом IP)

Обновление и CI/CD

• Образ: пересоберите тег или подтяните новый из registry, затем docker compose up -d --build или docker stop / docker run ... с тем же volume конфига.

• Конфиг: отредактируйте файл на хосте и перезапустите контейнер (шлюз не перечитывает конфиг на лету).

• Gitea Actions: workflow .gitea/workflows/docker.yaml сначала выполняет go mod tidy && go test ./..., затем собирает образ через Buildx и пушит в Container Registry Gitea.

  • В репозитории должен быть secret ACTIONS_PAT — personal access token пользователя с правом write:package (и при необходимости read:package), как для обычного docker login к registry.
  • Логин в registry: пользователь gitea.actor (кто запустил workflow), пароль — этот PAT.
  • Хост registry задаётся в workflow в env.REGISTRY (по умолчанию git.shts.su); при другом инстансе Gitea измените значение в .gitea/workflows/docker.yaml.
  • Теги образа: latest, имя ветки/тега (с / заменённым на -), и sha-<первые 12 символов коммита>. Полный путь: {REGISTRY}/{gitea.repository}:<тег>.

Устранение неполадок

• 403 forbidden с хоста при allow_all: false: добавьте CIDR клиента в whitelist_cidrs. Запросы из контейнера к самому себе идут с 127.0.0.1 — при необходимости добавьте 127.0.0.1/32.
• За reverse proxy: укажите CIDR прокси в trusted_proxies, иначе whitelist видит IP прокси, а не клиента.
• 502 bad_gateway: проверьте base_url, DNS в Docker‑сети и то, что Telemt слушает API ([server.api].enabled=true и корректный listen).
• Сборка Go без Docker: в корне репозитория выполните go mod tidy && go test ./....