iac/apps/ams-sync/CONFIGURATION.md

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

Версия: 1.0.0

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

Что делает сервис

ams-sync — утилита синхронизации пользователей sarex-backend с системой управления доступом (AMS) на базе Zitadel. У сервиса два режима работы:

• run — фоновый демон-потребитель Kafka (src/internal/app/service/sync_service.py, точка входа python3 cmd.py run, это же CMD контейнера). Слушает топик событий пользователей и создаёт/обновляет пользователей в Zitadel. Параллельно поднимает TCP-healthcheck.
• CLI-команды (migrate / sync / diff, реализованы в src/internal/app/console.py) — разовые задачи миграции и синхронизации, запускаются вручную. Читают пользователей и компании напрямую из БД sarex-backend.

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

Сервис настраивается только через переменные окружения. Разбор выполняется библиотекой pydantic-settings. В отличие от монолитного AppSettings, настройки разбиты на несколько независимых классов, каждый со своим префиксом:

Класс	Файл	Префикс
Settings (приложение)	src/internal/app/service/settings.py	(без префикса)
KafkaSettings	src/internal/app/service/settings.py	kafka_
Settings (console)	src/internal/app/console.py	(без префикса)
Settings (logger)	src/internal/adapter/logger/logger.py	log_
Settings (healthcheck)	src/internal/adapter/tcphealthcheck/healthcheck.py	healthcheck_
Settings (auth)	src/internal/adapter/auth/http/adapter.py	auth_
Settings (user server)	src/internal/adapter/users/http/adapter.py	user_server_
Settings (zitadel users)	src/internal/adapter/users/zitadel/adapter.py	zitadel_
Settings (organizations)	src/internal/adapter/organizations/adapter.py	zitadel_
Settings (grants)	src/internal/adapter/grants/adapter.py	zitadel_
Settings (user repo)	src/internal/repository/users/repository.py	user_db_
Settings (company repo)	src/internal/repository/companies/repository.py	user_db_

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

• у каждого класса задан env_file=".env", env_file_encoding="utf-8" и extra="ignore" — при наличии файла .env в рабочей директории он загружается автоматически, лишние переменные игнорируются;
• вложенного разделителя нет — каждая группа настроек читается отдельным классом по своему префиксу (либо без префикса для классов приложения);
• CLI-команды принимают флаг --env-file= (по умолчанию .env), который прокидывается в конструкторы настроек как _env_file; режим run всегда читает .env.

Отдельного конфиг-файла (yaml/toml) у приложения нет.

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

Способ запуска	Откуда берутся переменные
Локально (CLI)	Файл .env (или указанный через --env-file=) в директории с cmd.py и/или переменные окружения процесса
Локально (контейнер)	Dockerfile: CMD ["python3", "cmd.py", "run"]; переменные пробрасываются в окружение контейнера
Kubernetes (Helm)	.helm/values.yaml: блоки universal-chart.envs (обычные значения) и universal-chart.secretEnvs (значения из k8s-секретов). Базовый чарт — universal-chart
CI/CD (GitLab)	.gitlab-ci.yml: переменные пайплайна в workflow.rules (RELEASE_NAME, STAND, CHART_*, IMAGE_NAME, HELM_SET_ARGS и т.п.)

Команды CLI (python3 cmd.py <command>, см. README.md):

Команда	Аргументы	Назначение
run	—	Демон-потребитель Kafka + TCP-healthcheck (режим контейнера)
migrate	--user-id, --with-password/--no-with-password	Миграция пользователя(ей) из БД sarex-backend в Zitadel. Без --user-id мигрируются все (bulk)
sync	--user-id, --company-id	Синхронизация метадаты пользователя(ей) из БД sarex-backend в Zitadel
diff	—	Сравнение множества пользователей БД и Zitadel, отчёт по отсутствующим

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

Дефолт — означает, что значение обязательно (иначе ошибка старта).

App (без префикса)

Класс Settings в src/internal/app/service/settings.py (режим run) и Settings в console.py (CLI).

Переменная	Тип	Значение по умолчанию	Назначение
ENVIRONMENT	enum	LOCAL	Окружение: LOCAL/STAGE/PREPROD/PRODUCTION
AMS_SYNC_TOPIC	string	ams-sync	Имя топика Kafka с событиями пользователей
HOST_ORGANIZATION_ID	string	—	ID организации-хоста в Zitadel (обязателен и в run, и в CLI)
VERIFY_USERS	bool	False	При True события model_created обрабатываются через import_user (с верификацией e-mail), иначе через обычный create

Kafka (KAFKA_*)

Переменная	Тип	Значение по умолчанию	Назначение
KAFKA_BOOTSTRAP_SERVERS	list[str] (JSON)	—	Адреса брокеров, напр. ["host:9091"]
KAFKA_SASL_PLAIN_USERNAME	string	—	Логин SASL
KAFKA_SASL_PLAIN_PASSWORD	string	—	Пароль SASL
KAFKA_SSL_CAFILE	string	—	Путь к CA-сертификату для SSL
KAFKA_SECURITY_PROTOCOL	string	SASL_SSL	Протокол безопасности
KAFKA_SASL_MECHANISM	string	SCRAM-SHA-512	Механизм SASL

