add: documentation
This commit is contained in:
“Naeel”
@@ -0,0 +1,195 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user