# Схема зависимостей облачных сервисов (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. Как перегенерировать

```bash
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`:

```markdown
![Схема зависимостей облачных сервисов](../../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/` |