sarex/iac

emelinda 5f7fe11748 Add example .env files and configuration documentation for measurements and subscriptions services.

2026-07-13 20:35:36 +03:00

16 KiB

Raw Blame History

Конфигурация workspaces-api

Документ описывает все переменные окружения и способы конфигурирования сервиса workspaces-api (репозиторий pdm/workspaces-api) и его развёртывания из этого infra-репозитория (iac/apps/workspaces).

workspaces-api — HTTP-сервис (cmd/api), хранит рабочие пространства (workspaces) и приложения (apps) в PostgreSQL, обращается к сервису documentation и к bundle-сервису. Вместе с ним из одного образа собираются утилиты миграций (cmd/migrations) и CLI (cmd/workspaces-cli).

Способы конфигурирования

Сервис настраивается только через переменные окружения. Разбор выполняется в config/config.go через библиотеку envconfig (функция config.FromEnv() → envconfig.Process). Отдельного конфиг-файла (yaml/toml) у приложения нет.

В отличие от env-required-подхода, envconfig здесь не помечает переменные обязательными — при отсутствии значения FromEnv() не завершает процесс, поле остаётся нулевым. Поэтому «обязательность» переменных БД/documentation фактическая, а не форсированная кодом: без них сервис стартует, но работать не будет.

Источники переменных по способам запуска:

Способ запуска	Откуда берутся переменные
Локально (docker-compose + бинарник)	Файл `.env` в корне репозитория. `docker-compose.yml` (`env_file: .env`) поднимает только контейнер Postgres (`postgres:13`); сам API-сервис в compose закомментирован и запускается бинарником. `Makefile` (`make docker`) прокидывает `.env` в docker-compose
Kubernetes — собственный Helm-чарт репозитория	`.helm/values.yaml` (`universal-chart`): блоки `envs` (обычные значения по окружениям `_default`/`stage`/`preprod`/`production`) и `secretEnvs` (значения из k8s-секретов). Деплой запускается пайплайнами `generic/common-ci`
Kubernetes — этот infra-репозиторий (`iac/apps/workspaces`)	`base/` — kustomize-манифесты с инъекцией секретов через HashiCorp Vault (annotations `vault.hashicorp.com/*`), обычные переменные заданы инлайн в `env:`. Оверлеи: `yc-k8s-test` (base + postgresql через Flux), `brusnika-stage` и `brusnika-prod` (Flux `HelmRelease` на `universal-chart`, блоки `envs`/`secretEnvs`)
CI/CD (GitLab)	`.gitlab-ci.yml` подключает шаблоны `generic/common-ci` (`universal-pipeline.yaml`); в `workflow.rules` задаются переменные пайплайна (`STAND`, `NAMESPACE`, `RELEASE_NAME`, `CHART_NAME`, `CHART_VERSION`, `HELM_SET_ARGS` и т.п.), а также build-args образа

Миграции БД. Отдельного env-флага для миграций нет: порядок запуска задаёт entrypoint.sh — сначала выполняется /migrations migrate, затем стартует /api. Утилита миграций читает тот же конфиг (config/config.go) и использует ENABLE_SSL/YC-PG-CERTIFICATE для TLS-подключения к БД (cmd/migrations/main.go). В kustomize-/Helm-манифестах миграции запускаются той же командой в args/command контейнера (set -e; /migrations migrate; exec /api).

Переменные приложения (`config.Config`)

Читаются структурой config.Config (config/config.go). Тип bool в envconfig принимает 1/0, true/false, t/f.

HTTP-сервер

Переменная	Тип	По умолчанию	Назначение
`API_ADDRESS`	string	—	Адрес прослушивания HTTP-сервера (`host:port`), напр. `0.0.0.0:8000`. Эндпоинт `/ping` — liveness/readiness

PostgreSQL

Переменная	Тип	По умолчанию	Назначение
`POSTGRES_ADDRESS`	string	—	Хост PostgreSQL
`POSTGRES_PORT`	string	—	Порт PostgreSQL
`POSTGRES_DB`	string	—	Имя базы данных
`POSTGRES_USER`	string	—	Пользователь БД
`POSTGRES_PASSWORD`	string	—	Пароль пользователя БД
`POSTGRES_POOL_SIZE`	int	`0`	Размер пула соединений к БД
`ENABLE_SQL_QUERY`	bool	`false`	Логировать SQL-запросы (query-hook в go-pg)
`ENABLE_SSL`	bool	`false`	Подключаться к PostgreSQL по TLS с проверкой по `YC-PG-CERTIFICATE`; читается и в api, и в миграциях
`YC-PG-CERTIFICATE`	string	—	Содержимое (PEM) CA-сертификата PostgreSQL; используется при `ENABLE_SSL=1` (`cmd/api/main.go`, `cmd/migrations/main.go`)

