iac/apps/drawings/CONFIGURATION.md

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

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

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

Сервис написан на Go (gitlab.com/sarex-team/rnd/drawings-api) и настраивается только через переменные окружения. Разбор выполняется в config/config.go через библиотеку kelseyhightower/envconfig (envconfig.Process("", &Config)).

Особенности разбора:

• префикса нет — переменные читаются по именам из тега envconfig:"..." (напр. POSTGRES_ADDRESS, API_ADDRESS);
• вложенных секций через разделитель нет: Config — плоская композиция трёх структур (Postgres, API, Workflow), у каждого поля своё явное имя переменной;
• часть полей имеет дефолт через тег default:"..." (напр. CONTAINER_REGISTRY, TASK_VERSION); поля без дефолта при отсутствии переменной получают нулевое значение типа (пустая строка / 0 / false), ошибки старта из-за «обязательности» нет;
• при ошибке разбора (envconfig.Process) приложение завершается с logger.Fatalf (config.MustParse).

Отдельного конфиг-файла (yaml/toml) у приложения нет. Файл .env в репозитории — только шаблон; приложение его не загружает автоматически (в коде нет чтения .env/dotenv), переменные нужно экспортировать в окружение самому.

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

Способ запуска	Откуда берутся переменные
Локально (бинарник)	Переменные окружения процесса. .env — шаблон, экспортируется вручную, напр. set -a && . ./.env && set +a. Сборка — make drawings-api / make migrations
Локально (контейнер)	Dockerfile (multi-stage, golang:1.22) + entrypoint.sh. Переменные пробрасываются через --env/--env-file при запуске контейнера
Kubernetes (Helm)	.helm/values.yaml: блоки envs (обычные значения) и secretEnvs (значения из k8s-секретов) чарта universal-chart
CI/CD (GitLab)	.gitlab-ci.yml: общие шаблоны generic/common-ci (universal-pipeline.yaml, ref apps-business) и выбор окружения по ветке/тегу через workflow.rules

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

Точки входа (cmd/):

Команда	Точка входа	Назначение
drawings-api	cmd/drawings-api	HTTP API-сервер (gorilla/mux)
migrations migrate	cmd/migrations	Применение миграций БД (robinjoseph08/go-pg-migrations)

Переменные приложения

Все переменные ниже читаются кодом приложения (config/config.go). В столбце «Значение по умолчанию» указан дефолт из тега default:"..."; — означает, что дефолта нет (при отсутствии переменной поле получает нулевое значение типа).

API (API)

Переменная	Тип	Значение по умолчанию	Назначение
API_ADDRESS	string	—	Адрес прослушивания HTTP-сервера, напр. 0.0.0.0:8080

Postgres (Postgres)

Переменная	Тип	Значение по умолчанию	Назначение
POSTGRES_USER	string	—	Пользователь БД
POSTGRES_PASSWORD	string	—	Пароль пользователя БД
POSTGRES_DB	string	—	Имя базы данных
POSTGRES_ADDRESS	string	—	Адрес PostgreSQL в формате host:port
POSTGRES_POOL_SIZE	int	—	Размер пула соединений (pg.Options.PoolSize)
ENABLE_SSL	bool	—	Подключение к БД по TLS. При true строится tls.Config из YC-PG-CERTIFICATE
YC-PG-CERTIFICATE	string	—	PEM-содержимое CA-сертификата PostgreSQL (не путь к файлу). Используется только при ENABLE_SSL=true

При ENABLE_SSL=true из содержимого YC-PG-CERTIFICATE собирается пул корневых сертификатов; ServerName берётся из хостовой части POSTGRES_ADDRESS, при этом в коде выставлен InsecureSkipVerify: true. Имя переменной YC-PG-CERTIFICATE содержит дефисы (нестандартно для env), но именно так указано в теге envconfig.

Workflow (Workflow)

Интеграция с сервисом workflows через gitlab.com/sarex-team/sdk-go/pkg/workflows: создание workflow экспорта cross-section в DWG (задача парсинга + задача webhook-уведомления).

Переменная	Тип	Значение по умолчанию	Назначение
WORKFLOW_HOST	string	—	Базовый URL сервиса workflows
CONTAINER_REGISTRY	string	cr.yandex/crp3ccidau046kdj8g9q	Реестр образов для задач workflow
IMAGE_NAME_EXPORT_TO_DWG	string	—	Имя образа задачи экспорта cross-section в DWG
IMAGE_TAG	string	—	Тег образов задач workflow
TASK_VERSION	string	1	Версия задачи экспорта (параметр version)
DRAWING_INTERNAL_URL	string	—	Внутренний URL самого drawings-api; на него workflow вызывает webhook POST {DRAWING_INTERNAL_URL}internal/v1/exports/{export_id}/webhook
ATTACHMENT_URL	string	—	URL сервиса attachments (передаётся в задачу экспорта как attachment_url)

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

