Модуль **decort_kvmvm** предназначен для выполнения следующих действий над виртуальными машинами:
- **создать** (см. [примеры](#создать))
- **с указанием описания** (см. параметр **description** и [примеры](#с-указанием-описания))
- **с указанием объёма загрузочного диска** (см. параметр **boot.disk_size** и [примеры](#с-указанием-объёма-загрузочного-диска))
- **с указанием СХД** (см. параметры **sep_id** и **pool** и [примеры](#с-указанием-схд))
- **с указанием Cloud-init user data** (см. параметр **ci_user_data** и [примеры](#с-указанием-cloud-init-user-data))
- **с указанием SSH-ключа** (см. параметры **ssh_key** и **ssh_key_user** и [примеры](#с-указанием-ssh-ключа))
- **с указанием NUMA Affinity** (см. параметр **numa_affinity** и [примеры](#с-указанием-numa-affinity))
- **с указанием запуска на выделенных ядрах ЦП** (см. параметр **cpu_pin** и [примеры](#с-указанием-запуска-на-выделенных-ядрах-цп))
- **с использованием Huge Pages** (см. параметр **hp_backed** и [примеры](#с-использованием-huge-pages))
- **с указанием custom_fields** (см. параметр **custom_fields** и [примеры](#с-указанием-custom_fields))
- **с указанием affinity-метки** (см. параметр **affinity_label** и [примеры](#с-указанием-affinity-метки))
- **с указанием affinity правил** (см. параметр **aff_rule** и [примеры](#с-указанием-affinity-правил))
- **с указанием anti-affinity правил** (см. параметр **aaff_rule** и [примеры](#с-указанием-anti-affinity-правил))
- **с указанием тэгов** (см. параметр **tag** и [примеры](#с-указанием-тэгов))
- **с образом** (см. параметры **image_id** и **image_name** и [примеры](#с-образом))
- **без образа** (см. параметры **image_id** и **image_name** и [примеры](#без-образа))
- **с загрузочным диском** (см. параметр **boot.disk_size** и [примеры](#с-загрузочным-диском))
- **без загрузочного диска** (см. [примеры](#без-загрузочного-диска))
- **с указанием режима загрузки** (см. параметр **boot.mode** и [примеры](#с-указанием-режима-загрузки))
- **с указанием типа загрузчика ОС** (см. параметр **boot.loader_type** и [примеры](#с-указанием-типа-загрузчика-ос))
- **с указанием именования сетевых интерфейсов** (см. параметр **network_interface_naming** и [примеры](#с-указанием-именования-сетевых-интерфейсов))
- **с поддержкой изменения объема ОЗУ и количества ЦП у запущенной ВМ** (см. параметр **hot_resize** и [примеры](#с-поддержкой-изменения-объема-озу-и-количества-цп-у-запущенной-вм))
- **с включением автоматического запуска ВМ после перезапуска вычислительного узла, за которым она закреплена** (см. параметр **auto_start** и [примеры](#с-включением-автоматического-запуска-вм-после-перезапуска-вычислительного-узла-за-которым-она-закреплена))
- **с указанием чипсета** (см. параметр **chipset** и [примеры](#с-указанием-чипсета))
- **с указанием предпочтительных ядер** (см. параметр **preferred_cpu_cores** и [примеры](#с-указанием-предпочтительных-ядер))
- **путём клонирования другой ВМ** (см. параметр **clone_from** и [примеры](#путём-клонирования-другой-вм))
- **с указанием зоны** (см. параметр **zone_id** и [примеры](#с-указанием-зоны))
- **получить основную информацию** (см. [возвращаемые значения](#основная-информация) и [примеры](#получение-основной-информации-о-виртуальной-машине))
- **получить ссылку на консоль** (см. параметр **get_console_url** и [примеры](#получение-ссылки-на-консоль))
- **остановить/приостановить/запустить** (см. параметр **state** и [примеры](#остановитьприостановитьзапустить))
- **подключить/отключить диски** (см. параметр **disks** и [примеры](#подключитьотключить-диски))
- **подключить/отключить сети** (см. параметры **networks** и **network_order_changing** и [примеры](#подключитьотключить-сети))
- **откатить ВМ к состоянию снимка** (см. параметр **rollback_to** и [примеры](#откатить-вм-к-состоянию-снимка))
- **взаимодействовать c QEMU Guest Agent** (см. параметр **guest_agent** и [примеры](#взаимодействовать-c-qemu-guest-agent))
- **получить статус копирования данных из удаляемого снимка на СХД Shared** (см. параметр **get_snapshot_merge_status** и [примеры](#получение-статуса-копирования-данных-из-удаляемого-снимка-на-схд-shared))
- **изменить** (см. [примеры](#изменить))
- **объём загрузочного диска в большую сторону** (см. параметр **boot.disk_size** и [примеры](#объём-загрузочного-диска-в-большую-сторону))
- **количество ЦП** (см. параметр **cpu** и [примеры](#количество-цп))
- **объём ОЗУ** (см. параметр **ram** и [примеры](#объём-озу))
- **тэги** (см. параметр **tag** и [примеры](#тэги))
- **affinity метку** (см. параметр **affinity_label** и [примеры](#affinity-метку))
- **affinity правила** (см. параметр **aff_rule** и [примеры](#affinity-правила))
- **anti-affinity правила** (см. параметр **aaff_rule** и [примеры](#anti-affinity-правила))
- **описание** (см. параметр **description** и [примеры](#описание))
- **чипсет** (см. параметр **chipset** и [примеры](#чипсет))
- **правило NUMA Affinity** (см. параметр **numa_affinity** и [примеры](#правило-numa-affinity))
- **запуск на выделенных ядрах ЦП** (см. параметр **cpu_pin** и [примеры](#запуск-на-выделенных-ядрах-цп))
- **использование Huge Pages** (см. параметр **hp_backed** и [примеры](#использование-huge-pages))
- **имя** (см. параметр **name** и [примеры](#имя))
- **XML виртуальной машины** (см. параметр **custom_fields** и [примеры](#xml-виртуальной-машины))
- **автоматический запуск ВМ после перезапуска вычислительного узла, за которым она закреплена** (см. параметр **auto_start** и [примеры](#автоматический-запуск-вм-после-перезапуска-вычислительного-узла-за-которым-она-закреплена))
- **предпочтительные ядра** (см. параметр **preferred_cpu_cores** и [примеры](#предпочтительные-ядра))
- **загрузочный диск** (см. параметр **boot.disk_id** и [примеры](#загрузочный-диск))
- **режим загрузки** (см. параметр **boot.mode** и [примеры](#режим-загрузки))
- **тип загрузчика ОС** (см. параметр **boot.loader_type** и [примеры](#тип-загрузчика-ос))
- **именование сетевых интерфейсов** (см. параметр **network_interface_naming** и [примеры](#именование-сетевых-интерфейсов))
- **поддержку изменения объема ОЗУ и количества ЦП у запущенной ВМ** (см. параметр **hot_resize** и [примеры](#поддержку-изменения-объема-озу-и-количества-цп-у-запущенной-вм))
- **MAC-адрес сетевого интерфейса** (см. параметр **networks.mac** и [примеры](#mac-адрес-сетевого-интерфейса))
- **зону ВМ** (см. параметр **zone_id** и [примеры](#зону-вм))
- **удалить (безвозвратно)** (см. параметр **state** и [примеры](#безвозвратно))
## Параметры модуля decort_kvmvm
Ниже приведен список параметров для модуля **decort_kvmvm** (за исключением [общих параметров авторизации](./введение.md#общие-параметры-модулей-для-авторизации)):
| Параметр | Тип, допустимые значения | Описание |
| ------ | ------ | ------ |
| aaff_rule | (list) | Список словарей, описывающих anti-affinity правила.<br>Ключи словаря:<br>•`topology` (string) (обязательный) - назначение правила; значения: `node` (узел) или `compute` (ВМ)<br>•`policy` (string) (обязательный) - степень "необходимости" этого правила; значения: `RECOMMENDED` или `REQUIRED`<br>•`mode` (string) (обязательный) - режим сравнения; значения: `EQ` (должно соответствовать), `NE` (не должно соответствовать), `ANY` (любое)<br>•`key` (string) (обязательный) - ключ, который учитывается при анализе данного правила<br>•`value` (string) (обязательный) - значение ключа, учитываемого при анализе данного правила (зависит от ключа `mode`).<br>Чтобы очистить anti-affinity правила, нужно указать пустой список `[]`. |
| account_id | (int) | Идентификатор аккаунта. Этот параметр является опциональным и используется в сценариях, когда уже существующая ресурсная группа задается комбинацией `account_id` и `rg_name`. Если задан `account_id`, то `account_name` игнорируется.|
| account_name | (string) | Имя аккаунта. Этот параметр является опциональным и используется в сценариях, когда уже существующая ресурсная группа задается комбинацией `account_name` и `rg_name`. Если задан `account_id`, то `account_name` игнорируется. |
| aff_rule | (list) | Список словарей, описывающих affinity правила.<br>Ключи словаря:<br>•`topology` (string) (обязательный) - назначение правила; значения: `node` (узел) или `compute` (ВМ)<br>•`policy` (string) (обязательный) - степень "необходимости" этого правила; значения: `RECOMMENDED` или `REQUIRED`<br>•`mode` (string) (обязательный) - режим сравнения; значения: `EQ` (должно соответствовать), `NE` (не должно соответствовать), `ANY` (любое)<br>•`key` (string) (обязательный) - ключ, который учитывается при анализе данного правила<br>•`value` (string) (обязательный) - значение ключа, учитываемого при анализе данного правила (зависит от ключа `mode`).<br>Чтобы очистить affinity правила, нужно указать пустой список `[]`. |
| auto_start | (bool) | Включить/выключить автоматический запуск ВМ после перезапуска вычислительного узла, за которым она закреплена.<br> Если параметр не задан при создании ВМ, то значение будет выбрано платформой. |
| boot | (dict) | Параметры загрузки.<br>Ключи словаря:<br>•`disk_id` (int) - идентификатор диска, который будет установлен как загрузочный;<br>•`disk_size` (int) - объём загрузочного диска виртуальной машины в ГБ. Если параметр не задан, размер будет равен размеру образа. Если не заданы этот параметр и параметры `image_id` и `image_name`, то виртуальная машина будет создана без загрузочного диска;<br>•`mode` (str) - режим загрузки, значения: `bios`, `uefi`, значение по умолчанию при создании: `bios`;<br>•`loader_type` (str) - тип загрузчика операционной системы, значения: `linux`, `windows`, `unknown`, значение по умолчанию при создании: `unknown`. |
| chipset | (string)<br>Значения:<br>`Q35`<br>`i440fx` | Эмулируемый чипсет. Значение по умолчанию при создании: `i440fx`.|
| ci_user_data | (dict) | конфигурация для cloud-init
| clone_from | (dict) | Словарь параметров для создания ВМ путём клонирования другой ВМ.<br>Ключи словаря:<br>•`id` (int) (обязательный) - идентификатор клонируемой ВМ<br>•`force` (bool) - игнорировать, что ВМ запущена; значение по умолчанию: `false`<br>•`snapshot` (dict) - словарь параметров клонируемого снимка ВМ. Ключи словаря: `name` (str) - название снимка; `timestamp` (int) - unix-время; `datetime` (str) - дата и время в формате `ггггммддччммсс`, альтернатива параметру `timestamp`, допустимо использовать любой разделитель между группами цифр для повышения читаемости, например, `гггг-мм-дд чч:мм:сс`.<br>Для создания клона также должен быть указан параметр `name` для указания имени клона.|
| cpu | (int) | Количество виртуальных процессоров, выделяемых виртуальной машине. |
| cpu_pin | (bool) | Запуск виртуальной машины на выделенных ядрах ЦП. <br>Значение по умолчанию при создании: `false`. |
| custom_fields | (dict) | Словарь, управляющий XML виртуальной машины.<br>Ключи словаря:<br>•`disable` (bool) - отключение управления виртуальной машиной через XML. Значение по умолчанию при создании: `true`<br>•`fields` (dict) - поля для управления XML виртуальной машины. |
| description | (string) | Опциональное описание виртуальной машины. |
| disks | (dict) | Словарь, описывающий диски ВМ.<br>Ключи словаря:<br>•`mode` (str) - режим работы параметра; значения: `update` (по умолчанию) - указанные диски подключены, `detach` - указанные диски отключены, `delete` - указанные диски отключены и удалены; удаляются только отключаемые диски, `match` - подключены только указанные диски<br>•`ids` (list) - список идентификаторов дисков; для отключения всех дисков нужно передать пустой список в режиме match. |
| get_console_url | (bool)<br>Default:<br>`false` | Получить ссылку на консоль ВМ. |
| get_snapshot_merge_status | (bool) | Получить статус копирования данных из удаляемого снимка на СХД Shared. |
| guest_agent | (dict) | Параметры для взаимодействия с QEMU Guest Agent.<br>Ключи словаря:<br>•`enabled` (bool) - включить/выключить<br>•`exec` (dict) - команда, которую необходимо выполнить. Ключи словаря: `cmd` (str) (обязательный) - название; `args` (dict) - аргументы, значение по умолчанию: `{}`<br>•`update_available_commands` (bool) - обновить список доступных команд. |
| hot_resize | (bool) | Поддержка изменения объёма ОЗУ и количества процессоров у запущенной ВМ. <br>Значение по умолчанию при создании: `false`. |
| hp_backed | (bool) | Использовать Huge Pages для выделения оперативной памяти виртуальной машины. Система должна быть предварительно сконфигурирована путем выделения Huge Pages на физическом узле. <br>Значение по умолчанию при создании: `false`. |
| id | (int) | Уникальный цифровой идентификатор виртуальной машины. Этот параметр используется как один из методов идентификации существующей ВМ (альтернатива – по комбинации `name`, `rg_name` и `account_name`). Если при вызове модуля **decort_kvmvm** существующая ВМ идентифицируется по `id`, то параметры `account_id`, `account_name`, `rg_id` и `rg_name` игнорируются. |
| image_id | (int) | Уникальный цифровой идентификатор образа, на базе которого следует создать виртуальную машину.<br>Если заданы оба параметра (`image_id` и `image_name`), то `image_name` игнорируется.<br>Если этот параметр и параметр `image_name` не заданы, то виртуальная машина будет создана без образа. |
| image_name | (string) | Название образа, на базе которого следует создать ВМ.<br>Если этот параметр и параметр `image_id` не заданы, то виртуальная машина будет создана без образа. |
| name | (string) | Имя ВМ. Чтобы модуль **decort_kvmvm** мог управлять сервером по его названию, также необходимо задать комбинацию `account_name` и `rg_name` или `rg_id`. Если для существующей ВМ указаны и `name`, и `id`, то параметр `name` используется для переименования. |
| network_interface_naming | (string) <br>Значения:<br>`ens`<br>`eth`| Шаблон именования сетевых интерфейсов в ОС Linux. <br>Значение по умолчанию при создании: `ens`. |
| network_order_changing | (bool)<br>Default:<br>`false` | Соблюдение очерёдности сетей при их изменении.<br>Если `true`, то сравнение списка уже подключённых к ВМ сетей со списком из параметра `networks` будет производится <u>с учётом очерёдности сетей</u> и, <u>при выявлении несоответствия, сначала будет произведено отключение всех сетей от ВМ</u>, а затем подключение сетей в соответствии с параметром `networks`.<br> Если `false`, то очерёдность при сравнении учитываться не будет. Соответственно, сети, которые имеются в списке параметра `networks` и уже подключены к ВМ, переподключаться не будут, что может кратно уменьшить время выполнения изменения сетей. |
| networks | (list) | Список словарей, описывающих сети ВМ.<br>Ключи словаря:<br>•`type` (string) (обязательный) - тип сети; значения: `VINS` (внутренняя), `EXTNET` (внешняя), `VFNIC` (вирт. функция), `DPDK`, `SDN`, `TRUNK`, `EMPTY` (без подключения к сети)<br>•`id` (int \| str) (необязательный) - идентификатор внутренней/внешней/DPDK сети, пула вирт. функций или логического порта SDN<br>•`ip_addr` (string) (необязательный) - IP-адрес, используемый для подключения к данной сети; применимо только для `VINS` и `EXTNET`<br>•`mac` (str) (необязательный) - MAC-адрес сетевого интерфейса; не применим для сети типа `EMPTY`; обязателен для `SDN`.<br>•`mtu` (int) (необязательный) - MTU интерфейса; применимо только для `EXTNET` и `DPDK`<br><br>ВМ не может одновременно быть подключена к сети `DPDK` и к сети другого типа, кроме `EMPTY`.<br><br>ВМ не может одновременно быть подключена к сети `SDN` и к сети другого типа, кроме `EMPTY`, `VFNIC`.<br><br>Чтобы отключить все сети, нужно указать пустой список `[]`. |
| numa_affinity | (str)<br>Значения:<br>`strict`<br>`loose`<br>`none` | Правило применения NUMA affinity к виртуальной машине. <br>`strict` - строго с NUMA affinity, `loose` - использовать NUMA affinity, если возможно, `none` - отменить применение NUMA affinity. <br>Значение по умолчанию при создании: `none`. |
| pool | (str) | Пул СХД, заданной параметром `sep_id`. Если пул не задан, то он будет выбран платформой.
| preferred_cpu_cores | (list) | Список номеров предпочтительных выделенных ядер ЦП (см. параметр `cpu_pin`). Чтобы очистить список номеров предпочтительных выделенных ядер ЦП, нужно указать пустой список `[]`. |
| ram | (int) | Объем оперативной памяти в МБ, выделенной данной ВМ. Параметр является обязательным при создании. Если указать его для уже существующей ВМ, то будет выполнена попытка изменить объем выделенной памяти. |
| rg_id | (int) | Уникальный цифровой идентификатор уже существующей ресурсной группы, в которой будет создана новая или находится уже существующая ВМ. Данный параметр является одним из методов идентификации существующей РГ (альтернативой является задание комбинации `account_name` и `rg_name`).|
| rg_name | (string) | Имя уже существующей ресурсной группы, в которой будет создаа новая или находится уже существующая ВМ. Данный параметр является одним из методов идентификации существующей РГ, когда задается пара `account_name` и `rg_name` (альтернативой является задание `rg_id`). Если заданы и `rg_id`, и `rg_name`, то параметр `rg_name` игнорируется.|
| rollback_to | (string) | Имя снимка, к состоянию которого необходимо совершить откат ВМ. |
| sep_id | (int) | Идентификатор СХД для загрузочного диска ВМ. Если не задан, то будет использоваться СХД образа.
| ssh_key | (string) | Открытая часть SSH-ключа, который необходимо добавить на создаваемую ВМ для пользователя, заданного параметром `ssh_key_user`. Данный параметр применим только для ОС Linux, используется только при создании и игнорируется при других операциях. |
| ssh_key_user | (string) | Имя пользователя в гостевой ОС (только для Linux), для которого добавляется SSH-ключ, заданный параметром `ssh_key`. Данный параметр является обязательным, если задан `ssh_key`. Используется только при создании и игнорируется при других операциях. |
| state | (str)<br>Значения:<br>`present`<br>`absent`<br>`started`<br>`stopped`<br>`paused` | Целевое состояние ВМ.<br>`present` - виртуальная машина существует и не удалена. Если удалена в корзину, то будет восстановлена из корзины.<br>`absent` - виртуальная машина безвозвратно удалена. <br>`started` - виртуальная машина запущена. Если остановлена, то будет запущена. Если удалена в корзину, то будет восстановлена из корзины.<br>`stopped` - виртуальная машина остановлена. Если запущена, то будет остановлена.<br>`paused` - виртуальная машина приостановлена.<br>Значение по умолчанию при создании: `present`. |
| tag | (dict) | Словарь, пары ключ-значение которого, описывают тэги для ВМ.<br>Чтобы очистить теги, нужно указать пустой словарь `{}`.|
| zone_id | (int) | Идентификатор зоны ВМ.|
## Возвращаемые значения модуля decort_kvmvm
Модуль **decort_kvmvm** возвращает информацию о виртуальной машине в виде словаря `facts`со следующими ключами:
### Основная информация
| Ключ | Тип данных | Описание |
| ------ | ------ | ------ |
| account_id | int | Идентификатор аккаунта. |
| affinity_label | string | Метка affinity. |
| affinity_rules | list | Список словарей, описывающих affinity правила. |
| anti_affinity_rules | list | Список словарей, описывающих anti-affinity правила. |
| arch | string | Архитектура ВМ. |
| auto_start | bool | Автоматический запуск ВМ после перезапуска вычислительного узла, за которым она закреплена. |
| boot_mode | string | Режим загрузки. |
| clones | list | Список идентификаторов клонов ВМ. |
| clone_reference | int | Идентификатор ВМ, клоном которой является данная ВМ. |
| chipset | string | Эмулируемый чипсет. |
| cpu | int | Количество виртуальных процессоров. |
| cpu_pin | bool | Запуск виртуальной машины на выделенных ядрах ЦП. |
| custom_fields | dict | Словарь, управляющий XML виртуальной машины. Если `null`, то управление виртуальной машиной через XML отключено, иначе - управление через XML включено. |
| disks | list | Список идентификаторов дисков, подключенных к ВМ. |
| disk_size | int | Размер загрузочного диска в ГБ. |
| guest_agent | dict | Информация о QEMU Guest Agent ВМ.<br>Ключи словаря:<br>•`enabled` (bool) - включен/выключен<br>•`enabled_agent_features` (list) - список доступных команд<br>•`exec_result` (any) - результат выполнения команды<br>•`guid` (str) - идентификатор<br>•`last_update` (int) - временная метка последнего обновления доступных команд<br>•`user` (str) - пользователь, совершивший последнее обновление доступных команд. |
| hot_resize | bool | Поддержка изменения объёма ОЗУ и количества процессоров у запущенной ВМ. |
| hp_backed | bool | Использовать Huge Pages для выделения оперативной памяти виртуальной машины. |
