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,542 @@
|
||||
# DATA_STRUCTURE - Структуры данных и схемы
|
||||
|
||||
## JSON Schema: Instance Response
|
||||
|
||||
### Структура инстанса из API
|
||||
|
||||
```json
|
||||
{
|
||||
"instance": {
|
||||
"instanceUid": "0fcbae6c-6a36-4ce8-877d-58733f7c2fef",
|
||||
"displayName": "naeel-wheel",
|
||||
"svc": 1,
|
||||
"code": "S3",
|
||||
"explainedStatus": "running",
|
||||
"resourceRealm": "ceph.tst.nubes.ru",
|
||||
|
||||
"state": {
|
||||
"params": {
|
||||
"resourceCPU": 100,
|
||||
"resourceMemory": 128,
|
||||
"s3UserUid": "abc123...",
|
||||
"displayName": "naeel-wheel",
|
||||
// ... ещё 68 полей
|
||||
},
|
||||
"out": {
|
||||
"bucket_name": "naeel-wheel",
|
||||
"api_endpoint": "https://ceph.tst.nubes.ru",
|
||||
// ... ещё 21 поле
|
||||
}
|
||||
},
|
||||
|
||||
"dependencies": [
|
||||
{
|
||||
"instanceUid": "dep-uid-1",
|
||||
"displayName": "dep-name",
|
||||
"relationType": "PROVISIONING_DEPENDENCY"
|
||||
}
|
||||
],
|
||||
"dependentInstances": [
|
||||
{
|
||||
"instanceUid": "dep-uid-2",
|
||||
"displayName": "dep-name-2",
|
||||
"relationType": "DEPLOYMENT_DEPENDENCY"
|
||||
}
|
||||
],
|
||||
|
||||
"createdAt": "2024-03-15T10:30:52Z",
|
||||
"modifiedAt": "2024-03-20T14:22:01Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Типы данных
|
||||
|
||||
| Поле | Тип | Примеры | Известные значения |
|
||||
|------|-----|---------|-------------------|
|
||||
| `instanceUid` | UUID | `0fcbae6c-6a36-4ce8-877d-58733f7c2fef` | UUID v4 |
|
||||
| `displayName` | string | `naeel-wheel`, `iot-k8s-cluster` | 2-50 символов |
|
||||
| `svc` | number (enum) | 1, 2, 3, ... | Зависит от сервиса |
|
||||
| `code` | string (enum) | S3, PostgreSQL, Redis, ... | 12 известных кодов |
|
||||
| `explainedStatus` | string (enum) | running, deleted, suspended, pending, not_created | 5 значений |
|
||||
| `resourceRealm` | string | `ceph.tst.nubes.ru`, `"N/A"` | Адрес платформы или N/A |
|
||||
| `createdAt` | ISO8601 | `2024-03-15T10:30:52Z` | RFC3339 timestamp |
|
||||
|
||||
---
|
||||
|
||||
## Массивы параметров: Input Parameters (state.params)
|
||||
|
||||
### Категория 1: Infrastructure
|
||||
```json
|
||||
{
|
||||
"resourceCPU": 100,
|
||||
"resourceMemory": 128,
|
||||
"resourceStorage": 1024,
|
||||
"resourceNetwork": "1GbE",
|
||||
"resourceDisk": 50
|
||||
}
|
||||
```
|
||||
|
||||
### Категория 2: Storage References
|
||||
```json
|
||||
{
|
||||
"s3UserUid": "uuid",
|
||||
"s3Uid": "uuid",
|
||||
"s3BucketName": "mybucket",
|
||||
"s3Endpoint": "https://ceph.tst.nubes.ru"
|
||||
}
|
||||
```
|
||||
|
||||
### Категория 3: Network References
|
||||
```json
|
||||
{
|
||||
"vdcUid": "uuid",
|
||||
"organizationUid": "uuid",
|
||||
"edgeUid": "uuid",
|
||||
"networkUid": "uuid",
|
||||
"ipUuid": "uuid"
|
||||
}
|
||||
```
|
||||
|
||||
### Категория 4: Configuration
|
||||
```json
|
||||
{
|
||||
"displayName": "service-name",
|
||||
"description": "Service description",
|
||||
"tags": ["tag1", "tag2"],
|
||||
"labels": {"key": "value"},
|
||||
"environment": "test"
|
||||
}
|
||||
```
|
||||
|
||||
### Категория 5: Integration
|
||||
```json
|
||||
{
|
||||
"postgresHost": "host.domain",
|
||||
"postgresPort": 5432,
|
||||
"postgresDatabase": "dbname",
|
||||
"redisHost": "host",
|
||||
"rabbitmqHost": "host",
|
||||
"rabbitmqPort": 5672
|
||||
}
|
||||
```
|
||||
|
||||
**Полный список всех 72 input параметров**: см. `/doc/api/PARAMETERS_REFERENCE.md`
|
||||
|
||||
---
|
||||
|
||||
## Массивы параметров: Output Parameters (state.out)
|
||||
|
||||
### Категория 1: Service Endpoints
|
||||
```json
|
||||
{
|
||||
"api_endpoint": "https://api.example.com",
|
||||
"dns_name": "service.domain.com",
|
||||
"external_ip": "1.2.3.4",
|
||||
"internal_ip": "10.0.0.x",
|
||||
"port": 443
|
||||
}
|
||||
```
|
||||
|
||||
### Категория 2: Credentials
|
||||
```json
|
||||
{
|
||||
"username": "admin",
|
||||
"password": "***",
|
||||
"access_key": "AKIAXXXXXXX",
|
||||
"secret_key": "***",
|
||||
"auth_token": "token_string"
|
||||
}
|
||||
```
|
||||
|
||||
### Категория 3: Connection Strings
|
||||
```json
|
||||
{
|
||||
"connection_string": "postgresql://...",
|
||||
"db_uri": "postgresql://host:5432/db",
|
||||
"client_url": "redis://host:6379"
|
||||
}
|
||||
```
|
||||
|
||||
### Категория 4: Resource Identifiers
|
||||
```json
|
||||
{
|
||||
"bucket_name": "mybucket",
|
||||
"cluster_id": "k8s-cluster-id",
|
||||
"namespace": "default",
|
||||
"service_id": "svc-123"
|
||||
}
|
||||
```
|
||||
|
||||
### Категория 5: Metadata
|
||||
```json
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"status": "ready",
|
||||
"health": "healthy",
|
||||
"capacity": "100GB"
|
||||
}
|
||||
```
|
||||
|
||||
**Полный список всех 23 output параметров**: см. `/doc/api/PARAMETERS_REFERENCE.md`
|
||||
|
||||
---
|
||||
|
||||
## Dependencies: Структура связей
|
||||
|
||||
### API Dependencies (явные)
|
||||
```json
|
||||
{
|
||||
"dependencies": [
|
||||
{
|
||||
"instanceUid": "dep-uid",
|
||||
"displayName": "dependency-name",
|
||||
"relationType": "PROVISIONING_DEPENDENCY"
|
||||
}
|
||||
],
|
||||
"dependentInstances": [
|
||||
{
|
||||
"instanceUid": "client-uid",
|
||||
"displayName": "client-name",
|
||||
"relationType": "DEPLOYMENT_DEPENDENCY"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Parametric Dependencies (вычисленные)
|
||||
```json
|
||||
[
|
||||
{
|
||||
"from": "naeel-k8s-cluster",
|
||||
"from_uid": "k8s-uid",
|
||||
"to": "naeel-vdc",
|
||||
"to_uid": "vdc-uid",
|
||||
"param": "vdcUid",
|
||||
"category": "Orchestration"
|
||||
},
|
||||
{
|
||||
"from": "dnsA-record",
|
||||
"from_uid": "dns-uid",
|
||||
"to": "naeel-rabbit",
|
||||
"to_uid": "rabbit-uid",
|
||||
"param": "recordName",
|
||||
"category": "DNS Routing"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Полный список 12 parametric dependencies**: см. `/tmp/links.json`
|
||||
|
||||
---
|
||||
|
||||
## Service Type Catalogue
|
||||
|
||||
### 1. S3 Object Storage
|
||||
```json
|
||||
{
|
||||
"code": "S3",
|
||||
"svc": 1,
|
||||
"instances": ["naeel-s3"],
|
||||
"role": "Central storage provider",
|
||||
"input_params": ["resourceCPU", "resourceMemory", "s3UserUid"],
|
||||
"output_params": ["api_endpoint", "bucket_name"],
|
||||
"platforms": ["ceph.tst.nubes.ru"]
|
||||
}
|
||||
```
|
||||
|
||||
### 2. S3 Bucket
|
||||
```json
|
||||
{
|
||||
"code": "S3BUCKET",
|
||||
"svc": 2,
|
||||
"instances": 5,
|
||||
"role": "Data storage",
|
||||
"parents": ["naeel-s3"],
|
||||
"inputs": ["s3Uid", "s3BucketName"]
|
||||
}
|
||||
```
|
||||
|
||||
### 3. PostgreSQL Database
|
||||
```json
|
||||
{
|
||||
"code": "PostgreSQL",
|
||||
"svc": 3,
|
||||
"instances": ["naeel-postgres"],
|
||||
"role": "Relational database",
|
||||
"outputs": ["connection_string", "postgres_host"]
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Redis Cache
|
||||
```json
|
||||
{
|
||||
"code": "Redis",
|
||||
"svc": 4,
|
||||
"instances": ["naeel-redis"],
|
||||
"role": "In-memory cache"
|
||||
}
|
||||
```
|
||||
|
||||
### 5. RabbitMQ Message Broker
|
||||
```json
|
||||
{
|
||||
"code": "RabbitMQ",
|
||||
"svc": 5,
|
||||
"instances": ["naeel-rabbit"],
|
||||
"role": "Message queue"
|
||||
}
|
||||
```
|
||||
|
||||
### 6. Kubernetes Cluster
|
||||
```json
|
||||
{
|
||||
"code": "Kubernetes",
|
||||
"svc": 6,
|
||||
"instances": ["naeel-k8s-cluster"],
|
||||
"role": "Container orchestration",
|
||||
"depends_on": ["vdc", "edge"]
|
||||
}
|
||||
```
|
||||
|
||||
//... остальные 6 типов сервисов
|
||||
|
||||
**Всего 12 типов сервисов**: см. `/doc/api/PARAMETERS_REFERENCE.md#Service-Types`
|
||||
|
||||
---
|
||||
|
||||
## Platform Realms Distribution
|
||||
|
||||
```
|
||||
ceph.tst.nubes.ru:
|
||||
- naeel-s3 (S3 storage hub)
|
||||
- naeel-s3-1 (bucket)
|
||||
- naeel-s3-2 (bucket)
|
||||
- naeel-s3-3 (bucket)
|
||||
- naeel-s3-4 (bucket)
|
||||
- naeel-s3-5 (bucket)
|
||||
Total: 6 instances
|
||||
|
||||
iot-naeel:
|
||||
- mqtt-bridge (MQTT integration)
|
||||
- iot-service (IoT gateway)
|
||||
Total: 2 instances
|
||||
|
||||
naeel-test-3:
|
||||
- naeel-sqs (SQS queue)
|
||||
- naeel-k8s-cluster (Kubernetes)
|
||||
Total: 2 instances
|
||||
|
||||
sandbox.nubes.ru:
|
||||
- naeel-vdc (Virtual Data Center)
|
||||
- naeel-edge (NSX-T Edge)
|
||||
- naeel-postgres (PostgreSQL)
|
||||
- naeel-redis (Redis)
|
||||
- naeel-rabbit (RabbitMQ)
|
||||
- naeel-organization (Organization)
|
||||
Total: 6 instances
|
||||
|
||||
grafana.ngcloud.ru:
|
||||
- grafana-monitoring (Grafana)
|
||||
Total: 1 instance
|
||||
|
||||
N/A (No specific platform):
|
||||
- public-ips-pool
|
||||
- dnsA-records
|
||||
Total: 2 instances
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Request/Response Examples
|
||||
|
||||
### List Instances Request
|
||||
```bash
|
||||
GET /api/v1/index.cfm/instances?page=1&size=100
|
||||
Authorization: Bearer eyJhbGc...
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
### List Instances Response (200 OK)
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
"instanceUid": "0fcbae6c-...",
|
||||
"displayName": "naeel-wheel",
|
||||
"svc": 1,
|
||||
"code": "S3",
|
||||
"explainedStatus": "running",
|
||||
"resourceRealm": "ceph.tst.nubes.ru"
|
||||
},
|
||||
// ... до 100 инстансов
|
||||
],
|
||||
"page": 1,
|
||||
"size": 100,
|
||||
"total": 136
|
||||
}
|
||||
```
|
||||
|
||||
### Get Instance Details Request
|
||||
```bash
|
||||
GET /api/v1/index.cfm/instances/{instanceUid}
|
||||
Authorization: Bearer eyJhbGc...
|
||||
```
|
||||
|
||||
### Get Instance Details Response (200 OK)
|
||||
```json
|
||||
{
|
||||
"instance": {
|
||||
"instanceUid": "0fcbae6c-...",
|
||||
"displayName": "naeel-wheel",
|
||||
"state": {
|
||||
"params": { /* 72 параметров */ },
|
||||
"out": { /* 23 параметра */ }
|
||||
},
|
||||
"dependencies": [ /* API-based */ ],
|
||||
"dependentInstances": [ /* API-based */ ]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Error Response (401 Unauthorized)
|
||||
```json
|
||||
{
|
||||
"message": "invalid token format: JWT must consist of exactly three parts separated by dots",
|
||||
"requestId": "4c86f7321aaa4ed509b9205ece64e2d3",
|
||||
"statusCode": 401
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Files Reference
|
||||
|
||||
### `/tmp/all_instances.json` (Full list)
|
||||
- 136 инстансов (all states)
|
||||
- Fields: instanceUid, displayName, svc, code, explainedStatus, resourceRealm
|
||||
- ~280 KB
|
||||
- Updated: при каждом запуске скрипта
|
||||
|
||||
### `/tmp/all_params.json` (Filtered running)
|
||||
- 18 инстансов в статусе "running"
|
||||
- Полные параметры: state.params + state.out
|
||||
- 72 input + 23 output параметров
|
||||
- ~420 KB
|
||||
- Updated: при каждом запуске скрипта
|
||||
|
||||
### `/tmp/links.json` (Dependencies)
|
||||
- 12 parametric dependency links
|
||||
- Fields: from, from_uid, to, to_uid, param, category
|
||||
- ~8 KB
|
||||
- Updated: при каждом запуске скрипта
|
||||
|
||||
### `/doc/api/all_instances_params.json` (Backup)
|
||||
- Копия `/tmp/all_params.json` для длительного хранения
|
||||
- Same structure
|
||||
- ~420 KB
|
||||
- Manual backup
|
||||
|
||||
---
|
||||
|
||||
## Типы данных в разрезе по сервисам
|
||||
|
||||
### S3 Hub (naeel-s3)
|
||||
```
|
||||
Input Params (Example):
|
||||
- resourceCPU: 100
|
||||
- resourceMemory: 128
|
||||
- s3UserUid: xxxxx
|
||||
|
||||
Output Params (Example):
|
||||
- api_endpoint: https://ceph.tst.nubes.ru
|
||||
- bucket_name_prefix: naeel-s3
|
||||
```
|
||||
|
||||
### PostgreSQL (naeel-postgres)
|
||||
```
|
||||
Input Params (Example):
|
||||
- resourceCPU: 500
|
||||
- resourceMemory: 1024
|
||||
- resourceStorage: 50000
|
||||
- postgresDatabase: "sless_prod"
|
||||
|
||||
Output Params (Example):
|
||||
- connection_string: postgresql://admin:***@host:5432/sless_prod
|
||||
- postgresHost: postgres.naeel.svc
|
||||
- postgresPort: 5432
|
||||
```
|
||||
|
||||
### Kubernetes (naeel-k8s-cluster)
|
||||
```
|
||||
Input Params (Example):
|
||||
- resourceCPU: 4000
|
||||
- resourceMemory: 8192
|
||||
- vdcUid: vdc-uuid
|
||||
- edgeUid: edge-uuid
|
||||
|
||||
Output Params (Example):
|
||||
- cluster_id: k8s-test-3
|
||||
- kubeconfig: base64-encoded
|
||||
- api_endpoint: https://k8s-api:6443
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Critical Data Points
|
||||
|
||||
### Single Points of Failure
|
||||
1. **naeel-s3** (S3 Hub)
|
||||
- Если упадёт → 5 bucket'ов станут недоступны
|
||||
- Impact: HIGH
|
||||
|
||||
2. **naeel-vdc** (Virtual DC)
|
||||
- Если упадёт → 1 edge + 1 k8s станут недоступны
|
||||
- Impact: HIGH
|
||||
|
||||
3. **naeel-postgres** (Database)
|
||||
- Если упадёт → 6+ сервисов потеряют данные
|
||||
- Impact: CRITICAL
|
||||
|
||||
4. **naeel-k8s-cluster** (Container Orchestration)
|
||||
- Если упадёт → IoT сервисы остановятся
|
||||
- Impact: HIGH
|
||||
|
||||
### Параметры, требующие синхронизации
|
||||
```json
|
||||
{
|
||||
"sync_required": [
|
||||
{
|
||||
"param": "vdcUid",
|
||||
"who_has": ["naeel-k8s-cluster", "naeel-edge"],
|
||||
"what_references": "naeel-vdc",
|
||||
"risk": "Несинхронизированность → broken links in cluster"
|
||||
},
|
||||
{
|
||||
"param": "s3Uid",
|
||||
"who_has": ["все 5 buckets"],
|
||||
"what_references": "naeel-s3",
|
||||
"risk": "Orphaned buckets if s3 params changed"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Статистика данных
|
||||
|
||||
- **Total Instances**: 136
|
||||
- **Running Instances**: 18
|
||||
- **Input Parameters per Instance**: ~4 (среднее)
|
||||
- **Output Parameters per Instance**: ~1.3 (среднее)
|
||||
- **Total Unique Input Key Names**: 72
|
||||
- **Total Unique Output Key Names**: 23
|
||||
- **Parametric Dependencies**: 12
|
||||
- **API Dependencies**: ~4 (average)
|
||||
- **Average Response Time**: 150ms
|
||||
- **Max Response Time**: 5000ms (PostgreSQL)
|
||||
- **Service Types**: 12
|
||||
- **Deployment Platforms**: 6
|
||||
- **Instances with Unknown Platform**: 2
|
||||
|
||||
Reference in New Issue
Block a user