sless/SESSION_ANALYSIS_2026-04-13/API_FINDINGS.md

API FINDINGS - Что открыл об API

Endpoint'ы Deck API

1. Основной список инстансов

GET https://deck-api-test.ngcloud.ru/api/v1/index.cfm/instances?page=1&size=100

Параметры:

• page — номер страницы (начиная с 1)
• size — количество результатов на странице (макс 200)

Ответ:

{
  "results": [
    {
      "instanceUid": "uuid-string",
      "displayName": "имя инстанса",
      "svc": "тип сервиса",
      "code": "код",
      "explainedStatus": "running|deleted|suspended|pending|not created",
      "resourceRealmCnt": число,
      "isCreated": boolean,
      "isDeleted": boolean,
      "dependencies": ["uuid-1", "uuid-2"],
      "dependentInstances": ["uuid-3"]
    }
  ]
}

Пагинация:

• Максимум 200 результатов на странице
• Нужно итерировать по page чтобы получить все
• Всего инстансов в системе: 136 (на момент анализа)

---

2. Детали конкретного инстанса

GET https://deck-api-test.ngcloud.ru/api/v1/index.cfm/instances/{instanceUid}

Ответ:

{
  "instance": {
    "instanceUid": "full-uuid",
    "displayName": "name",
    "serviceId": число,
    "svc": "service type",
    "code": "service code",
    "resourceRealm": "platform (or N/A)",
    "explainedStatus": "running|...",
    "state": {
      "creatorId": число,
      "dtState": "ISO timestamp",
      "isTest": boolean,
      "params": {
        // INPUT PARAMETERS (72 уникальных ключа)
        "resourceCPU": число,
        "resourceMemory": число,
        "resourceDisk": "строка",
        // ... ещё параметры
      },
      "out": {
        // OUTPUT PARAMETERS (23 уникальных ключа)
        "monitoring": { /* nested */ },
        "urlConnect": "строка",
        "externalIp": "IP",
        // ... ещё параметры
      }
    },
    "dependencies": ["uuid"],
    "dependentInstances": ["uuid"]
  },
  "runDurationMs": число
}

---

Типы сервисов (svc field)

S3 услуги

• S3 Object Storage — корневой S3 сервис (1)
• S3 бакет — контейнер для данных (5 у нас)

Базы данных

• PostgreSQL — реляционная БД (1)
• Redis — кэш в памяти (1)

Message Queue

• RabbitMQ — message broker (1)

Контейнеризация

• Kubernetes кластер Штурвал — K8s кластер (1)

Инфраструктура

• Организация в Cloud Director — Organization (1)
• Виртуальный датацентр (vDC) — Virtual DC (1)
• Сетевой шлюз периметра (Edge) — NSX-T Edge (1)
• Публичные IP адреса — Public IPs (1)

Мониторинг & Network

• Тенант в Grafana — Monitoring tenant (1)
• DNS запись — DNS records (2)

---

Платформы развёртывания (resourceRealm)

resourceRealm — это K8s кластер или платформа, на которой работает сервис

Известные платформы

Платформа	Инстансы	Тип
ceph.tst.nubes.ru	naeel-s3 (1)	S3 Storage
iot-naeel	Redis, PostgreSQL (2)	IoT K8s
naeel-test-3	RabbitMQ (1)	SQS K8s
sandbox.nubes.ru	Organization, vIP (2)	Cloud Director
grafana.ngcloud.ru	Grafana Tenant (1)	Monitoring
N/A	S3 Buckets, vDC, Edge, K8s, DNS (10)	Unknown

Замечание: Некоторые инстансы имеют resourceRealm = N/A — это либо абстрактные ресурсы, либо информация недоступна через API.

---

Input параметры (всего 72)

Ресурсные параметры (встречаются часто)

{
  "resourceCPU": число,              // в миллиядрах (1000 = 1 CPU)
  "resourceMemory": число,           // в МБ
  "resourceDisk": "строка",          // в ГБ
  "resourceRealm": "платформа",      // K8s кластер
  "resourceInstances": число         // количество реплик
}

Флаги и конфигурация

{
  "enablePgPooler": boolean,         // Connection pooling
  "needExternalAddress": boolean,    // Требуется внешний IP
  "autoScale": boolean,              // Автомасштабирование
  "isTrial": boolean                 // Пробный период
}

Параметры S3

{
  "s3UserUid": "uuid",               // Родительский S3 user
  "bucketName": "строка",            // Имя bucket'а
  "maxSizeGbPerUser": "число",       // Макс размер на пользователя
  "maxBucketsPerUser": число,        // Макс buckets на пользователя
  "placement": "COLD|HOT"            // Размещение данных
}

Параметры K8s

{
  "controlPlaneConfiguration": {     // Master nodes
    "count": "3",
    "sizingPolicy": "TKG 4CPU 8GB",
    "sizingDisk": "50"
  },
  "workerConfiguration": [           // Worker nodes
    {
      "count": "3",
      "groupName": "workers",
      "sizingPolicy": "TKG 4CPU 8GB",
      "sizingDisk": "50"
    }
  ],
  "clusterConfiguration": {
    "appVersion": "2.12.1"           // K8s версия
  }
}

