160 lines
7.4 KiB
Markdown
160 lines
7.4 KiB
Markdown
# Алгоритмы обнаружения ресурсов и параметров API Deck
|
||
|
||
Этот документ описывает последовательность действий для получения полного списка ресурсов и их конфигурационных параметров через API Deck (`https://deck-api.ngcloud.ru/api/v1`).
|
||
|
||
---
|
||
|
||
## 1. Получение списка всех инстансов (Resources)
|
||
|
||
Для получения всех ресурсов, которыми владеет текущий пользователь:
|
||
|
||
1. **Запрос:** `GET /v1/index.cfm/instances`
|
||
2. **Параметры:** `?fields=instanceUid,displayName,serviceId,svc,state,explainedStatus`
|
||
3. **Алгоритм обработки:**
|
||
- Итерировать по массиву `results`.
|
||
- Для каждого инстанса:
|
||
- `instanceUid`: Уникальный ID (используется для импорта в TF).
|
||
- `svc`: Человеческое название типа сервиса.
|
||
- `state.params`: Текущие примененные параметры (Discovery).
|
||
- `state.out`: Выходные данные от оркестратора (IP, имена сетей и т.д.).
|
||
|
||
---
|
||
|
||
## 2. Получение списка доступных типов сервисов (Service Inventory)
|
||
|
||
Для понимания того, какие сервисы в принципе можно создать:
|
||
|
||
1. **Запрос:** `GET /v1/index.cfm/services`
|
||
2. **Результат:** Список объектов сервисов.
|
||
3. **Ключевые поля:**
|
||
- `svcId`: ID сервиса (нужен для создания операций).
|
||
- `svc`: Название (например, "Виртуальный датацентр").
|
||
- `orchestratorName`: Имя бэкенда.
|
||
|
||
---
|
||
|
||
## 3. Обнаружение схемы параметров для сервиса (метод Виталия)
|
||
|
||
> **Это канонический метод получения ВСЕХ параметров, включая подполя map-fixed.**
|
||
> Источник: Виталий Зайцев (DevOps Nubes), 15.07.2026.
|
||
|
||
### Три шага — полный список параметров без создания инстанса:
|
||
|
||
**Шаг 1: найти svcId по имени сервиса**
|
||
```bash
|
||
curl -s -H "Authorization: Bearer $TOKEN" $URL/services | jq '.results[] | select(.svc == "ApacheKafka") | .svcId'
|
||
# → 116
|
||
```
|
||
|
||
**Шаг 2: найти svcOperationId нужной операции**
|
||
```bash
|
||
curl -s -H "Authorization: Bearer $TOKEN" $URL/services/116 | jq '.svc.operations[] | select(.operation == "create") | .svcOperationId'
|
||
# → 148
|
||
```
|
||
|
||
**Шаг 3: получить параметры с подполями и допустимыми значениями**
|
||
```bash
|
||
curl -s -H "Authorization: Bearer $TOKEN" $URL/instanceOperations/default/148 | jq '.svcOperation.cfsParams[]'
|
||
```
|
||
|
||
### Почему `/instanceOperations/default/{id}` а не `/serviceOperation/{id}`:
|
||
|
||
| Данные | `/serviceOperation/{id}` | `/instanceOperations/default/{id}` |
|
||
|--------|--------------------------|-------------------------------------|
|
||
| ID, code, тип, isRequired | ✅ | ✅ |
|
||
| `valueList` (допустимые значения) | ❌ | ✅ `['false','true']`, `['HOT','COLD']` |
|
||
| `dataDescriptor` (подполя map-fixed) | ❌ | ✅ cpu, memory, replicas, disk... |
|
||
| `isModifiable` | ❌ | ✅ на уровне подполей |
|
||
| `regex`, `maxLength`, `minValue`... | ❌ | ✅ |
|
||
| `isSensitive` | ❌ | ✅ |
|
||
|
||
### Структура dataDescriptor (подполя map-fixed):
|
||
|
||
```json
|
||
{
|
||
"svcOperationCfsParamId": 788,
|
||
"svcOperationCfsParam": "clusterConfiguration",
|
||
"dataType": "map-fixed",
|
||
"dataDescriptor": {
|
||
"cpu": {
|
||
"svcOperationCfsSubparamId": 109,
|
||
"dataType": "integer > 0",
|
||
"isRequired": true,
|
||
"valueList": ""
|
||
},
|
||
"replicas": {
|
||
"svcOperationCfsSubparamId": 135,
|
||
"dataType": "integer > 0",
|
||
"isRequired": true,
|
||
"valueList": "1,3,5,7"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Формат valueList:
|
||
|
||
- Для **верхнеуровневых** параметров: JSON-массив `["false", "true"]`
|
||
- Для **подполей** dataDescriptor: comma-separated строка `"1,3,5,7"`
|
||
- Для `boolean`: всегда `"false,true"` или `["false","true"]`
|
||
|
||
### URL для разных стендов:
|
||
|
||
| Стенд | Базовый URL |
|
||
|-------|-------------|
|
||
| test (новый Gateway) | `https://lk-api-gateway-test.ngcloud.ru/api/v1/svc` |
|
||
| test (старый proxy) | `https://deck-api-test.ngcloud.ru/api/v1/index.cfm?endpoint=` |
|
||
| dev | `https://deck-api-dev.ngcloud.ru/api/v1/index.cfm?endpoint=` |
|
||
| prod | `https://deck-api.ngcloud.ru/api/v1/index.cfm?endpoint=` |
|
||
|
||
### Старый метод (через черновик) — НЕ ИСПОЛЬЗОВАТЬ:
|
||
|
||
Ранее использовался паттерн "Черновик операции" (POST /instanceOperations → GET с ?fields=cfsParams).
|
||
Он НЕ даёт dataDescriptor и valueList. Вместо него использовать `/instanceOperations/default/{id}`.
|
||
|
||
---
|
||
|
||
## 4. Маппинг параметров при импорте (Discovery Recipe)
|
||
|
||
При импорте существующего ресурса (Data Source в TF), необходимо сопоставить значения из `instance.state.params` с `svcOperationCfsParamId`.
|
||
|
||
**Прямой связи по ключам нет**, поэтому используется эвристика или ручной маппинг:
|
||
1. Смотрим `instance.state.params` -> находим ключ, например, `vdcUid`.
|
||
2. Смотрим `cfsParams` из Шага 3 -> находим параметр с `label`, похожим на "VDC UUID".
|
||
3. Используем его `svcOperationCfsParamId` для последующих операций `modify`.
|
||
|
||
---
|
||
|
||
## Примеры фильтрации через `curl` и `jq`
|
||
|
||
**Список всех Edge Gateway:**
|
||
```bash
|
||
curl -s -H "Authorization: Bearer $TOKEN" \
|
||
"https://deck-api.ngcloud.ru/api/v1/index.cfm/instances?fields=instanceUid,displayName,serviceId,svc" | \
|
||
jq '.results[] | select(.serviceId == 22)'
|
||
```
|
||
|
||
**Все параметры для создания VM (serviceId 28):**
|
||
```bash
|
||
# 1. Создать черновик
|
||
OP_UID=$(curl -s -H "Authorization: Bearer $TOKEN" -X POST ... -d '{"operation":"create","serviceId":28,"instanceUid":null}' | jq -r .instanceOperationUid)
|
||
|
||
# 2. Прочитать схему
|
||
curl -s -H "Authorization: Bearer $TOKEN" \
|
||
"https://deck-api.ngcloud.ru/api/v1/index.cfm/instanceOperations/$OP_UID?fields=cfsParams" | jq .cfsParams
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Эталонный snapshot реальных Output-полей
|
||
|
||
Сохранён baseline-снимок реальных output-полей по инстансам в статусах `running`/`suspended`:
|
||
|
||
- Каталог: `docs/70_api/output_inventory_snapshot_2026-03-02/`
|
||
- Основной файл для docs: `running_suspended_output_fields_for_docs.json`
|
||
- Описание и сводка: `README.md`
|
||
|
||
Назначение:
|
||
- использовать как шаблон при наполнении страниц `Output params`;
|
||
- затем перепроверять актуальность на live API, так как состав полей в облаке может меняться.
|