# 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