terraform/tf_provider
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
20bb7bc0e9a3327c2282c877f9e3711ad185ca09
tf_provider/prompt_for_ds_pro.md
T
“Naeel” 250a8a6be2 add: HAR traces
2026-06-30 15:46:41 +04:00

15 KiB
Raw Blame History

Запрос на глубокий анализ — Terraform Provider for Nubes Cloud

Контекст

Проект — Terraform Provider для облачной платформы Nubes Cloud (Taffy/Deck API). Провайдер написан на Go с использованием terraform-plugin-framework (SDK v2).

Версия: 5.0.52
Тип: Universal Provider — один core-движок, ресурсы генерируются из YAML-спек.

Структура проекта

Папки (корень: /home/naeel/tf_provider/)

internal/
├── core/               # Универсальный клиент API (client.go, instance_ops.go, instance_lookup.go)
├── provider/           # Реализация провайдера и НЕ-сгенерированных ресурсов (VM, Edge, VDC, VApp, Postgres, S3 и др.)
├── generated/          # Сгенерированные bolvan-ресурсы
└── registrykeys/       # Ключи для GPG-подписи

universal_rebuild/      # Новая универсальная архитектура (ядро, генераторы, YAML-спеки)
├── internal/
│   ├── core/           # Универсальный клиент (client.go) — v6 API flow
│   ├── provider/       # Конфиг провайдера
│   ├── resources_core/ # CRUD-логика (crud.go), хелперы, валидация, реф-параметры
│   └── resources_gen/  # АВТОМАТИЧЕСКИ СГЕНЕРИРОВАННЫЕ ресурсы (~100 файлов)
├── tools/
│   ├── gen/            # Go-генератор (читает YAML → генерирует ресурсы + registry.go)
│   ├── gen_v2/         # Версия 2 генератора
│   ├── service_params_gen/  # YAML-генератор (API → YAML)
│   ├── docs_template_gen/   # Генератор документации
│   └── service_spec_gen/    # Генератор спек
└── resources_yaml/     # YAML-спеки (сейчас только embed.go — встраиваются в бинарник)

devops/                 # Скрипты сборки и деплоя
├── config/
│   ├── services_list.txt           # Список всех сервисов (30+ строк)
│   └── operation_timeouts.json     # Таймауты операций по сервисам
├── 01_generate_yamls.sh           # Шаг 1: YAML из API
├── 02_generate_resources_and_docs*.sh  # Шаг 2: генерация Go + docs
└── 03_build_and_upload_provider.sh     # Шаг 3: сборка + публикация

docs/                   # Документация
├── 00_overview/        # Обзор
├── 20_discovery/       # Discovery сервисов
├── 30_registry/        # Реестр ресурсов
├── 40_analysis/        # Анализы и форензика
├── 50_history/         # История (23 файла — пошагово весь процесс разработки)
├── 60_strategy/        # Стратегия и философия провайдера
├── 70_api/             # API-документация и дампы
└── help/               # Справка

Что уже сделано и известно

Архитектура API (Taffy/Deck)

Базовый URL: https://deck-api.ngcloud.ru/api/v1/index.cfm

Жизненный цикл операции:

  1. POST /instances — создать placeholder инстанса → получаем instanceUid
  2. POST /instanceOperations — создать операцию (create/modify/suspend/resume/delete) → instanceOperationUid
  3. GET /instanceOperations/{uid}?fields=cfsParams — получить схему параметров
  4. POST /instanceOperationCfsParams — отправить значения параметров (каждый параметр по svcOperationCfsParamId)
  5. GET /instanceOperations/{uid}/validate-cfs — валидация
  6. POST /instanceOperations/{uid}/run — запуск операции
  7. GET /instanceOperations/{uid} — поллинг до dtFinish (критерий завершения)

Получение состояния инстанса: GET /instances/{instanceUid} → explainedStatus, isDeleted, availableOperations

Получение списка инстансов: GET /instances?page=N&size=100

Список сервисов (30+)

