iac/apps/attachments/CONFIGURATION.md

Конфигурация проекта Attachments

Версия: 0.11.1

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

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

Настройка сервиса выполняется только через переменные окружения. Отдельного файла с настройками (yaml/toml) в приложении нет — за конфигурацию отвечает internal/config/settings.py на базе pydantic.BaseSettings.

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

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

Дополнительно секреты доступа к S3 не задаются напрямую, а читаются из JSON-файла (см. YANDEX_S3_ACCOUNT_PATH ниже).

Переменные приложения (класс Settings)

Читаются напрямую по имени (регистрозависимо, case_sensitive = True). Переменные без значения по умолчанию обязательны — без них приложение не стартует.

Переменная	Тип	Обязательна	Значение по умолчанию	Назначение
API	str	нет	/api	Префикс всех HTTP-роутов
NAME	str	нет	Attachments	Имя сервиса (title в FastAPI/OpenAPI)
VERSION	str	нет	0.0.1	Версия сервиса
DESCRIPTION	str	нет	Attachments	Описание сервиса
YANDEX_S3_ENDPOINT_URL	str	да*	—	Endpoint S3 (без схемы; https:///http:// добавляется в коде по YANDEX_S3_USE_SSL)
YANDEX_S3_ACCESS_KEY_ID	str	да*	—	Access Key ID для S3
YANDEX_S3_SECRET_ACCESS_KEY	str	да*	—	Secret Access Key для S3
YANDEX_S3_USE_SSL	bool	нет	True	Использовать ли HTTPS при обращении к S3
YANDEX_S3_REGION	str	нет	ru-central1	Регион S3
YANDEX_S3_VERIFY	bool	да	—	Проверять ли SSL-сертификат S3
BUCKET_NAME	str	да	—	Имя бакета для вложений
DATABASE_NAME	str	да	—	Имя базы данных PostgreSQL
DATABASE_USER	str	да	—	Пользователь БД
DATABASE_PASSWORD	str	да	—	Пароль пользователя БД
DATABASE_HOST	str	да	—	Хост БД
DATABASE_PORT	int	да	—	Порт БД
DATABASE_SSL_MODE	str	да	—	Режим SSL при подключении к БД (напр. disable, require, verify-full)

* Три переменные YANDEX_S3_ENDPOINT_URL, YANDEX_S3_ACCESS_KEY_ID, YANDEX_S3_SECRET_ACCESS_KEY формально обязательны, но при старте приложения они проставляются автоматически функцией json_config_s3_account_settings() из JSON-файла (см. YANDEX_S3_ACCOUNT_PATH). Задавать их вручную не нужно, если задан путь к файлу.

Настройки S3 через JSON-файл

Переменная	Обязательна	Назначение
YANDEX_S3_ACCOUNT_PATH	да	Путь к JSON-файлу с реквизитами сервисного аккаунта S3

При старте функция json_config_s3_account_settings() читает файл по этому пути и выставляет переменные окружения YANDEX_S3_ENDPOINT_URL, YANDEX_S3_ACCESS_KEY_ID, YANDEX_S3_SECRET_ACCESS_KEY.

Ожидаемая структура JSON-файла:

{
  "endpoint": "storage.yandexcloud.net",
  "access_key_id": "<ключ>",
  "secret_access_key": "<секрет>"
}

В Kubernetes файл монтируется из секрета attachments-s3-secret (в prod — yc-s3) в /etc/sarex/yc-s3-storage/yc-s3-service-account.json.

Логирование (класс LoggerSettings, префикс LOG_)

Переменная	Тип	Значение по умолчанию	Назначение
LOG_LEVEL	str	INFO	Уровень логирования (DEBUG, INFO, WARNING, ...). При неизвестном значении откатывается на INFO
LOG_FORMAT	str	JSON-шаблон с полями timestamp, level, message	Формат строк лога (используется pythonjsonlogger)

Трейсинг / OpenTelemetry (класс TraceSettings, префикс TRACING_)

Переменная	Тип	Значение по умолчанию	Назначение
TRACING_USE	bool	False	Включает OTEL-трейсинг, логгер и middleware
TRACING_HOST	str	localhost:4317	Адрес OTLP-коллектора
TRACING_SERVICE_NAME	str	attachments	Имя сервиса в трейсах
TRACING_INSECURE	bool	False	Небезопасное (без TLS) подключение к коллектору

Трейсинг активируется только при TRACING_USE=true.

Переменные инфраструктуры и сборки

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

Переменная	Где используется	Назначение
POSTGRES_PASSWORD	docker-compose.yml (контейнер db)	Пароль суперпользователя PostgreSQL при локальном запуске
PIP_EXTRA_INDEX_URL	docker/Dockerfile (build-arg)	Доп. индекс pip для установки приватных пакетов при сборке образа
GITLAB_PYPI_EXTRA_INDEX_URL	.gitlab-ci.yml	Значение, пробрасываемое в PIP_EXTRA_INDEX_URL при сборке в CI

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

Служебные переменные пайплайна: SERVICE_NAME, DOCKERFILE_PATH, BUILD_ARGS, CI_TRIGGER_SOURCE, а также подставляемые по окружениям STAND, NAMESPACE, RELEASE_NAME, CHART_NAME, CHART_VERSION, K8S_HUSTLER_BRANCH, HELM_SET_ARGS. Окружение выбирается по ветке/тегу: stage → ветка stage, preprod → ветка master, production → git-тег.

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

Обычные переменные (envs):

Переменная	Значение	Примечание
API_ADDRESS	0.0.0.0:8000	Задаётся в чарте, но кодом приложения не читается
POSTGRES_POOL_SIZE	10	Задаётся в чарте, но кодом приложения не читается
DATABASE_SSL_MODE	verify-full
YANDEX_S3_VERIFY	true
YANDEX_S3_ACCOUNT_PATH	/etc/sarex/yc-s3-storage/yc-s3-service-account.json
BUCKET_NAME	attachments-stage-2 / attachments-prod-2	Зависит от окружения

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

Переменная	Ключ секрета	Примечание
DATABASE_PORT	port
DATABASE_HOST	host
DATABASE_USER	username
DATABASE_PASSWORD	password
DATABASE_NAME	database
YC-PG-CERTIFICATE	ca.crt	CA-сертификат PostgreSQL; также монтируется файлом в /root/.postgresql/root.crt

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

Для запуска через docker-compose в файле .env достаточно задать (см. .env.example):

• POSTGRES_PASSWORD — для контейнера БД
• DATABASE_* — параметры подключения к БД
• BUCKET_NAME, YANDEX_S3_VERIFY
• YANDEX_S3_ACCOUNT_PATH или напрямую YANDEX_S3_ENDPOINT_URL + YANDEX_S3_ACCESS_KEY_ID + YANDEX_S3_SECRET_ACCESS_KEY