From 390cf969d666bdbea68f2fd341dea055ea4877b1 Mon Sep 17 00:00:00 2001 From: emelinda Date: Thu, 20 Aug 2026 11:47:19 +0300 Subject: [PATCH] exclude CLAUDE.md from .gitignore --- .gitignore | 1 - CLAUDE.md | 81 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 CLAUDE.md diff --git a/.gitignore b/.gitignore index 92f4b0c..d4cf8ce 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,5 @@ .idea .claude -CLAUDE.md .env tmp diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..6880797 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,81 @@ +# Карта репозитория + +Навигационный индекс `infra/iac`: где что лежит, какие здесь конвенции путей и на чём легко ошибиться. Для быстрого входа новым людям и для агентов (файл автоматически подхватывается Claude Code). + +Не дублирует [README.md](README.md) (как пользоваться Flux, как добавить компонент) и [IAC-CATALOG.md](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/:`. Все приложения ставятся на общий чарт `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//kustomization.yaml` — плоский список `../../apps//`. Инфраструктура подключается двумя разными способами: + +- `d8-ugmk-prod` — прямо в корневом kustomization как `../../infrastructure//d8-ugmk-prod`; +- `brusnika-prod`, `brusnika-stage`, `wb` — через `clusters//infrastructure/kustomization.yaml`, который ссылается на `../../../infrastructure/` (резолвится в `base`), а различия лежат в `clusters//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//base/` — по одному `.yaml` на процесс (`backend.yaml`, `celery.yaml`, `frontend.yaml`) плюс `namespace.yaml`; оверлеи в `apps///`. Namespace = имя приложения. Рядом с манифестами лежит документация: `CONFIGURATION.md` (все env-переменные и откуда берутся), `ENDPOINTS.md` (исходящие HTTP-вызовы), `openapi.yaml` (входящий контракт), `.env.example`. Если процессов несколько — файлы с префиксом процесса: `api.ENDPOINTS.md`, `pdm.CONFIGURATION.md`, `frontend.CONFIGURATION.md`. + +**Инфра-компонент.** `infrastructure//base/` + оверлеи `//`. Корневой `infrastructure//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//istio-config.yaml` либо `clusters//infrastructure/patches/istio-config.yaml` | +| Кто кого зовёт (граф сервисов) | `apps/*/ENDPOINTS.md` + env-переменные с `*.svc.cluster.local` в `apps/**/*.yaml` | +| Что делает сервис, его БД / брокер / S3 | `docs/apps/.md` | +| Значение env-переменной | `apps//CONFIGURATION.md` | +| Секреты | Vault Agent Injector; путь `secrets/data/apps//postgres`, role = имя приложения, SA = `-vault` | +| Тег образа в контуре | `apps///*.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`.