Деплой выполняется через universal-chart (Chart.yaml, зависимость universal-chart). Сервис drawings-api слушает порт 8080; probes настроены на /ping (в чарте выключены). Обычные значения задаются в блоке envs, значения из секретов — в secretEnvs. Значения различаются по окружениям через ключи _default / stage / preprod / production.

Обычные значения (envs) — те же переменные приложения, что описаны выше (API_ADDRESS, ENABLE_SSL, WORKFLOW_HOST, CONTAINER_REGISTRY, IMAGE_NAME_EXPORT_TO_DWG, IMAGE_TAG, TASK_VERSION, DRAWING_INTERNAL_URL, ATTACHMENT_URL), различаются адресами сервисов, тегами образов и флагом ENABLE_SSL по окружениям.

Значения из секретов (secretEnvs, монтируются как env через secretKeyRef):

Переменная	Секрет (_default)	Секрет (stage)	Ключ
POSTGRES_USER	ya-pg-secret	drawings-postgresql-secret	username
POSTGRES_PASSWORD	ya-pg-secret	drawings-postgresql-secret	password
POSTGRES_DB	ya-pg-secret	drawings-postgresql-secret	database
POSTGRES_POOL_SIZE	ya-pg-secret	drawings-postgresql-secret	pool-size
POSTGRES_ADDRESS	ya-pg-secret	drawings-postgresql-secret	address
YC-PG-CERTIFICATE	yc-pg-certificate	drawings-postgresql-secret	ca.crt

Переменные в CI (.gitlab-ci.yml)

Пайплайн подключает общие шаблоны из generic/common-ci (common-security-scan.yaml, universal-pipeline.yaml ref apps-business) и переключает окружение по ветке/тегу через workflow.rules:

Условие	STAND	NAMESPACE	CHART_VERSION	K8S_HUSTLER_BRANCH
ветка stage	stage	aero	0.0.1-stage	universal-chart-stage
ветка master	preprod	drawings-preprod	0.0.1-preprod	universal-chart-preprod
тег (CI_COMMIT_TAG)	production	drawings-prod	0.0.1-prod	universal-chart-production
merge request	—	—	—	сборка образа отключена (ENABLE_BUILD_IMAGE=false)

Ключевые переменные пайплайна: SERVICE_NAME=drawings-api, DOCKERFILE_PATH=./Dockerfile, RELEASE_NAME=drawings-api, CHART_NAME=${SERVICE_NAME}, BUILD_ARGS (--build-arg CI_COMMIT_SHORT_SHA=…), HELM_SET_ARGS (--set universal-chart.services.drawings-api.image.name.<env>=…, --set universal-chart.global.env=<env>, а также commitSha/gitlabUri/gitlabJobUrl/owner).

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

• Нет обязательности полей. В отличие от pydantic-конфигов других сервисов, envconfig не помечает поля обязательными — при отсутствии переменной поле молча получает нулевое значение. Например, пустой POSTGRES_ADDRESS не вызовет ошибку старта конфига, но приведёт к ошибке при подключении к БД.
• Имя YC-PG-CERTIFICATE с дефисами нестандартно для переменных окружения, но именно так задано в теге envconfig и в Helm-секрете. В отличие от других сервисов, здесь это содержимое сертификата (PEM), а не путь к файлу.
• TLS к БД с InsecureSkipVerify: true. При ENABLE_SSL=true корневой сертификат подхватывается, но проверка имени/цепочки фактически ослаблена флагом InsecureSkipVerify.
• Webhook-петля. DRAWING_INTERNAL_URL должен указывать на сам drawings-api внутри кластера — по нему workflow дергает POST internal/v1/exports/{export_id}/webhook для перевода экспорта в статус done. Неверный URL оставит экспорты в статусе running.
• .env не загружается автоматически — переменные нужно экспортировать вручную либо задавать через окружение контейнера.

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

Минимально необходимо задать:

• API_ADDRESS (напр. localhost:6666)
• POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, POSTGRES_ADDRESS, POSTGRES_POOL_SIZE, ENABLE_SSL (false локально; тогда YC-PG-CERTIFICATE не нужен)
• WORKFLOW_HOST, IMAGE_NAME_EXPORT_TO_DWG, IMAGE_TAG, DRAWING_INTERNAL_URL, ATTACHMENT_URL (для сценариев экспорта; CONTAINER_REGISTRY и TASK_VERSION имеют дефолты)

Готовые значения-примеры приведены в .env.example.