decort-ansible/wiki/5.2.6/модуль-decort_kvmvm.md

03.01 Модуль decort_kvmvm

Обзор модуля decort_kvmvm

Модуль decort_kvmvm предназначен для предназначен для выполнения следующих действий над виртуальными серверами, созданными на базе технологии виртуализации KVM, в облачной платформе DECORT:

1. Создание нового виртуального сервера указанной аппаратной архитектуры. Платформа поддерживает виртуальные сервера архитектуры Intel x86 и IBM PowerPC.
2. Изменение конфигурации существующего виртуального сервера:
   • Изменение количества выделенных CPU и виртуальной ОЗУ. Следует иметь ввиду, что изменение этих параметров в меньшую сторону может потребовать перезагрузки гостевой ОС.
   • Увеличение размера загрузочного диска
   • Подключение / отключение дополнительных дисковых ресурсов.
   • Создание / удаление сетевых подлкючений.
3. Изменение состояния существующего виртуального сервера:
   • Выключение / включение.
   • Перезагрузка, приостановка / возобновление работы гостевой ОС.
4. Удаление существующего виртуального сервера.
5. Получение информации о существующем виртуальном сервере без изменения его конфигурации.

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

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

Параметр	Тип, допустимые значения	Описание
account_id	int	Уникальный цифровой идентификатор подписчика, владеющего данным виртуальным сервером.Этот параметр является опциональным и используется в сценариях, когда уже существующая ресурсная группа задается комбинацией account_id и rg_name. Если задан account_id, то account_name игнорируется.
account_name	(string)	Имя подписчика, которому будет принадлежать новый виртуальный сервер (или уже принадлежит существующий). Параметр должен задаваться в точном соответствии с тем, как назван нужный подписчик в облачной инфраструктуре (с соблюдением заглавных и строчных символов, а также пробелов). Этот параметр является опциональным и используется в сценариях, когда уже существующая ресурсная группа задается комбинацией account_name и rg_name. Если задан account_id, то account_name игнорируется.
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.
arch	Значения: KVM_X86 <- default KVM_PPC	Аппаратная архитектура виртуального сервера. Данный параметр является обязательным при создании нового вирутального сервера и игнорируется для уже существующего сервера. Платформа DECORT поддерживает виртуальные серверы KVM аппаратных архитектур Intel x86 и IBM PowerPC.
authenticator	Значения: legacy oauth2 jwt <- default	Режим аутентификации при подключении к контроллеру облачной платформы DECORT.
boot_disk	(int)	Размер загрузочного диска виртуального сервера в ГБ. Загрузочный диск всегда создаётся на той же системе хранения и в том же пуле, где размещён образ ОС (см. параметры image_name или image_id), на базе которого создаётся данный виртуальный сервер. Если данный параметр не указан на момент создания виртуального сервера, то размер загрузочного диска будет установлен равным размеру образа ОС.
controller_url	(string)	URL контроллера, соответствующего экземпляру облачной платформы DECORT, в рамках которого должен быть создан (или уже существует) данный виртуальный сервер. Данный параметр является обязательным.
cpu	(int)	Количество виртуальных CPU, выделенных виртуальному серверу. Параметр является обязательным при создании нового сервера, во всех других случаях он опциональный. Если указать его для уже существующего сервера, то будет выполнена попытка изменить количество CPU. Следует иметь ввиду, что уменьшение количества CPU у работающего сервера, как правило, потребует его перезагрузки.
data_disks	(list)	Список идентификаторов дисков, которые следует подключить к данному виртуальному серверу как дополнительные (помимо загрузочного диска, который создаётся автоматически вместе с виртуальным сервером).
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_id по image_name можно использовать модуль decort_osimage.
image_name	(string)	Название образа ОС, на базе которого следует создать виртуальный сервер. При создании нового виртуального сервера требуется задать этот параметр или параметр image_id. При любых других операциях данные параметры игнорируются. Параметр image_name должен задаваться в точном соответствии с тем, как назван нужный образ ОС в облачной инфраструктуре (с соблюдением заглавных и строчных символов, а также пробелов).
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. Параметр должен задаваться в точном соответствии с тем, как назван сервер в облачной инфраструктуре (с соблюдением заглавных и строчных символов, а также пробелов). Если для существующего виртуального сервера указаны и name, и id, то параметр name игнорируется и идентификация сервера выполняется по его id.
networks	(list of dicts)	Опциональный список словарей, задающих сетевые подключения для данного виртуального сервера. Структура словаря:- (string) type - тип сетевого подключения, одно из VINS или EXTNET; - (int) id - идентификатор сетевого сегмента данного подключения; для type: VINS это VINS ID, для type: EXTNET это ID внешнего сетевого сегмента; - (string) ip_addr - опциональный IP адрес, который надлежит присвоить данному подключению; если данный параметр не указан, то платформа назначит свободный IP адрес из нужного диапазона автоматически. Если этот параметр не задан, то будет создан сервер без сетевых подключений, а если модуль вызван для уже существуюшего сервера, то все его сетевые подключения будут удалены.
oauth2_url	(string)	URL авторизационного сервера, работающего по протоколу Oauth2, который должен использоваться в режиме authenticator: oauth2. Данный параметр является обязательным для указанного режима. Если параметр не задан в playbook, модуль decort_kvmvm будет использовать значение переменной окружения DECORT_OAUTH2_URL.
password	(string)	Пароль для подключения к контроллеру облачной инфраструктуры DECORT в режиме authenticator: legacy. Данный параметр является обязательным для указанного режима. Так как он содержит секретную информацию, то его не рекомендуется задавать в playbook. Если параметр не задан в playbook, то модуль decort_kvmvm будет использовать значение переменной окружения DECORT_PASSWORD.
ram	(int)	Объем оперативной памяти (RAM) в MB, выделенной данному виртуальному серверу. Параметр является обязательным при создании нового сервера. Если указать его для уже существующего сервера, то будет выполнена попытка изменить объем выделенной серверу памяти. Следует иметь ввиду, что уменьшение объема памяти работающего сервера в большинстве случаев потребует его перезагрузки.
rg_id	(int)	Уникальный цифровой идентификатор уже существующей ресурсной группы (RG), в которой будет создан новый или находится уже существующий виртуальный сервер. Данный параметр является одним из методов идентификации существующей RG (альтернативой является задание комбинации account_name и rg_name).
rg_name	(string)	Имя уже существующей ресурсной группы (RG), в которой будет создан новый или находится уже существующий виртуальный сервер. Данный параметр является одним из методов идентификации существующей RG, когда задается пара account_name и rg_name (альтернативой является задание rg_id, который можно получить с помощью модуля decort_rg). Параметр должен задаваться в точном соответствии с тем, как нужная ресурсная группа названа в облачной инфраструктуре (с соблюдением заглавных и строчных символов, а также пробелов). Если заданы и rg_id, и rg_name, то параметр rg_name игнорируется.
ssh_key	(string)	Открытая часть SSH ключа, который необходимо авторизовать на создаваемом виртуальном сервере для пользователя, заданного параметром ssh_key_user. Данный параметр применим только для Linux серверов, является опциональным, используется только при создании нового сервера и игнорируется при других операциях.
ssh_key_user	(string)	Имя пользователя на уровне гостевой ОС (только для Linux серверов) для которого авторизуется SSH ключ, заданный параметром ssh_key. Данный параметр является обязательным, если задан ssh_key, используется только при создании нового сервера и игнорируется при других операциях.
state	Значения: present <- default absent poweredon poweredoff halted paused check	Целевое состояние виртуального сервера на выходе из модуля decort_kvmvm. Значение 'halted' - синоним к 'poweredoff'. Значение 'check' вызывает модуль в read-only режиме и считывает характеристики существующего виртуального сервера.
tags	(string)	Строка, содержащая набор текстовых меток, которые надлежит присвоить данному виртуальному серверу. Данные текстовые метки представляют собой произвольный текст, который можно использовать для группировки и индексирования виртуальных серверов во внешних приложениях. Параметр является опциональным.
user	(string)	Имя пользователя, непосредственно зарегистрированного на контроллере облачной инфраструктуры DECORT, которое используется для подключения к контроллеру в режиме authenticator: legacy. Данный параметр является обязательным для указанного режима. Если параметр не задан в playbook, модуль decort_kvmvm будет использовать значение переменной окружения DECORT_USER.
verify_ssl	(bool) True <- default False	Позволяет отключить проверку SSL сертификатов при выполнении API вызовов в адрес контроллера облачной инфраструктуры, например, при работе с изолированной облачной инфраструктурой, использующей самоподписанные сертификаты. Применяйте данный параметр с осторожностью, предпочтительно в защищенных средах.
workflow_callback	(string)	URL, по которому вышестоящее приложение (например, пользовательский портал или оркестратор верхнего уровня, инициирующий запуск Ansible playbook) ожидает API вызова, в параметрах которого модуль будет оперативно передавать информацию о своем статусе и текущей фазе исполнения. Данный параметр является опциональным. Функциональность callbacks в текущей версии модуля не реализована.
workflow_context	(string)	Контекстная информация, которая будет содержаться в параметрах API вызова, адресованного к workflow_callback URL. Данная информация призвана однозначно идентифицировать задачу, выполняемую модулем в настоящий момент, чтобы оркестратор верхнего уровня мог сопоставить получаемые через вызов workflow_callback данные со своим внутренним состоянием и отслеживать инициированные им задачи. Параметр является опциональным и имеет значение только при условии, что также задан workflow_callback. Функциональность callbacks в текущей версии модуля decort_kvmvm не реализована.

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

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

