<!-- ⛔ LEGACY: deck-api.ngcloud.ru ЗАКРЫВАЕТСЯ. Актуальный API: lk-api-gateway.ngcloud.ru/api/v1/svc -->
# VM Service Discovery & Implementation Details

## Обзор
Сервис управления виртуальными машинами (VM) в облаке Nubes. 
Позволяет выполнять операции полного жизненного цикла: создание, изменение, остановка, запуск, удаление.

**ВАЖНО:** Удаление ВМ происходит через механизм карантина (`suspend`), аналогично VDC. Реальное удаление происходит через 14 дней административными процессами облака.

## API Endpoints

*   **Base URL**: `/api/v1/index.cfm`
*   **Service ID**: 28

### Основные методы

| Операция | HTTP метод | URL | Описание |
| :--- | :--- | :--- | :--- |
| **Create Draft** | `POST` | `/instances` | Создание черновика инстанса. |
| **Start Op** | `POST` | `/instanceOperations` | Инициация операции (create, modify, suspend, resume). |
| **Add Params** | `POST` | `/instanceOperationCfsParams` | Добавление параметров к операции. |
| **Validate** | `GET` | `/instanceOperations/{opId}/validate-cfs` | Валидация (опционально). |
| **Run Op** | `POST` | `/instanceOperations/{opId}/run` | Запуск выполнения операции. |

## Parameter Mapping (Code & IDs)

API использует `svcOperationCfsParamId` для идентификации параметров. 
**Внимание:** ID отличаются для создани (`create`) и изменения (`modify`).
В провайдере (v1.0.3+) реализована логика маппинга по `code` (имени), а также fallback на ID.

| Parameter Name (Terraform) | API Code | Create ID | Modify ID | Тип данных | Описание |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `vapp_uid` | `vappUid` | **407** | - | String | UUID vApp контейнера |
| `vm_name` | `vmName` | **408** | - | String | Уникальное имя ВМ |
| `vm_cpu` | `vmCpu` | **409** | **493** | Int | Кол-во ядер |
| `vm_ram` | `vmRam` | **410** | **494** | Int | RAM (GB) |
| `vm_disk` | `vmDisk` | **411** | **495**? | Int | Доп. диск (GB) |
| `ip_space_name` | `ipSpaceName` | **412** | **496** | String | Public IP setting ("no-needed") |
| `access_ip_list` | `accessIpList` | **413** | **497** | JSON/List | Whitelist IP |
| `image_vm` | `imageVm` | **414** | - | String | OS Template (e.g. Ubuntu_22-20G) |
| `cloud_init` | `cloudInit` | **415** | - | String | YAML конфиг |
| `user_login` | `userLogin` | **416** | - | String | Admin User |
| `user_public_key` | `userPublicKey` | **417** | - | String | SSH Key (OpenSSH) |
| `access_port_list` | `accessPortList` | **448** | **498** | JSON/List | Whitelist Ports |
| `need_add_zabbix_template` | `needAddZabbixTemplate` | **449** | **499** | Bool | Мониторинг |

## Операции и Жизненный цикл

### Create (Создание)
1. `POST /instances` -> создает объект.
2. `POST /instanceOperations` (op="create").
3. Заполняются параметры 407-449.
4. `Run`.

### Modify (Изменение)
1. `POST /instanceOperations` (op="modify").
2. Заполняются параметры (ID 493-499).
3. `Run`.
4. Влияет на ресурсы (CPU, RAM), сеть и мониторинг. Имя и OS обычно не меняются.

### Suspend (Карантин/Удаление)
1. `POST /instanceOperations` (op="suspend").
2. `Run` (обычно без параметров).
3. ВМ останавливается и помечается для удаления.

### Resume (Восстановление)
1. `POST /instanceOperations` (op="resume").
2. `Run`.
3. ВМ запускается из состояния `suspend`.

## Реализация Terraform

### Deletion Protection
Ресурс `nubes_vm_instance` поддерживает параметр `deletion_protection` (default: `true`).

*   **true**: При `terraform destroy` ресурс удаляется только из tfstate. В облаке остается активным.
*   **false**: При `terraform destroy` выполняется операция **suspend**. ВМ выключается и попадает в карантин (14 дней).

### Modify Logic
Метод `Update` распознает изменения и вызывает операцию `modify`.
Параметры CPU, RAM, PortList, IpList, Zabbix и др. обновляются.
Параметры создания (Template, Login, Key, vApp, Name) обычно immutable или требуют пересоздания (ForceNew).

## Результаты анализа HAR
*   `vmOK.har`: Успешное создание ВМ. Подтверждены ID 407-449.
*   `vmsuspendresumemodify.har`: Анализ операций `modify` (ID 493-499), `suspend`, `resume`.

## Известные проблемы
*   API не возвращает `code` (имя параметра) в некоторых случаях, полагаемся на хардкод маппинг ID или порядок. (Исправлено в v1.0.3 через универсальный маппер).
*   `accessIpList` и `accessPortList` требуют явной передачи зависимостей JSON/Array даже если пусты.