Zitadel / AMS (ZITADEL_*)

Префикс используют три класса (адаптеры пользователей, организаций и грантов). Общие поля:

Переменная	Тип	Значение по умолчанию	Назначение
ZITADEL_SERVICE_ACCESS_TOKEN	string	—	Service-токен доступа к API Zitadel (Bearer)
ZITADEL_HOST	string	— (у адаптера пользователей); https://idp.dev.stage.sarex.io (у адаптеров организаций/грантов)	Базовый URL Zitadel
ZITADEL_TIMEOUT	int / string	10 (адаптер пользователей, минуты) / 10m (организации, гранты)	Таймаут. См. замечание о конфликте типов ниже
ZITADEL_MAX_BATCH	int	2000	Максимум пользователей в одной пачке bulk-импорта
ZITADEL_USERS_MANAGEMENT_ENDPOINT	string	management/v1/users	Базовый путь management-API
ZITADEL_USERS_ENDPOINT	string	v2/users	Базовый путь users-API v2

Логирование (LOG_*)

Переменная	Тип	Значение по умолчанию	Назначение
LOG_LEVEL	string	INFO	Уровень логирования
LOG_FORMAT	string	%(asctime)s [%(levelname)s]: %(message)s	Формат строки лога

Логи пишутся в stdout и в файл latest.log в рабочей директории.

TCP Healthcheck (HEALTHCHECK_*)

Только режим run. Поднимает сырой TCP-сокет, отвечающий строкой-ответом на каждое подключение.

Переменная	Тип	Значение по умолчанию	Назначение
HEALTHCHECK_HOST	string	0.0.0.0	Адрес прослушивания
HEALTHCHECK_PORT	int	8008	Порт
HEALTHCHECK_MAX_CONNECTIONS	int	10	Размер очереди подключений (listen)
HEALTHCHECK_REPLY	string	healthy	Строка-ответ на подключение

Auth: sarex-backend (AUTH_*)

Получение JWT под сервисным админом (используется в обоих режимах — адаптер создаётся и в run, и в CLI).

Переменная	Тип	Значение по умолчанию	Назначение
AUTH_HOST	string	—	Базовый URL sarex-backend
AUTH_ADMIN_USERNAME	string	—	Логин админа
AUTH_ADMIN_PASSWORD	string	—	Пароль админа
AUTH_AUTH_ENDPOINT	string	api/token/	Путь получения токена

Sarex user server (USER_SERVER_*) — только CLI

Источник метадаты пользователя при миграции/синхронизации.

Переменная	Тип	Значение по умолчанию	Назначение
USER_SERVER_HOST	string	—	Базовый URL сервиса пользователей sarex-backend
USER_SERVER_USERS_ENDPOINT	string	api/core/admin/users	Базовый путь эндпоинта пользователей

База данных sarex-backend (USER_DB_*) — только CLI

Один префикс на два репозитория (пользователи и компании). Подключение через psycopg2.

Переменная	Тип	Значение по умолчанию	Назначение
USER_DB_NAME	string	—	Имя базы данных
USER_DB_USER	string	—	Пользователь БД
USER_DB_PASSWORD	string	—	Пароль
USER_DB_HOST	string	—	Хост PostgreSQL
USER_DB_PORT	int	—	Порт PostgreSQL
USER_DB_USER_TABLE_NAME	string	base_baseuser	Таблица пользователей
USER_DB_COMPANYUSER_TABLE_NAME	string	core_companyuser	Таблица связи пользователь↔компания
USER_DB_COMPANY_TABLE_NAME	string	core_company	Таблица компаний
USER_DB_ITER_SIZE	int	10000	Размер серверного курсора при итерации

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

Базовый чарт — universal-chart. Обычные значения (universal-chart.envs) задаются на окружение (_default/stage/preprod/production):

Переменная	Значения по окружениям
AMS_SYNC_TOPIC	ams-sync
ENVIRONMENT	STAGE / PREPROD / PRODUCTION
HOST_ORGANIZATION_ID	stage 339439562105337368, preprod 337394329179947547, production 337555824748561429
USER_SERVER_HOST	stage https://stage.sarex.io, preprod https://preprod.sarex.io, production https://.lk.sarex.io
AUTH_HOST	stage https://stage.sarex.io, preprod https://preprod.sarex.io, production https://lk.sarex.io
KAFKA_SECURITY_PROTOCOL	SASL_SSL
KAFKA_SASL_MECHANISM	SCRAM-SHA-512

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