Ключ	Тип данных	Описание
account_id	int	Цифровой идентификатор подписчика, владеющего данным виртуальным сервером.
account_name	string	Имя подписчика, владеющего данным виртуальным сервером.
arch	string	Аппаратная архитектура данного виртуального сервера. Допустимые значения: KVM_X86 для Intel x86 и KVM_PPC для IBM PowerPC.
cpu	int	Количество виртуальных CPU, выделенных данному виртуальному серверу.
data_disks	list of ints	Список идентификаторов data-дисков, в настоящий момент подключенных к данному серверу.
disk_size	int	Размер загрузочного диска в ГБ.
id	int	Уникальный цифровой идентификатор данного виртуального сервера (экземпляра compute) в платформе DECORT.
name	string	Имя виртуального сервера. Имя уникально только в рамках одной и той же ресурсной группы.
password	string	Пароль системного пользователя по умолчанию.
private_ips	list of strings	Список IP адресов на сетевых интерфейсах сервера, которые подключены к виртуальным сетевым сегментам (Virtual Network Segments, ViNS).
public_ips	list of strings	Список IP адресов на сетевых интерфейсах сервера, которые подключены непосредственно к внешним сетевым сегментам (external network segments).
ram	int	Объём ОЗУ в МБ, выделенный виртуальному серверу.
rg_id	int	Уникальный цифровой идентификатор ресурсной группы (RG), к которой принадлежит данный сервер.
state	string	Состояние виртуального сервера.
username	string	Имя системного пользователя по умолчанию.

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

