docs(curated): страница «vDC → Edge → IP → SNAT → Штурвал» (требования, заморозка, проверка результата) + nav + HISTORY

HISTORY/2026-09-25_fullpipe_example_shturval_and_docs.md

@@ -0,0 +1,43 @@
+# 2026-09-25 — Штурвал в примере `fullpipe_chain` + страница документации
+
+## Что сделано
+
+Примеры (`tf_examples`, отдельный репозиторий `https://gitea.services.ngcloud.ru/Nail/tf_examples.git`)
+и страница документации приведены к рабочей конфигурации стенда `DEV_STAND/FullPipe`
+(аккаунт `tazet@narod.ru`) — теперь цепочка полная: **vDC → Edge → внешние IP → SNAT → Штурвал**.
+
+| Файл | Изменение |
+|---|---|
+| `tf_examples/fullpipe_chain/shturval.tf` | **новый**: все настройки Штурвала в одном файле (переменные + `locals` + ресурс `nubes_k8s_sthutrval_cluster`), как в рабочем стенде |
+| `tf_examples/fullpipe_chain/versions.tf` | провайдер `2.0.21` → `2.0.23` (последняя dev) |
+| `tf_examples/fullpipe_chain/edge.tf` | `keep_on_destroy = true`, `adopt_existing_on_create = true` |
+| `tf_examples/fullpipe_chain/modifiers.tf` | `keep_on_destroy = true` у квоты IP и SNAT (было `false`) |
+| `tf_examples/fullpipe_chain/outputs.tf` | выводы Штурвала: `shturval_id`, `shturval_name`, `shturval_state_params` |
+| `tf_examples/fullpipe_chain/terraform.tfvars.example` | блок параметров Штурвала (закомментированные значения = рабочие default) |
+| `tf_examples/fullpipe_chain/README.md`, `tf_examples/README.md` | цепочка со Штурвалом, 5 ресурсов, требования, таблица «заморозки», состав файлов |
+| `docs/curated/pipeline/vdc_edge_ip_snat.md` | переписан: требования, чек-лист услуги 150 (ALB + AVI ≥ 3, IP ≥ 3), проверка результата (адреса API/Ingress), «заморозка» при destroy, полное удаление |
+| `mkdocs.yml` | заголовок в nav: «Пайплайн vDC → Edge → IP → SNAT → Штурвал» |
+
+## Проверки
+
+- `terraform init` + `terraform validate` + `terraform fmt -check` на копии примера в `/tmp` — без ошибок.
+- `terraform plan` (копия в `/tmp`, организация `kontra`, токен `secrets/dev.token`) — `5 to add, 0 change, 0 destroy`, ошибок нет.
+- Копия для проверки делалась в `/tmp`, **не** в `tf_examples/`: там нет `.gitignore` для `.terraform/`, и служебные файлы уехали бы в публичный репозиторий.
+
+## Факты и правила, подтверждённые по ходу
+
+- Все настройки Штурвала держим **в одном файле** `shturval.tf` (переменные + ресурс): чтобы выключить Штурвал — удалить файл.
+- Порядок из чек-листа услуги 150: организация (вручную в ЛК) → vDC → Edge (ALB, AVI VS ≥ 3) →
+  внешние IP (≥ 3) → SNAT → кластер. Минимум ноды: 1 + 1 по 4 vCPU / 8 ГБ / 50 ГБ.
+- `worker_configuration` — JSON-строка с **camelCase**-ключами (`groupName`…): snake_case валит платформу
+  («Cannot invoke method size.split() on null object»).
+- «Заморозка»: `keep_on_destroy` важнее `suspend_on_destroy`; у Edge операции `suspend` нет вообще.
+- Публикация доков: `TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/dev <версия>`
+  (версию надо передавать аргументом — в `profile.env` она отстаёт);
+  сборка локальным mkdocs (docker на этой машине недоступен).
+
+## Ошибка в работе (зафиксировано)
+
+При первой проверке стенда я вывел в терминал содержимое `DEV_STAND/FullPipe/terraform.tfvars` —
+файл содержит живой `api_token`. В git файл не попадает (`*.tfvars` в `.gitignore`), но токен оказался
+в логе вывода. Правило: секреты из `.tfvars` не печатать, сравнивать по хешу/маскировать.

docs/curated/pipeline/vdc_edge_ip_snat.md

@@ -1,17 +1,33 @@
-# Как развернуть vDC, Edge, внешние IP и SNAT
+# Как развернуть vDC, Edge, внешние IP, SNAT и кластер Штурвал
 
 Пошаговая инструкция. Готовые файлы примера — в репозитории `tf_examples`, папка `fullpipe_chain`.
 
 Что получится в итоге:
 
 - виртуальный датацентр (vDC);
