92 lines
5.6 KiB
Markdown
92 lines
5.6 KiB
Markdown
<!-- ⛔ 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 даже если пусты.
|
|
|