docs: страница «Как работает провайдер: отличия от канонического Terraform» (freeze/destroy, пайплайн vDC→Edge→IP→SNAT→Штурвал, FAQ) + кейс UUID внутри JSON в case-sensitivity документе

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`.

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 ругнётся на несоответствие плана конфигу.