Сервисы с service_id от 1 до 150:

  • Инфраструктурные: vcOrg(19), vc_vdc(21), vc_nsxt(22), vc_vm(23/27/28), vapp(26), vcexternalip(25), vcVdcGroup(29)
  • Базы данных: postgres(90), mariadb(115), mongodb(92), redis(91), clickhouse(120), vmpostgre(32), kafka(116)
  • Хранилища: s3(12), s3bucket(13)
  • Приложения: nextcloud(50), superset(81), harbor(82), flask(89), lucee(94), nodejs(95), pgadmin(96), nodered(97), http(98), gitea(99), rabbitmq(93), nifi(117), openwhisk(100)
  • DNS: dnszone(110), dnsrecord(111)
  • K8s: k8s_sthutrval_cluster(150)
  • Прочее: dummy(1), template(2), tenant(112), vcComplex(113), GiteaComplex(114), akhq(119), valoTenant(149)

Lifecycle-логика (для сервисов с suspend/resume)

  • Флаги: adopt_existing_on_create (default: false), suspend_on_destroy (default: true)
  • Apply/Create: проверка облака по resource_name → статус-матрица принятия решений
  • Destroy: по умолчанию suspend, при suspend_on_destroy=false — только state
  • Modify: через RunInstanceOperationUniversal с params по svcOperationCfsParamId
  • Replace: запрещён для suspend-сервисов

Проблемы, известные из истории

  1. Case-sensitivity имён (docs/60_strategy/terraform_case_sensitivity_fix.md)
  2. Ref-параметры и валидация на adopt (docs/60_strategy/adopt_ref_validation.md)
  3. VApp UID inconsistency / displayName resolve bug (история 23)
  4. Subresource generation — не все подресурсы корректно генерируются
  5. Params normalisation — CamelCase → snake_case может ломаться
  6. Postgres immutables — некоторые параметры нельзя менять после создания (ForceNew)
  7. Operation timeouts — разные сервисы требуют разных таймаутов
  8. Deleted instances — определение deleted через explainedStatus и isDeleted
  9. Валидация статусов — not created, pending, failed должны блокировать adopt
  10. ResourceAlreadyExists diagnostics — обязательны два варианта в сообщении

Архитектура universal_rebuild (ключевые особенности)

  • Ядро (core): UniversalClient — универсальный клиент, CreateGenericInstanceUniversalV6, RunInstanceOperationUniversal, FindInstanceByDisplayName
  • Resources_core: CreateResource, UpdateResource, DeleteResource, RunOperationByCode — обёртки CRUD с timeout override
  • Resources_gen: ~100 автогенерированных файлов ресурсов (все сервисы)
  • Генераторы: service_params_gen → YAML, gen/gen_v2 → Go код, docs_template_gen → документация
  • YAML-спеки: сейчас встраиваются через embed.go, но есть YAML-генератор

Генерация (devops pipeline)

  1. 01_generate_yamls.sh — получает YAML из API для всех сервисов из services_list.txt
  2. 02_generate_resources_and_docs*.sh — запускает Go-генератор + docs-генератор
  3. 03_build_and_upload_provider.sh — сборка под 3 ОС + GPG-подпись + загрузка в S3
  4. 04_build_and_publish_docs.sh — сборка mkdocs + публикация в S3

Документация

  • MkDocs Material theme
  • Документация генерируется из тех же YAML-спек
  • Публикуется в S3 bucket terraform-registry

Что НУЖНО изучить подробно

1. API: неизвестные эндпойнты и возможности

  • Есть ли другие эндпойнты, кроме задокументированных?
  • Как работает /services/{svcId}/default (deprecated — что вместо)?
  • Есть ли batch-операции?
  • Пагинация: какие лимиты? Есть ли курсор?
  • Rate limiting: есть ли? Какие лимиты?
  • Есть ли эндпойнт для массового получения всех инстансов с параметрами?

2. Параметры сервисов (svcOperationCfsParamId)

