tf_provider/docs/ARCHITECTURE_NEW.md

Universal Rebuild — Архитектура и рабочая цепочка (актуально)

Документ для нового чата: описывает, как устроено «универсальное ядро», как формируются YAML‑спеки сервисов и как генерируются Go‑ресурсы. Учитывает ошибки/уроки из текущего чата.

---

0) Базовые правила работы

• Не менять существующий Go‑код без явного согласования.
• Новая логика — только новые функции/файлы (если не было явного разрешения на правку).
• Все операции с облаком — read‑only, если отдельно не разрешено создание/удаление.
• Для токенов: новый access_token сохранять в /home/naeel/terra/HH-MM-SS.token.

---

1) Архитектура (слои)

1.1 Универсальное ядро (core)

Папка: universal_rebuild/internal/core

• client.go — универсальный клиент API и общий flow операций.
• Критерий завершения операции: dtFinish (см. комментарии в коде). Логику запрещено менять без согласования.

1.2 Провайдер (provider)

Папка: universal_rebuild/internal/provider

• Конфигурация провайдера, получение токена, подключение ресурсов через реестр.

1.3 Сгенерированные ресурсы

Папка: universal_rebuild/internal/resources_gen

• Автогенерируемые ресурсы Terraform по YAML‑спецификациям.
• registry.go (генерируется) — регистрирует все ресурсы.
• crud.go — общие CRUD‑хелперы (создание/modify/delete). Этот файл не генерируется, его нужно сохранять.

1.4 YAML‑спеки ресурсов

Папка: universal_rebuild/resources_yaml

• YAML для каждого сервиса. Источник истины для генератора ресурсов.
• Формат включает create.params, modify.params, lifecycle.

1.5 Генераторы

• YAML‑генератор без instanceUid
  • universal_rebuild/tools/service_params_gen/main.go
  • Получает параметры сервиса напрямую через /index.cfm?endpoint=....
• Go‑генератор
  • universal_rebuild/tools/gen/main.go
  • Читает YAML и генерирует ресурсы + registry.go.

---

2) Как получить параметры сервиса (без instanceUid)

Источник описан в:

• docs/40_analysis/har/discovery/service_parameters_fetch.md

API‑цепочка:

1. GET /api/v1/index.cfm?endpoint=/services/{svcId}
   • даёт список операций сервиса (operations)
2. GET /api/v1/index.cfm?endpoint=/serviceOperation/{svcOperationId}
   • даёт cfsParams (id, code, type, required, default, valueList, refSvcId, func)
3. (опц.) GET /api/v1/index.cfm?endpoint=/param-value-list/{svcOperationCfsParamId}

Почему так: прямых эндпойнтов на список параметров по service_id нет. Параметры извлекаются из описаний операций.

---

3) YAML‑генерация (service_params_gen)

Файл: universal_rebuild/tools/service_params_gen/main.go

Входные переменные:

• NUBES_API_TOKEN (если не задан — берётся из test_universal/terraform.tfvars)
• NUBES_API_ENDPOINT (по умолчанию https://deck-api.ngcloud.ru/api/v1/index.cfm)
• NUBES_SERVICE_ID (обязателен)
• NUBES_SERVICE_NAME (опц.)
• NUBES_OUTPUT (опц.)

Пример:

cd /home/naeel/terra/universal_rebuild
NUBES_SERVICE_ID=1 NUBES_SERVICE_NAME=dummy go run ./tools/service_params_gen/main.go

Результат:

• /home/naeel/terra/universal_rebuild/resources_yaml/dummy.yaml

---

4) Go‑генерация (tools/gen)

Файл: universal_rebuild/tools/gen/main.go

Что делает:

• читает все YAML из resources_yaml/
• генерирует ресурсы в internal/resources_gen/
• генерирует registry.go

Команда:

cd /home/naeel/terra/universal_rebuild
go run ./tools/gen/main.go

---

5) Build

cd /home/naeel/terra/universal_rebuild
go build -o terraform-provider-nubes

---

6) Важные нюансы и ошибки (из опыта чата)

6.1 resourceRealm

• resourceRealm должен задаваться пользователем в .tf, если параметр required.
• Нельзя автоподставлять serviceName как realm: API отклонит (пример с Postgres).

6.2 Warnings о дубликатах

• Предупреждение о RESOURCE WITH SAME NAME EXISTS должно появляться только на create (когда state.ID отсутствует).
• Для managed ресурсов (ID уже есть) предупреждения быть не должно.

6.3 Deleted ресурсы

• Если explainedStatus=deleted или isDeleted=true → ресурс считается отсутствующим, state должен очищаться.

6.4 Имена параметров

• Генератор может создавать «разбитые» snake_case для CamelCase (например resource_c_p_u).
• Это ожидаемо, но если критично — нужен отдельный маппинг (по согласованию).

---

7) Проверенная цепочка (dummy)

1. YAML:

NUBES_SERVICE_ID=1 NUBES_SERVICE_NAME=dummy go run ./tools/service_params_gen/main.go

2. Go‑код:

go run ./tools/gen/main.go

3. Build:

go build -o terraform-provider-nubes

---

8) Что делать дальше

• Повторять пункты 3–5 для каждого сервиса:
  • NUBES_SERVICE_ID=13 NUBES_SERVICE_NAME=bucket
  • NUBES_SERVICE_ID=90 NUBES_SERVICE_NAME=postgres
• Проверять YAML на корректность required‑параметров, resourceRealm и defaults.
• Поднимать ресурсы в .tf и тестировать: create / modify / suspend / delete.

---

9) Где искать доп. материалы

• Архитектура (старые, но полезные):
  • docs/ai_universal_provider_gen.md
  • docs/00_overview/ai_universal_provider_gen.md
• API discovery:
  • docs/40_analysis/har/discovery/service_parameters_fetch.md

---

Короткая формула: API (services → serviceOperation) → YAML → Go resources + registry → build → tests.

---

10) Политика удаления (карантин)

• Многие инстансы нельзя удалять сразу: из-за возможных данных действует 2‑недельный карантин.
• Dummy подпадает под эту политику.
• Для nubes_dummy при destroy или удалении из манифеста выполняется suspend, а не delete.
• При apply, если инстанс dummy в состоянии suspend, выполняется resume.