Переменная	Секрет (secretName)	Ключ (secretKey)
ZITADEL_HOST	zitadel-token-secret	zitadel-host
ZITADEL_SERVICE_ACCESS_TOKEN	zitadel-token-secret	zitadel-access-token
KAFKA_BOOTSTRAP_SERVERS	ams-kafka-secret	kafka-bootstrap-servers
KAFKA_SASL_PLAIN_USERNAME	ams-kafka-secret	kafka-username
KAFKA_SASL_PLAIN_PASSWORD	ams-kafka-secret	kafka-password
KAFKA_SSL_CAFILE	ams-kafka-secret	kafka-ca-file
AUTH_ADMIN_USERNAME	auth-secret	admin-username
AUTH_ADMIN_PASSWORD	auth-secret	admin-password
USER_DB_NAME	user-db-secret	user-db-name
USER_DB_USER	user-db-secret	user-db-user
USER_DB_PASSWORD	user-db-secret	user-db-password
USER_DB_HOST	user-db-secret	user-db-host
USER_DB_PORT	user-db-secret	user-db-port

Помимо env, чарт монтирует CA-сертификат Kafka из секрета ya-ca-secret в /etc/ca-certificates/Yandex (volumes/volumeMounts) и раздаёт YandexInternalRootCA.crt через configMap ya-ca-cert. Прочие значения чарта (не переменные приложения): deployment.* (имя, реплики, ресурсы, порт 8008), service.* (ClusterIP, порт 8008), probes.* (TCP-пробы на 8008, по умолчанию выключены), serviceAccount.*, imagePullSecrets.*.

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

Пайплайн подключает общие шаблоны из generic/common-ci и переключает окружение по ветке/тегу через workflow.rules:

Условие	STAND	Namespace
ветка stage	stage	platform (STAGE_NAMESPACE)
ветка master	preprod	ams-sync-preprod
тег (CI_COMMIT_TAG)	prod	ams-sync-prod

Ключевые переменные пайплайна: RELEASE_NAME=ams-sync, CHART_NAME=ams-sync, CHART_VERSION (0.0.1-<stand>), IMAGE_NAME, IMAGE_PATH=universal-chart.image.name, HELM_SET_ARGS, DOCKERFILE_PATH=Dockerfile, флаги ENABLE_LINTER/ENABLE_BUILD_CHART/ENABLE_BUILD_IMAGE/ENABLE_STATE_UPDATE/ENABLE_DEPLOY.

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

• Конфликт ZITADEL_TIMEOUT. Переменную читают три класса с общим префиксом zitadel_, но разного типа: адаптер пользователей ожидает int (минуты, дефолт 10), адаптеры организаций и грантов — str (дефолт 10m). Если задать ZITADEL_TIMEOUT=10m, инициализация адаптера пользователей упадёт на разборе int. Рекомендуется задавать целое число.
• ZITADEL_HOST без дефолта у адаптера пользователей. В users/zitadel/adapter.py поле host обязательно (дефолта нет), тогда как в адаптерах организаций/грантов есть дефолт https://idp.dev.stage.sarex.io. Для режима run переменную нужно задать явно (в Helm приходит из секрета zitadel-token-secret).
• Режим run не использует БД и user-server. Демон-потребитель (sync_service.py) поднимает только logger, healthcheck, auth-провайдер, адаптер Zitadel и Kafka. Переменные USER_DB_* и USER_SERVER_* требуются только CLI-командам (migrate/sync/diff), хотя в Helm они проброшены для запуска этих команд через kubectl exec.
• Приложение загружает .env автоматически (у всех классов задан env_file), в отличие от некоторых других сервисов. CLI дополнительно поддерживает --env-file= для альтернативного файла.
• TLS-проверка отключена. Все исходящие HTTP-запросы (Zitadel, sarex-backend) выполняются с verify=False. Отдельного флага в конфиге нет.
• Zitadel org-ID захардкожены в коде. Помимо HOST_ORGANIZATION_ID, в use-case зашиты glorax_org_id и dogma_org_id, в которые распределяются пользователи по доменам e-mail (см. usecase/migration/usecase.py, usecase/user/usecase.py).

Минимальный набор для режима run (демон)

• ENVIRONMENT, HOST_ORGANIZATION_ID, AMS_SYNC_TOPIC
• KAFKA_BOOTSTRAP_SERVERS, KAFKA_SASL_PLAIN_USERNAME, KAFKA_SASL_PLAIN_PASSWORD, KAFKA_SSL_CAFILE (+ при необходимости KAFKA_SECURITY_PROTOCOL, KAFKA_SASL_MECHANISM)
• ZITADEL_HOST, ZITADEL_SERVICE_ACCESS_TOKEN
• AUTH_HOST, AUTH_ADMIN_USERNAME, AUTH_ADMIN_PASSWORD

Дополнительно для CLI (migrate / sync / diff)

• USER_SERVER_HOST
• USER_DB_NAME, USER_DB_USER, USER_DB_PASSWORD, USER_DB_HOST, USER_DB_PORT