1

.github/copilot-instructions.md

@@ -1,17 +1,31 @@
-НИКАКОЙ САМОДЕЙТЕЛЬНОСТИ !!! делать ТОЛЬКО ТО НА ЧТО ПОЛУЧЕНО РАЗРЕШЕНИЕ !!!!
+# Правила работы в этом репозитории
-НИКАКИХ ДОГАДОК !!! ЕСТь сомнения - СПРОСИ !!!
+
-НИКОГДА НЕ ДЕЛАЙ ПРЕДПОЛОЖЕНИЙ !!!
+## Разрешения и самодеятельность
-ВСЕГДА СПРАШИВАЙ, ЕСЛИ НЕ УВЕРЕН !!!
+
-НИКОГДА НЕ ИГНОРИРУЙ ПОЛУЧЕННЫЕ ИНСТРУКЦИИ !!!
+- **Никакой самодеятельности**: делать только то, на что получено разрешение.
-ВСЕГДА ПОДТВЕРЖДАЙ ПОЛУЧЕННЫЕ ИНСТРУКЦИИ !!!
+- Полученные инструкции **не игнорировать**: соблюдать их и подтверждать.
-НИКОГДА НЕ ИЗМЕНЯЙ ИНСТРУКЦИИ БЕЗ РАЗРЕШЕНИЯ !!!
+- Соблюдать порядок и последовательность инструкций.
-ВСЕГДА СОБЛЮДАЙ ПОРЯДОК И ПОСЛЕДОВАТЕЛЬНОСТЬ В ИНСТРУКЦИЯХ !!!
+- Не превышать свои полномочия.
-НИКОГДА НЕ ПРЕВЫШАЙ СВОИ ПОЛНОМОЧИЯ !!!
+- Соблюдать безопасность и конфиденциальность.
-ВСЕГДА СОБЛЮДАЙ БЕЗОПАСНОСТЬ И КОНФИДЕНЦИАЛЬНОСТЬ !!!
+- Не изменять инструкции без разрешения.
-НИКОГДА НЕ ПЕРЕДАВАЙ СЕКРЕТЫ ИНТЕРНЕТУ БЕЗ РАЗРЕШЕНИЯ !!!
+- Не вызывать другие агенты без разрешения.
-НЕ ВЫЗЫВАТЬ ДРУГИЕ АГЕНТЫ БЕЗ РАЗРЕШЕНИЯ !!!
+- Не передавать секреты в интернет без разрешения.
-коммитить после каждой правки, чтобы зафиксировать текущее состояние и избежать потери изменений. Использовать осмысленные сообщения коммитов, отражающие суть изменений.
+
-ВСЕГДА СОХРАНЯТЬ РЕЗЕРВНЫЕ КОПИИ ВАЖНЫХ ФАЙЛОВ ПЕРЕД ВНЕСЕНИЕМ ИЗМЕНЕНИЙ.
+## Сомнения и вопросы
-НИКОГДА НЕ ПОЛАГАЙСЯ НА ПАМЯТЬ — ВСЕГДА ПРОВЕРЯЙ АКТУАЛЬНОСТЬ ИНСТРУКЦИЙ.
+
-ВСЕГДА СОБЛЮДАЙ ИНСТРУКЦИИ, ДАВАЙТЕ ПОДТВЕРЖДЕНИЯ И НЕ ДЕЛАЙТЕ САМОСТОЯТЕЛЬНЫХ ИЗМЕНЕНИЙ.
+- **Никаких догадок**: есть сомнения — спроси.
-Если не на 100% уверен в распоряжениях - СПРОСИ СНОВА И ПОДТВЕРДИ. НЕ ГАДАЙ ЧТО Я ИМЛ ВВИДУ !!!!
+- Никогда не делать предположений и не действовать по догадкам.
+- Всегда спрашивать, если не уверен.
+- Если уверенности в распоряжении нет на 100 % — остановиться, спросить снова и подтвердить, что имел в виду пользователь. Не гадать.
+- Перепроверять всё несколько раз.
+
+## Коммиты и бэкапы
+
+- Коммитить после каждой правки — чтобы зафиксировать текущее состояние и не потерять изменения.
+- Сообщения коммитов — осмысленные, отражающие суть изменений.
+- Всегда сохранять резервные копии важных файлов перед внесением изменений.
+
+## Общий принцип
+
+- Соблюдать инструкции, давать подтверждения и не делать самостоятельных изменений.
+- Не полагаться на память — всегда проверять актуальность инструкций.

