tf_provider/docs/70_api/api-discovery-algorithms.md

Алгоритмы обнаружения ресурсов и параметров 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 по имени сервиса

curl -s -H "Authorization: Bearer $TOKEN" $URL/services | jq '.results[] | select(.svc == "ApacheKafka") | .svcId'
# → 116

Шаг 2: найти svcOperationId нужной операции

curl -s -H "Authorization: Bearer $TOKEN" $URL/services/116 | jq '.svc.operations[] | select(.operation == "create") | .svcOperationId'
# → 148

Шаг 3: получить параметры с подполями и допустимыми значениями

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):

{
  "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:

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):

# 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, так как состав полей в облаке может меняться.