iac/CLAUDE.md

Карта репозитория

Навигационный индекс infra/iac: где что лежит, какие здесь конвенции путей и на чём легко ошибиться. Для быстрого входа новым людям и для агентов (файл автоматически подхватывается Claude Code).

Не дублирует README.md (как пользоваться Flux, как добавить компонент) и IAC-CATALOG.md (подробный каталог всего estate infra/*) — отсылает к ним.

Что это за репозиторий

Только FluxCD v2 (GitOps) + Kustomize-оверлеи + HelmRelease.

Здесь принципиально нет и искать бесполезно:

Что	Где искать
Terraform / Terragrunt	infra/terraform, infra/terraform-contour, infra/terraform-contour-mirror
Ansible	infra/ansible-playbooks, ansible-patroni-cluster, ansible-minio-cluster
Провижининг кластеров	infra/kubespray, infra/k8s-provision
ArgoCD (контур ГПН)	infra/iac-gpn
CI сборки образов	generic/common-ci, generic/base-image
Push-деплой через .helm/ (ветка = контур)	~60 компонентных репозиториев, см. IAC-CATALOG.md §4

Чарты тянутся из oci://cr.yandex/crp3ccidau046kdj8g9q/charts, образы — cr.yandex/crp3ccidau046kdj8g9q/<name>:<tag>. Все приложения ставятся на общий чарт universal-chart; значения обёрнуты в ключ _default и выбираются по global.env.

Дерево

Путь	Что
clusters/	10 точек входа Flux — источник истины «что где раскатано»
infrastructure/	36 платформенных компонентов
apps/	37 прикладных сервисов
docs/apps/	35 mermaid-диаграмм по сервисам + README.md с доменной группировкой
docs/closed-contour-deployment.md	ранбук поднятия закрытого контура
README.md	mermaid-мегакарта платформы, структура репозитория, инструкции по добавлению app / infra / кластера
IAC-CATALOG.md	каталог всего infra/*; §5 — про этот репозиторий
inventory.yaml	сгенерированный снимок прода: 59 namespace → kind → имена

Конвенции путей

Кластер. clusters/<cluster>/kustomization.yaml — плоский список ../../apps/<app>/<cluster>. Инфраструктура подключается двумя разными способами:

• d8-ugmk-prod — прямо в корневом kustomization как ../../infrastructure/<comp>/d8-ugmk-prod;
• brusnika-prod, brusnika-stage, wb — через clusters/<c>/infrastructure/kustomization.yaml, который ссылается на ../../../infrastructure/<comp> (резолвится в base), а различия лежат в clusters/<c>/infrastructure/patches/*.yaml.

Кластеры: brusnika-prod, brusnika-stage, d8-ugmk-prod, wb, yc-cps-prod, yc-ecp, yc-infra-prod, yc-k8s-test, yc-k8s-test-02, contour.

Приложение. apps/<app>/base/ — по одному .yaml на процесс (backend.yaml, celery.yaml, frontend.yaml) плюс namespace.yaml; оверлеи в apps/<app>/<cluster>/. Namespace = имя приложения. Рядом с манифестами лежит документация: CONFIGURATION.md (все env-переменные и откуда берутся), ENDPOINTS.md (исходящие HTTP-вызовы), openapi.yaml (входящий контракт), .env.example. Если процессов несколько — файлы с префиксом процесса: api.ENDPOINTS.md, pdm.CONFIGURATION.md, frontend.CONFIGURATION.md.

Инфра-компонент. infrastructure/<comp>/base/ + оверлеи <comp>/<cluster>/. Корневой infrastructure/<comp>/kustomization.yaml всегда указывает просто на base. Чарты идут с суффиксом контура: vault-contour, keycloak-contour, postgresql-contour и — внимание — idp-contour это Zitadel.

Где искать конкретное

Вопрос	Файл
Что развёрнуто в контуре X	clusters/X/kustomization.yaml (+ clusters/X/infrastructure/kustomization.yaml)
Откуда Flux тянет контур	clusters/X/flux-system/gotk-sync.yaml
Внешние хосты, TLS, path-роутинг	infrastructure/istio-config/<cluster>/istio-config.yaml либо clusters/<c>/infrastructure/patches/istio-config.yaml
Кто кого зовёт (граф сервисов)	apps/*/ENDPOINTS.md + env-переменные с *.svc.cluster.local в apps/**/*.yaml
Что делает сервис, его БД / брокер / S3	docs/apps/<app>.md
Значение env-переменной	apps/<app>/CONFIGURATION.md
Секреты	Vault Agent Injector; путь secrets/data/apps/<app>/postgres, role = имя приложения, SA = <app>-vault
Тег образа в контуре	apps/<app>/<cluster>/*.yaml, поле image.tag
Что реально в проде по namespace	inventory.yaml
Где лежит исходный код приложения	IAC-CATALOG.md §5.3.8

Ловушки

• dsinv/ — оверлей есть у 25 приложений, но clusters/dsinv/ не существует. Это материализованный снимок живого контура WB, а не источник деплоя. Развёрнутым не считать.
• Две несовместимые конвенции оверлеев (IAC-CATALOG.md §5.3.4). d8-ugmk-prod, yc-k8s-test, dsinv наследуют base и патчат его. brusnika-prod, brusnika-stage, yc-ecp — полные копии HelmRelease, которые молча дрейфуют от base. Правка base на них не влияет.
• IAC-CATALOG.md — снимок на 05.08.2026 и по составу приложений на контур уже расходится с реальностью (там у wb ноль приложений, фактически 26 оверлеев). Всегда сверяться с clusters/*/kustomization.yaml.
• Мегадиаграмма в README.md идеализирована — рисована руками, показывает все приложения на одной Postgres и все фронтенды за control-interface. Проверяемые источники — env-переменные и istio-config.
• clusters/contour/ — не кластер, а шаблон: в нём нет flux-system, только apps.yaml, infrastructure.yaml, helm-repositories.yaml.
• Path-роутинг виден в репозитории только у d8-ugmk-prod и yc-ecp. В Brusnika и WB весь прикладной трафик уходит одним правилом в nginx-service.global-ingress / yet-another-nginx-service.global-ingress, а разводка по путям происходит вне репозитория. Через Istio там публикуются только платформенные UI (Gitea, Grafana, OpenObserve, Superset, Vault, Zitadel, Camunda, MinIO).
• Имена namespace расходятся между источниками: inventory.yaml использует суффикс (flows-prod), apps/ — голое имя (flows).
• 17 оверлеев приложений не подключены ни к одному кластеру — мёртвый код.
• Нет диаграмм в docs/apps/ для iam, auth-flow, ams-sync.
• Чистые фронтенды без бэкенда в этом репозитории: auth-flow, control-interface, cross-section, document-link, prescriptions, projects, remarks, reviews, stamp-verification. Бэкенд projects живёт в planning/projects-backend.
• Самые центральные сервисы по числу входящих ссылок: documentations (~85), processing / workflow (~76), django (~53), eav (~47), resources (~44), bim (~39), flows (~38). Менять их конфигурацию — дороже всего.

Поддержка файла

Карта описывает структуру и конвенции, а не текущий состав. Обновлять при появлении нового кластера, смене конвенции оверлеев или когда очередная ловушка перестаёт быть правдой. Списки приложений и версии сюда не дублировать — для этого есть clusters/*/kustomization.yaml и IAC-CATALOG.md.