iac/docs/architecture

Модель архитектуры в нотации ArchiMate

Модель технологического слоя типового контура платформы. Все данные, зависящие от конкретной инсталляции — имя кластера, узлы, домены, реестр — заменены на примеры. Реальные значения в репозиторий не попадают: они задаются профилем контура, который держится отдельно.

Прикладной слой представлен потребителями технологических сервисов и межсервисными вызовами. Бизнес-слой будет добавлен отдельно.

Файлы

Файл	Формат	Чем открывать
example-technology.archimate	нативный формат Archi	десктопный Archi: File → Open
example-technology.xml	The Open Group ArchiMate Model Exchange File Format 3.1	любой инструмент с импортом Open Exchange, в том числе archi-online.com: Import, save, and create models → Open Exchange
preview.html	SVG-рендер всех представлений	любой браузер, без установки чего-либо
matrix.example.json	снимок матрицы «приложение → технологический сервис»	вход для сборки
calls.example.json	снимок графа межсервисных вызовов	вход для сборки

80 элементов, 318 отношений, 23 представления.

Представление	Что показывает
T1	Кластер, ПО внутри него, внешние узлы, технологические сервисы. Без приложений — обзорная схема
T2	Развёртывание по узлам: какая группа узлов какие компоненты несёт
A1	Ядро прикладного слоя: восемь самых связанных сервисов и вызовы между ними
A2–A12	По представлению на сервис с тремя и более потребителями: кто от него зависит
T15–T23	По одному представлению на технологический сервис: кто им пользуется

Направление связи — как принято в ArchiMate: стрелка идёт от вызываемого к вызывающему (serving). Читается как «кого лишишься — тот и сломается».

Разбиение по сервисам сделано осознанно: 148 связей «технологический сервис → приложение» и 86 межсервисных вызовов на одной схеме нечитаемы. В модели они лежат одним набором, представления — это срезы.

Метамодель намеренно урезана. Технологический слой: Node, SystemSoftware, TechnologyService, Artifact. Прикладной: ApplicationComponent. Отношения: Composition, Realization, Serving, Assignment. Не используются Device, Path, CommunicationNetwork, TechnologyFunction — они не несут информации на этом уровне.

Как собрать модель для реального контура

1. Снять с нужного кластера матрицу использования технологических сервисов и граф межсервисных вызовов:

   py scan_contour.py <имя-кластера> matrix.json
   py scan_calls.py   <имя-кластера> calls.json
   

2. Скопировать contour-profile.example.json, подставить настоящие имена кластера, узлов, доменов и реестра. Копию хранить вне репозитория.

3. Собрать модель и производные форматы:

   py build_archimate.py <профиль.json> matrix.json out.archimate calls.json
   py to_open_exchange.py out.archimate out.xml
   py render_preview.py out.archimate out.html
   

   Последний аргумент build_archimate.py необязателен: без него собирается только технологический слой.

Результат шага 3 в репозиторий не коммитить — он содержит данные контура.

Откуда взяты связи

Не нарисованы от руки, а выведены из манифестов, поэтому проверяемы.

Связь	Источник
Состав кластера, версии чартов	clusters/<контур>/kustomization.yaml, infrastructure/<comp>/base/helmrelease.yaml
Приложение → PostgreSQL	env POSTGRES_*, DB__HOST или путь Vault secrets/data/apps/<app>/postgres
Приложение → RabbitMQ	env RABBITMQ*, AMQP__*
Приложение → Kafka	env KAFKA*, BOOTSTRAP_SERVERS
Приложение → S3	env S3__*, S3_ENDPOINT, S3_ACCESS, S3_BUCKET
Приложение → Redis	env REDIS_HOST, REDIS__*
Приложение → Vault	аннотации vault.hashicorp.com/agent-inject*
Приложение → Zitadel	env ZITADEL*, JWKS, OIDC, секрет jwt-public
Приложение → Istio	service: в маршрутах infrastructure/istio-config/<контур>/istio-config.yaml (закомментированные не считаются)
Приложение → приложение	адрес <сервис>.<namespace> в манифестах вызывающего; либо переменная <APP>_URL / _HOST / _BASE_URL / _ENDPOINT

Сканируются *.yaml в apps/<app>/base/ и apps/<app>/<контур>/. Для матрицы технологических сервисов документация *.md служит вторым источником, для графа вызовов — *ENDPOINTS.md и *CONFIGURATION.md.

Две поправки, без которых граф вызовов врёт:

• суффикс контура в namespace. Адреса встречаются в формах documentations, documentations-prod, bim-api; без нормализации связь теряется, а короткая форма <сервис>.<namespace> без .svc.cluster.local не распознаётся вовсе.
• инфраструктурный сегмент в имени переменной. DJANGO_POSTGRES_HOST и ISSUES_DB_HOST адресуют базу данных чужого сервиса, а не сам сервис. Это связь другого рода, и как вызов её показывать нельзя.

matrix.example.json и calls.example.json — снимки. В них только имена приложений и флаги связей; идентификаторов контура нет.

Про формат файлов

Нативный .archimate нигде не стандартизирован, и его словарь неочевиден: объекты схем сериализуются как <child xsi:type="archimate:DiagramObject">, соединения — через атрибут relationship. Имена EClass из метамодели (DiagramModelArchimateObject, archimateRelationship) в XML не используются — на них легко попасться, модель тогда открывается с пустыми представлениями.

Эталон для сверки — любая модель из archimatetool/ArchiModels, созданная самим Archi.

example-technology.xml проверен на соответствие официальной схеме archimate3_Diagram.xsd. Если сторонний инструмент не берёт нативный формат, используйте его. Отличие обменной версии: вложенность узлов развёрнута в плоский список с абсолютными координатами (в обменном формате трактовка координат вложенного узла неоднозначна между реализациями). Визуально раскладка та же, но компоненты внутри кластера не будут его дочерними элементами.

Скрипты

Требуется Python 3, внешних зависимостей нет. На Windows запускать через py, а не python.

Скрипт	Назначение
scan_contour.py	матрица «приложение → технологический сервис» по кластеру
scan_calls.py	граф межсервисных вызовов прикладного слоя
build_archimate.py	сборка модели из профиля и матрицы
to_open_exchange.py	конвертация в обменный формат
render_preview.py	рендер представлений в HTML со встроенным SVG

Внимание: после ручной правки модели в Archi источником истины становится .archimate, а повторный запуск build_archimate.py затрёт расстановку элементов. Производные форматы (to_open_exchange.py, render_preview.py) пересобирать после каждой правки, иначе они разъедутся с моделью.