58 lines
3.9 KiB
Markdown
58 lines
3.9 KiB
Markdown
<!-- ⛔ LEGACY: deck-api.ngcloud.ru ЗАКРЫВАЕТСЯ. Актуальный API: lk-api-gateway.ngcloud.ru/api/v1/svc -->
|
||
# Архитектура и методы (CRUD)
|
||
|
||
## 1. Актуальная архитектура (универсальный rebuild)
|
||
- Ядро: universal_rebuild/internal/core (универсальный клиент API, общий flow операций).
|
||
- Провайдер: universal_rebuild/internal/provider (schema, конфигурация, подключение ресурсов).
|
||
- YAML-спеки сервисов: universal_rebuild/resources_yaml (источник истины).
|
||
- Генератор Go-ресурсов: universal_rebuild/tools/gen (читает YAML, генерирует ресурсы и реестр).
|
||
|
||
Ключевое правило: новая логика — только новые функции/файлы. Существующий Go-код не менять без согласования.
|
||
|
||
## 2. Источник параметров (discovery)
|
||
Параметры сервиса извлекаются через proxy endpoint API:
|
||
- /index.cfm?endpoint=/services/{svcId}
|
||
- /index.cfm?endpoint=/serviceOperation/{svcOperationId}
|
||
- (опц.) /index.cfm?endpoint=/param-value-list/{svcOperationCfsParamId}
|
||
|
||
Схема: сервис → операции → CFS параметры → YAML → генерация Go.
|
||
|
||
## 3. Универсальный Create (7 шагов)
|
||
1) POST /instances → instanceUid
|
||
2) POST /instanceOperations (create) → instanceOperationUid
|
||
3) GET /instanceOperations/{uid}?fields=cfsParams
|
||
4) POST /instanceOperationCfsParams для каждого параметра
|
||
5) GET /instanceOperations/{uid}/validate-cfs
|
||
6) POST /instanceOperations/{uid}/run с payload {}
|
||
7) Polling до завершения операции
|
||
|
||
Критично: параметры отправляются все, включая дефолты, иначе бэкенд может упасть на валидации.
|
||
|
||
## 4. Read/Adopt
|
||
- При isDeleted или explainedStatus=deleted — state очищается.
|
||
- При статусе `running` adopt допускается только при `adopt_existing_on_create=true`.
|
||
- При статусе `suspend` допускается `resume` только при совпадении основных параметров.
|
||
- Предупреждения показываются только на create и не мешают managed ресурсам.
|
||
|
||
## 5. Update/Modify
|
||
- IDs параметров на modify отличаются от create.
|
||
- Нельзя хардкодить ID, нужно получать manifest операции и строить маппинг.
|
||
- Если modify отсутствует в availableOperations — выдавать ясную ошибку.
|
||
|
||
## 6. Polling (железные правила)
|
||
- Завершение операции определяется только по dtFinish.
|
||
- После dtFinish результат определяется isSuccessful.
|
||
- Для VM применяется двойной контроль: статус операции + статус инстанса (ERROR/STOPPED).
|
||
|
||
## 7. Нормализация типов
|
||
- map/json → "{}"
|
||
- list/array → "[]"
|
||
- Пустые строки в JSON-параметрах запрещены (валидаторы на plan).
|
||
|
||
## 8. Soft Delete и карантин
|
||
- Для тяжёлых ресурсов delete часто заменён на suspend с периодом удержания.
|
||
- Для сервисов с `suspend`/`resume` действует флаг `suspend_on_destroy`:
|
||
- `true` (default) -> выполнять `suspend`;
|
||
- `false` -> удалять только из Terraform state (без API-вызова).
|
||
- Повторный apply при `suspend` может выполнять `resume` только при совпадении ключевых параметров.
|