TMP/backup_2026-09-28/copilot-instructions.md.bak

@@ -0,0 +1,18 @@
+НИКАКОЙ САМОДЕЙТЕЛЬНОСТИ !!! делать ТОЛЬКО ТО НА ЧТО ПОЛУЧЕНО РАЗРЕШЕНИЕ !!!!
+НИКАКИХ ДОГАДОК !!! ЕСТь сомнения - СПРОСИ !!!
+НИКОГДА НЕ ДЕЛАЙ ПРЕДПОЛОЖЕНИЙ !!!
+ВСЕГДА СПРАШИВАЙ, ЕСЛИ НЕ УВЕРЕН !!!
+НИКОГДА НЕ ИГНОРИРУЙ ПОЛУЧЕННЫЕ ИНСТРУКЦИИ !!!
+ВСЕГДА ПОДТВЕРЖДАЙ ПОЛУЧЕННЫЕ ИНСТРУКЦИИ !!!
+НИКОГДА НЕ ИЗМЕНЯЙ ИНСТРУКЦИИ БЕЗ РАЗРЕШЕНИЯ !!!
+ВСЕГДА СОБЛЮДАЙ ПОРЯДОК И ПОСЛЕДОВАТЕЛЬНОСТЬ В ИНСТРУКЦИЯХ !!!
+НИКОГДА НЕ ПРЕВЫШАЙ СВОИ ПОЛНОМОЧИЯ !!!
+ВСЕГДА СОБЛЮДАЙ БЕЗОПАСНОСТЬ И КОНФИДЕНЦИАЛЬНОСТЬ !!!
+НИКОГДА НЕ ПЕРЕДАВАЙ СЕКРЕТЫ ИНТЕРНЕТУ БЕЗ РАЗРЕШЕНИЯ !!!
+НЕ ВЫЗЫВАТЬ ДРУГИЕ АГЕНТЫ БЕЗ РАЗРЕШЕНИЯ !!!
+коммитить после каждой правки, чтобы зафиксировать текущее состояние и избежать потери изменений. Использовать осмысленные сообщения коммитов, отражающие суть изменений.
+ВСЕГДА СОХРАНЯТЬ РЕЗЕРВНЫЕ КОПИИ ВАЖНЫХ ФАЙЛОВ ПЕРЕД ВНЕСЕНИЕМ ИЗМЕНЕНИЙ.
+НИКОГДА НЕ ПОЛАГАЙСЯ НА ПАМЯТЬ — ВСЕГДА ПРОВЕРЯЙ АКТУАЛЬНОСТЬ ИНСТРУКЦИЙ.
+ВСЕГДА СОБЛЮДАЙ ИНСТРУКЦИИ, ДАВАЙТЕ ПОДТВЕРЖДЕНИЯ И НЕ ДЕЛАЙТЕ САМОСТОЯТЕЛЬНЫХ ИЗМЕНЕНИЙ.
+Если не на 100% уверен в распоряжениях - СПРОСИ СНОВА И ПОДТВЕРДИ. НЕ ГАДАЙ ЧТО Я ИМЛ ВВИДУ !!!!
+ЕСЛИ В ЧЁМ совменваешься - ОСТАНОВИСЬ И СПРОСИ !!!! НИКОГДА не действуй по догадкам и преположенгиям !!! ПЕРЕПРОВЕРЯЙ ВСЁ НЕСКОЛЬКО РАЗ !!!

TOOLS/scripts/04_build_and_publish_docs.sh

@@ -164,6 +164,13 @@ if [[ -n "${MKDOCS_DOCS_DIR:-}" ]]; then
     mkdir -p "${MKDOCS_DOCS_DIR}/curated"
     cp -r "${ROOT_DIR}/docs/curated/"* "${MKDOCS_DOCS_DIR}/curated/" 2>/dev/null || true
   fi
