terraform/tf_provider
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4c5a61cbbf39aafdc02d50279a1b211aca142f18
tf_provider/docs/00_overview/ai_universal_provider_gen.md
T
“Naeel” ca276d200f add: documentation
2026-06-30 15:45:24 +04:00

9.9 KiB
Raw Blame History

Universal Provider (ядро + генератор ресурсов) — подробный отчёт

Дата: 2026-01-31

Цель

Нужна архитектура «универсального провайдера», где:

  • есть ядро (общий клиент и универсальный флоу операций);
  • есть папка ресурсов (Go-файлы ресурсов);
  • есть папка YAML-описаний сервисов (чтобы DevOps мог добавить сервис одним файлом);
  • есть генератор, который:
    • читает YAML,
    • генерирует ресурсы,
    • генерирует реестр ресурсов,
    • дальше выполняется build (ядро + ресурсы из папки).

В итоге: если файла ресурса нет — в провайдере его не будет. Если YAML изменён — перегенерация.

Итоговая архитектура (v2.0.0, «голое» ядро + ресурсы)

Новая сборка размещена в:

Структура:

1) Ядро (core)

Файл: 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
  • Адрес: terrareg.kube5s.ru/nubes/nubes
  • Ресурсы приходят из реестра:
    • resources_gen.AllResources() — возвращает список функций создания ресурсов.

3) Генератор (tools/gen)

Файл: 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

Минимальная схема (пример 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. «Голое» ядро + генератор

Создан отдельный проект:

Шаг 2. YAML для dummy

Создан YAML dummy: nubes_provider_gen/resources_yaml/dummy.yaml

Шаг 3. Генерация ресурсов

Команда:

  • go run ./tools/gen

Сгенерированы:

Шаг 4. Build

Команда:

  • go build -o terraform-provider-nubes

Шаг 5. Тесты dummy

Тестовый конфиг:

Проверены сценарии:

  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» тестов

Важные файлы

MAYDO (отложено до запроса заказчика)

  • Добавить в YAML outputs (из state/out) и state_params (из state/params).
  • Добавить param_meta: valueList, func, refSvcId, dataDescriptor.
  • Добавить secrets (из vault) с пометкой чувствительных данных.
  • Добавить operations (man/описания, доступные операции) для генерации доков.
  • Добавить поддержку subparams (nested/list/json) и типизацию сложных структур.
  • Добавить обработку версий операций (если API это отдаёт).
Reference in New Issue View Git Blame Copy Permalink