В данном примере создается виртуальный сервер KVM VM по имени MyFirstVM с аппаратной архитектурой Intel x86.

- 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.digitalenergy.online"
    controller_url: "https://cloud.digitalenergy.online"
    name: MyFirstVM
    arch: KVM_X86
    state: present
    cpu: 2
    ram: 4096
    boot_disk: 10
    image_id: "{{ my_img.facts.id }}"
    networks:
      - type: VINS
        id: "{{ my_vins.facts.id }}"
    rg_id: "{{ my_rg.facts.id }}"
    annotation: "My 1st VM created and managed with DECORT KVMVM module"
  delegate_to: localhost
  register: new_vm

Виртуальный сервер создаётся на базе некоторого системного образа (дискового ресурса, содержащего операционную систему). В данном примере системный образ задаётся по его идентификатору (image_id: "{{ my_img.facts.id }}"). Для получения такого идентификатора можно использовать модуль decort_osimage.

Виртуальный сервер всегда создаётся в принадлежности к некоторой ресурсной группе. В данном примере соответствующая ресурсная группа задаётся по её идентификатору (rg_id: "{{ my_rg.facts.id }}"). Для управления ресурсными группами предназначен модуль decort_rg. С помощью этого модуля можно также получит идентификатор ресурсной группы, чтобы использовать его при создании виртуального сервера.

Для управления сетевыми подключениями виртуального сервера в модуле decort_kvmvm используется параметр networks, представляющий собой список с описанием требующихся подключений. В данном примере задано одно подключение в виртуальному сетевому сегменту (type: VINS) с указанным идентификатором (id: "{{ my_vins.facts.id }}"). Для управления виртуальными сетевыми сегментами и получения их идентификаторов служит модуль decort_vins.