add: documentation

2026-06-30 15:45:24 +04:00
parent 540c1f7293
commit ca276d200f
1055 changed files with 47294 additions and 0 deletions
@@ -0,0 +1,188 @@
+# Universal Provider (ядро + генератор ресурсов) — подробный отчёт
+
+Дата: 2026-01-31
+
+## Цель
+Нужна архитектура «универсального провайдера», где:
+- есть **ядро** (общий клиент и универсальный флоу операций);
+- есть **папка ресурсов** (Go-файлы ресурсов);
+- есть **папка YAML-описаний сервисов** (чтобы DevOps мог добавить сервис одним файлом);
+- есть **генератор**, который:
+  - читает YAML,
+  - генерирует ресурсы,
+  - генерирует реестр ресурсов,
+  - дальше выполняется build (ядро + ресурсы из папки).
+
+В итоге: если файла ресурса нет — в провайдере его не будет. Если YAML изменён — перегенерация.
+
+---
+
+## Итоговая архитектура (v2.0.0, «голое» ядро + ресурсы)
+Новая сборка размещена в:
+- [nubes_provider_gen](nubes_provider_gen)
+
+Структура:
+- [nubes_provider_gen/internal/core](nubes_provider_gen/internal/core) — **ядро** (клиент, универсальный flow, запуск операций)
+- [nubes_provider_gen/internal/provider](nubes_provider_gen/internal/provider) — **провайдер** (schema + клиент)
+- [nubes_provider_gen/internal/resources_gen](nubes_provider_gen/internal/resources_gen) — **сгенерированные ресурсы** (Go)
+- [nubes_provider_gen/resources_yaml](nubes_provider_gen/resources_yaml) — **YAML-описания сервисов**
+- [nubes_provider_gen/tools/gen](nubes_provider_gen/tools/gen) — **генератор**
+- [nubes_provider_gen/test_persistent](nubes_provider_gen/test_persistent) — тестовые манифесты
+
+### 1) Ядро (core)
+Файл: [nubes_provider_gen/internal/core/client.go](nubes_provider_gen/internal/core/client.go)
+
+Содержит:
+- `UniversalClient` с HTTP-клиентом и API endpoint/token.
+- Универсальный flow **CreateGenericInstanceUniversalV6**:
+  1. POST /instances
+  2. POST /instanceOperations (create)
+  3. GET /instanceOperations/{opUid}?fields=cfsParams
+  4. POST /instanceOperationCfsParams (явные параметры)
+  5. POST /instanceOperationCfsParams (дефолтные/пустые для пропущенных)
+  6. GET /instanceOperations/{opUid}/validate-cfs
+  7. POST /instanceOperations/{opUid}/run
+- Универсальные операции:
+  - `RunInstanceOperationUniversal` (delete/suspend/resume и т.д.)
+  - `RunInstanceOperationUniversalWithDefaults` (modify с автоподстановкой параметров)
+- Утилиты:
+  - `FindInstanceByDisplayName`
+  - `GetInstanceState`
+
+**Почему нужно WithDefaults для modify**
+На modify требуются обязательные параметры (часто даже те, что не меняются). Без них backend падает.
+
+### 2) Провайдер (provider)
+Файл: [nubes_provider_gen/internal/provider/provider.go](nubes_provider_gen/internal/provider/provider.go)
+
+- Тип провайдера: `nubes`
+- Адрес: `terrareg.kube5s.ru/nubes/nubes`
+- Ресурсы приходят из **реестра**:
+  - `resources_gen.AllResources()` — возвращает список функций создания ресурсов.
+
+### 3) Генератор (tools/gen)
+Файл: [nubes_provider_gen/tools/gen/main.go](nubes_provider_gen/tools/gen/main.go)
+
+Функции:
+- Читает все YAML-файлы в `resources_yaml/`
+- Генерирует ресурсный Go-файл в `internal/resources_gen/` для каждого YAML
+- Генерирует `registry.go` с `AllResources()`
+
+То есть:
+- **Добавили YAML → сгенерировали Go → build**
+- Нет YAML → нет Go → нет ресурса
+
+### 4) YAML-описания
+Файл: [nubes_provider_gen/resources_yaml/dummy.yaml](nubes_provider_gen/resources_yaml/dummy.yaml)
+
+Минимальная схема (пример dummy):
+- `name`, `service_id`, `display_name_default`
+- `create.params` — ID параметров create
+- `modify.params` — ID параметров modify
+- `lifecycle` — defaults для `adopt_existing_on_create` и `suspend_on_destroy`
+
+---
+
+## Что было сделано (конкретные шаги)
+
+### Шаг 1. «Голое» ядро + генератор
+Создан отдельный проект:
+- [nubes_provider_gen](nubes_provider_gen)
+Сделан core + provider + tools/gen + resources_yaml.
+
+### Шаг 2. YAML для dummy
+Создан YAML dummy: [nubes_provider_gen/resources_yaml/dummy.yaml](nubes_provider_gen/resources_yaml/dummy.yaml)
+
+### Шаг 3. Генерация ресурсов
+Команда:
+- `go run ./tools/gen`
+
+Сгенерированы:
+- [nubes_provider_gen/internal/resources_gen/dummy_resource.go](nubes_provider_gen/internal/resources_gen/dummy_resource.go)
+- [nubes_provider_gen/internal/resources_gen/registry.go](nubes_provider_gen/internal/resources_gen/registry.go)
+
+### Шаг 4. Build
+Команда:
+- `go build -o terraform-provider-nubes`
+
+### Шаг 5. Тесты dummy
+Тестовый конфиг:
+- [nubes_provider_gen/test_persistent/main.tf](nubes_provider_gen/test_persistent/main.tf)
+- [nubes_provider_gen/test_persistent/dev_override.tfrc](nubes_provider_gen/test_persistent/dev_override.tfrc)
+
+Проверены сценарии:
+1. `apply` (create/adopt) — OK
+2. `modify` (duration 750 → 820) — OK
+3. `destroy` (`suspend_on_destroy = true`) — OK
+4. `apply` после suspend (resume/adopt c явным `adopt_existing_on_create`) — OK
+5. удаление ресурса из манифеста + `apply` — OK
+6. возвращение ресурса в манифест + `apply` — OK
+
+---
+
+## Ошибки и как решались
+
+### 1) `action modify not available`
+Причина: в Update использовался `id` из `Plan` (неизвестен).
+Решение: брать `id` из `State`.
+
+### 2) `API error 400: Parameter specified does not belong to this operation`
+Причина: неверные ID параметров modify.
+Решение: для modify использовать `287/288` вместо `198/199`.
+
+### 3) `API error 500: checkParam ... instanceOperationCfsParamUid` (повторно)
+Причина: операция modify требует подстановки всех параметров; без них backend падает.
+Решение:
+- Добавлен `RunInstanceOperationUniversalWithDefaults` — читает `cfsParams` и заполняет недостающие
+- Позже для dummy оказалось нужно отправлять **все** параметры (не только required)
+
+### 4) `TLS handshake timeout`
+Причина: VPN/сеть.
+Решение: повторить команду.
+
+### 5) `status 401`
+Причина: токен истёк/невалидный.
+Решение: заменить токен и сохранить по правилу `/home/naeel/terra/HH-MM-SS.token`.
+
+### 6) Критерий завершения операции (важно)
+Любая операция (create/modify/delete/suspend/resume) считается **завершённой**, когда у неё заполнено **время окончания**.
+Это является признаком завершения **и успеха, и ошибки**. В UI и API ориентируемся на наличие `dtFinish`.
+
+---
+
+## Текущее состояние
+- Провайдер «голый» + ресурсы из YAML работает.
+- `dummy` полностью тестируется из YAML → Go → build.
+- В `resources_gen` присутствует 1 ресурс: `nubes_dummy`.
+
+---
+
+## План (следующий шаг)
+1) Расширить YAML-схему:
+   - поддержку дополнительных параметров (например, failInProgress, whereFail и т.п.)
+   - поддержку optional параметров с явными defaults
+2) Добавить генерацию документации из YAML
+3) Добавить проверку схемы YAML (валидация) перед генерацией
+4) Скрипт "build pipeline":
+   - gen → registry → go build
+5) Опционально: тестовый фреймворк для «batch» тестов
+
+---
+
+## Важные файлы
+- Ядро: [nubes_provider_gen/internal/core/client.go](nubes_provider_gen/internal/core/client.go)
+- Генератор: [nubes_provider_gen/tools/gen/main.go](nubes_provider_gen/tools/gen/main.go)
+- Реестр: [nubes_provider_gen/internal/resources_gen/registry.go](nubes_provider_gen/internal/resources_gen/registry.go)
+- YAML dummy: [nubes_provider_gen/resources_yaml/dummy.yaml](nubes_provider_gen/resources_yaml/dummy.yaml)
+- Сгенерированный ресурс: [nubes_provider_gen/internal/resources_gen/dummy_resource.go](nubes_provider_gen/internal/resources_gen/dummy_resource.go)
+- Тесты: [nubes_provider_gen/test_persistent/main.tf](nubes_provider_gen/test_persistent/main.tf)
+
+---
+
+## MAYDO (отложено до запроса заказчика)
+- Добавить в YAML `outputs` (из `state/out`) и `state_params` (из `state/params`).
+- Добавить `param_meta`: `valueList`, `func`, `refSvcId`, `dataDescriptor`.
+- Добавить `secrets` (из `vault`) с пометкой чувствительных данных.
+- Добавить `operations` (man/описания, доступные операции) для генерации доков.
+- Добавить поддержку `subparams` (nested/list/json) и типизацию сложных структур.
+- Добавить обработку версий операций (если API это отдаёт).