iac/apps/workspaces/CONFIGURATION.md

Конфигурация проекта workspaces-api

Документ описывает все переменные окружения и способы конфигурирования сервиса.

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

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

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

Способ запуска	Откуда берутся переменные
Локально (docker-compose)	Файл .env в корне (env_file: .env); поднимает только контейнер Postgres, сам API-сервис в compose закомментирован
Локально (бинарник)	Переменные окружения процесса; пример значений — в .env, приватные — в .private.env (см. .private.env.example)
Kubernetes (Helm)	.helm/values.yaml: блок envs (обычные значения) и secretEnvs (значения из k8s-секретов)
CI/CD (GitLab)	.gitlab-ci.yml: переменные пайплайна и build-args для сборки образа

Порядок запуска в контейнере (entrypoint.sh): сначала выполняются миграции (/migrations migrate), затем стартует API (/api).

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

Читаются напрямую по имени. Пустые обязательные значения не приводят к ошибке старта (envconfig не помечает их как required) — но без корректных значений БД/documentation сервис работать не будет.

Переменная	Тип	Значение по умолчанию	Назначение
POSTGRES_ADDRESS	string	—	Хост PostgreSQL
POSTGRES_PORT	string	—	Порт PostgreSQL
POSTGRES_USER	string	—	Пользователь БД
POSTGRES_PASSWORD	string	—	Пароль пользователя БД
POSTGRES_DB	string	—	Имя базы данных
POSTGRES_POOL_SIZE	int	0	Размер пула соединений к БД
API_ADDRESS	string	—	Адрес прослушивания HTTP-сервера (host:port), напр. 0.0.0.0:8000
DOCUMENTATION_HOST	string	—	Базовый URL сервиса документации (documentation service)
DOCUMENTATION_ORIGINATOR	string	—	Идентификатор источника, передаваемый в сервис документации
DOCUMENTATION_LOGGER_FEATURE	bool	false	Включает фичу логирования обращений к сервису документации
SENTRY_DSN	string	—	DSN для отправки ошибок в Sentry
SENTRY_DEBUG	bool	false	Debug-режим Sentry
ENVIRONMENT	string	—	Имя окружения (передаётся в Sentry как environment)
BUNDLES_RETRY_COUNT	int	3	Кол-во ретраев клиента bundles (если задано <= 0, берётся 3)
BUNDLES_NJOBS	int	3	Кол-во параллельных задач при работе с bundles (если <= 0, берётся 3)
ENABLE_SQL_QUERY	bool	false	Логировать SQL-запросы (добавляет query-hook в go-pg)
YC-PG-CERTIFICATE	string	—	Содержимое (PEM) CA-сертификата PostgreSQL; используется при ENABLE_SSL=1
ENABLE_SSL	bool	false	Подключаться к PostgreSQL по TLS с проверкой по YC-PG-CERTIFICATE
TRACER_USE	bool	false	Включает OpenTelemetry-трейсинг и otel-логгер
TRACER_HOST	string	localhost:4317	Адрес OTLP-коллектора
SERVICE_NAME	string	workspaces	Имя сервиса в трейсах
TRACER_USE_INSECURE	bool	true	Небезопасное (без TLS) подключение к коллектору
TRACER_LOGGER_NAME	string	tracer_logger	Имя otel-логгера

Тип bool в envconfig принимает 1/0, true/false, t/f и т.п.

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

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

Переменная	Где используется	Назначение
POSTGRES_EXTERNAL_PORT	docker-compose.yml	Внешний порт проброса контейнера Postgres
API_PORT	.env, docker-compose.yml (закомментированный сервис)	Порт API при локальном запуске в контейнере
FAKE_API_ADDRESS	fake_bundle_api/main.go	Адрес фейкового 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)	Версия приложения при сборке

Переменные из Helm-чарта (.helm/values.yaml)

Обычные переменные (envs) — переопределяют дефолты по окружениям (_default/stage/preprod/production):

Переменная	Значение _default	Примечание
POSTGRES_POOL_SIZE	3
BUNDLES_RETRY_COUNT	5
BUNDLES_NJOBS	5
API_ADDRESS	0.0.0.0:8000	В preprod/production — порт 8080
NAMESPACE	workspaces	Задаётся в чарте, но кодом приложения не читается
ENABLE_SQL_QUERY	0
ENABLE_SSL	1
DOCUMENTATION_HOST	http://documentations-api-svc.documentations:8000	Зависит от окружения
DOCUMENTATION_LOGGER_FEATURE	0
DOCUMENTATION_ORIGINATOR	stage_ws	В prod — prod_ws
SENTRY_DSN	https://…@o279218.ingest.sentry.io/6229949
SENTRY_DEBUG	0
ENVIRONMENT	stage	В prod — prod
TRACER_USE	1
TRACER_HOST	signoz-otel-collector.signoz.svc.cluster.local:4317	Зависит от окружения
SERVICE_NAME	workspaces-api.platform	Зависит от окружения
TRACER_USE_INSECURE	1
INTERNAL_PATH	/internal/	Задаётся в чарте, но кодом приложения не читается

Переменные из секретов (secretEnvs, секрет workspaces-postgresql-secret / ya-pg-secret):

Переменная	Ключ секрета
POSTGRES_USER	username
POSTGRES_PASSWORD	password
YC-PG-CERTIFICATE	ca.crt
POSTGRES_ADDRESS	host
POSTGRES_PORT	port
POSTGRES_DB	database

JWT-ключи

RSA-ключи для JWT лежат в .pub_keys/ и при сборке образа копируются в /etc/sarex/keys (см. api.Dockerfile). Пути к ключам передаются в функции работы с токенами (pkg/gotools/auth/jwt.go) как аргументы, отдельной переменной окружения для пути к ключам в текущем коде нет.

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

• В файле .env переменная названа POSTGRES_POLL_SIZE (опечатка), тогда как код читает POSTGRES_POOL_SIZE. При локальном запуске из .env размер пула не применится и останется 0.
• Имя переменной YC-PG-CERTIFICATE содержит дефисы — envconfig сопоставляет её по точному совпадению тега.
• В .helm/values.yaml у secretEnvs.POSTGRES_PORT значение _default.secretName указано как a-pg-secret (похоже на опечатку, ожидается ya-pg-secret/workspaces-postgresql-secret).
• Переменные NAMESPACE и INTERNAL_PATH задаются в Helm-чарте, но не используются в коде приложения.

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

Для запуска сервиса локально (Postgres — через docker-compose, API — бинарником) нужно задать:

• POSTGRES_ADDRESS, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB
• API_ADDRESS (напр. 0.0.0.0:6666)
• DOCUMENTATION_HOST, DOCUMENTATION_ORIGINATOR
• ENVIRONMENT (напр. local)
• при необходимости — SENTRY_DSN, ENABLE_SQL_QUERY

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