-- сетевой шлюз периметра (Edge);
+- сетевой шлюз периметра (Edge) с балансировщиком AVI;
 - внешние IP на организации;
-- SNAT на шлюзе.
-
-Кластер Штурвал в эту инструкцию не входит — он разворачивается долго, отдельным шагом.
+- SNAT на шлюзе;
+- Kubernetes-кластер Штурвал (сервис 150) на этой сети.
 
 **Организацию создайте заранее в ЛК** — Terraform её не создаёт и не удаляет.
+Кластер Штурвал создаётся десятки минут, поэтому провайдер ждёт его до часу
+(`operation_timeout = "60m"`); остальные ресурсы — минуты.
+
+## Что нужно перед началом
+
+| Требование | Зачем | Где смотреть |
+|---|---|---|
+| Terraform 1.5 или новее | работает провайдер | `terraform version` |
+| Токен 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"` |
+| SNAT на Edge | выход в интернет для машин кластера | ресурс `nubes_vc_nsxt_snat` |
+
+Порядок из чек-листа услуги 150 (именно так связаны ресурсы в примере):
+организация → vDC → Edge (ALB, AVI ≥ 3) → внешние IP (≥ 3) → SNAT → кластер Штурвал.
+Минимум для кластера: 1 мастер-нода и 1 воркер-нода по 4 vCPU / 8 ГБ RAM / 50 ГБ диска.
 
 ## 1. Скачайте пример
 
@@ -79,7 +95,7 @@ nsxt_second_dns             = "185.247.187.77" # второй DNS
 
 ```bash
 terraform init     # один раз — скачает провайдер
-terraform plan     # покажет, что будет создано: 4 ресурса
+terraform plan     # покажет, что будет создано: 5 ресурсов
 terraform apply    # создаст (подтвердить: yes)
 ```
 
@@ -89,17 +105,37 @@ terraform apply    # создаст (подтвердить: yes)
 terraform output   # UUID и имена созданных услуг
 ```
 
-И в ЛК: появились vDC и Edge, на организации выделены внешние IP, на шлюзе включён SNAT.
-Повторный `terraform plan` должен показать `No changes`.
+И в ЛК: появились vDC, Edge и кластер Штурвал, на организации выделены внешние IP,
+на шлюзе включён SNAT. Повторный `terraform plan` должен показать `No changes`.
 
-## 6. Удаление
+Кластер создаётся десятки минут — провайдер ждёт его (`operation_timeout = "60m"`),
+в ЛК он появится со статусом `running`. Адреса Kubernetes API и Ingress — в
+`terraform output shturval_state_params` (поля `kubernetesApiAddress` и `ingressAddress`).
+
+## 6. Удаление: «заморозка» вместо удаления
 
 ```bash
 terraform destroy
 ```
 
-Порядок обратный: SNAT выключается, квота внешних IP обнуляется, затем удаляется шлюз,
-а vDC приостанавливается (данные сохраняются). **Организация не удаляется.**
+По умолчанию пример повторяет рабочую конфигурацию — при `destroy` объекты **не удаляются**:
+
+| Ресурс | Что делает `destroy` | Флаг в примере |
+|---|---|---|
+| Кластер Штурвал | `suspend`: выключается, данные и адреса сохраняются | `suspend_on_destroy = true` |
+| vDC | `suspend` | `suspend_on_destroy = true` |
+| Edge | не трогается: у эджа нет операции `suspend` | `keep_on_destroy = true` |
+| SNAT | не выключается | `keep_on_destroy = true` |
+| Квота внешних IP | не меняется: адреса держит кластер Штурвала | `keep_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`) →
+SNAT → Edge → vDC. Квоту нельзя опустить ниже занятых адресов, поэтому — только
+после удаления кластера; vDC удаляется лишь через 14 дней после `suspend`.
 
 ## Файлы примера
 
@@ -111,7 +147,8 @@ terraform destroy
 | `vdc.tf` | виртуальный датацентр |
 | `edge.tf` | сетевой шлюз периметра (Edge) |
 | `modifiers.tf` | внешние IP на организации + SNAT на шлюзе |
-| `outputs.tf` | UUID и имена созданных услуг |
+| `shturval.tf` | Kubernetes-кластер Штурвал: переменные Штурвала, группы воркеров и сам ресурс |
+| `outputs.tf` | UUID и имена созданных услуг (vDC, Edge, Штурвал) |
 | `terraform.tfvars.example` | шаблон значений (копируется в `terraform.tfvars`) |
 
 Подробнее про два последних ресурса — на странице

mkdocs.yml

@@ -60,5 +60,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 → Штурвал: curated/pipeline/vdc_edge_ip_snat.md
     - Ресурсы-модификаторы (IP организации, SNAT): curated/modifiers/org_ip_and_snat.md