Initial decort_kvmvm page

XX.-Модуль-decort_kvmvm.md

@@ -0,0 +1,91 @@
+# Модуль decort_kvmvm
+## XX.1 Обзор модуля _decort_kvmvm_
+Модуль _decs_osimage_ предназначен для предназначен для выполнения следующих действий над виртуальными серверами, созданными на базе технологии виртуализации KVM, в облачной платформе DECORT:
+1. Создание нового виртуального сервера указанной аппаратной архитектуры. Платформа поддерживает виртуальные сервера архитектуры Intel x86 и IBM PowerPC.
+2. Изменение конфигурации существующего виртуального сервера:
+    - Изменение количества выделенных CPU и виртуальной ОЗУ. Следует иметь ввиду, что изменение этих параметров в меньшую сторону может потребовать перезагрузки гостевой ОС.
+    - Увеличение размера загрузочного диска.
+3. Изменение состояния существующего виртуального сервера:
+    - Выключение / включение.
+    - Перезагрузка, приостановка / возобновление работы гостевой ОС.
+4. Удаление существующего виртуального сервера.
+5. Получение информации о существующем виртуальном сервере без изменения его конфигурации.
+
+
+## XX.2 Параметры модуля _decort_kvmvm_
+Ниже в алфавитном порядке приведен полный список параметров для модуля _decs_kvmvm_. Актуальную информацию по параметрам, которые поддерживает версия модуля, установленного на вашем Ansible-сервере, можно получить командой:
+
+`ansible-doc -t module decort_kvmvm`
+
+| Параметр | Тип, допустимые значения | Описание |
+| --- | --- | --- |
+| annotation | (string) | Опциональное описание виртуального сервера. Этот параметр используется только в момент создания нового виртуального сервера и игнорируется при любых действиях над существующими серверами. |
+| app_id | (string) | Идентификатор приложения, использующийся для подключения к контроллеру облачной платформы DECS в режиме `authenticator: oauth2`. Данный параметр является обязательным для указанного режима.<br/> Если параметр не задан в _playbook_, модуль _decort_kvmvm_ будет использовать значение переменной окружения _DECS_APP_ID_. |
+| app_secret | (string) | Секретный ключ приложения, который используется для подключения к контроллеру облачной платформы DECS в режиме `authenticator: oauth2`. Данный параметр является обязательным для указанного режима. Так как он содержит секретную информацию, то его не рекомендуется задавать непосредственно в _playbook_.<br/> Если параметр не задан в _playbook_, то модуль _decort_kvmvm_ будет использовать значение переменной окружения _DECS_APP_SECRET_. |
+| authenticator | Значения:<br/>`legacy`<br/>`oauth2`<br/>`jwt` <- default | Режим аутентификации при подключении к контроллеру облачной платформы DECS. |
+| boot_disk | (dict) | Конфигурация загрузочного диска виртуального сервера. Данный параметр является обязательным при создании нового виртуального сервера. Для существующих виртуальных серверов этот параметр является опциональным – с его помощью можно увеличить размер загрузочного диска. Параметр представляет собой словарь со следующими ключами:<br/>* (int) `size` – размер диска в GB.<br/>* (string) `pool` – пул дисковых ресурсов, из которого будет предоставлен данный загрузочный диск. Имена пулов могут меняться от одной модели СХД к другой. Если указанный пул не найден, модуль ожидает, что платформа создаст дисковый ресурс в “default” пуле, который всегда должен присутствовать.<br/>Обратите внимание, что загрузочный диск будет создан на той же системе хранения, где размещён образ ОС (см. параметры `image_name` или `image_id`), на базе которого создаётся данный виртуальный сервер. |
+| controller_url | (string) | URL контроллера, соответствующего экземпляру облачной платформы DECS, в рамках которого должен быть создан (или уже существует) данный виртуальный сервер.<br/>Данный параметр является обязательным. |
+| cpu | (int) | Количество виртуальных CPU, выделенных виртуальному серверу.<br/>Параметр является обязательным при создании нового сервера, во всех других случаях он опциональный. Если указать его для уже существующего сервера, то будет выполнена попытка изменить количество CPU.<br/>Следует иметь ввиду, что _уменьшение_ количества CPU у работающего сервера, как правило, потребует его перезагрузки. |
+| datacenter | (string) | Целевой _datacenter_ под управлением заданного DECS контроллера, где размещается данный виртуальный сервер.<br/>Этот параметр является обязательным при создании нового виртуального сервера, когда вместе с сервером также требуется создать виртуальный сетевой сегмент, в котором он будет расположен. При всех прочих операциях данный параметр игнорируется. |
+| id | (int) | Уникальный цифровой идентификатор виртуального сервера внутри платформы.<br/>Этот параметр используется как один из методов идентификации существующего сервера (альтернатива – по комбинации `name`, `vdc_name` и `tenant`) и игнорируется при создании нового сервера, так как для нового сервера облачная платформа назначает этот идентификатор автоматически.<br/>Если при вызове модуля _decort_kvmvm_ существующий виртуальный сервер идентифицируется по своему `id`, то параметры `tenant`, `vdc_name` и `vdc_id` игнорируются. |
+| image_id | (int)| Уникальный цифровой идентификатор образа ОС, на базе которого следует создать виртуальный сервер.<br/>При создании нового виртуального сервера требуется задать этот параметр или параметр `image_name`. При любых других операциях данные параметры игнорируются.<br/>Если заданы оба этих параметра (`image_id` и `image_name`), то `image_name` игнорируется. Для получения `image_id` по `image_name` можно использовать модуль _decort_osimage_. |
+| image_name | (string) | Название образа ОС, на базе которого следует создать виртуальный сервер.<br/>При создании нового виртуального сервера требуется задать этот параметр или параметр `image_id`. При любых других операциях данные параметры игнорируются.<br/>Параметр `image_name` должен задаваться в точном соответствии с тем, как назван нужный образ ОС в облачной инфраструктуре (с соблюдением заглавных и строчных символов, а также пробелов). |
+| jwt | (string) | JSON Web Token (JWT), который будет использоваться для подключения к контроллеру облачной платформы DECS в режиме `authenticator: jwt`<br/>Данный параметр является обязательным для указанного режима.<br/>Так как он содержит потенциально секретную информацию, а сам JWT, как правило, имеет ограниченное время жизни, то его не рекомендуется задавать непосредственно в _playbook_.<br/>Если этот параметр не определен в _playbook_, то модуль _decort_kvmvm_ будет использовать значение переменной окружения _DECS_JWT_. |
+| name | (string) | Название виртуального сервера.<br/>Чтобы модуль _decort_kvmvm_ мог управлять сервером по его названию, также необходимо задать комбинацию `tenant` и `rg_name` или идентификатор `rg_id`.<br/>Параметр должен задаваться в точном соответствии с тем, как назван сервер в облачной инфраструктуре (с соблюдением заглавных и строчных символов, а также пробелов).<br/>Если для существующего виртуального сервера указаны и `name`, и `id`, то параметр `name` игнорируется и идентификация сервера выполняется по его `id`. |
+| oauth2_url | (string) | URL авторизационного сервера, работающего по протоколу _Oauth2_, который должен использоваться в режиме `authenticator: oauth2`.<br/>Данный параметр является обязательным для указанного режима.<br/>Если параметр не задан в _playbook_, модуль _decort_kvmvm_ будет использовать значение переменной окружения _DECS_OAUTH2_URL_. |
+| password | (string) | Пароль для подключения к контроллеру облачной инфраструктуры DECS в режиме `authenticator: legacy`.<br/>Данный параметр является обязательным для указанного режима.<br/>Так как он содержит секретную информацию, то его не рекомендуется задавать в _playbook_.<br/>Если параметр не задан в _playbook_, то модуль _decort_kvmvm_ будет использовать значение переменной окружения _DECS_PASSWORD_. |
+| ram | (int) | Объем оперативной памяти (RAM) в MB, выделенной данному виртуальному серверу.<br/>Параметр является обязательным при создании нового сервера. Если указать его для уже существующего сервера, то будет выполнена попытка изменить объем выделенной серверу памяти.<br/>Следует иметь ввиду, что уменьшение объема памяти работающего сервера в большинстве случаев потребует его перезагрузки. |
+| rg_id | (int) | Уникальный цифровой идентификатор уже существующей ресурсной группы (RG), в которой будет создан новый или находится уже существующий виртуальный сервер.<br/>Данный параметр является одним из методов идентификации существующей RG (альтернативой является задание комбинации `tenant` и `rg_name`). |
+| rg_name | (string) | Имя уже существующей ресурсной группы (RG), в которой будет создан новый или находится уже существующий виртуальный сервер.<br/>Данный параметр является одним из методов идентификации существующей RG, когда задается пара `tenant` и `rg_name` (альтернативой является задание rg_id, однако такой метод применим только для уже существующих RG).<br/>Параметр должен задаваться в точном соответствии с тем, как нужная ресурсная группа названа в облачной инфраструктуре (с соблюдением заглавных и строчных символов, а также пробелов).<br/>Если заданы и `rg_id`, и `rg_name`, то параметр `rg_name` игнорируется. |
+| ssh_key | (string) | Открытая часть SSH ключа, который необходимо авторизовать на создаваемом виртуальном сервере для пользователя, заданного параметром `ssh_key_user`.<br/>Данный параметр применим только для Linux серверов, является опциональным, используется только при создании нового сервера и игнорируется при других операциях. |
+| ssh_key_user | (string) | Имя пользователя на уровне гостевой ОС (только для Linux серверов) для которого авторизуется SSH ключ, заданный параметром `ssh_key`.<br/>Данный параметр является обязательным, если задан `ssh_key`, используется только при создании нового сервера и игнорируется при других операциях. |
+| state | Значения:<br/>`present` <- default<br/>`absent`<br/>`poweredon`<br/>`poweredoff`<br/>`halted`<br/>`paused`<br/>`check` | Целевое состояние виртуального сервера на выходе из модуля _decort_kvmvm_.<br/> Значение 'halted' - синоним к 'poweredoff'.<br/>Значение 'check' вызывает модуль в _read-only_ режиме и считывает характеристики существующего виртуального сервера. |
+| tags | (string) | Строка, содержащая набор текстовых меток, которые надлежит присвоить данному виртуальному серверу.<br/>Данные текстовые метки представляют собой произвольный текст, который можно использовать для группировки и индексирования виртуальных серверов во внешних приложениях.<br/>Параметр является опциональным.|
+| tenant | (string) | Имя подписчика, которому будет принадлежать новый виртуальный сервер (или уже принадлежит существующий).<br/>Параметр должен задаваться в точном соответствии с тем, как назван нужный подписчик в облачной инфраструктуре (с соблюдением заглавных и строчных символов, а также пробелов).<br/>Этот параметр является опциональным и используется в сценариях, когда вместе с новым виртуальным сервером создается новый виртуальный сетевой сегмент (_VDC_), в котором будет размещаться данный сервер, или когда уже существующий целевой сегмент задается комбинацией `tenant` и `vdc_name`. |
+| user | (string) | Имя пользователя, непосредственно зарегистрированного на контроллере облачной инфраструктуры DECS, которое используется для подключения к контроллеру в режиме `authenticator: legacy`.<br/>Данный параметр является обязательным для указанного режима.<br/>Если параметр не задан в _playbook_, модуль _decort_kvmvm_ будет использовать значение переменной окружения _DECS_USER_.|
+| verify_ssl | (bool)<br/>`True` <- default<br/>`False` | Позволяет отключить проверку SSL сертификатов при выполнении API вызовов в адрес контроллера облачной инфраструктуры, например, при работе с изолированной облачной инфраструктурой, использующей самоподписанные сертификаты.<br/>Применяйте данный параметр с осторожностью, предпочтительно в защищенных средах. |
+| workflow_callback | (string) | URL, по которому вышестоящее приложение (например, пользовательский портал или оркестратор верхнего уровня, инициирующий запуск Ansible playbook) ожидает API вызова, в параметрах которого модуль _desc_vm_ будет оперативно передавать информацию о своем статусе и текущей фазе исполнения.<br/>Данный параметр является опциональным.<br/>Функциональность callbacks в текущей версии модуля _decort_kvmvm_ не реализована.|
+| workflow_context | (string) | Контекстная информация, которая будет содержаться в параметрах API вызова, адресованного к `workflow_callback` URL.<br>Данная информация призвана однозначно идентифицировать задачу, выполняемую модулем в настоящий момент, чтобы оркестратор верхнего уровня мог сопоставить получаемые через вызов `workflow_callback` данные со своим внутренним состоянием и отслеживать инициированные им задачи.<br/>Параметр является опциональным и имеет значение только при условии, что также задан `workflow_callback`.<br/>Функциональность callbacks в текущей версии модуля _decort_kvmvm_ не реализована.|
+
+
+## XX.3 Возвращаемые значения модуля _decort_kvmvm_
+При успешном выполнении модуль _decs_osimage_ возвращает словарь `osimage_facts` со следующими ключами:
+
+| Ключ | Тип данных | Описание |
+| --- | --- | --- |
+| id | int | Уникальный цифровой идентификатор образа ОС в платформе DECS. |
+| name | string | Имя образа ОС. |
+| size | int | Размер образа ОС в ГБ. |
+| type | string | Тип образа ОС. Доступные типы: `Linux`, `Windows`, `Other`. |
+| state | string | Текущее состояние образа ОС. Доступные статусы: `CREATED`, `DISABLED`. |
+
+## 12.4 Пример использования модуля _decort_kvmvm_
+В данном примере сначала извлекается идентификатор образа ОС, а затем на базе этого образа создается виртуальный сервер.
+
+```
+
+- name: create new x86 KVM VM according to the specs
+  decort_kvmvm:
+      authenticator: oauth2
+      app_id: "{{ my_app_id }}"
+      app_secret: "{{ my_app_secret }}"
+      oauth2_url: "https://sso.decs.online"
+      controller_url: "https://cloud.digitalenergy.online"
+      name: NewVM01
+      arch: KVM_X86
+      state: present
+      cpu: 2
+      ram: 4096
+      boot_disk:
+        size: 10
+      image_id: "{{ ubuntu_img.osimage_facts.id }}"
+      rg_id: "MyFirstRG"
+      annotation: "My new x86 VM created and managed with decort_kvmvm module"
+  delegate_to: localhost
+  register: kvmvm01_specs
+...
+```
+
+Обратите внимание, как используется идентификатор образа ОС при создании нового виртуального сервера (в предположении, что результат выполнения _task_ для модуля _decs_osimage_ был сохранен в переменной `ubuntu_img`):
+
+`    image_id: "{{ ubuntu_img.osimage_facts.id }}"`