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)

**Ответ**:
```json
{
  "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}
```

**Ответ**:
```json
{
  "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)

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

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

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

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

### Параметры S3

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

### Параметры K8s

```json
{
  "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 версия
  }
}
```

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

```json
{
  "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)

### Подключение

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

### DNS & Сеть

```json
{
  "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": "..."}
  }
}
```

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

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

### Мониторинг

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

### Управление

```json
{
  "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