Сервис documentation

Переменная	Тип	По умолчанию	Назначение
`DOCUMENTATION_HOST`	string	—	Базовый URL сервиса documentation
`DOCUMENTATION_ORIGINATOR`	string	—	Идентификатор источника, передаваемый в сервис documentation
`DOCUMENTATION_LOGGER_FEATURE`	bool	`false`	Включает фичу логирования обращений к сервису documentation

Bundles

Переменная	Тип	По умолчанию	Назначение
`BUNDLES_RETRY_COUNT`	int	`3`	Кол-во ретраев клиента bundles; при значении `<= 0` в `FromEnv()` принудительно берётся `3`
`BUNDLES_NJOBS`	int	`3`	Кол-во параллельных задач при работе с bundles; при значении `<= 0` берётся `3`

Sentry

Переменная	Тип	По умолчанию	Назначение
`SENTRY_DSN`	string	—	DSN для отправки ошибок в Sentry
`SENTRY_DEBUG`	bool	`false`	Debug-режим Sentry
`ENVIRONMENT`	string	—	Имя окружения (передаётся в Sentry как environment)

Трейсинг (OpenTelemetry)

Переменная	Тип	По умолчанию	Назначение
`TRACER_USE`	bool	`false`	Включает OpenTelemetry-трейсинг и otel-логгер
`TRACER_HOST`	string	`localhost:4317`	Адрес OTLP-коллектора
`TRACER_USE_INSECURE`	bool	`true`	Небезопасное (без TLS) подключение к коллектору
`SERVICE_NAME`	string	`workspaces`	Имя сервиса в трейсах
`TRACER_LOGGER_NAME`	string	`tracer_logger`	Имя otel-логгера

Дефолты TRACER_* и SERVICE_NAME заданы прямо в тегах default:"..." структуры config.Config; остальные поля дефолтов не имеют (нулевое значение типа).

Инфраструктурные, сборочные и вспомогательные переменные

Не читаются основным кодом приложения (config.Config), но участвуют в запуске/сборке/деплое.

Переменная	Где используется	Назначение
`POSTGRES_EXTERNAL_PORT`	`.env`, `docker-compose.yml`	Внешний порт проброса контейнера Postgres
`API_PORT`	`.env`, `docker-compose.yml` (закомментированный сервис api)	Порт API при локальном запуске в контейнере
`FAKE_API_ADDRESS`	`fake_bundle_api/main.go` (`envconfig`)	Адрес фейкового bundle-API для локальной разработки/тестов; читается отдельной утилитой, не основным сервисом
`GITLAB_CREDENTIALS`	`api.Dockerfile` (build-arg)	Креды `https://<user>:<token>@gitlab.sarex.io` для доступа к приватным Go-модулям при сборке
`CI_COMMIT_SHORT_SHA`	`api.Dockerfile` (build-arg) → `APP_VERSION`	Хэш коммита, прокидываемый в сборку `make api`
`APP_VERSION`	`Makefile` (`make api`)	Версия приложения при сборке (значение — из `CI_COMMIT_SHORT_SHA`)
`NAMESPACE`	`.helm/values.yaml`, `base/*.yaml`, brusnika-оверлеи	Задаётся в манифестах, но кодом приложения не читается
`INTERNAL_PATH`	`.helm/values.yaml`	Задаётся в чарте, но кодом приложения не читается
`DJANGO_HOST`, `DJANGO_ORIGINATOR`	`base/backend-deployment.yaml`, brusnika-оверлеи	Заданы в манифестах, но `config.Config` их не читает (в текущем коде полей Django нет)
`DJANGO_BASIC_AUTH`	`base/backend-deployment.yaml` (Vault), brusnika `secretEnvs`	Инъектируется из секрета, но `config.Config` его не читает

Деплой из этого репозитория (`iac/apps/workspaces`)

Здесь используется kustomize (base/ + оверлеи), а не собственный Helm-чарт сервиса. Секреты БД и Django инъектируются агентом Vault и подгружаются в окружение процесса до старта (set -a; . /vault/secrets/...; exec /api).

`base/`

