# Модуль decort_kvmvm
## Обзор модуля decort_kvmvm
Модуль **decort_kvmvm** предназначен для выполнения следующих действий над виртуальными машинами:
- **создать** (см. [примеры](#создать))
- **с указанием описания** (см. параметр **description** и [примеры](#с-указанием-описания))
- **с указанием объёма загрузочного диска** (см. параметр **boot_disk** и [примеры](#с-указанием-объёма-загрузочного-диска))
- **с указанием СХД** (см. параметры **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** и [примеры](#с-загрузочным-диском))
- **без загрузочного диска** (см. параметр **boot_disk** и [примеры](#без-загрузочного-диска))
- **с включением автоматического запуска ВМ после перезапуска вычислительного узла, за которым она закреплена** (см. параметр **auto_start** и [примеры](#с-включением-автоматического-запуска-вм-после-перезапуска-вычислительного-узла-за-которым-она-закреплена))
- **получить информацию** (см. [возвращаемые значения](#возвращаемые-значения-модуля-decort_kvmvm) и [примеры](#получение-основной-информации-о-виртуальной-машине))
- **остановить/приостановить/запустить** (см. параметр **state** и [примеры](#остановитьприостановитьзапустить))
- **подключить/отключить диски с данными** (см. параметр **data_disks** и [примеры](#подключитьотключить-диски-с-данными))
- **подключить/отключить сети** (см. параметры **networks** и **network_order_changing** и [примеры](#подключитьотключить-сети))
- **изменить** (см. [примеры](#изменить))
- **объём загрузочного диска в большую сторону** (см. параметр **boot_disk** и [примеры](#объём-загрузочного-диска-в-большую-сторону))
- **количество CPU** (см. параметр **cpu** и [примеры](#количество-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 Pinning** (см. параметр **cpu_pin** и [примеры](#использование-cpu-pinning))
- **использование Huge Pages** (см. параметр **hp_backed** и [примеры](#использование-huge-pages))
- **имя** (см. параметр **name** и [примеры](#имя))
- **XML виртуальной машины** (см. параметр **custom_fields** и [примеры](#xml-виртуальной-машины))
- **автоматический запуск ВМ после перезапуска вычислительного узла, за которым она закреплена** (см. параметр **auto_start** и [примеры](#автоматический-запуск-вм-после-перезапуска-вычислительного-узла-за-которым-она-закреплена))
- **удалить (безвозвратно)** (см. параметр **state** и [примеры](#безвозвратно))
## Параметры модуля decort_kvmvm
Ниже приведен список параметров для модуля **decort_kvmvm** (за исключением [общих параметров авторизации](./введение.md#общие-параметры-модулей-для-авторизации)):
| Параметр | Тип, допустимые значения | Описание |
| ------ | ------ | ------ |
| aaff_rule | (list) | Список словарей, описывающих anti-affinity правила.
Ключи словаря:
• `topology` (string) (обязательный) - назначение правила; значения: `node` (узел) или `compute` (ВМ)
• `policy` (string) (обязательный) - степень "необходимости" этого правила; значения: `RECOMMENDED` или `REQUIRED`
• `mode` (string) (обязательный) - режим сравнения; значения: `EQ` (должно соответствовать), `NE` (не должно соответствовать), `ANY` (любое)
• `key` (string) (обязательный) - ключ, который учитывается при анализе данного правила
• `value` (string) (обязательный) - значение ключа, учитываемого при анализе данного правила (зависит от ключа `mode`).
Чтобы очистить 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 правила.
Ключи словаря:
• `topology` (string) (обязательный) - назначение правила; значения: `node` (узел) или `compute` (ВМ)
• `policy` (string) (обязательный) - степень "необходимости" этого правила; значения: `RECOMMENDED` или `REQUIRED`
• `mode` (string) (обязательный) - режим сравнения; значения: `EQ` (должно соответствовать), `NE` (не должно соответствовать), `ANY` (любое)
• `key` (string) (обязательный) - ключ, который учитывается при анализе данного правила
• `value` (string) (обязательный) - значение ключа, учитываемого при анализе данного правила (зависит от ключа `mode`).
Чтобы очистить affinity правила, нужно указать пустой список `[]`. |
| affinity_label | (str) | Метка affinity.
Чтобы очистить метку affinity, нужно указать пустую строку `""`. |
| auto_start | (bool) | Включить/выключить автоматический запуск ВМ после перезапуска вычислительного узла, за которым она закреплена.
Если параметр не задан при создании ВМ, то значение будет выбрано платформой. |
| boot_disk | (int) | Объём загрузочного диска виртуальной машины в ГБ. |
| chipset | (string)
Значения:
`Q35`
`i440fx` | Эмулируемый чипсет. |
| ci_user_data | (dict) | конфигурация для cloud-init
| cpu | (int) | Количество виртуальных процессоров, выделяемых виртуальной машине. |
| cpu_pin | (bool) | Запуск виртуальной машины на выделенных процессорах. Чтобы использовать эту функцию, система должна быть предварительно сконфигурирована путем выделения процессоров на физическом узле.
Значение по умолчанию при создании: `false`. |
| custom_fields | (dict) | Словарь, управляющий XML виртуальной машины.
Ключи словаря:
• `disable` (bool) - отключение управления виртуальной машиной через XML. Значение по умолчанию при создании: `true`
• `fields` (dict) - поля для управления XML виртуальной машины. |
| data_disks | (list) | Список идентификаторов дисков, которые следует подключить к данной виртуальной машине как дополнительные.
Чтобы отключить все диски, нужно указать пустой список `[]`.|
| description | (string) | Опциональное описание виртуальной машины. |
| hp_backed | (bool) | Использовать Huge Pages для выделения оперативной памяти виртуальной машины. Система должна быть предварительно сконфигурирована путем выделения Huge Pages на физическом узле.
Значение по умолчанию при создании: `false`. |
| id | (int) | Уникальный цифровой идентификатор виртуальной машины. Этот параметр используется как один из методов идентификации существующей ВМ (альтернатива – по комбинации `name`, `rg_name` и `account_name`). Если при вызове модуля **decort_kvmvm** существующая ВМ идентифицируется по `id`, то параметры `account_id`, `account_name`, `rg_id` и `rg_name` игнорируются. |
| image_id | (int) | Уникальный цифровой идентификатор образа, на базе которого следует создать виртуальную машину. При создании задать этот параметр или параметр `image_name`. При любых других операциях данные параметры игнорируются. Если заданы оба этих параметра (`image_id` и `image_name`), то `image_name` игнорируется. |
| image_name | (string) | Название образа, на базе которого следует создать ВМ. При создании требуется задать этот параметр или параметр `image_id`. При любых других операциях данные параметры игнорируются. |
| name | (string) | Имя ВМ. Чтобы модуль **decort_kvmvm** мог управлять сервером по его названию, также необходимо задать комбинацию `account_name` и `rg_name` или `rg_id`. Если для существующей ВМ указаны и `name`, и `id`, то параметр `name` игнорируется и идентификация сервера выполняется по `id`.|
| network_order_changing | (bool)
Default:
`false` | Соблюдение очерёдности сетей при их изменении.
Если `true`, то сравнение списка уже подключённых к ВМ сетей со списком из параметра `networks` будет производится с учётом очерёдности сетей и, при выявлении несоответствия, сначала будет произведено отключение всех сетей от ВМ, а затем подключение сетей в соответствии с параметром `networks`.
Если `false`, то очерёдность при сравнении учитываться не будет. Соответственно, сети, которые имеются в списке параметра `networks` и уже подключены к ВМ, переподключаться не будут, что может кратно уменьшить время выполнения изменения сетей. |
| networks | (list) | Список словарей, описывающих сети ВМ.
Ключи словаря:
• `type` (string) (обязательный) - тип сети; значения: `VINS` (внутренняя), `EXTNET` (внешняя), `VFNIC` (вирт. функция), `DPDK`, `EMPTY` (без подключения к сети)
• `id` (int) (необязательный) - идентификатор внутренней/внешней/DPDK сети или пула вирт. функций
• `ip_addr` (string) (необязательный) - IP-адрес, используемый для подключения к данной сети; применимо только для `VINS` и `EXTNET`
• `mtu` (int) (необязательный) - MTU интерфейса; применимо только для `DPDK`.
ВМ не может одновременно быть подключена к сети DPDK и к сети другого типа.
Чтобы отключить все сети, нужно указать пустой список `[]`. |
| numa_affinity | (str)
Значения:
`strict`
`loose`
`none` | Правило применения NUMA affinity к виртуальной машине.
`strict` - строго с NUMA affinity, `loose` - использовать NUMA affinity, если возможно, `none` - отменить применение NUMA affinity.
Значение по умолчанию при создании: `none`. |
| pool | (str) | Пул СХД, заданной параметром `sep_id`. Если пул не задан, то он будет выбран платформой.
| ram | (int) | Объем оперативной памяти в МБ, выделенной данной ВМ. Параметр является обязательным при создании. Если указать его для уже существующей ВМ, то будет выполнена попытка изменить объем выделенной памяти. |
| rg_id | (int) | Уникальный цифровой идентификатор уже существующей ресурсной группы, в которой будет создана новая или находится уже существующая ВМ. Данный параметр является одним из методов идентификации существующей РГ (альтернативой является задание комбинации `account_name` и `rg_name`).|
| rg_name | (string) | Имя уже существующей ресурсной группы, в которой будет создаа новая или находится уже существующая ВМ. Данный параметр является одним из методов идентификации существующей РГ, когда задается пара `account_name` и `rg_name` (альтернативой является задание `rg_id`). Если заданы и `rg_id`, и `rg_name`, то параметр `rg_name` игнорируется.|
| sep_id | (int) | Идентификатор СХД для загрузочного диска ВМ. Если не задан, то будет использоваться СХД образа.
| ssh_key | (string) | Открытая часть SSH-ключа, который необходимо добавить на создаваемую ВМ для пользователя, заданного параметром `ssh_key_user`. Данный параметр применим только для ОС Linux, используется только при создании и игнорируется при других операциях. |
| ssh_key_user | (string) | Имя пользователя в гостевой ОС (только для Linux), для которого добавляется SSH-ключ, заданный параметром `ssh_key`. Данный параметр является обязательным, если задан `ssh_key`. Используется только при создании и игнорируется при других операциях. |
| state | (str)
Значения:
`present`
`absent`
`poweredon`
`poweredoff`
`halted`
`paused` | Целевое состояние ВМ.
`present` - виртуальная машина существует и не удалена. Если удалена в корзину, то будет восстановлена из корзины.
`absent` - виртуальная машина безвозвратно удалена.
`poweredon` - виртуальная машина запущена. Если остановлена, то будет запущена. Если удалена в корзину, то будет восстановлена из корзины.
`poweredoff` - виртуальная машина остановлена. Если запущена, то будет остановлена.
`halted` - аналогично `poweredoff`.
`paused` - виртуальная машина приостановлена.
Значение по умолчанию при создании: `present`. |
| tag | (dict) | Словарь, пары ключ-значение которого, описывают тэги для ВМ.
Чтобы очистить теги, нужно указать пустой словарь `{}`.|
## Возвращаемые значения модуля decort_kvmvm
Модуль **decort_kvmvm** возвращает информацию о виртуальной машине в виде словаря `facts` со следующими ключами:
| Ключ | Тип данных | Описание |
| ------ | ------ | ------ |
| account_id | int | Идентификатор аккаунта. |
| arch | string | Архитектура ВМ. |
| auto_start | bool | Автоматический запуск ВМ после перезапуска вычислительного узла, за которым она закреплена. |
| chipset | string | Эмулируемый чипсет. |
| cpu | int | Количество виртуальных процессоров. |
| cpu_pin | bool | Запуск виртуальной машины на выделенных процессорах. |
| custom_fields | dict | Словарь, управляющий XML виртуальной машины. Если `null`, то управление виртуальной машиной через XML отключено, иначе - управление через XML включено. |
| data_disks | list | Список идентификаторов дисков с данными, подключенных к ВМ. |
| disk_size | int | Размер загрузочного диска в ГБ. |
| hp_backed | bool | Использовать Huge Pages для выделения оперативной памяти виртуальной машины. |
| id | int | Идентификатор ВМ. |
| image_id | id | Идентификатор образа.
| interfaces | list | Список словарей, описывающих сетевые интерфейсы ВМ. |
| name | string | Имя ВМ. |
| numa_affinity | str | Правило применения NUMA affinity к виртуальной машине. |
| password | string | Пароль пользователя ОС по умолчанию. |
| private_ips | list | Список IP-адресов на сетевых интерфейсах ВМ, которые подключены к внутренним сетям. |
| public_ips | list | Список IP адресов на сетевых интерфейсах ВМ, которые подключены к внешним сетям. |
| ram | int | Объём ОЗУ ВМ в МБ. |
| rg_id | int | Идентификатор ресурсной группы, которой принадлежит данная ВМ. |
| state | string | Состояние ВМ.|
| tags | dict | Словарь, пары ключ-значение которого, описывают тэги ВМ.
| tech_status | str | Технический статус ВМ.
| username | string | Имя пользователя ОС по умолчанию. |
| vnc_password | string | Пароль, используемый для подключения к ВМ через VNC. |
## Примеры использования
### Создать
#### С указанием описания
```
- name: Example
hosts: localhost
tasks:
- name: Create VM with image
decort_kvmvm:
# Параметры для авторизации упущены
rg_id: "{{ rg_id }}"
name: "{{ vm_name }}"
cpu: 1
ram: 512
image_id: "{{ image_id }}"
chipset: Q35
description: vm description
state: present
```
#### С указанием объёма загрузочного диска
```
- name: Example
hosts: localhost
tasks:
- name: Create VM with image
decort_kvmvm:
# Параметры для авторизации упущены
rg_id: "{{ rg_id }}"
name: "{{ vm_name }}"
cpu: 1
ram: 512
image_id: "{{ image_id }}"
chipset: Q35
boot_disk: 10
state: present
```
#### С указанием СХД
```
- name: Example
hosts: localhost
tasks:
- name: Create VM with image
decort_kvmvm:
# Параметры для авторизации упущены
rg_id: "{{ rg_id }}"
name: "{{ vm_name }}"
cpu: 1
ram: 512
image_id: "{{ image_id }}"
chipset: Q35
sep_id: "{{ sep_id }}"
pool: "{{ sep_pool_name }}"
state: present
```
#### С указанием Cloud-init user data
```
- name: Example
hosts: localhost
tasks:
- name: Create VM with image
decort_kvmvm:
# Параметры для авторизации упущены
rg_id: "{{ rg_id }}"
name: "{{ vm_name }}"
cpu: 1
ram: 512
image_id: "{{ image_id }}"
chipset: Q35
ci_user_data:
packages:
- apache2
write_files:
- content: |