docs: move diagram artifacts to docs/diagrams, add vApp-IP precondition link and creation guide
This commit is contained in:
Repinoid
@@ -0,0 +1,129 @@
|
||||
# Схема зависимостей облачных сервисов (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 формируется текстом.
|
||||
|
||||
Для 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/` |
|
||||
Reference in New Issue
Block a user