Параметры инфраструктуры

{
  "vdcUid": "uuid",                  // VDC, в котором сервис
  "organizationUid": "uuid",         // Organization
  "networkProvider": "nsxt",         // Сетевой провайдер (NSX-T)
  "ipSpaceName": "internet-ipv4-v1", // IP pool для VM'ок
  "vIPConfigure": [                  // Virtual IP config
    {"name": "internet-ipv4-v1", "count": "10"}
  ]
}

---

Output параметры (всего 23)

Подключение

{
  "urlConnect": "https://url.com",           // Где подключаться
  "httpConnect": "http://realm/resource",    // HTTP endpoint
  "webUrl": "https://...",                   // Web dashboard
  "externalIp": "185.247.187.154"            // Публичный IP
}

DNS & Сеть

{
  "dnsServers": ["8.8.8.8", "8.8.4.4"],     // DNS серверы
  "record": "admin.example.com",              // DNS запись
  "internalConnect": {                        // Внутреннее подключение
    "master": "hostname.svc.cluster.local",
    "slave": ""
  },
  "externalConnect": {                        // Внешнее подключение
    "master": {"ip": "...", "fqdn": "...", "port": "..."},
    "slave": {"ip": "...", "fqdn": "...", "port": "..."}
  }
}

Адреса сервисов

{
  "kubernetesApiAddress": "185.247.187.146",  // K8s API
  "ingressAddress": "185.247.187.147",        // Ingress controller
  "clusterDomain": "cluster.local"            // K8s domain
}

Мониторинг

{
  "monitoring": {
    "resourceMetrics": "https://grafana.ngcloud.ru/d/...",
    "base": "...",
    "loki": "...",
    "pdu": {...}
  },
  "connectionUrl": "https://grafana.ngcloud.ru/?orgId=962"
}

Управление

{
  "isTrial": true,                           // Пробный период
  "dtStartTrial": "2026-03-13T18:16:11+0300",
  "dtEndTrial": "2026-03-27T18:16:11+0300",
  "vdcName": "WZ03709-iaas-sandbox-v1cl1-pvdc-ywmmd",  // VDC name
  "nsxName": "nsx_WZ03709-iaas-h67go75t",    // NSX-T name
  "routedNet": "routed_WZ03709-iaas-..."     // Сеть
}

---

Параметрические зависимости (12 штук)

Hub-and-Spoke (S3)

From	Param	To	Type
S3-Bucket-1-5	s3UserUid	naeel-s3	Owner ref
poc-s3event	s3UserUid	naeel-s3	Owner ref
PostgreSQL	s3Uid	naeel-s3	Integration

Паттерн: 5 S3 buckets + 1 PostgreSQL ссылаются на корневой S3 service

Infrastructure Chain

From	Param	To	Type
Edge-Gateway	vdcUid	Virtual-DC	Ownership
Virtual-DC	organizationUid	Organization	Hierarchy

Паттерн: Иерархическая структура

K8s Orchestration

From	Param	To	Type
K8s-Cluster	startupConfiguration.vdcUid	Virtual-DC	Deployment
K8s-Cluster	startupConfiguration.nsxtUid	Edge-Gateway	Network

Паттерн: K8s требует две инструкции для инициализации

Data Integration

From	Param	To	Type
S3-Bucket	bucketName	PostgreSQL	DataSource

Паттерн: Bucket используется как источник данных для БД

Routing

From	Param	To	Type
DNS-Record	recordName	RabbitMQ	Routing

Паттерн: DNS указывает на service

---

Критичные точки отказа

🔴 CRITICAL: naeel-s3 (S3 Hub)

• Если упадёт: 6 инстансов потеряют функциональность
• Восстановление: Требуется восстановление ceph кластера
• Влияние: 35% архитектуры

🔴 CRITICAL: Edge-Gateway + Virtual-DC

• Если упадёт: K8s потеряет сетевую инструкцию
• Восстановление: Требуется восстановление vCloud Director
• Влияние: Все новые VM'ки и контейнеры

🟠 HIGH: Organization

• Если упадёт: Потеря управления
• Восстановление: Требуется восстановление Cloud Director
• Влияние: Нельзя создавать новые ресурсы

🟠 HIGH: PostgreSQL

• Если упадёт: Потеря данных IoT
• Восстановление: Требуется восстановление из backup
• Влияние: Потеря исторических данных

---

HTTP Header'ы

Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

Токен должен быть valido:

• JWT формат (3 части через точки)
• Не истекший (проверить exp claim в payload)

---

Rate Limits

• Наблюдалось: Нет явных rate limits
• Рекомендация: Добавить небольшие задержки между запросами при массовых операциях
• Timeout: Установить 5-10 сек для медленных инстансов

---

Последнее обновление: 2026-04-13