tf_provider/docs/diagrams

Схема зависимостей облачных сервисов (docs/diagrams)

Папка содержит все артефакты схемы: исходники, отрендеренные изображения и генератор. Здесь же описан процесс создания и результаты сверки с контрактами.

1. Состав папки

Файл	Что это	Чем создаётся
infra_services_flow.mmd	исходник Mermaid-версии схемы	правится вручную
infra_services_flow.svg	вектор Mermaid-версии	рендер через mermaid.ink
infra_services_flow.png	растр Mermaid-версии	рендер через mermaid.ink
render_infra_diagram.py	генератор стилизованной схемы (PNG + SVG)	чистый Python + Pillow
infra_services_diagram.png	стилизованная схема, растр 1600×720 (рендер 2x + LANCZOS)	render_infra_diagram.py
infra_services_diagram.svg	стилизованная схема, вектор	render_infra_diagram.py

Две версии существуют одновременно: Mermaid — для правок текстом и встраивания в Markdown; стилизованная — как готовая картинка для показа.

2. Источник данных

Единственный источник фактов — YAML-контракты сервисов:

generated/dev/resources_yaml/*.yaml

Из них берутся:

• service_id, service_display_name — идентичность сервиса;
• operations[].params[].ref_svc_id — прямая зависимость от другого сервиса;
• operations[].params[].depends_on — зависимость порядка внутри операции;
• value_list, default, man, descr — значения на блоках (CPU, сети и т.п.);
• service_man — чек-листы и порядок действий, заданные самой платформой.

Terraform-файлы DEV_STAND/* не используются как источник для этой схемы — они лишь один из примеров потребления.

3. Как перегенерировать

cd /home/naeel/TF/tf_provider
python3 docs/diagrams/render_infra_diagram.py

Скрипт пишет infra_services_diagram.png и .svg в свою же папку (docs/diagrams/), путь вычисляется от расположения файла.

Требования: python3 с Pillow и шрифты DejaVu (/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf, ...-Bold.ttf). Сторонние библиотеки для SVG не нужны — SVG формируется текстом.

Публикация картинок на сайте

Скрипт TOOLS/scripts/04_build_and_publish_docs.sh копирует только картинки (docs/diagrams/*.svg, *.png) в публикуемый docs_dir → diagrams/: исходники (.mmd, .py) на сайт не попадают. Поэтому картинку можно вставлять в опубликованные страницы относительной ссылкой, например со страницы docs/curated/pipeline/vdc_edge_ip_snat.md:

![Схема зависимостей облачных сервисов](../../diagrams/infra_services_diagram.svg)

Изменения в docs/diagrams/ попадают на сайт только при следующей публикации документации.

Для Mermaid-версии нужен рендерер (mermaid.ink, mmdc или предпросмотр Markdown в VS Code); в этом репозитории использовался mermaid.ink через python3 + urllib.

4. Структура картинки

Пять колонок = этапы создания, слева направо:

1. Тенант — Организация в Cloud Director (19)
2. Пул ресурсов — Виртуальный датацентр (21)
3. Сетевой периметр — Сетевой шлюз периметра / Edge (22)
4. Среда запуска — Каталог ВМ / vApp (26) + Внешние IP (vcOrg modify / 25)
5. Потребители — Виртуальная машина (28) и Kubernetes кластер Штурвал (150)

Обозначения

• Сплошная стрелка — обязательная зависимость, ссылка на UUID существующего инстанса (ref_svc_id).
• Пунктирная стрелка — выделение ресурса, операция modify или предусловие.
• Направление стрелки всегда от зависимости к потребителю: Org → vDC, vApp → VM. То есть стрелка отвечает на вопрос «что должно существовать до».
• Цвет колонки кодирует этап, цвет рамки блока — группу (тенант / ресурсы / сеть / потребители / адреса). Легенда — в правом нижнем углу картинки.

Бейджи точек выделения ресурсов

Бейдж	Где на схеме	Что означает
«здесь выделяются CPU / RAM / Диск»	блок vDC (21)	cpuAllocated, memAllocated, storageConfig
«SNAT настраивается операцией modify»	блок Edge (22)	SNAT — не сервис, а modify у Edge
«здесь выделяются IP»	блок «Внешние IP»	выделение адресов на организации
«требует ALB + VS ≥ 3»	блок Штурвала (150)	обязательное условие из чек-листа

5. Результат сверки с YAML

Проверено построчно (коммит 6791e8f, дополнение — связь vApp → Внешние IP).

Утверждение на схеме	Источник
Организация: типы iaas / saas	19_vc_org.yaml:47-53
Выделение IP через vcOrg modify (vIPConfigure)	19_vc_org.yaml:115
Для внешних IP нужны vDC и Edge	19_vc_org.yaml:112 (man)
vDC: cpuGuaranteed: 0% / 50% / 80%	21_vc_vdc.yaml:71-78
vDC: cpuAllocated, memAllocated, storageConfig	21_vc_vdc.yaml:49,83,93
Edge: AVI Load Balancer	22_vc_nsxt.yaml (needEnableAVI)
Edge: routed-сеть 10.10.102.0/24	22_vc_nsxt.yaml:5
Edge: SNAT настраивается операцией modify	22_vc_nsxt.yaml (modify → ipSpaceName)
vApp → vDC (vdcUid), Edge (nsxtUid)	26_vapp.yaml:38,56
ВМ → vApp (vappUid), vmCpu · vmRam · vmDisk	28_vc_vm_v3.yaml:39,49,59,69
Штурвал: vdcUid, nsxtUid; sizingPolicy · sizingDisk · count	150_k8s_sthutrval_cluster.yaml:41,47,132,141,148
Публичные IP: NAT/DNAT через сервис 25	25_vcexternalip.yaml:41,57,100
Публичные IP требуют «Каталог» (vApp)	25_vcexternalip.yaml:5 (service_man)
Штурвал: обязательны ALB и VS ≥ 3; суммарно 3 внешних адреса	150_k8s_sthutrval_cluster.yaml (service_man, чек-лист)

6. Известные ограничения

1. Переиспользование инстансов («vDC и Edge могут быть переиспользованы») не написано в YAML буквально — это следствие семантики ссылок на UUID существующего инстанса. Уверенность средняя, не высокая.
2. Блок «Внешние IP» объединяет два механизма: выделение адресов на организации (vcOrg modify) и правила NAT у сервиса 25 (vcexternalip). Они подписаны раздельно внутри блока, но нарисованы одной вершиной.
3. Остальные 33 сервиса каталога на схеме не показаны — отрисованы только инфраструктурные цепочки и их прямые потребители.
4. Схема — компоновка по контрактам, а не результат наблюдения за развёртыванием. Фактический порядок и доступность нужно подтверждать отдельно.

7. История

Дата	Изменение
2026-09-26	Создана Mermaid-версия (infra_services_flow.*)
2026-09-26	Исправлена связь «вычислительный пул»: от vDC, а не от внешних IP
2026-09-26	Добавлен генератор стилизованной схемы (render_infra_diagram.py)
2026-09-26	Убрана дублирующая подпись modify: SNAT у блока Edge
2026-09-26	Сверка с YAML; добавлена связь vApp → Внешние IP — предусловие сервиса 25
2026-09-26	Все артефакты перенесены в docs/diagrams/