130 lines
9.0 KiB
Markdown
130 lines
9.0 KiB
Markdown
# Конфигурация проекта 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-файла:
|
||
|
||
```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`
|