227 lines
15 KiB
Markdown
227 lines
15 KiB
Markdown
# Запрос на глубокий анализ — 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-запросы выполнить).
|
||
|
||
**Важно:** Ничего НЕ ДЕЛАЙ в файловой системе. Никаких изменений кода, файлов, конфигов. Только анализ.
|