13 KiB
Конфигурация проекта comparisons-backend
Документ описывает все переменные окружения и способы конфигурирования сервиса comparisons-backend (Go).
Способы конфигурирования
Сервис настраивается только через переменные окружения. Разбор выполняется в config/config.go функцией FromEnv() через библиотеку kelseyhightower/envconfig (структура Config).
Особенности разбора:
- префикса нет —
envconfig.Process("", &cfg)вызывается с пустым префиксом, поэтому имена переменных совпадают с тегамиenvconfig:"..."(напр.POSTGRES_ADDRESS,API_ADDRESS); - вложенности нет — все переменные плоские (без разделителя секций);
- отдельные значения читаются напрямую через
os.Getenvв обход структурыConfig:DOCUMENTATION_FILESTREAM_URL(config/storage.go) иDJANGO_HOST(clients/workflow_cli/pdf2pdf.go).
Отдельного конфиг-файла (yaml/toml) у приложения нет. Приложение не загружает .env автоматически — переменные нужно экспортировать в окружение самому либо задавать через --env/env_file (docker-compose).
Источники переменных по способам запуска:
| Способ запуска | Откуда берутся переменные |
|---|---|
| Локально (бинарник) | Переменные окружения процесса. Собирается через make api (go install ./cmd/api, ./cmd/migrations) |
| Локально (контейнеры) | .docker/.env + .docker/docker-compose.yml (make docker). Postgres поднимается из этого же compose |
| Kubernetes (Helm, репозиторий бэкенда) | .helm/values-<env>.yaml: блок envs (обычные значения) и secrets (значения из k8s-секретов); шаблон .helm/templates/api.yaml |
| Kubernetes (Kustomize, этот репозиторий infra) | apps/comparisons/base + оверлеи; env задаются в base/backend-deployment.yaml и патчах оверлеев. Схема переменных здесь отличается — см. раздел ниже |
| CI/CD (GitLab) | .gitlab-ci.yml: подключает шаблоны generic/common-ci (stage/preprod/prod), job unit-tests (образ golang:1.21) |
Способы запуска процессов (cmd/*):
| Команда | Точка входа | Назначение |
|---|---|---|
api (make api) |
cmd/api/main.go |
HTTP API (gorilla/mux). Перед стартом настраивает Sentry и подключение к Postgres |
migrations |
cmd/migrations/main.go |
Миграции БД (robinjoseph08/go-pg-migrations). Создание: go run ./cmd/migrations/main.go create <name> |
Переменные приложения
Дефолт — означает, что явного значения по умолчанию нет (пустая строка / нулевое значение типа Go). Обязательность отдельных переменных проверяется в рантайме при создании клиентов.
API
| Переменная | Тип | Значение по умолчанию | Назначение |
|---|---|---|---|
API_ADDRESS |
string | — | Адрес и порт прослушивания HTTP-сервера (напр. 0.0.0.0:8080) |
Database (PostgreSQL)
| Переменная | Тип | Значение по умолчанию | Назначение |
|---|---|---|---|
POSTGRES_ADDRESS |
string | — | Хост PostgreSQL |
POSTGRES_PORT |
string | — | Порт PostgreSQL |
POSTGRES_USER |
string | — | Пользователь БД |
POSTGRES_PASSWORD |
string | — | Пароль пользователя БД |
POSTGRES_DB |
string | — | Имя базы данных |
POSTGRES_POOL_SIZE |
int | — | Размер пула соединений (в коде main.go пул жёстко равен 30; переменная читается, но фактически используется значение из кода) |
ENABLE_SSL |
bool | false |
Подключение к БД по TLS. При true используется YC-PG-CERTIFICATE как корневой сертификат, ServerName = POSTGRES_ADDRESS |
DB_CERT_PATH |
string | — | Путь к CA-сертификату PostgreSQL (используется инфраструктурой; в Helm — смонтированный файл) |
YC-PG-CERTIFICATE |
string | — | Содержимое CA-сертификата для TLS-подключения к БД. Имя с дефисами не соответствует остальным (envconfig допускает произвольный тег) |
Внешние сервисы
| Переменная | Тип | Значение по умолчанию | Назначение |
|---|---|---|---|
DOCUMENTATION_URL |
string | — | Внутренний URL сервиса документаций (обязателен для documentation_cli) |
EXTERNAL_DOCUMENTATION_URL |
string | — | Внешний URL сервиса документаций (обязателен для documentation_cli) |
DOCUMENTATION_FILESTREAM_URL |
string | — | URL PDM-хранилища файлов (config/storage.go). Если не задан — сервис стартует, но PDM-хранилище недоступно (лог-warning) |
WORKFLOW_URL |
string | — | Внутренний URL сервиса workflow (обязателен для workflow_cli) |
WORKSPACE_URL |
string | — | Внутренний URL сервиса workspace (обязателен для workspace_cli) |
EXTERNAL_WORKSPACE_URL |
string | — | Внешний URL сервиса workspace |
COMPARISON_URL |
string | — | URL самого сервиса сравнений (обязателен для workflow_cli) |
WORKFLOW_IMAGES_VERSION |
string | — | Версия/тег образов задач workflow (обязателен для workflow_cli) |
BIM_V2_INTERNAL_URL |
string | — | Внутренний URL BIM API v2 |
DJANGO_HOST |
string | — | Хост Django (LK). Передаётся как django_host в параметры задачи pdf2pdf (clients/workflow_cli/pdf2pdf.go) |
Comparisons
| Переменная | Тип | Значение по умолчанию | Назначение |
|---|---|---|---|
ABAP_FIXED_CONC |
uint64 | 0 |
Ограничение параллелизма ABAP-сравнения (0 — без ограничения) |
Sentry и окружение
| Переменная | Тип | Значение по умолчанию | Назначение |
|---|---|---|---|
ENVIRONMENT |
string | — | Окружение развёртывания (stage/preprod/prod); передаётся в Sentry |
SENTRY_DSN |
string | — | DSN Sentry |
SENTRY_DEBUG |
bool | false |
Debug-режим Sentry |
Отладка
| Переменная | Тип | Значение по умолчанию | Назначение |
|---|---|---|---|
ENABLE_SQL_QUERY |
bool | false |
Логировать SQL-запросы (query hook go-pg) |
Дополнительные переменные (не читаются config.Config)
Присутствуют в .docker/.env для локального запуска или используются внешними библиотеками (gotools), но напрямую структурой Config не разбираются:
| Переменная | Где встречается | Назначение |
|---|---|---|
S3_SERVICE_ACCOUNT |
.docker/.env |
Путь к JSON сервисного аккаунта S3 |
DJANGO_ORIGINATOR |
.docker/.env |
Ориджинатор для интеграции с Django |
NAMESPACE |
.docker/.env |
Логическое пространство имён для локального запуска |
API_ADDRESS_FILE |
.helm/values-*.yaml |
Адрес file-варианта API (задан в Helm, кодом не используется) |
Переменные из Helm-чарта (.helm/values-<env>.yaml)
Обычные значения задаются в блоке envs для каждого окружения (stage/preprod/production) и содержат те же переменные приложения, что описаны выше (различаются адресами БД/сервисов, WORKFLOW_IMAGES_VERSION, доменом Django и т.п.).
Значения из секретов (блок secrets, монтируются как env через secretKeyRef):
| Переменная | Секрет (secret_name) |
Ключ (secret_key) |
|---|---|---|
POSTGRES_USER |
ya-pg-secret |
username |
POSTGRES_PASSWORD |
ya-pg-secret |
password |
YC-PG-CERTIFICATE |
yc-pg-certificate |
certificate |
Прочие значения чарта (не переменные приложения): api.* (имя, образ, порт, реплики, ресурсы, ingress api_host/api_host_prefix/api_path/internal_path, permitted_ns), version, imagePullSecrets.
Развёртывание через Kustomize (этот репозиторий, apps/comparisons)
Структура: base (общие манифесты) и оверлеи brusnika-stage, brusnika-prod, yc-k8s-test. Секреты БД и публичный JWT-ключ подтягиваются из HashiCorp Vault (аннотации vault.hashicorp.com/* в base/backend-deployment.yaml), а не из k8s-секретов.
Важно: расхождение схем переменных. Манифест
base/backend-deployment.yamlиспользует другой (более новый) набор имён переменных, чем Go-код изcomparisons-backend(config/config.go): напр.HTTP_PORT,LOGGER_LOG_LEVEL,DATABASE_NAME,DOCUMENTATIONS_INTERNAL_HOST,DOCUMENTATIONS_EXTERNAL_HOST,WORKFLOWS_HOST,WORKFLOWS_DJANGO_HOST,WORKFLOWS_BIMV2_INTERNAL_HOST,WORKSPACES_HOST,EAV_HOST,APP_NAME,AUTH_PUBLIC_KEY,WORKFLOWS_CONFIG_FILEPATHи др., а также/pingв health-проверках и образcomparisons_backend_prod. Такой схемы нет в Go-репозитории. Перед использованием этих файлов стоит убедиться, какой именно образ бэкенда деплоится оверлеем: если это Go-сервис изcomparisons-backend, набор env нужно привести к именам из таблиц выше.
Переменные в CI (.gitlab-ci.yml)
Пайплайн подключает общие шаблоны generic/common-ci и переключает окружение по ветке/тегу:
| Условие | Шаблон | Окружение |
|---|---|---|
ветка stage |
gitlab-ci/comparisons-backend/.gitlab-ci-stage.yml |
stage |
ветка master |
gitlab-ci/comparisons-backend/.gitlab-ci-preprod.yml |
preprod |
тег (CI_COMMIT_TAG) |
gitlab-ci/comparisons-backend/.gitlab-ci-prod.yml |
prod |
Стадии: prebuild-secscan, dependencies-build, unittest, build, state-update, deploy. Job unit-tests (образ golang:1.21) выполняет make unit-tests.
Минимальный набор для локального запуска
Postgres поднимается через .docker/docker-compose.yml (make docker). Минимально необходимо задать:
API_ADDRESSPOSTGRES_ADDRESS,POSTGRES_PORT,POSTGRES_USER,POSTGRES_PASSWORD,POSTGRES_DB,POSTGRES_POOL_SIZE,ENABLE_SSL(0локально)DOCUMENTATION_URL,EXTERNAL_DOCUMENTATION_URL,DOCUMENTATION_FILESTREAM_URLWORKFLOW_URL,WORKSPACE_URL,COMPARISON_URL,WORKFLOW_IMAGES_VERSIONBIM_V2_INTERNAL_URL,DJANGO_HOSTENVIRONMENT; при использовании Sentry —SENTRY_DSN- по желанию:
ENABLE_SQL_QUERY(1для отладки SQL),ABAP_FIXED_CONC
Готовые значения-примеры приведены в .env.example.