docs(resume): подробное резюме состояния Штурвал/freeze для нового чата + стенд DEV_STAND/FPipeGmail

2026-09-25 08:05:12 +03:00
parent c808a3b345
commit dbaadccc50
10 changed files with 583 additions and 0 deletions
@@ -0,0 +1,142 @@
+# CHAT RESUME — Штурвал + «freeze on destroy»: состояние на 2026-09-25
+
+> Цель файла: начать новый чат **без уточняющих вопросов** — здесь всё, что сделано, где живёт
+> документация, что в каком состоянии и что делать дальше.
+
+## 0. Где что лежит (точки входа)
+
+| Что | Путь |
+|---|---|
+| Полный разбор сессии (диагностика, пайплайн, аудит регистра UUID) | `NOTES/30_analysis/SHTURVAL_DEV00_DIAG_AND_FREEZE_DESIGN_2026-09-24.md` |
+| Страница для пользователя/DevOps: поведение и отличия от канонического Terraform | `docs/30_registry/guides/provider-behavior.md` |
+| Регистр UUID (все нерабочие подходы + кейс UUID внутри JSON, §10) | `docs/60_strategy/terraform_case_sensitivity_fix.md` |
+| Запись дня с коммитами и результатами | `HISTORY/2026-09-24_shturval_dev00_adopt_and_freeze_design.md` |
+| Память репозитория (факты, шпаргалки, уроки) | `/memories/repo/shturval-destroy-freeze.md` |
+| Версии провайдеров по стендам | `VERSIONS.md` |
+
+Репозиторий: `/home/naeel/TF/tf_provider`, ветка `master`, remote `origin`
+(`https://gitea.services.ngcloud.ru/terraform/tf_provider.git`). Снапшот состояния — ветка
+`snapshot/2026-09-25-shturval-freeze-state`.
+
+## 1. Что уже сделано
+
+1. **Диагностика стенда `shturval-dev-00`** (услуга 150, инстанс `shturval-dev`, uid `94627ff4-…`):
+   кластер здоров (2 ноды Ready, 41/41 Shturval-сервисов `ready`, NodeConfigItems 4/4, у всех сервисов
+   есть endpoints). Единственный мусор — 4 подвисших пода `kube-system/shturval-init-job`
+   (3 Error + 1 Unknown при `Complete 1/1`), причина — webhook-и Штурвала недоступны до готовности Cilium
+   (`connect: operation not permitted`); самоочистка по `ttlSecondsAfterFinished: 86400` (≈25.09 14:31 UTC).
+2. **Расшифрованы счётчики ЛК/Штурвала**: `Pods X/Y` = готовые/всего (без `Completed`);
+   «Системные сервисы» = число сервисов в режиме `auto`; «Конфигурация узлов» = NodeConfigItems;
+   «Ingress» = домен-шаблон, не счётчик.
+3. **Разобран провал `destroy`**: `nubes_vc_org_ip_allocation` отправлял `count=0`, платформа не даёт
+   опустить `count` ниже занятых адресов — их держит кластер (`.146` API и `.148` ingress), `suspend`
+   адреса не освобождает.
+4. **Усыновление исправлено**: в `DEV_STAND/FullPipe/shturval.tf` добавлен `adopt_existing_on_create = true`
+   (коммит `57abb7b`); проверено вживую — apply усыновил существующий инстанс и сам сделал `resume`.
+5. **Реализован третий режим destroy** (коммит `22c6c83`, генератор, универсально для всех instance-ресурсов):
+   `keep_on_destroy` → `state_only` (приоритет), иначе `suspend_on_destroy` → `suspend`, иначе `delete`;
+   в `Delete` добавлены предупреждения «Ресурс заморожен, а не удалён» / «оставлен как есть».
+6. **Конфиг стенда переведён в режим «заморозки»** (коммит `40aef87`): `keep_on_destroy = true` у квоты IP,
+   SNAT и эджа; `adopt_existing_on_create = true` и `suspend_on_destroy = true` у кластера; у vDC оба флага
+   уже стояли.
+7. **Проверен цикл `destroy` = заморозка** на живом стенде (`2.0.22`): `0 added, 0 changed, 5 destroyed`,
+   ошибок нет; кластер и vDC → `suspended`, эдж `running` с `ipSpaceName=internet-ipv4-v1`, квота IP `count=3`,
+   state пуст; в выводе — 5 предупреждений.
+8. **Найден и исправлен баг регистра UUID внутри JSON** (коммит `621280a`, релиз `2.0.23`): первый `apply`
+   после заморозки падал на `required params mismatch … startupConfiguration` (`2c37fed1-…` в плане против
+   `2C37FED1-…` в живом инстансе). Проведён аудит 8 мест (см. §10 в `terraform_case_sensitivity_fix.md`),
+   добавлены `jsonutil.LowercaseUUIDsInText` и нормализация строк внутри JSON, `JsonNormalize()` приводит
+   UUID-подстроки к lowercase; покрыто тестами (`jsonutil_test.go`, `params_compare_test.go`), `go test ./...` зелёный.
+9. **Документация**: страница `docs/30_registry/guides/provider-behavior.md`, обновлённый §10 в
+   `terraform_case_sensitivity_fix.md`, записи в `NOTES`/`HISTORY`, память репозитория.
+
+## 2. Текущее состояние (на момент записи)
+
+- `DEV_STAND/FullPipe`: **`terraform state list` пуст** (после проверочного `destroy`).
+- В облаке: кластер `shturval-dev-00` — `suspended`; vDC — `suspended`; эдж — `running`
+  (`ipSpaceName = internet-ipv4-v1`, SNAT включён); квота IP организации — `count = 3`.
+- Кластер «спит»: `.146:6443` TCP принимается эджем, но k8s не отвечает (`connection reset by peer`);
+  `.148:443` открыт (эдж/AVI живут).
+- Версия провайдера: в реестре dev — **`2.0.23`**; пины `versions.tf` в `DEV_STAND/FullPipe` и
+  `DEV_STAND/FPipeGmail` — `2.0.23`.
+- Новый (не проверенный вживую) стенд пользователя: `DEV_STAND/FPipeGmail/`.
+
+## 3. Что делать дальше
+
+1. **Проверить обратный ход** (запускает только пользователь): `terraform apply` в `DEV_STAND/FullPipe`.
+   Ожидание: `adopt` по имени + `resume` для кластера и vDC; эдж/SNAT/квота — no-op; затем `plan` = `No changes`.
+   Проверки: `terraform state list`, `terraform state show`, статусы инстансов в API ЛК, `kubectl get nodes`
+   (снова Ready), поды `44/48` (+ мусор `shturval-init-job`, уйдёт сам).
+2. **Доку при необходимости**: добавить страницу `provider-behavior.md` в `nav` (`mkdocs.yml`) и запустить
+   `TOOLS/scripts/04_build_and_publish_docs.sh` — **не запускать без прямой команды**.
+3. **Открытые техдолги:**
+   - ref-параметр внутри JSON **не валидируется** при adopt (`resources_core/ref_validation.go`);
+   - регистр ключей в `lookupLiveParam` (`core/operation_run.go`, `operation_run_bycode.go`) — требует живой проверки;
+   - тикет в платформу: TTL/очистка Failed-подов установщика + порядок установки компонентов до готовности Cilium;
+   - тикет в платформу: у Эджа нет операции `suspend` (в `availableOperations` только `delete/modify/reconcile`).
+4. **Полный teardown** — осознанно: `keep_on_destroy = false` и `suspend_on_destroy = false`, порядок
+   кластер → `count=0` → SNAT → эдж → vDC (для vDC действует правило «14 дней после suspend»).
+
+## 4. Шпаргалка: режимы destroy
+
+| Ресурс | Флаг | Поведение при destroy | Предупреждение |
+|---|---|---|---|
+| `nubes_k8s_sthutrval_cluster` | `suspend_on_destroy = true` | `suspend` | «Ресурс заморожен, а не удалён» |
+| `nubes_vc_vdc` | `suspend_on_destroy = true` | `suspend` | то же |
+| `nubes_vc_nsxt` (эдж) | `keep_on_destroy = true` | не трогается | «Ресурс оставлен как есть, а не удалён» |
+| `nubes_vc_nsxt_snat` | `keep_on_destroy = true` | не трогается | «SNAT не выключался» |
+| `nubes_vc_org_ip_allocation` | `keep_on_destroy = true` | не трогается | «Аллокация IP не снималась» |
+
+Приоритет: `keep_on_destroy` > `suspend_on_destroy` > обычное удаление. Дефолты провайдера — разрушающие;
+«заморозка» включается в `.tf` стенда.
+
+## 5. Факты платформы (проверено)
+
+- 1 кластер Штурвала = 1 vDC; vDC удаляется только через 14 дней после `suspend`.
+- Квоту IP нельзя опустить ниже занятых адресов; адреса кластера `suspend` не освобождает.
+- У эджа нет `suspend`; удаление эджа при живых зависимых (vApp/VM/кластер) недопустимо.
+- API ЛК: `GET /api/v1/svc/instances/{uid}`, состояние — `instance.state.params`, статус — `explainedStatus`,
+  операции — `availableOperations`; ошибки операции — в теле (`isSuccessful=false`, `errorLog`), HTTP 200/201.
+- Обязательные заголовки API ЛК: браузерный `User-Agent`, `Referer: https://deck-dev.ngcloud.ru/`,
+  `Authorization: Bearer <secrets/narodDEV.token>` — иначе `403`.
+- Регистр UUID: облако отдаёт один и тот же UUID в разных регистрах → сравнивать всегда без учёта регистра
+  (в т.ч. **внутри JSON**).
+
+## 6. Релизы
+
+- Схема: prod `1.*`, dev `2.*`, test `3.*`; актуальная dev — `2.0.23` (`VERSIONS.md`).
+- Релиз: `TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/dev <версия>`
+  (сам прогоняет `01` + `02`, собирает, подписывает, заливает, обновить `VERSIONS.md` вручную).
+- Локальная проверка без релиза: `go build -o TMP/devbin/terraform-provider-nubes .` в `provider/`
+  и `TF_CLI_CONFIG_FILE=TMP/terraformrc.dev terraform validate|plan` (dev_overrides).
+- YAML-спеки (`generated/*/resources_yaml/`) **не редактировать руками** — `01_generate_yamls.sh` перезапишет их из API.
+
+## 7. Правила работы (для нового чата)
+
+- `terraform apply` / `destroy` — только пользователь. Мне доступны `init/plan/validate/show/state show`.
+- Никаких правок, коммитов, релизов и публикаций без прямой команды; после каждой правки — коммит.
+- Перед правками важных файлов — бэкап в `TMP/backup_<дата>/`.
+- Не «улучшать» соседние стенды/сервисы без команды (scope creep запрещён).
+
+## 8. Быстрые команды
+
+```bash
+# состояние стенда
+cd DEV_STAND/FullPipe && terraform state list && terraform plan
+terraform state show nubes_k8s_sthutrval_cluster.shturval | grep -E "id|adopt|suspend|keep"
+
+# кластер
+kubectl get nodes
+kubectl get pods -A --no-headers | awk '{split($3,a,"/"); tot++; if($4=="Running"&&a[1]==a[2]) ok++} END{print tot, ok}'
+kubectl get pods -A | grep -v -E "Running|Completed"
+
+# API ЛК (dev)
+TOK=$(tr -d '\n' < secrets/narodDEV.token)
+curl -s -H "Authorization: Bearer $TOK" \
+     -H "User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36" \
+     -H "Referer: https://deck-dev.ngcloud.ru/" \
+     'https://lk-api-gateway-dev.ngcloud.ru/api/v1/svc/instances/94627ff4-33a5-48f2-aca1-695741e0b6a2'
+
+# реестр провайдера (dev)
+curl -s https://tf-registry.containerk8s.services.ngcloud.ru/v1/providers/nubes-dev/nubes/versions
+```