197 lines
7.8 KiB
Markdown
197 lines
7.8 KiB
Markdown
<!-- ⛔ LEGACY: deck-api.ngcloud.ru ЗАКРЫВАЕТСЯ. Актуальный API: lk-api-gateway.ngcloud.ru/api/v1/svc -->
|
|
# Instance State Transitions - Матрица состояний инстансов ngcloud
|
|
|
|
Полное руководство по определению состояния инстансов через API ngcloud на основе комбинаций флагов и истории операций.
|
|
|
|
---
|
|
|
|
## 📊 Таблица состояний
|
|
|
|
| **Состояние** | `isCreated` | `isDeleted` | `isSuspended` | `operationIsInProgress` | `operationIsPending` | `isSuccessful` | Описание |
|
|
|---|---|---|---|---|---|---|---|
|
|
| **NOT_CREATED** | `false` | `false` | `false` | `false` | `false` | - | Ресурс в TF, но в облаке его нет |
|
|
| **CREATING** | `false` | `false` | `false` | `true` | `false` | - | Идет создание инстанса |
|
|
| **CREATION_FAILED** | `false` | `false` | `false` | `false` | `false` | `false` | ❌ Попытка создания завершилась ошибкой |
|
|
| **RUNNING** | `true` | `false` | `false` | `false` | `false` | `true` | ✅ Нормальное работающее состояние |
|
|
| **RUNNING_PENDING** | `true` | `false` | `false` | `false` | `true` | - | ✅ Работает, но в очереди ждет операция |
|
|
|
|
---
|
|
|
|
## 📊 Полная таблица состояний
|
|
|
|
| **Состояние** | `isCreated` | `isDeleted` | `isSuspended` | `operationIsInProgress` | `operationIsPending` | `isSuccessful` | Описание |
|
|
|---|---|---|---|---|---|---|---|
|
|
| **NOT_CREATED** | `false` | `false` | `false` | `false` | `false` | - | Ресурс в TF, но в облаке его нет |
|
|
| **CREATING** | `false` | `false` | `false` | `true` | `false` | - | Идет создание инстанса |
|
|
| **CREATION_FAILED** | `false` | `false` | `false` | `false` | `false` | `false` | ❌ Попытка создания завершилась ошибкой |
|
|
| **RUNNING** | `true` | `false` | `false` | `false` | `false` | `true` | ✅ Нормальное работающее состояние |
|
|
| **RUNNING_PENDING** | `true` | `false` | `false` | `false` | `true` | - | ✅ Работает, но в очереди ждет операция |
|
|
| **MODIFYING** | `true` | `false` | `false` | `true` | `false` | - | Идет изменение конфигурации |
|
|
| **MODIFICATION_FAILED** | `true` | `false` | `false` | `false` | `false` | `false` | ❌ Ошибка при изменении |
|
|
| **SUSPENDING** | `true` | `false` | `false` | `true` | `false` | - | Идет приостановка |
|
|
| **SUSPEND_FAILED** | `true` | `false` | `false` | `false` | `false` | `false` | ❌ Ошибка при приостановке |
|
|
| **SUSPENDED** | `true` | `false` | `true` | `false` | `false` | `true` | ⏸️ Приостановлен |
|
|
| **RESUMING** | `true` | `false` | `true` | `true` | `false` | - | Идет возобновление |
|
|
| **RESUME_FAILED** | `true` | `false` | `true` | `false` | `false` | `false` | ❌ Ошибка при возобновлении |
|
|
| **DELETING** | `true` | `false` | `false` | `true` | `false` | - | Идет удаление |
|
|
| **DELETION_FAILED** | `true` | `false` | `false` | `false` | `false` | `false` | ❌ Ошибка при удалении |
|
|
| **DELETED** | `true` | `true` | - | - | - | - | ❌ Удален |
|
|
| **ORPHANED** | `false` | `false` | - | - | - | `false` | ⚠️ История ошибок |
|
|
|
|
---
|
|
|
|
## 🔗 API Запросы для определения состояния
|
|
|
|
### Основной запрос к инстансу
|
|
|
|
```bash
|
|
curl -s -H "Authorization: Bearer $(cat /home/naeel/remote_dev/terraform/secrets/prod.token)" \
|
|
"https://deck-api.ngcloud.ru/api/v1/index.cfm/instances/{instanceUid}?fields=isCreated,isDeleted,isSuspended,operationIsInProgress,operationIsPending,operations,availableOperations,explainedStatus,uptime"
|
|
```
|
|
|
|
### Ответ API при CREATION_FAILED
|
|
|
|
```json
|
|
{
|
|
"instance": {
|
|
"instanceUid": "vcOrg-2402",
|
|
"displayName": "Организация в Cloud Director",
|
|
"isCreated": false,
|
|
"isDeleted": false,
|
|
"isSuspended": false,
|
|
"operationIsInProgress": false,
|
|
"operationIsPending": false,
|
|
"operations": [
|
|
{
|
|
"operation": "create",
|
|
"isSuccessful": false,
|
|
"errorLog": "Connection timeout to Cloud Director API",
|
|
"dtFinish": "2026-02-24T18:51:30+0300",
|
|
"duration": 80.5
|
|
}
|
|
],
|
|
"availableOperations": [
|
|
{"operation": "create"},
|
|
{"operation": "delete"}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🐍 Python функция определения состояния
|
|
|
|
```python
|
|
def get_instance_state(instance_data):
|
|
"""Определить состояние инстанса на основе ответа API"""
|
|
|
|
ic = instance_data.get('isCreated', False)
|
|
id = instance_data.get('isDeleted', False)
|
|
is_susp = instance_data.get('isSuspended', False)
|
|
is_in_prog = instance_data.get('operationIsInProgress', False)
|
|
is_pend = instance_data.get('operationIsPending', False)
|
|
ops = instance_data.get('operations', [])
|
|
|
|
# ПЕРВЫЙ ПРИОРИТЕТ: Проверить ошибки в последней операции
|
|
if ops and len(ops) > 0:
|
|
last_op = ops[0]
|
|
if last_op.get('isSuccessful') == False: # явное False
|
|
op_type = last_op.get('operation', 'unknown').upper()
|
|
return {
|
|
'state': f'{op_type}_FAILED',
|
|
'error': last_op.get('errorLog'),
|
|
'attempt_at': last_op.get('dtFinish'),
|
|
'can_retry': True
|
|
}
|
|
|
|
# Операции в процессе
|
|
if is_in_prog:
|
|
return {'state': 'OPERATING'}
|
|
|
|
# Ожидающие операции
|
|
if is_pend:
|
|
return {'state': 'RUNNING_PENDING'}
|
|
|
|
# Не создан
|
|
if not ic:
|
|
return {'state': 'NOT_CREATED'}
|
|
|
|
# Удален
|
|
if id:
|
|
return {'state': 'DELETED'}
|
|
|
|
# Приостановлен
|
|
if is_susp:
|
|
return {'state': 'SUSPENDED'}
|
|
|
|
# Работает
|
|
return {
|
|
'state': 'RUNNING',
|
|
'uptime': instance_data.get('uptime')
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 📋 Логика для Terraform Provider
|
|
|
|
### terraform apply
|
|
|
|
- **NOT_CREATED** → CreateInstance
|
|
- **RUNNING** + config_changed → ModifyInstance
|
|
- **CREATION_FAILED**, **MODIFICATION_FAILED** → Retry
|
|
- **OPERATING_*** → Wait
|
|
|
|
### terraform destroy
|
|
|
|
- **NOT_CREATED** → Skip
|
|
- **DELETED** → RemoveFromState
|
|
- **DELETION_FAILED** → Retry
|
|
- **Остальные** → DeleteInstance
|
|
|
|
---
|
|
|
|
## ⚠️ Критические комбинации
|
|
|
|
### 1. Инстанс не видно, но ошибка создания
|
|
|
|
```
|
|
isCreated=false + operations[0].isSuccessful=false + operation=create
|
|
= CREATION_FAILED
|
|
```
|
|
|
|
**Действие:**
|
|
- Проверить `errorLog` для деталей
|
|
- Использовать `availableOperations` для определения возможных действий
|
|
- Перепопытаться через create или удалить
|
|
|
|
### 2. Операция зависла
|
|
|
|
```
|
|
operationIsInProgress=true + duration > 3600 сек
|
|
= STUCK_OPERATION
|
|
```
|
|
|
|
**Действие:** Требует ручного вмешательства
|
|
|
|
### 3. Ошибка удаления (инстанс остался)
|
|
|
|
```
|
|
isDeleted=false + operations[0].operation=delete + isSuccessful=false
|
|
= DELETION_FAILED
|
|
```
|
|
|
|
**Действие:**
|
|
- Инстанс остается в облаке
|
|
- Перепопытаться delete или обратиться в поддержку
|
|
|
|
---
|
|
|
|
## 📖 Ссылки
|
|
|
|
- API: https://deck-api.ngcloud.ru/api/v1/
|
|
- Операции: create, modify, delete, suspend, resume
|
|
- Токен: /home/naeel/remote_dev/terraform/secrets/prod.token
|
|
|