add: documentation

2026-06-30 15:45:24 +04:00
parent 540c1f7293
commit ca276d200f
1055 changed files with 47294 additions and 0 deletions
@@ -0,0 +1,90 @@
+# 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 даже если пусты.
+