From f8d64948c803ac6d439035490401ff600e8db63e Mon Sep 17 00:00:00 2001 From: Repinoid Date: Fri, 25 Sep 2026 09:47:33 +0300 Subject: [PATCH] =?UTF-8?q?docs(curated):=20=D1=81=D1=82=D1=80=D0=B0=D0=BD?= =?UTF-8?q?=D0=B8=D1=86=D0=B0=20=C2=ABvDC=20=E2=86=92=20Edge=20=E2=86=92?= =?UTF-8?q?=20IP=20=E2=86=92=20SNAT=20=E2=86=92=20=D0=A8=D1=82=D1=83=D1=80?= =?UTF-8?q?=D0=B2=D0=B0=D0=BB=C2=BB=20(=D1=82=D1=80=D0=B5=D0=B1=D0=BE?= =?UTF-8?q?=D0=B2=D0=B0=D0=BD=D0=B8=D1=8F,=20=D0=B7=D0=B0=D0=BC=D0=BE?= =?UTF-8?q?=D1=80=D0=BE=D0=B7=D0=BA=D0=B0,=20=D0=BF=D1=80=D0=BE=D0=B2?= =?UTF-8?q?=D0=B5=D1=80=D0=BA=D0=B0=20=D1=80=D0=B5=D0=B7=D1=83=D0=BB=D1=8C?= =?UTF-8?q?=D1=82=D0=B0=D1=82=D0=B0)=20+=20nav=20+=20HISTORY?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...9-25_fullpipe_example_shturval_and_docs.md | 43 +++++++++++++ docs/curated/pipeline/vdc_edge_ip_snat.md | 61 +++++++++++++++---- mkdocs.yml | 2 +- 3 files changed, 93 insertions(+), 13 deletions(-) create mode 100644 HISTORY/2026-09-25_fullpipe_example_shturval_and_docs.md diff --git a/HISTORY/2026-09-25_fullpipe_example_shturval_and_docs.md b/HISTORY/2026-09-25_fullpipe_example_shturval_and_docs.md new file mode 100644 index 0000000..8a03d1d --- /dev/null +++ b/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` не печатать, сравнивать по хешу/маскировать. diff --git a/docs/curated/pipeline/vdc_edge_ip_snat.md b/docs/curated/pipeline/vdc_edge_ip_snat.md index af70999..74026b7 100644 --- a/docs/curated/pipeline/vdc_edge_ip_snat.md +++ b/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`) | Подробнее про два последних ресурса — на странице diff --git a/mkdocs.yml b/mkdocs.yml index e6894ba..a983d88 100644 --- a/mkdocs.yml +++ b/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