+  # Картинки схемы зависимостей (docs/diagrams/*.svg|png) — чтобы их можно было
+  # показывать на опубликованных страницах. Исходники (.mmd, .py) не копируются.
+  if [[ -d "${ROOT_DIR}/docs/diagrams" ]]; then
+    mkdir -p "${MKDOCS_DOCS_DIR}/diagrams"
+    cp "${ROOT_DIR}/docs/diagrams/"*.svg "${MKDOCS_DOCS_DIR}/diagrams/" 2>/dev/null || true
+    cp "${ROOT_DIR}/docs/diagrams/"*.png "${MKDOCS_DOCS_DIR}/diagrams/" 2>/dev/null || true
+  fi
 fi
 
 # Per-стенд подстановка во все скопированные Markdown-файлы.

docs/30_registry/guides/provider-behavior.md

@@ -24,6 +24,8 @@
 | Виртуальный датацентр (21) | `nubes_vc_vdc` | создаёт vDC с ресурсами (CPU/RAM/Storage) |
 | Сетевой шлюз периметра (22) | `nubes_vc_nsxt` | создаёт Edge (routed-сеть, ALB/AVI) |
 | Сетевой шлюз периметра (22) | `nubes_vc_nsxt_snat` | **модификатор**: включает/переключает SNAT (`ipSpaceName`) на существующем Edge |
+| Виртуальный каталог ВМ (26) | `nubes_vapp` | создаёт vApp (каталог для ВМ) на существующих vDC и Edge |
+| Виртуальная машина (28) | `nubes_vc_vm_v3` | создаёт ВМ внутри vApp (CPU/RAM/диск, образ, SSH-ключ, внешний IP) |
 | Kubernetes кластер Штурвал (150) | `nubes_k8s_sthutrval_cluster` | создаёт кластер (control plane + группы воркеров) |
 
 Общее правило. Ресурс, у которого есть свой «объект в облаке», **создаёт** этот объект. А то, что платформа
@@ -74,7 +76,7 @@
 
 | Флаг | Где применим | Поведение при `destroy` | Предупреждение в выводе |
 |---|---|---|---|
-| `suspend_on_destroy = true` | кластер Штурвала, vDC (по умолчанию `true`) | объект **приостанавливается**, не удаляется | «Ресурс заморожен, а не удалён» |
+| `suspend_on_destroy = true` | кластер Штурвала, vDC, vApp, ВМ (по умолчанию `true`) | объект **приостанавливается**, не удаляется | «Ресурс заморожен, а не удалён» |
 | `keep_on_destroy = true` | Edge, SNAT, квота IP (по умолчанию `false`) | объект **не трогается в облаке**, только убирается из state | «Оставлен как есть» (для SNAT — «SNAT не выключался», для квоты IP — «Аллокация IP не снималась») |
 | оба `false` | любой | обычное удаление | — |
 
@@ -96,7 +98,8 @@ Edge **физически не умеет `suspend`**: в списке дост
   то есть SNAT для виртуальных машин остаётся в прежнем состоянии.
 - Квота внешних IP: уменьшать `count` **ниже фактически занятых адресов платформа не разрешает**
   (ошибка вида «Кол-во занятых Ip … Невозможно выставить параметр count ниже этого параметра»).
-  Адреса держит кластер Штурвала (API + ingress), и `suspend` кластера их **не освобождает**.
+  Адреса держит кластер Штурвала (API + ingress), и `suspend` кластера их **не освобождает**;
+  если у ВМ есть внешний адрес, он тоже держится инстансом ВМ — даже остановленной.
   Поэтому при «заморозке» квота не изменяется вовсе, а реальное освобождение адресов возможно только после
   удаления кластера — отдельным шагом.
 
@@ -109,6 +112,8 @@ Edge **физически не умеет `suspend`**: в списке дост
 |---|---|---|
 | Кластер Штурвала | `suspend` | adopt по имени + `resume` |
 | vDC | `suspend` | adopt по имени + `resume` |
+| vApp | `suspend` | adopt по имени + `resume` |
+| ВМ | `suspend` | adopt по имени + `resume` |
 | Edge | не трогается (`running`) | adopt (инстанс уже работает) |
 | SNAT | не трогается (включён) | повторный `modify` теми же значениями (фактически no-op) |
 | Квота IP | не трогается | `modify` с тем же `count` (no-op) |