Для каждого сервиса:

  • Полный список cfsParams (все операции: create, modify, suspend, resume, delete, action)
  • Какие параметры required, какие optional, какие read-only (outputs)
  • Какие параметры имеют refSvcId (ссылки на другие сервисы)
  • Какие параметры имеют valueList (выпадающие списки)
  • DataType: какие бывают (string, boolean, list, uuid, int, float, json?)
  • Default values — откуда берутся?
  • Какие параметры immutable (create-only)
  • Какие параметры зависят от других (dependency chain)

3. Статусы и состояния инстансов

  • Все возможные значения explainedStatus
  • Все возможные значения isDeleted
  • Матрица переходов (state machine):
    • creating → running
    • running → suspend → running
    • running → deleted
    • failed → ?
    • not created → ?
  • Что происходит при pending / operation in progress?
  • Как долго длятся типичные операции?

4. Операции (kinds и их семантика)

  • kind: instance — полный CRUD
  • kind: subresource — операции внутри инстанса (create_user, delete_database и т.д.)
  • kind: action — одноразовые операции (restart, redeploy, recovery)
  • Для каждого сервиса: какие subresource и action операции доступны?
  • Как subresource идентифицируются? (через parent instanceUid? свой instanceUid?)
  • Есть ли операции, которые не вписываются в схему?

5. Схема YAML-спек

  • Нужно восстановить формат YAML для примера одного-двух сервисов (dummy, postgres, s3bucket)
  • Какие поля обязательны? Какие опциональны?
  • Как описываются operations с kind-ами?
  • Как описываются timeout-ы?
  • Как описываются outputs?
  • Как описываются service_man (руководство пользователя)?
  • Как описываются lifecycle-правила (suspend_on_destroy, adopt_existing_on_create)?

6. Ошибки и проблемы продакшена

  • Все известные баги из истории (23 файла в docs/50_history/)
  • Какие ресурсы сейчас не работают? (VApp UID, Postgres immutables и т.д.)
  • Какие тесты падают или неполны?
  • Есть ли проблемы с GPG-ключами / реестром?
  • Есть ли проблемы с S3-публикацией?

7. Тестовое покрытие

  • Какие тесты написаны в universal_rebuild/internal/resources_core/?
  • Есть ли интеграционные тесты с реальным API?
  • Какие тесты нужны, но отсутствуют?
  • Есть ли моки для API?

8. Безопасность

  • Как управляются токены? Какой механизм refresh?
  • Есть ли поддержка разных эндпойнтов (prod/dev)?
  • Как обрабатываются чувствительные данные (пароли БД, ключи)?
  • Есть ли валидация входящих параметров на injection?

9. Производительность

  • Сколько времени занимает типичный apply?
  • Есть ли узкие места в поллинге?
  • Оптимальные интервалы поллинга для разных операций?
  • Есть ли кэширование?

10. Документация (MkDocs)

  • Как генерируется документация из YAML?
  • Как работает шаблонизация?
  • Что надо исправить/дополнить?

Формат ответа

Пожалуйста, предоставь детальный анализ по каждому из 10 пунктов. Для каждого пункта:

  1. Текущее понимание (что уже известно из контекста)
  2. Пробелы в знаниях (чего не хватает)
  3. Гипотезы (что можно предположить на основе имеющихся данных)
  4. Что нужно сделать (конкретные шаги: какие файлы прочитать, какие API вызвать, какие тесты запустить)
  5. Риски (какие проблемы могут возникнуть)

Особое внимание удели:

  • Формату YAML-спек (п.5) — это основа всей генерации
  • Полному списку cfsParams для топ-10 сервисов (п.2)
  • Матрице состояний (п.3) — критично для lifecycle-логики
  • Ошибкам из истории (п.6) — чтобы не повторять

Если для какого-то пункта информации в предоставленном контексте недостаточно — укажи это и предложи, где искать недостающие данные (какие файлы прочитать, какие curl-запросы выполнить).

Важно: Ничего НЕ ДЕЛАЙ в файловой системе. Никаких изменений кода, файлов, конфигов. Только анализ.

Reference in New Issue View Git Blame Copy Permalink