add: documentation
This commit is contained in:
“Naeel”
@@ -0,0 +1,174 @@
|
||||
# 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` (опц.)
|
||||
|
||||
Пример:
|
||||
```bash
|
||||
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`
|
||||
|
||||
Команда:
|
||||
```bash
|
||||
cd /home/naeel/terra/universal_rebuild
|
||||
go run ./tools/gen/main.go
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5) Build
|
||||
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
NUBES_SERVICE_ID=1 NUBES_SERVICE_NAME=dummy go run ./tools/service_params_gen/main.go
|
||||
```
|
||||
2) Go‑код:
|
||||
```bash
|
||||
go run ./tools/gen/main.go
|
||||
```
|
||||
3) Build:
|
||||
```bash
|
||||
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`**.
|
||||
Reference in New Issue
Block a user