# Модуль decort_kvmvm
## Обзор модуля decort_kvmvm

Модуль **decort_kvmvm** предназначен для выполнения следующих действий над виртуальными машинами:
- создать
- получить информацию
- остановить/приостановить/запустить
- подключить/отключить диски с данными
- подключить/отключить сети
- изменить
  - объём загрузочного диска в большую сторону
  - количество CPU
  - объём ОЗУ
  - тэги
  - affinity метку
  - affinity правила
  - anti-affinity правила
- удалить (безвозвратно)

## Параметры модуля decort_kvmvm

Ниже в алфавитном порядке приведен полный список параметров для модуля **decort_kvmvm**. Актуальную информацию по параметрам, которые поддерживает версия модуля, установленного на вашем Ansible-сервере, можно получить командой:
`ansible-doc -t module decort_kvmvm`


| Параметр | Тип, допустимые значения | Описание |
| ------ | ------ | ------ |
| aaff_rule | (list) | Список словарей, описывающих anti-affinity правила.<br>Ключи словаря:<br>&bull; `topology` (string) (обязательный) - назначение правила; значения: `node` (узел) или `compute` (ВМ)<br>&bull; `policy` (string) (обязательный) - степень "необходимости" этого правила; значения: `RECOMMENDED` или `REQUIRED`<br>&bull; `mode` (string) (обязательный) - режим сравнения; значения: `EQ` (должно соответствовать), `NE` (не должно соответствовать), `ANY` (любое)<br>&bull; `key` (string) (обязательный) - ключ, который учитывается при анализе данного правила<br>&bull; `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>&bull; `topology` (string) (обязательный) - назначение правила; значения: `node` (узел) или `compute` (ВМ)<br>&bull; `policy` (string) (обязательный) - степень "необходимости" этого правила; значения: `RECOMMENDED` или `REQUIRED`<br>&bull; `mode` (string) (обязательный) - режим сравнения; значения: `EQ` (должно соответствовать), `NE` (не должно соответствовать), `ANY` (любое)<br>&bull; `key` (string) (обязательный) - ключ, который учитывается при анализе данного правила<br>&bull; `value` (string) (обязательный) - значение ключа, учитываемого при анализе данного правила (зависит от ключа `mode`).<br>Чтобы очистить affinity правила, нужно указать пустой список `[]`. |
| affinity_label | (str) | Метка affinity.<br>Чтобы очистить метку affinity, нужно указать пустую строку `""`. |
| annotation | (string) | Опциональное описание виртуальной машины. Этот параметр используется только при создании.|
| app_id | (string) | Идентификатор приложения, использующийся для подключения к контроллеру облачной платформы DECORT в режиме `authenticator: oauth2`. Данный параметр является обязательным для указанного режима. Если параметр не задан в playbook, модуль **decort_kvmvm** будет использовать значение переменной окружения `DECORT_APP_ID`.|
| app_secret | (string) | Секретный ключ приложения, который используется для подключения к контроллеру облачной платформы DCORT в режиме `authenticator: oauth2`. Данный параметр является обязательным для указанного режима. Так как он содержит секретную информацию, то его не рекомендуется задавать непосредственно в playbook. Если параметр не задан в playbook, то модуль **decort_kvmvm** будет использовать значение переменной окружения `DECORT_APP_SECRET`.|
| authenticator | (str)<br>Значения:<br>`oauth2`<br>`jwt` | Режим аутентификации при подключении к контроллеру облачной платформы DECORT. Обязательный параметр. |
| boot_disk | (int) | Объём загрузочного диска виртуальной машины в ГБ.<br>Если параметр не задан, размер будет равен размеру образа.<br>Если не заданы этот параметр и параметры `image_id` и `image_name`, то виртуальная машина будет создана без загрузочного диска. |
| chipset | (string)<br>Значения:<br>`q35`<br>`i440fx`<br>Default: `i440fx` | Эмулируемый чипсет. |
| ci_user_data | (dict) | конфигурация для cloud-init
| controller_url | (string) | URL контроллера, соответствующего экземпляру облачной платформы DECORT, в рамках которого должен быть создан (или уже существует) данная виртуальная машина. Данный параметр является обязательным. |
| cpu | (int) | Количество виртуальных процессоров, выделяемых виртуальной машине. |
| data_disks | (list) | Список идентификаторов дисков, которые следует подключить к данной виртуальной машине как дополнительные.<br>Чтобы отключить все диски, нужно указать пустой список `[]`.|
| id | (int) | Уникальный цифровой идентификатор виртуальной машины. Этот параметр используется как один из методов идентификации существующей ВМ (альтернатива – по комбинации `name`, `rg_name` и `account_name`). Если при вызове модуля **decort_kvmvm** существующая ВМ идентифицируется по `id`, то параметры `account_id`, `account_name`, `rg_id` и `rg_name` игнорируются. |
| image_id | (int) | Уникальный цифровой идентификатор образа, на базе которого следует создать виртуальную машину.<br>При создании задать этот параметр или параметр `image_name`. При любых других операциях данные параметры игнорируются.<br>Если заданы оба этих параметра (`image_id` и `image_name`), то `image_name` игнорируется.<br>Если этот параметр и параметр `image_name` не заданы, то виртуальная машина будет создана без образа. |
| image_name | (string) | Название образа, на базе которого следует создать ВМ.<br>При создании требуется задать этот параметр или параметр `image_id`. При любых других операциях данные параметры игнорируются.<br>Если этот параметр и параметр `image_id` не заданы, то виртуальная машина будет создана без образа. |
| jwt | (string) | JSON Web Token (JWT), который будет использоваться для подключения к контроллеру облачной платформы DECORT в режиме `authenticator: jwt`. Данный параметр является обязательным для указанного режима. Так как он содержит потенциально секретную информацию, а сам JWT, как правило, имеет ограниченное время жизни, то его не рекомендуется задавать непосредственно в playbook. Если этот параметр не определен в playbook, то модуль **decort_kvmvm** будет использовать значение переменной окружения `DECORT_JWT`.
| name | (string) | Имя ВМ. Чтобы модуль **decort_kvmvm** мог управлять сервером по его названию, также необходимо задать комбинацию `account_name` и `rg_name` или `rg_id`.<br>Если для существующей ВМ указаны и `name`, и `id`, то параметр `name` используется для переименования. |
| network_order_changing | (bool)<br>Default:<br>`false` | Соблюдение очерёдности сетей при их изменении.<br>Если `true`, то сравнение списка уже подключённых к ВМ сетей со списком из параметра `networks` будет производится <u>с учётом очерёдности сетей</u> и, <u>при выявлении несоответствия, сначала будет произведено отключение всех сетей от ВМ</u>, а затем подключение сетей в соответствии с параметром `networks`.<br> Если `false`, то очерёдность при сравнении учитываться не будет. Соответственно, сети, которые имеются в списке параметра `networks` и уже подключены к ВМ, переподключаться не будут, что может кратно уменьшить время выполнения изменения сетей. |
| networks | (list) | Список словарей, описывающих сети ВМ.<br>Ключи словаря:<br>&bull; `type` (string) (обязательный) - тип сети; значения: `VINS` (внутренняя), `EXTNET` (внешняя), `VFNIC` (вирт. функция), `DPDK`, `EMPTY` (без подключения к сети)<br>&bull; `id` (int) (необязательный) - идентификатор внутренней/внешней/DPDK сети или пула вирт. функций<br>&bull; `ip_addr` (string) (необязательный) - IP-адрес, используемый для подключения к данной сети; применимо только для `VINS` и `EXTNET`.<br>ВМ не может одновременно быть подключена к сети DPDK и к сети другого типа.<br>Чтобы отключить все сети, нужно указать пустой список `[]`. |
| oauth2_url | (string) | URL авторизационного сервера, работающего по протоколу Oauth2, который должен использоваться в режиме `authenticator: oauth2`. Данный параметр является обязательным для указанного режима. Если параметр не задан в playbook, модуль **decort_kvmvm** будет использовать значение переменной окружения `DECORT_OAUTH2_URL`. |
| 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)<br>Значения:<br>`present`<br>`absent`<br>`poweredon`<br>`poweredoff`<br>`halted`<br>`paused`<br>`check`<br>Default: `present` | Целевое состояние ВМ.<br> Значение `halted` - синоним к `poweredoff`. Значения `present` и `poweredon` равнозначны. <br>Значение `check` вызывает модуль в _read-only_ режиме и считывает характеристики существующей ВМ. |
| tag | (dict) | Словарь, пары ключ-значение которого, описывают тэги для ВМ.<br>Чтобы очистить теги, нужно указать пустой словарь `{}`.|
| verify_ssl | (bool)<br>Default: `true` | Позволяет отключить проверку SSL сертификатов при выполнении API вызовов в адрес контроллера облачной инфраструктуры, например, при работе с изолированной облачной инфраструктурой, использующей самоподписанные сертификаты.<br>Применяйте данный параметр с осторожностью, предпочтительно в защищенных средах. |

## Возвращаемые значения модуля decort_kvmvm

Модуль **decort_kvmvm** возвращает информацию о виртуальной машине в виде словаря `facts` со следующими ключами:


| Ключ | Тип данных | Описание |
| ------ | ------ | ------ |
| account_id | int | Идентификатор аккаунта. |
| arch | string | Архитектура ВМ. |
| chipset | string | Эмулируемый чипсет. |
| cpu | int | Количество виртуальных процессоров. |
| data_disks | list | Список идентификаторов дисков с данными, подключенных к ВМ. |
| disk_size | int | Размер загрузочного диска в ГБ. |
| id | int | Идентификатор ВМ. |
| image_id | id | Идентификатор образа.
| interfaces | list | Список словарей, описывающих сетевые интерфейсы ВМ, отсортированный по номеру слота PCI. |
| name | string | Имя ВМ. |
| password | string | Пароль пользователя ОС по умолчанию. |
| private_ips | list | Список IP-адресов на сетевых интерфейсах ВМ, которые подключены к внутренним сетям. |
| public_ips | list | Список IP адресов на сетевых интерфейсах ВМ, которые подключены к внешним сетям. |
| ram | int | Объём ОЗУ ВМ в МБ. |
| rg_id | int | Идентификатор ресурсной группы, которой принадлежит данная ВМ. |
| state | string | Состояние ВМ.|
| tags | dict | Словарь, пары ключ-значение которого, описывают тэги ВМ.
| tech_status | str | Технический статус ВМ.
| username | string | Имя пользователя ОС по умолчанию. |

## Пример использования модуля decort_kvmvm

В данном примере создается ВМ с именем MyFirstVM.
```
- name: Сreate VM
  decort_kvmvm:
    app_id: "{{ my_app_id }}"
    app_secret: "{{ my_app_secret }}"
    authenticator: oauth2
    controller_url: "https://cloud.digitalenergy.online"
    cpu: 2
    image_id: "{{ my_img.facts.id }}"
    name: MyFirstVM
    networks:
      - type: VINS
        id: "{{ my_vins.facts.id }}"
    oauth2_url: "https://sso.digitalenergy.online"
    ram: 4096
    rg_id: "{{ my_rg.facts.id }}"
  register: my_vm
```