# 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