doc: Complete session analysis documentation with all details and errors
- Added ERRORS_SOLUTIONS.md (12 detailed error cases with root causes) - Added DATA_STRUCTURE.md (JSON schemas, type definitions, examples) - Added NEXT_STEPS.md (roadmap priorities 1-4 with implementation notes) - Added INDEX.md (navigation guide for future agents) Total documentation: - 6 markdown files (~2360 lines) explaining entire session - Covers all 6 phases of work - Includes workflow, errors, fixes, architecture findings - Reference for any future agent to understand and continue work Session now fully documented for handoff.
This commit is contained in:
Repinoid
@@ -0,0 +1,374 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user