From aaf87d966b0149d1378383a7a0bec21f0fe17ac7 Mon Sep 17 00:00:00 2001 From: Nail Date: Thu, 24 Sep 2026 20:40:18 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D1=81=D1=82=D1=80=D0=B0=D0=BD=D0=B8?= =?UTF-8?q?=D1=86=D0=B0=20=C2=AB=D0=9A=D0=B0=D0=BA=20=D1=80=D0=B0=D0=B1?= =?UTF-8?q?=D0=BE=D1=82=D0=B0=D0=B5=D1=82=20=D0=BF=D1=80=D0=BE=D0=B2=D0=B0?= =?UTF-8?q?=D0=B9=D0=B4=D0=B5=D1=80:=20=D0=BE=D1=82=D0=BB=D0=B8=D1=87?= =?UTF-8?q?=D0=B8=D1=8F=20=D0=BE=D1=82=20=D0=BA=D0=B0=D0=BD=D0=BE=D0=BD?= =?UTF-8?q?=D0=B8=D1=87=D0=B5=D1=81=D0=BA=D0=BE=D0=B3=D0=BE=20Terraform?= =?UTF-8?q?=C2=BB=20(freeze/destroy,=20=D0=BF=D0=B0=D0=B9=D0=BF=D0=BB?= =?UTF-8?q?=D0=B0=D0=B9=D0=BD=20vDC=E2=86=92Edge=E2=86=92IP=E2=86=92SNAT?= =?UTF-8?q?=E2=86=92=D0=A8=D1=82=D1=83=D1=80=D0=B2=D0=B0=D0=BB,=20FAQ)=20+?= =?UTF-8?q?=20=D0=BA=D0=B5=D0=B9=D1=81=20UUID=20=D0=B2=D0=BD=D1=83=D1=82?= =?UTF-8?q?=D1=80=D0=B8=20JSON=20=D0=B2=20case-sensitivity=20=D0=B4=D0=BE?= =?UTF-8?q?=D0=BA=D1=83=D0=BC=D0=B5=D0=BD=D1=82=D0=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/30_registry/guides/provider-behavior.md | 199 ++++++++++++++++++ .../terraform_case_sensitivity_fix.md | 56 ++++- 2 files changed, 254 insertions(+), 1 deletion(-) create mode 100644 docs/30_registry/guides/provider-behavior.md diff --git a/docs/30_registry/guides/provider-behavior.md b/docs/30_registry/guides/provider-behavior.md new file mode 100644 index 0000000..5784a51 --- /dev/null +++ b/docs/30_registry/guides/provider-behavior.md @@ -0,0 +1,199 @@ +# Как работает провайдер Nubes: поведение и отличия от канонического Terraform + +> Страница для тех, кто уже работал с Terraform и хочет понять, чего ожидать от провайдера Nubes, +> и для DevOps, которым важно знать, что реально произойдёт в облаке при `plan`, `apply` и `destroy`. +> Здесь описан наблюдаемый контракт (что уже проверено на живых стендах) и ограничения платформы. + +## 1. Суть в одном абзаце + +Провайдер Nubes — это не плагин к гипервизору, а **обёртка над API личного кабинета**: каждый Terraform-ресурс +соответствует *инстансу услуги* в облаке, а `create` / `update` / `delete` транслируются в **асинхронные операции** +платформы (`create`, `modify`, `suspend`, `resume`, `delete`). Отсюда все отличия: долгие операции с поллингом, +изменение вместо пересоздания, ошибки внутри тела ответа, идентичность ресурса по имени и возможность +«мягкого» удаления. + +## 2. Какие ресурсы за что отвечают + +| Услуга облака | Ресурс Terraform | Что делает | +|---|---|---| +| Организация в Cloud Director (19) | `nubes_vc_org_ip_allocation` | **модификатор**: меняет квоту внешних IP в уже существующей организации (саму организацию создают в ЛК) | +| Виртуальный датацентр (21) | `nubes_vc_vdc` | создаёт vDC с ресурсами (CPU/RAM/Storage) | +| Сетевой шлюз периметра (22) | `nubes_vc_nsxt` | создаёт Edge (routed-сеть, ALB/AVI) | +| Сетевой шлюз периметра (22) | `nubes_vc_nsxt_snat` | **модификатор**: включает/переключает SNAT (`ipSpaceName`) на существующем Edge | +| Kubernetes кластер Штурвал (150) | `nubes_k8s_sthutrval_cluster` | создаёт кластер (control plane + группы воркеров) | + +Общее правило: **создаёт** только «инстансный» ресурс услуги, а всё остальное, что делается операцией `modify` +(квота IP, SNAT, свойства шлюза), — это отдельные ресурсы-модификаторы со своим жизненным циклом. + +## 3. Отличия от «учебного» Terraform + +| Ожидание по канону | Как в Nubes | Причина | +|---|---|---| +| `create` = один вызов API | Создание инстанса — **последовательность**: `POST /instances` → `POST /instanceOperations` → параметры (`instanceOperationCfsParams`) → `run` → поллинг до `dtFinish` | Так устроен API платформы | +| `id` — произвольная строка | `id` = UUID инстанса в облаке; чтение — из `instance.state.params` / `state.out` | Состояние живёт в облаке, не в Terraform | +| `update` = замена при несовместимых параметрах | `update` = операция **`modify`** над тем же инстансом; часть параметров — **create-only** (менять нельзя → ошибка на этапе plan) | Платформа не пересоздаёт объекты «из коробки» | +| есть `data sources` для поиска существующего | Поиск/ссылки — через **ref-параметры**: можно указать UUID **или имя** инстанса | Экономит data sources, но требует дисциплины в значениях | +| `import` — явная команда | Плюс к `import` есть **авто-усыновление** `adopt_existing_on_create = true`: ресурс сам находит инстанс **по имени** | В проде объекты живут неделями, и пересоздавать их нельзя | +| `plan` показывает, что ресурс уже существует | **Нет**: проверка «инстанс с таким именем уже есть / adopt» выполняется в `Create`, то есть на `apply` | Иначе ломается `destroy` и работа с tainted-ресурсами | +| `delete` удаляет | `delete` может быть `delete` / `suspend` / `state_only` — см. §5 | У платформы не всё удаляется, а часть объектов удалять нельзя, пока жив потребитель | +| ошибка приходит HTTP-кодом | Ошибка операции — **в теле**: `isSuccessful=false` + `errorLog`, при успешном HTTP-коде | API платформы отвечает 200/201 почти всегда | +| операции быстрые | Операции асинхронные и долгие (Штурвал — десятки минут) → параметр `operation_timeout`; одновременные операции на одном инстансе не поддерживаются | Наследство платформы (внутри — CFS-оркестратор) | +| план обязан совпадать с config | Тоже, но с оговоркой: **ref-параметры в плане не нормализуются** (нельзя подменить `name` → `uuid`), нормализация только перед вызовом API | Иначе Terraform упадёт с «Provider produced invalid plan» | +| параметры сравниваются как строки | JSON-параметры сравниваются **канонично**: порядок ключей и пробелы не важны, скаляры приводятся к строке, UUID — без учёта регистра | API возвращает JSON в своём виде, иначе будет «вечный diff» | +| идентичность — по `id` | Дополнительно: инстанс ищется по `resource_name` (displayName) → **переименование = новый ресурс** | Имя задаётся при создании и не меняется | + +### Что из этого следует на практике + +- `terraform plan` **не может** проверить, что «такой объект уже есть»: он это покажет как `will be created`, + а разбираться будет `apply`. +- `terraform apply` на существующей инфраструктуре — это нормальный сценарий (adopt), если включён + `adopt_existing_on_create`; без флага вы получите явную ошибку-конфликт, а не дубль ресурса. +- Долгие операции требуют терпения: смотрите `operation_timeout`, не запускайте вторую операцию по тому же объекту. + +## 4. Создание, чтение, изменение, удаление + +**Создание.** Провайдер формирует параметры операции, отправляет её и ждёт завершения. Параметры, зависящие +от других ресурсов (например `vdc_uid`, `nsxt_uid`), передаются как ref-значения: UUID или имя. + +**Чтение (refresh).** Значения `state_params` / `state_out` приходят из облака: так в state попадают +адреса (`kubernetesApiAddress`, `ingressAddress`), имена, текущие параметры. + +**Изменение.** Если параметры поменялись, вызывается `modify` (для модификаторов — обратный `modify` при удалении). +Параметры, помеченные как create-only, изменить нельзя — провайдер скажет об этом до обращения к API. + +**Удаление.** См. следующий раздел — это самое неочевидное место. + +## 5. Удаление: `delete`, `suspend` и «оставить как есть» + +У платформы три разных исхода, и провайдер умеет все три. Управляется флагами: + +| Флаг | Где применим | Поведение при `destroy` | Предупреждение в выводе | +|---|---|---|---| +| `suspend_on_destroy = true` | кластер Штурвала, vDC (по умолчанию `true`) | объект **приостанавливается**, не удаляется | «Ресурс заморожен, а не удалён» | +| `keep_on_destroy = true` | Edge, SNAT, квота IP (по умолчанию `false`) | объект **не трогается в облаке**, только убирается из state | «Ресурс оставлен как есть, а не удалён» / «SNAT не выключался» / «Аллокация IP не снималась» | +| оба `false` | любой | обычное удаление | — | + +Приоритет: `keep_on_destroy` важнее `suspend_on_destroy`. Дефолты провайдера — **разрушающие** +(`keep_on_destroy = false`), «заморозку» включают явно в конфигурации стенда. + +### Почему Edge остаётся `running` + +Edge **физически не умеет `suspend`**: в списке доступных операций шлюза есть только `delete`, `modify`, +`reconcile`. Усыпить его платформа не даёт, поэтому единственный корректный способ «не удалять шлюз» — +не трогать его: `keep_on_destroy = true`. Побочный эффект — шлюз продолжает работать и тарифицироваться, +и через него продолжают публиковаться внешние адреса (API кластера и ingress). Именно поэтому удаление Edge +при живом кластере Штурвала (или других зависимых объектах: vApp, VM) считается недопустимым. + +### Почему SNAT остаётся включённым, а квота IP не обнуляется + +- SNAT-модификатор с `keep_on_destroy = true` **не отправляет** обратный `modify` с `ipSpaceName = "no-needed"`, + то есть SNAT для виртуальных машин остаётся в прежнем состоянии. +- Квота внешних IP: уменьшать `count` **ниже фактически занятых адресов платформа не разрешает** + (ошибка вида «Кол-во занятых Ip … Невозможно выставить параметр count ниже этого параметра»). + Адреса держит кластер Штурвала (API + ingress), и `suspend` кластера их **не освобождает**. + Поэтому при «заморозке» квота не изменяется вовсе, а реальное освобождение адресов возможно только после + удаления кластера — отдельным шагом. + +### Почему кластер и vDC уходят в `suspend` + +Для них `suspend` поддерживается платформой, и это самый близкий к «выключить» вариант: ВМ останавливаются, +объекты не удаляются, адреса и конфигурация сохраняются. Обратный ход делает `apply`: + +| Что | При `destroy` (заморозка) | При следующем `apply` | +|---|---|---| +| Кластер Штурвала | `suspend` | adopt по имени + `resume` | +| vDC | `suspend` | adopt по имени + `resume` | +| Edge | не трогается (`running`) | adopt (инстанс уже работает) | +| SNAT | не трогается (включён) | повторный `modify` теми же значениями (фактически no-op) | +| Квота IP | не трогается | `modify` с тем же `count` (no-op) | + +Итого цикл «`destroy` → `apply`» на стенде выглядит как «усыпить → разбудить», а не «снести → поднять заново». +Полностью удалить такой стенд можно только явным отказом от заморозки (`keep_on_destroy = false` / +`suspend_on_destroy = false`) и в правильном порядке (см. §6). + +## 6. Конкретный пайплайн стенда: vDC → Edge → внешние IP → SNAT → Штурвал + +Порядок создания и зависимости: + +1. Организация — **вручную в ЛК** (Terraform её не создаёт). +2. `nubes_vc_vdc` — виртуальный датацентр. +3. `nubes_vc_nsxt` — Edge; обязательно с ALB (`need_enable_avi = true`) и `virtual_services_count >= 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: нодам нужен выход в интернет). + +При удалении Terraform идёт в обратном порядке. Ограничения платформы, которые встречаются на этом пути: + +- **1 кластер Штурвала = 1 vDC** (действующее ограничение услуги). +- vDC удаляется только **через 14 дней после `suspend`**; при живых Edge/vApp/VM/кластере — через поддержку. +- Edge не удаляется при живых зависимых объектах (по инструкции услуги). +- Квота IP не опускается ниже занятых адресов (см. §5). + +Практическая проверка корректности конфигурации: `terraform plan` после `apply` должен говорить +`No changes`. Если появляется стабильный diff — сравнивайте не «на глаз», а по `terraform state show` +и состоянию инстанса в ЛК. + +## 7. Регистр UUID и канонизация значений + +UUID в облаке не имеет «правильного» регистра: один и тот же идентификатор может прийти как `2c37fed1-…` +и как `2C37FED1-…`. Поэтому провайдер сравнивает UUID **без учёта регистра** — в том числе внутри JSON-параметров +(например, `startupConfiguration` кластера Штурвала). Подробный разбор проблемы и всех мест, где она может +проявиться, — в `60_strategy/terraform_case_sensitivity_fix.md` (внутренний документ). + +Для JSON-параметров сравнение также игнорирует порядок ключей и пробелы, а скаляры приводит к строковому виду — +это нужно, чтобы `plan` не показывал «изменение» там, где API вернул то же значение в другом формате. + +## 8. Чек-лист DevOps + +- Пин версии провайдера привязан к стенду: **prod `1.*`, dev `2.*`, test `3.*`**; после смены версии — + `terraform init -upgrade`. +- Перед `apply` и после — смотрите `plan`; ожидаемый финальный результат — `No changes`. +- **Читайте предупреждения `destroy`**: «заморожен», «оставлен как есть», «SNAT не выключался» — это не косметика, + а отчёт о том, что объекты продолжают жить и тарифицироваться. +- Не удаляйте объекты стенда руками в ЛК между `destroy` и `apply`: авто-усыновление ищет их по имени, и на удалённом + объекте упрётся в состояние `not created`. +- Долгие операции: задавайте `operation_timeout` (для Штурвала — `60m`), не запускайте параллельные операции + по одному объекту. +- Проверяя состояние через API ЛК, помните про обязательные заголовки (браузерный `User-Agent` и `Referer`) — + иначе отдаёт `403`. + +## 9. FAQ + +**Почему `plan` пишет `will be created`, если объект уже есть?** +Потому что проверка существования и усыновление выполняются на `apply` (в `Create`). В state ресурса нет → план +честно планирует создание. Решение — `adopt_existing_on_create = true`. + +**Почему `destroy` сказал `5 destroyed`, а в облаке всё живо?** +Сработала «заморозка»: кластер и vDC приостановлены, Edge, SNAT и квота IP не изменялись. Terraform «удалил» +ресурсы только из своего состояния. Смотрите предупреждения в выводе. + +**Почему IP не освободились?** +Квота не может стать меньше числа занятых адресов, а их держит кластер. Пока кластер существует (даже в `suspend`), +платформа не даст уменьшить `count`. + +**Почему Edge нельзя приостановить?** +У платформы для шлюза нет операции `suspend` — только `delete`, `modify`, `reconcile`. + +**Почему после `apply` кластер ожил сам?** +Сработало усыновление: ресурс нашёл инстанс по имени (`adopt_existing_on_create`), увидел статус `suspended` +и выполнил `resume`. + +**State пуст, а объекты в облаке есть. Что делать?** +Это ожидаемый результат «заморозки». `terraform apply` в том же каталоге усыновит объекты обратно. + +**Кто-то удалил объект в ЛК. Что будет?** +Усыновление не найдёт его и провайдер завершится ошибкой с указанием статуса (`not created`) — нужно либо создать +объект заново, либо разбираться с конфигурацией. + +**А можно всё-таки удалить стенд полностью?** +Да, но осознанно: выставить `keep_on_destroy = false` и `suspend_on_destroy = false`, затем удалять в порядке +кластер → квота IP → SNAT → Edge → vDC, при необходимости — через поддержку (для vDC действует правило 14 дней). + +## 10. Куда смотреть дальше + +- `curated/pipeline/vdc_edge_ip_snat.md` — пошаговый разбор цепочки vDC → Edge → IP → SNAT. +- `curated/modifiers/org_ip_and_snat.md` — ресурсы-модификаторы. +- `30_registry/guides/terraform-structure.md` — структура манифестов. +- Внутренние документы (не публикуются): `60_strategy/provider_philosophy.md`, + `60_strategy/modifier_resources_ideology_and_specification.md`, + `60_strategy/adopt_ref_validation.md`, `60_strategy/terraform_case_sensitivity_fix.md`. diff --git a/docs/60_strategy/terraform_case_sensitivity_fix.md b/docs/60_strategy/terraform_case_sensitivity_fix.md index 14ad646..14c0cc5 100644 --- a/docs/60_strategy/terraform_case_sensitivity_fix.md +++ b/docs/60_strategy/terraform_case_sensitivity_fix.md @@ -239,5 +239,59 @@ gr.NeedsStringsImport = hasRestoreCasingParams(gr.SchemaParams) || analyzeNeedsS ## 9. Версия -Фикс введён в версии провайдера **5.0.46**. +Фикс введён в версии провайдера **5.0.46** (старая линия; актуальные линии — prod `1.*`, dev `2.*`, test `3.*`, см. §10). Сгенерированные ресурсы пересозданы после изменения генератора. + +--- + +## 10. Обновление 2026-09-24: UUID внутри JSON (важно) + +**Что уточнилось.** Посылка «API всегда возвращает lowercase» **неверна**. На живом стенде (Shturval dev-00) +один и тот же UUID приходил в разных регистрах: `vdcUid` — `d0937335-…` (lowercase), а `nsxtUid` кластера — +`2C37FED1-…` (UPPERCASE). Значит ориентироваться на «API нормализует» нельзя: сравнивать нужно всегда +без учёта регистра. + +**Где вылезло.** Первый `apply` после «заморозки» стенда упал на усыновлении приостановленного кластера: + +``` +Error: required params mismatch for resource_name shturval-dev: startupConfiguration +(plan={… "nsxtUid":"2c37fed1-…" }, actual={… "nsxtUid":"2C37FED1-…" }). +``` + +**Почему предыдущие пять фиксов не помогли.** Они закрывали: отправку в API (`core/refsvc.go`, +`core/refsvc_resolve.go`), сравнение **одиночных** значений (`resources_core/params_compare.go`, +`normalizeCompareValue`), сравнение create-only атрибутов (`strings.EqualFold` в шаблоне генератора) +и восстановление регистра в state. Ни один из них не смотрит **внутрь JSON**, а adopt приостановленного +инстанса сравнивает параметр целиком как JSON: +`RequiredParamsMismatch` → `paramsEquivalent` → `JSONStringsEquivalent` → `jsonutil.normalizeJSONScalarsToStrings`, +где строки возвращались как есть (`case string: return val`). У Штурвала ref-параметры упакованы в JSON +(`startupConfiguration`), а путь adopt-suspended задействован впервые. + +**Аудит: где регистр UUID может вылезти (проверено 24.09).** + +| # | Место | Что ломает | +|---|---|---| +| 1 | `resources_core/required_params_compare.go` (`paramsEquivalent` → `JSONStringsEquivalent`) | adopt приостановленного инстанса — hard error (этот кейс) | +| 2 | `core/modifier_compare.go` | ложное «параметр изменился» → лишний `modify` на каждом apply | +| 3 | `resources_core/state_refresh.go` (сохранение планового JSON) | в state уедет регистр API вместо значения из config | +| 4 | `resources_core/resource_diagnostics_required.go` (create-диагностика) | та же `RequiredParamsMismatch` | +| 5 | `resources_core/params_compare.go` (`ParamsMatchForResume`) | одиночный UUID ок, JSON — та же дыра | +| 6 | `resources_core/json_planmodifier.go` (`JsonNormalize()`) | для JSON-атрибутов с UUID внутри — риск вечного diff | +| 7 | `resources_core/ref_validation.go` (`ValidateRefParamsOnAdopt`) | ref-параметр, зашитый внутрь JSON, **не проверяется вообще** (открыто) | +| 8 | `core/operation_run*.go` (`lookupLiveParam`) | подстановка live-значений по ключам: при другом регистре ключа может молча не сработать (открыто, требует живой проверки) | + +**Фикс (провайдер `2.0.23`, dev).** + +- `internal/core/jsonutil/jsonutil.go`: добавлен `LowercaseUUIDsInText` (UUID-подстрока → lowercase), и строковые + значения **внутри JSON** теперь нормализуются в `normalizeJSONScalarsToStrings` — закрывает пункты 1–5. +- `internal/resources_core/json_planmodifier.go`: `JsonNormalize()` после `json.Compact` приводит UUID-подстроки + к lowercase (типы и порядок ключей **не** меняются — план обязан совпадать с config) — закрывает пункт 6. +- Тесты: `internal/core/jsonutil/jsonutil_test.go`, `internal/resources_core/params_compare_test.go` + (в т.ч. на реальном `startupConfiguration` кластера). + +**Дополнение к алгоритму диагностики (§8):** + +7. Если расхождение — внутри JSON-параметра, проверьте именно UUID-подстроки и их регистр (не только одиночные + значения); смотрите `jsonutil.LowercaseUUIDsInText`. +8. Не «лечите» это нормализацией плана целиком (скаляры → строки, сортировка ключей): для атрибутов из config + допустимо менять только регистр UUID-подстрок, иначе Terraform ругнётся на несоответствие плана конфигу.