backend-deployment.yaml (api, namespace workspaces) — обычные переменные заданы инлайн в env: (POSTGRES_POOL_SIZE, BUNDLES_*, API_ADDRESS, NAMESPACE, ENABLE_SQL_QUERY, ENABLE_SSL, DOCUMENTATION_*, ENVIRONMENT, DJANGO_HOST, DJANGO_ORIGINATOR). Vault-шаблоны формируют файл /vault/secrets/workspaces-db с POSTGRES_ADDRESS/PORT/DB/USER/PASSWORD (из secrets/data/postgresql/apps/workspaces) и /vault/secrets/workspaces-django-auth с DJANGO_BASIC_AUTH (из secrets/data/vault/common/django_auth). Контейнер стартует через command: /bin/sh -ec + args, который подгружает эти файлы (set -a; . /vault/secrets/...) и exec /api. Vault-роль — workspaces, ServiceAccount — workspaces-vault. Namespace размечен istio-injection: enabled.
frontend-deployment.yaml (frontend, образ workspaces-v2-frontend) и frontend-service.yaml — статический фронтенд, переменных окружения не имеет.
backend-service.yaml (backend-svc, :80 → 8000), namespace.yaml, serviceaccount.yaml.
kustomization.yaml собирает namespace, serviceaccount, backend/frontend deployments и services (namespace workspaces).

Оверлеи

yc-k8s-test — ../base + postgresql.yaml (Flux HelmRelease postgresql-contour: БД workspaces_db, пользователь workspaces, расширение uuid-ossp, восстановление из дампа, интеграция с Vault). Патч replicas.yaml (replicas: 1 для workspaces-api).
brusnika-stage и brusnika-prod — Flux HelmRelease на universal-chart (0.1.7) для api и фронтенда. Переменные — в envs, секреты — в secretEnvs (postgres-secret → POSTGRES_USER/POSTGRES_PASSWORD, django-auth → DJANGO_BASIC_AUTH). Отличаются значениями POSTGRES_ADDRESS и DOCUMENTATION_HOST (stage: 192.168.2.45 / https://test.sarex.brusnika.tech/documentations; prod: postgres-service / https://cde.brusnika.ru/documentations). Api-под запускает /migrations migrate перед /api в args.

JWT-ключи

RSA-ключи для JWT лежат в .pub_keys/ (prod.rsa.pub, stage.rsa.pub, test.rsa*) и при сборке образа копируются в /etc/sarex/keys (см. api.Dockerfile). Пути к ключам передаются в код работы с токенами как аргументы; отдельной переменной окружения для пути к ключам в текущем коде нет.

Замечания и потенциальные проблемы

Опечатка в .env: переменная названа POSTGRES_POLL_SIZE, тогда как код читает POSTGRES_POOL_SIZE. При локальном запуске из .env размер пула не применится и останется 0.
env-required не используется: отсутствие обязательных значений (БД, documentation) не приводит к ошибке FromEnv() — процесс стартует с пустыми полями и падает позже при обращении к БД/сервисам.
Django-переменные не читаются кодом: DJANGO_HOST, DJANGO_ORIGINATOR, DJANGO_BASIC_AUTH заданы в манифестах iac (base + brusnika-оверлеи), но в config.Config соответствующих полей нет — значения игнорируются приложением.
NAMESPACE и INTERNAL_PATH задаются в манифестах/чарте, но кодом приложения не читаются.
Имя переменной YC-PG-CERTIFICATE содержит дефисы — envconfig сопоставляет её по точному совпадению тега.
Расхождение секретов между источниками деплоя: в .helm/values.yaml secretEnvs.POSTGRES_PORT._default.secretName указан как a-pg-secret (похоже на опечатку от ya-pg-secret); ключи секрета БД различаются между окружениями (workspaces-postgresql-secret с ключами username/ca.crt vs ya-pg-secret/yc-pg-certificate). В kustomize (base/) те же значения приходят из Vault, а не из k8s-секретов.
Порты различаются по окружениям: локально/_default — 8000, в preprod/production Helm-чарта — 8080 (см. API_ADDRESS и probes).

Минимальный набор для локального запуска

Postgres — через docker-compose, api — бинарником (миграции применяются entrypoint.sh/вручную перед стартом):

API_ADDRESS (напр. 0.0.0.0:6666)
POSTGRES_ADDRESS, POSTGRES_PORT, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD
DOCUMENTATION_HOST, DOCUMENTATION_ORIGINATOR
ENVIRONMENT (напр. local)
при необходимости — ENABLE_SQL_QUERY, SENTRY_DSN, ENABLE_SSL (+ YC-PG-CERTIFICATE), TRACER_*

См. пример значений в .env / .env.example.

16 KiB Raw Blame History Unescape Escape