@@ -117,7 +122,7 @@ Edge **физически не умеет `suspend`**: в списке дост
 Полностью удалить такой стенд можно только явным отказом от заморозки (`keep_on_destroy = false` /
 `suspend_on_destroy = false`) и в правильном порядке (см. §6).
 
-## 6. Конкретный пайплайн стенда: vDC → Edge → внешние IP → SNAT → Штурвал
+## 6. Конкретный пайплайн стенда: vDC → Edge → внешние IP → SNAT → vApp → ВМ → Штурвал
 
 Порядок создания и зависимости:
 
@@ -125,14 +130,24 @@ Edge **физически не умеет `suspend`**: в списке дост
 2. `nubes_vc_vdc` — виртуальный датацентр.
 3. `nubes_vc_nsxt` — Edge. Обязательно включать балансировщик (параметр `need_enable_avi = true`)
    и задать не меньше 3 виртуальных сервисов (`virtual_services_count >= 3`) — это нужно кластеру Штурвала.
-4. `nubes_vc_org_ip_allocation` — внешние адреса в организации (минимум 3 по инструкции услуги Штурвала).
+4. `nubes_vc_org_ip_allocation` — внешние адреса в организации (минимум 3 по инструкции услуги Штурвала,
+   плюс ещё один, если у ВМ будет внешний адрес).
 5. `nubes_vc_nsxt_snat` — SNAT на Edge (по `depends_on` после аллокации адресов).
-6. `nubes_k8s_sthutrval_cluster` — кластер Штурвала (по `depends_on` после SNAT: нодам нужен выход в интернет).
+6. `nubes_vapp` — vApp: привязка к vDC (`vdc_uid`) и Edge (`nsxt_uid`); создаётся после SNAT,
+   чтобы сеть была уже готова.
+7. `nubes_vc_vm_v3` — ВМ внутри vApp (`vapp_uid`): образ, CPU/RAM/диск, учётка и SSH-ключ, порты FW.
+8. `nubes_k8s_sthutrval_cluster` — кластер Штурвала (по `depends_on` после SNAT: нодам нужен выход в интернет).
 
 При удалении Terraform идёт в обратном порядке. Ограничения платформы, которые встречаются на этом пути:
 
 - **1 кластер Штурвала = 1 vDC** (действующее ограничение услуги).
 - vDC удаляется только **через 14 дней после `suspend`**; при живых Edge/vApp/VM/кластере — через поддержку.
+- У vApp удаление требует **предварительного `suspend`**, полное удаление — тоже через 14 дней.
+- У vApp и ВМ есть `suspend` и `resume`; у Edge операции `suspend` нет вообще.
+- **ВМ не включится, если в vDC не осталось vCPU**: Штурвал при настройках по умолчанию занимает всё
+  (2 ноды × 4 vCPU при `vdc_cpu_allocated = 8`). Платформа отвечает общей ошибкой
+  `[400:VALIDATION] Unable to perform this action` на этапе power-on, инстанс остаётся в `not created`.
+- Создание ВМ идёт дольше остальных ресурсов (customization + power-on) — задавайте `operation_timeout = "15m"`.
 - Edge не удаляется при живых зависимых объектах (по инструкции услуги).
 - Квота IP не опускается ниже занятых адресов (см. §5).
 
@@ -198,7 +213,7 @@ UUID в облаке не имеет «правильного» регистра
 
 ## 10. Куда смотреть дальше
 
