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

Пример для PowerShell (подставьте путь к своему config.yaml):

docker run -d --name telemt-gateway `
  -p 8080:8080 `
  -v "C:\path\to\config.yaml:/etc/telemt-gateway/config.yaml:ro" `
  -e CONFIG_PATH=/etc/telemt-gateway/config.yaml `
  telemt-api-gateway:local

Проверка:

Invoke-WebRequest -Uri http://127.0.0.1:8080/health -UseBasicParsing
Invoke-WebRequest -Uri http://127.0.0.1:8080/api/main_srv/health -UseBasicParsing

Второй запрос проксируется на {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 compose up -d --build
docker compose logs -f gateway
docker compose down

На старых Linux‑хостах, где нет host.docker.internal, замените base_url на IP хоста или добавьте сервис Telemt в тот же docker-compose и укажите его DNS‑имя.

Проверка

Сценарий	Ожидание
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 test и собирает Docker‑образ. Для пуша в registry задайте secrets:

  • REGISTRY_IMAGE — полное имя образа без тега, например git.example.com/owner/telemt-api-gateway
  • REGISTRY_URL — хост registry, например git.example.com
  • REGISTRY_USER / REGISTRY_PASSWORD

  Если secrets не заданы, образ только собирается в runner без push.

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

• 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 ./... в корне репозитория.