374 lines
12 KiB
Markdown
374 lines
12 KiB
Markdown
<!-- ⛔ LEGACY: deck-api.ngcloud.ru ЗАКРЫВАЕТСЯ. Актуальный API: lk-api-gateway.ngcloud.ru/api/v1/svc -->
|
|
# Матрица состояний ресурсов в облаке ngcloud
|
|
|
|
## Основные параметры состояния
|
|
|
|
### 1. В структуре инстанса (instance object)
|
|
|
|
Каждый ресурс имеет следующие флаги:
|
|
|
|
| Параметр | Тип | Возможные значения | Описание |
|
|
|----------|-----|------------------|---------|
|
|
| `explainedStatus` | string | `running`, (другие?) | Основной объяснительный статус |
|
|
| `isCreated` | boolean | `true`, `false` | Был ли инстанс создан |
|
|
| `isDeleted` | boolean | `true`, `false` | Отмечен ли как удаленный |
|
|
| `isSuspended` | boolean | `true`, `false` | Приостановлен ли |
|
|
| `operationIsInProgress` | boolean | `true`, `false` | Идет ли корректная операция |
|
|
| `operationIsPending` | boolean | `true`, `false` | Есть ли ожидающие операции |
|
|
| `uptime` | number | >= 0 | Время работы в секундах (0, если не создан) |
|
|
|
|
### 2. Структура state (instanceState object)
|
|
|
|
```json
|
|
{
|
|
"state": {
|
|
"instanceStateUid": "uuid",
|
|
"version": 1, // версия состояния
|
|
"dtState": "timestamp", // дата состояния
|
|
"isTest": boolean
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. Операции (operations array)
|
|
|
|
```json
|
|
{
|
|
"operation": "create|modify|delete|suspend|resume",
|
|
"dtSubmit": "timestamp",
|
|
"dtStart": null, // null если еще не началась
|
|
"dtFinish": null, // null если еще не закончилась
|
|
"isSuccessful": null|true|false, // null если не выполнялась
|
|
"isInProgress": boolean,
|
|
"isPending": boolean,
|
|
"submitResult": "201|..." // HTTP статус результата отправки
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## МАТРИЦА СОСТОЯНИЙ
|
|
|
|
### ✅ СОСТОЯНИЕ: АКТИВНЫЙ РАБОЧИЙ ИНСТАНС (RUNNING)
|
|
```
|
|
isCreated=true
|
|
isDeleted=false
|
|
isSuspended=false
|
|
explainedStatus="running"
|
|
operationIsInProgress=false
|
|
operationIsPending=false
|
|
uptime > 0
|
|
state.version >= 1
|
|
```
|
|
**Значение:** Ресурс создан, работает, нет выполняющихся операций
|
|
|
|
---
|
|
|
|
### 🔄 СОСТОЯНИЕ: СОЗДАНИЕ В ПРОЦЕССЕ (CREATING)
|
|
```
|
|
isCreated=true (или может быть false на ранних стадиях)
|
|
isDeleted=false
|
|
isSuspended=false
|
|
operationIsInProgress=true
|
|
operationIsPending=false
|
|
state.version = 1
|
|
operations[0].operation = "create"
|
|
operations[0].isSuccessful = null (еще не завершено)
|
|
operations[0].dtStart != null
|
|
operations[0].dtFinish = null
|
|
```
|
|
**Значение:** Операция создания выполняется
|
|
|
|
---
|
|
|
|
### ⏸️ СОСТОЯНИЕ: ПРИОСТАНОВЛЕН (SUSPENDED)
|
|
```
|
|
isCreated=true
|
|
isDeleted=false
|
|
isSuspended=true
|
|
explainedStatus="suspended" (или может быть другое)
|
|
operationIsInProgress=false
|
|
```
|
|
**Значение:** Ресурс создан, но приостановлен (власт нет - suspend)
|
|
|
|
---
|
|
|
|
### ⏸️ СОСТОЯНИЕ: ПРИОСТАНОВКА В ПРОЦЕССЕ (SUSPENDING)
|
|
```
|
|
isCreated=true
|
|
isSuspended=false (еще не приостановлен)
|
|
operationIsInProgress=true
|
|
operations[last].operation = "suspend"
|
|
operations[last].isSuccessful = null
|
|
```
|
|
**Значение:** Операция приостановки выполняется
|
|
|
|
---
|
|
|
|
### ▶️ СОСТОЯНИЕ: ВОЗОБНОВЛЕНИЕ В ПРОЦЕССЕ (RESUMING)
|
|
```
|
|
isCreated=true
|
|
isSuspended=true (еще приостановлен)
|
|
operationIsInProgress=true
|
|
operations[last].operation = "resume"
|
|
operations[last].isSuccessful = null
|
|
```
|
|
**Значение:** Операция возобновления выполняется
|
|
|
|
---
|
|
|
|
### ❌ СОСТОЯНИЕ: НЕ СОЗДАН (NOT CREATED)
|
|
```
|
|
isCreated=false
|
|
isDeleted=false
|
|
isSuspended=false
|
|
state = null или пуст
|
|
uptime = 0
|
|
version = null или отсутствует
|
|
```
|
|
**Значение:** Ресурс был определен в коде, но никогда не создавался в облаке
|
|
|
|
---
|
|
|
|
### 🗑️ СОСТОЯНИЕ: УДАЛЕН (DELETED)
|
|
```
|
|
isDeleted=true
|
|
isCreated=true (был когда-то создан)
|
|
state.version может быть или не быть
|
|
```
|
|
**Значение:** Ресурс был удален, может оставаться в истории
|
|
|
|
---
|
|
|
|
### 🔄 СОСТОЯНИЕ: УДАЛЕНИЕ В ПРОЦЕССЕ (DELETING)
|
|
```
|
|
isCreated=true
|
|
isDeleted=false (еще не отмечен как удаленный)
|
|
operationIsInProgress=true
|
|
operations[last].operation = "delete"
|
|
operations[last].isSuccessful = null
|
|
```
|
|
**Значение:** Операция удаления выполняется
|
|
|
|
---
|
|
|
|
### 🔧 СОСТОЯНИЕ: ИЗМЕНЕНИЕ В ПРОЦЕССЕ (MODIFYING)
|
|
```
|
|
isCreated=true
|
|
isDeleted=false
|
|
operationIsInProgress=true
|
|
operations[last].operation = "modify"
|
|
operations[last].isSuccessful = null
|
|
```
|
|
**Значение:** Конфигурация ресурса изменяется
|
|
|
|
---
|
|
|
|
### ⏳ СОСТОЯНИЕ: ОПЕРАЦИЯ ОЖИДАЕТ (PENDING)
|
|
```
|
|
operationIsPending=true
|
|
operationIsInProgress=false
|
|
operations[last].dtStart = null (еще не началась, но создана)
|
|
operations[last].isSuccessful = null
|
|
```
|
|
**Значение:** Операция создана, но еще не началась (в очереди)
|
|
|
|
---
|
|
|
|
### ⚠️ СОСТОЯНИЕ: ОШИБКА ОПЕРАЦИИ (OPERATION_FAILED)
|
|
```
|
|
operations[last].isSuccessful=false
|
|
operations[last].dtFinish != null
|
|
operations[last].errorLog != null
|
|
operationIsInProgress=false
|
|
```
|
|
**Значение:** Последняя операция завершилась с ошибкой
|
|
|
|
---
|
|
|
|
### 🔀 СОСТОЯНИЕ: ГИБРИДНОЕ/ПЕРЕХОДНОЕ (HYBRID)
|
|
|
|
**Противоречивые комбинации указывают на переходное состояние:**
|
|
- `operationIsInProgress=true` + `operations[last].dtStart=null` → операция только создана, еще не началась
|
|
- `isCreated=true` + `operationIsPending=true` → есть ожидающая операция
|
|
- `state.version=null` + `isCreated=true` → некорректное состояние
|
|
|
|
---
|
|
|
|
## АЛГОРИТМ ОПРЕДЕЛЕНИЯ СОСТОЯНИЯ
|
|
|
|
### На уровне API (GET /api/v1/index.cfm/instances/{uid})
|
|
|
|
```python
|
|
def get_instance_state(instance_data):
|
|
"""
|
|
instance_data = {
|
|
'isCreated': bool,
|
|
'isDeleted': bool,
|
|
'isSuspended': bool,
|
|
'explainedStatus': str,
|
|
'operationIsInProgress': bool,
|
|
'operationIsPending': bool,
|
|
'uptime': float,
|
|
'state': {...} or null,
|
|
'operations': [...]
|
|
}
|
|
"""
|
|
|
|
# Шаг 1: Проверка удаления
|
|
if instance_data['isDeleted']:
|
|
return 'DELETED'
|
|
|
|
# Шаг 2: Проверка создания
|
|
if not instance_data['isCreated']:
|
|
return 'NOT_CREATED'
|
|
|
|
# Шаг 3: Проверка операции в процессе
|
|
if instance_data['operationIsInProgress']:
|
|
last_op = instance_data['operations'][-1] if instance_data['operations'] else None
|
|
if last_op:
|
|
operation_type = last_op.get('operation', 'unknown')
|
|
return f'{operation_type.upper()}_IN_PROGRESS'
|
|
|
|
# Шаг 4: Проверка ожидающей операции
|
|
if instance_data['operationIsPending']:
|
|
last_op = instance_data['operations'][-1] if instance_data['operations'] else None
|
|
if last_op and not last_op.get('dtStart'):
|
|
return 'OPERATION_PENDING'
|
|
|
|
# Шаг 5: Проверка приостановки
|
|
if instance_data['isSuspended']:
|
|
return 'SUSPENDED'
|
|
|
|
# Шаг 6: Проверка основного статуса
|
|
if instance_data['explainedStatus'] == 'running':
|
|
return 'RUNNING'
|
|
|
|
# Шаг 7: Проверка ошибок в операциях
|
|
if instance_data['operations']:
|
|
last_op = instance_data['operations'][-1]
|
|
if last_op.get('isSuccessful') == False:
|
|
return 'OPERATION_FAILED'
|
|
|
|
return 'UNKNOWN'
|
|
```
|
|
|
|
---
|
|
|
|
## РЕКОМЕНДУЕМЫЕ ЗАПРОСЫ К API
|
|
|
|
### Получить список ресурсов определенного типа
|
|
|
|
```bash
|
|
GET /api/v1/index.cfm/instances?fields=instanceConfigDtCreated,instanceUid,displayName,svc,uptime,explainedStatus,svcExtendedName,updaterLogin,updaterShortname,operationIsInProgress,operationIsPending,monitoringUrl&search={resource_name}&isAuxiliary=false&isDeleted=false
|
|
```
|
|
|
|
### Получить полную информацию о ресурсе
|
|
|
|
```bash
|
|
GET /api/v1/index.cfm/instances/{instance_uid}?fields=instanceConfigDtCreated,instanceUid,displayName,descr,svc,state,operations,availableOperations,uptime,isDeleted,updaterLogin,updaterShortname,explainedStatus,man,dependencies,dependentInstances,svcExtendedName
|
|
```
|
|
|
|
### Выполнить операцию
|
|
|
|
```bash
|
|
POST /api/v1/index.cfm/instanceOperations
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"instanceUid": "uuid",
|
|
"operation": "create|modify|delete|suspend|resume"
|
|
}
|
|
```
|
|
|
|
### Получить статус операции
|
|
|
|
```bash
|
|
GET /api/v1/index.cfm/instanceOperations/{operation_uid}?fields=instanceOperationUid,instanceUid,state,stages,cfsParams,isSuccessful,dtCreated,dtUpdated,dtStart,dtFinish,operation,svcOperationId,svc,displayName,submitResult,duration,errorLog,updaterShortname,man,nestedRefData,isInProgress,isPending,dtSubmit
|
|
```
|
|
|
|
---
|
|
|
|
## ПРИМЕРЫ ИЗ HAR
|
|
|
|
### Пример 1: RUNNING инстанс
|
|
```json
|
|
{
|
|
"displayName": "Newly Added",
|
|
"isCreated": true,
|
|
"isDeleted": false,
|
|
"isSuspended": false,
|
|
"explainedStatus": "running",
|
|
"operationIsInProgress": false,
|
|
"operationIsPending": false,
|
|
"uptime": 1102.739073,
|
|
"state": {
|
|
"instanceStateUid": "48bfdbc5-e8fc-4286-8098-d6ab7f6de50e",
|
|
"version": 2
|
|
}
|
|
}
|
|
```
|
|
|
|
### Пример 2: CREATE_IN_PROGRESS инстанс
|
|
```json
|
|
{
|
|
"displayName": "ttst00",
|
|
"isCreated": true,
|
|
"isDeleted": false,
|
|
"isSuspended": false,
|
|
"explainedStatus": "running",
|
|
"operationIsInProgress": false,
|
|
"operationIsPending": true,
|
|
"uptime": 0,
|
|
"operations": [
|
|
{
|
|
"operation": "modify",
|
|
"dtSubmit": "2026-01-22T19:30:21.790+0300",
|
|
"dtStart": null,
|
|
"dtFinish": null,
|
|
"isSuccessful": null,
|
|
"isInProgress": false,
|
|
"isPending": true
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Пример 3: DELETE_IN_PROGRESS инстанс
|
|
```json
|
|
{
|
|
"displayName": "ttt0-terraform",
|
|
"isCreated": true,
|
|
"isDeleted": false,
|
|
"isSuspended": false,
|
|
"operations": [
|
|
{
|
|
"operation": "delete",
|
|
"dtSubmit": "2026-01-22T19:28:24.720+0300",
|
|
"dtStart": null,
|
|
"dtFinish": null,
|
|
"isSuccessful": null
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## СВОДНАЯ ТАБЛИЦА ВОЗМОЖНЫХ СОСТОЯНИЙ
|
|
|
|
| Состояние | isCreated | isDeleted | isSuspended | operationIsInProgress | Описание |
|
|
|-----------|-----------|-----------|-------------|----------------------|---------|
|
|
| NOT_CREATED | false | false | false | false | Еще не создан |
|
|
| CREATING | true | false | false | true | Создание выполняется |
|
|
| RUNNING | true | false | false | false | Работает нормально |
|
|
| MODIFYING | true | false | false | true | Конфигурация изменяется |
|
|
| SUSPENDING | true | false | false | true | Приостановка выполняется |
|
|
| SUSPENDED | true | false | true | false | Приостановлен |
|
|
| RESUMING | true | false | true | true | Возобновление выполняется |
|
|
| DELETING | true | false | false | true | Удаление выполняется |
|
|
| DELETED | true | true | - | - | Удален |
|
|
| OPERATION_PENDING | true | false | - | false | Есть ожидающая операция |
|
|
| OPERATION_FAILED | true | false | - | false | Операция завершилась ошибкой |
|
|
|