-- [Как развернуть vDC, Edge, внешние IP, SNAT и кластер Штурвал](https://tf-docs.nodejsk8s.dev.nubes.ru/nubes-dev/curated/pipeline/vdc_edge_ip_snat/) —
+- [Как развернуть цепочку: vDC → Edge → внешние IP → SNAT → vApp → ВМ → Штурвал](https://tf-docs.nodejsk8s.dev.nubes.ru/nubes-dev/curated/pipeline/vdc_edge_ip_snat/) —
   пошаговая инструкция по всей цепочке вашего стенда.
 - `curated/modifiers/org_ip_and_snat.md` — ресурсы-модификаторы.
 - `30_registry/guides/terraform-structure.md` — структура манифестов.

docs/curated/modifiers/org_ip_and_snat.md

@@ -10,8 +10,8 @@
 
 Оба ресурса проверены живым прогоном: создание, проверка состояния в ЛК и удаление.
 
-Полный рабочий пример (vDC + Edge + IP + SNAT) — на странице
+Полный рабочий пример (vDC + Edge + IP + SNAT + vApp + ВМ + Штурвал) — на странице
-[«Как развернуть vDC, Edge, внешние IP и SNAT»](../pipeline/vdc_edge_ip_snat.md),
+[«Как развернуть цепочку: vDC → Edge → внешние IP → SNAT → vApp → ВМ → Штурвал»](../pipeline/vdc_edge_ip_snat.md),
 файлы — в репозитории `tf_examples`, папка `fullpipe_chain`.
 
 ## `nubes_vc_org_ip_allocation` — внешние IP на организации
@@ -19,7 +19,7 @@
 | Атрибут | Тип | Описание |
 |---|---|---|
 | `organization` | string, обязательный | Организация: название услуги из ЛК или её UUID |
-| `vip_configure` | string (JSON), обязательный | Сколько IP выделить: `[{"name":"internet-ipv4-v1","count":"3"}]`. `count` — строкой |
+| `vip_configure` | string (JSON), обязательный | Сколько IP выделить: `[{"name":"internet-ipv4-v1","count":"3"}]`. `count` — строкой. Для Штурвала нужно не меньше 3 адресов, ещё один — если у ВМ будет внешний адрес |
 | `keep_on_destroy` | bool, по умолчанию `false` | `false` — при удалении квота обнуляется; `true` — остаётся как есть |
 
 ```hcl
@@ -39,7 +39,10 @@ resource "nubes_vc_org_ip_allocation" "this" {
 - массив `vip_configure` записывается **целиком**, поэтому ресурс владеет всей аллокацией организации:
   если нужно поменять количество — меняйте значение и делайте `apply`;
 - снять аллокацию через пустой массив нельзя — для этого удалите ресурс
-  (`terraform destroy -target=nubes_vc_org_ip_allocation.this`), тогда отправится запрос с `count = "0"`.
+  (`terraform destroy -target=nubes_vc_org_ip_allocation.this`), тогда отправится запрос с `count = "0"`;
+- **считайте потребителей адресов**: кластер Штурвал держит 3 адреса (API и Ingress), а ВМ с внешним
+  адресом (`ip_space_name = "internet-ipv4-v1"`) занимает ещё один — итого `count = "4"`.
+  Адреса освобождаются только после удаления потребителя: `suspend` их не снимает.
 
 ## `nubes_vc_nsxt_snat` — SNAT на шлюзе
 

docs/curated/pipeline/vdc_edge_ip_snat.md

@@ -1,4 +1,4 @@
-# Как развернуть vDC, Edge, внешние IP, SNAT и кластер Штурвал
+# Как развернуть цепочку: vDC → Edge → внешние IP → SNAT → vApp → ВМ → Штурвал
 
 Пошаговая инструкция. Готовые файлы примера — в репозитории `tf_examples`, папка `fullpipe_chain`.
 
@@ -8,11 +8,15 @@
 - сетевой шлюз периметра (Edge) с балансировщиком AVI;
 - внешние IP на организации;
 - SNAT на шлюзе;
+- виртуальный каталог (vApp) и виртуальная машина (ВМ) внутри него — с доступом по SSH;
 - Kubernetes-кластер Штурвал (сервис 150) на этой сети.
 
+![Схема зависимостей облачных сервисов](../../diagrams/infra_services_diagram.svg)
+
 **Организацию создайте заранее в ЛК** — Terraform её не создаёт и не удаляет.
 Кластер Штурвал создаётся десятки минут, поэтому провайдер ждёт его до часу
-(`operation_timeout = "60m"`); остальные ресурсы — минуты.
+(`operation_timeout = "60m"`); ВМ тоже создаётся небыстро (у неё отдельный таймаут `15m`),
+остальные ресурсы — минуты.
 
 ## Что нужно перед началом
 
@@ -22,12 +26,15 @@
 | Токен API | доступ к ЛК | ЛК → Профиль → Токены → «Технический» |
 | Организация в Cloud Director | всё создаётся внутри неё | услуга «Организация в Cloud Director» |
 | Edge с балансировщиком AVI | без ALB кластер Штурвал не поднимется | `nsxt_need_enable_avi = true`, `nsxt_virtual_services_count >= 3` |
-| Не меньше 3 внешних IP | адрес Kubernetes API, адрес Ingress и запас | `ip_count = "3"` |
+| Внешние IP: не меньше 3 + 1 под ВМ | адрес Kubernetes API, адрес Ingress, адрес ВМ и запас | `ip_count = "4"` |
-| SNAT на Edge | выход в интернет для машин кластера | ресурс `nubes_vc_nsxt_snat` |
+| SNAT на Edge | выход в интернет для машин кластера и для ВМ | ресурс `nubes_vc_nsxt_snat` |
+| Публичный SSH-ключ | вход на ВМ по SSH | `~/.ssh/id_ed25519.pub` → `vm_user_public_key` |
+| Запас vCPU в vDC | Штурвал занимает 8 vCPU из 8 при настройках по умолчанию, и тогда ВМ не включится | `vdc_cpu_allocated` |
 
 Порядок из чек-листа услуги 150 (именно так связаны ресурсы в примере):
-организация → vDC → Edge (ALB, AVI ≥ 3) → внешние IP (≥ 3) → SNAT → кластер Штурвал.
+организация → vDC → Edge (ALB, AVI ≥ 3) → внешние IP (≥ 3) → SNAT → **vApp → ВМ** → кластер Штурвал.
-Минимум для кластера: 1 мастер-нода и 1 воркер-нода по 4 vCPU / 8 ГБ RAM / 50 ГБ диска.
+Минимум для кластера: 1 мастер-нода и 1 воркер-нода по 4 vCPU / 8 ГБ RAM / 50 ГБ диска;
+минимум для ВМ: 1 vCPU / 1 ГБ RAM (в примере — 2 vCPU / 2 ГБ).
 
 ## 1. Скачайте пример
 
@@ -67,13 +74,13 @@ organization = "organ"
 
 # Внешние IP
 ip_space_name = "internet-ipv4-v1"
-ip_count      = "3"
+ip_count      = "4"                        # 3 под Штурвал + 1 под ВМ
 
 # vDC
 vdc_resource_name    = "fullpipe-vdc"          # имя услуги в ЛК, любое
 vdc_network_provider = "snb1"                  # ЛК → создание vDC → «Сетевой провайдер»
 vdc_provider_vdc     = "Intel Broadwell 2.4"   # ЛК → создание vDC → «Provider VDC»
-vdc_cpu_allocated    = 8                       # vCPU, шт.
+vdc_cpu_allocated    = 12                      # 8 под Штурвал + 2 под ВМ + 2 запаса
 vdc_cpu_guaranteed   = 0                       # резервирование vCPU, %: 0, 50 или 80
 vdc_mem_allocated    = 32                      # RAM, ГБ
 vdc_storage_config   = "[{\"name\":\"SATA\",\"size\":\"200\"}]"   # политика и размер, ГБ
@@ -86,6 +93,17 @@ nsxt_virtual_services_count = 3                # виртуальных серв
 nsxt_ip_addr_pool           = "10.10.102.0/24" # пул адресов routed-сети, маска /24
 nsxt_main_dns               = "81.22.46.22"    # основной DNS
 nsxt_second_dns             = "185.247.187.77" # второй DNS
+
+# vApp и ВМ
+vapp_name          = "fullpipe-vapp-01"    # имя vApp: маска ^[a-z0-9][a-z0-9.-]{3,61}[a-z0-9]$, уникально в организации
+vm_name            = "web01"              # имя ВМ: задаёт имя IP Set {vapp_name}-{vm_name}
+vm_image           = "Ubuntu_22-20G"      # RockyLinux_9-16G-cloudinit | Ubuntu_22-20G | Debian_13-20G
+vm_cpu             = 2                    # vCPU, 1..64
+vm_ram             = 2                    # RAM, ГБ, 1..256
+vm_disk            = 20                   # дополнительный диск, ГБ
+vm_user_login      = "ubuntu"             # учётка SSH
+vm_user_public_key = "ssh-ed25519 AAAA..." # содержимое ~/.ssh/id_ed25519.pub
+vm_same_snat       = false                # false — за общим SNAT шлюза
 ```
 
 Описание всех параметров — в `variables.tf`. `terraform.tfvars` с токеном никому не передавайте
@@ -95,7 +113,7 @@ nsxt_second_dns             = "185.247.187.77" # второй DNS
 
 ```bash
 terraform init     # один раз — скачает провайдер
-terraform plan     # покажет, что будет создано: 5 ресурсов
+terraform plan     # покажет, что будет создано: 7 ресурсов (vDC, Edge, IP, SNAT, vApp, ВМ, Штурвал)
 terraform apply    # создаст (подтвердить: yes)
 ```
 
@@ -105,14 +123,73 @@ terraform apply    # создаст (подтвердить: yes)
 terraform output   # UUID и имена созданных услуг
 ```
 
-И в ЛК: появились vDC, Edge и кластер Штурвал, на организации выделены внешние IP,
+И в ЛК: появились vDC, Edge, vApp с ВМ и кластер Штурвал, на организации выделены внешние IP,
 на шлюзе включён SNAT. Повторный `terraform plan` должен показать `No changes`.
 
+Адрес ВМ виден в `terraform output vm_state_flat` — поля `externalConnect` (внешний IP),
+`internalConnect` (адрес в routed-сети) и `fqdn`: `ssh <vm_user_login>@<externalConnect>`.
+
 Кластер создаётся десятки минут — провайдер ждёт его (`operation_timeout = "60m"`),
 в ЛК он появится со статусом `running`. Адреса Kubernetes API и Ingress — в
 `terraform output shturval_state_params` (поля `kubernetesApiAddress` и `ingressAddress`).
 
-## 6. Удаление: «заморозка» вместо удаления
+## 6. vApp и ВМ
+
+Виртуальная машина живёт **внутри vApp**: vApp привязывается к vDC (`vdc_uid`) и к Edge (`nsxt_uid`),
+а ВМ — к vApp (`vapp_uid`) и получает адрес в routed-сети шлюза. Своей сети у vApp нет.
+
+| Ресурс | Услуга | Ключевые параметры |
+|---|---|---|
+| `nubes_vapp` | 26 | `vapp_name` (уникальное в организации, маска DNS-имени), `vdc_uid`, `nsxt_uid` |
+| `nubes_vc_vm_v3` | 28 | `vapp_uid`, `vm_name`, `vm_cpu`, `vm_ram`, `vm_disk`, `image_vm`, `user_login`, `user_public_key`, `ip_space_name`, `access_port_list` |
+
+### Параметры ВМ
+
+| Параметр | Значения |
+|---|---|
+| `image_vm` | `RockyLinux_9-16G-cloudinit`, `Ubuntu_22-20G`, `Debian_13-20G` |
+| `vm_cpu` / `vm_ram` | 1..64 шт. / 1..256 ГБ |
+| `vm_disk` | дополнительный диск, ГБ (основной диск зависит от образа) |
+| `user_login` | учётка SSH (по умолчанию `myuser`) |
+| `access_port_list` | `[{ "port": "22", "type": "tcp" }]`; `type` — `tcp`, `udp` или `all` |
+| `access_ip_list` | белый список адресов; по умолчанию `["0.0.0.0/0"]` |
+
+`image_vm`, `vm_name`, `user_login`, `user_public_key` и `vapp_uid` — **create-only** (менять нельзя).
+`vm_cpu`, `vm_ram`, `vm_disk`, `access_port_list`, `ip_space_name` меняются операцией `modify`.
+
+### Внешний доступ
+
+| `ip_space_name` | Что это значит |
+|---|---|
+| `internet-ipv4-v1` | у ВМ есть внешний адрес: в `vm_state_flat` появятся `externalConnect` и `fqdn` |
+| `no-needed` | внешнего адреса нет, доступ только изнутри |
+
+Адрес берётся из квоты организации, поэтому при внешнем доступе нужен **4-й адрес** (`ip_count = "4"`).
+При `same_snat = false` (по умолчанию) ВМ публикуется за общим SNAT шлюза.
+
+Пример результата на живом стенде:
+
+```
+vm_state_flat = {
+  "externalConnect" = "185.247.187.235"
+  "internalConnect" = "10.10.102.4"
+  "fqdn"            = "web01.85ea682f-...dev.nubes.ru"
+}
+```
+
+### Что проверять при создании ВМ
+
+1. **Запас vCPU в vDC.** Штурвал при настройках по умолчанию занимает 8 vCPU из 8 (2 ноды × «TKG 4CPU 8RAM»).
+   Тогда ВМ не включится: платформа отдаёт `[400:VALIDATION] Unable to perform this action` на этапе
+   power-on, а инстанс остаётся в статусе `not created`. Лечится увеличением `vdc_cpu_allocated`.
+2. **Квота IP.** `ip_count ≥ 4`, иначе внешний адрес для ВМ не выделится.
+3. **Ключ.** Публичный ключ кладите в `terraform.tfvars`, не в репозиторий.
+4. **Время.** ВМ создаётся и включается с customization (запись учётки и ключа) — на живом стенде
+   операция шла больше 15 минут. В примере стоит `operation_timeout = "15m"`; при медленной платформе
+   увеличьте его. Симптом таймаута — «операция … не завершилась за установленный таймаут».
+5. **Проверка.** `ssh <vm_user_login>@<externalConnect>` и `terraform plan` → `No changes`.
+
+## 7. Удаление: «заморозка» вместо удаления
 
 ```bash
 terraform destroy
@@ -127,15 +204,18 @@ terraform destroy
 | Edge | не трогается: у эджа нет операции `suspend` | `keep_on_destroy = true` |
 | SNAT | не выключается | `keep_on_destroy = true` |
 | Квота внешних IP | не меняется: адреса держит кластер Штурвала | `keep_on_destroy = true` |
+| vApp | `suspend`: выключаются все ВМ внутри каталога | `suspend_on_destroy = true` |
+| ВМ | `suspend` | `suspend_on_destroy = true` |
 
 Приоритет флагов: `keep_on_destroy` важнее `suspend_on_destroy`. Следующий `apply`
 усыновит объекты по имени и разморозит кластер и vDC
 (`adopt_existing_on_create = true` → `resume`). **Организация не удаляется никогда.**
 
 Полное удаление — осознанно: поставьте `keep_on_destroy = false` и
-`suspend_on_destroy = false` и удаляйте по порядку: кластер → квота IP (`count = 0`) →
+`suspend_on_destroy = false` и удаляйте по порядку: кластер → ВМ → vApp → квота IP (`count = 0`) →
 SNAT → Edge → vDC. Квоту нельзя опустить ниже занятых адресов, поэтому — только
-после удаления кластера; vDC удаляется лишь через 14 дней после `suspend`.
+после удаления кластера и ВМ; vApp удаляется лишь после `suspend` (полное удаление — через 14 дней),
+а vDC — через 14 дней после `suspend`.
 
 ## Файлы примера
 
@@ -147,8 +227,9 @@ SNAT → Edge → vDC. Квоту нельзя опустить ниже зан
 | `vdc.tf` | виртуальный датацентр |
 | `edge.tf` | сетевой шлюз периметра (Edge) |
 | `modifiers.tf` | внешние IP на организации + SNAT на шлюзе |
+| `vm.tf` | vApp и ВМ: переменные vApp/ВМ, оба ресурса и выводы (отключается удалением файла) |
 | `shturval.tf` | Kubernetes-кластер Штурвал: переменные Штурвала, группы воркеров и сам ресурс |
-| `outputs.tf` | UUID и имена созданных услуг (vDC, Edge, Штурвал) |
+| `outputs.tf` | UUID и имена созданных услуг (vDC, Edge, vApp, ВМ, Штурвал) |
 | `terraform.tfvars.example` | шаблон значений (копируется в `terraform.tfvars`) |
 
 Подробнее про два последних ресурса — на странице

docs/diagrams/README.md

@@ -50,6 +50,19 @@ python3 docs/diagrams/render_infra_diagram.py
 (`/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`.

mkdocs.yml

@@ -61,5 +61,5 @@ nav:
     - Глоссарий: 30_registry/guides/glossary.md
   - Проверенные примеры:
     - PostgreSQL: curated/postgres/pg_user_db.md
-    - Пайплайн vDC → Edge → IP → SNAT → Штурвал: curated/pipeline/vdc_edge_ip_snat.md
+    - Пайплайн vDC → Edge → IP → SNAT → vApp → ВМ → Штурвал: curated/pipeline/vdc_edge_ip_snat.md
     - Ресурсы-модификаторы (IP организации, SNAT): curated/modifiers/org_ip_and_snat.md