community.general.xenserver_guest модуль — Управление виртуальными машинами, работающими на хосте/пуле Citrix Hypervisor/XenServer

Примечание

Этот модуль входит в состав коллекции community.general (версия 9.5.0).

У вас, возможно, уже установлена эта коллекция, если вы используете пакет ansible. Она не включена в ansible-core. Чтобы проверить установку, выполните ansible-galaxy collection list.

Для установки используйте: ansible-galaxy collection install community.general. Для использования этого модуля необходимы дополнительные требования. Подробности см. в разделе Требования.

Для использования в плейбуке укажите: community.general.xenserver_guest.

Описание
Требования
Параметры
Атрибуты
Примечания
Примеры
Возвращаемые значения

Описание

Этот модуль можно использовать для создания новых виртуальных машин из шаблонов или других виртуальных машин, изменения различных компонентов виртуальной машины, таких как сеть и диск, переименования виртуальной машины и удаления виртуальной машины с связанными компонентами.

Требования

Ниже перечислены требования к хосту, на котором выполняется этот модуль.

XenAPI

Параметры

Параметр	Комментарии
cdrom dictionary	Конфигурация CD-ROM для виртуальной машины. Все параметры чувствительны к регистру.
iso_name string	Имя файла образа ISO из одной из библиотек ISO XenServer (подразумевает `cdrom.type=iso`). Обязательно, если `cdrom.type` установлено в `iso`.
type string	Тип CD-ROM. С `none` устройство CD-ROM будет присутствовать, но будет пустым. Варианты: `"none"` `"iso"`
custom_params list / elements=dictionary	Определите список пользовательских параметров виртуальной машины для установки на виртуальной машине. Полезно для опытных пользователей, знакомых с управлением параметрами виртуальных машин через xe CLI. Объект пользовательского значения содержит два поля `custom_params[].key` и `custom_params[].value` (см. пример ниже).
key string / required	Имя параметра виртуальной машины.
value any / required	Значение параметра виртуальной машины.
disks aliases: disk list / elements=dictionary	Список дисков для добавления в виртуальную машину. Все параметры чувствительны к регистру. Удаление или отключение существующих дисков виртуальной машины не поддерживается. Для новых дисков необходимо указать либо `disks[].size`, либо один из параметров `disks[].size_[tb,gb,mb,kb,b]`. Виртуальная машина должна быть выключена для изменения размера диска.
name aliases: name_label string	Имя диска.
name_desc string	Описание диска.
size string	Размер диска с единицей измерения. Единица измерения должна быть: `b`, `kb`, `mb`, `gb`, `tb`. Виртуальная машина должна быть выключена для изменения этого параметра. Если единица измерения не указана, размер считается в байтах.
size_b string	Размер диска в байтах.
size_gb string	Размер диска в гигабайтах.
size_kb string	Размер диска в килобайтах.
size_mb string	Размер диска в мегабайтах.
size_tb string	Размер диска в терабайтах.
sr string	Репозиторий хранения для создания диска. Если не указано, будет использоваться репозиторий по умолчанию. Не может использоваться для перемещения диска в другой репозиторий.
sr_uuid string	UUID репозитория хранения для создания диска. Используйте, если имя репозитория хранения не уникально.
folder string	Папка назначения для виртуальной машины. Этот параметр чувствителен к регистру. Пример: folder: /folder1/folder2
force boolean	Игнорировать предупреждения и выполнить действия. Этот параметр полезен для удаления виртуальной машины в запущенном состоянии или для перенастройки параметров виртуальной машины, которые требуют выключения виртуальной машины. Варианты: `false` ← (default) `true`
hardware dictionary	Управление аппаратными параметрами виртуальной машины. Виртуальная машина должна быть выключена для перенастройки этих параметров.
memory_mb integer	Объем памяти в МБ.

num_cpu_cores_per_socket целое число	Количество ядер на процессорный сокет. `hardware.num_cpus` должно быть кратно `hardware.num_cpu_cores_per_socket`.
num_cpus целое число	Количество процессоров.
home_server строка	Имя хоста XenServer, который будет домашним сервером для виртуальной машины. Этот параметр чувствителен к регистру.
hostname псевдонимы: host, pool строка	Имя хоста или IP-адрес хоста XenServer или мастер-пула XenServer. Если значение не указано в задаче, вместо него будет использовано значение переменной окружения `XENSERVER_HOST`. По умолчанию: `"localhost"`
is_template логическое значение	Преобразовать виртуальную машину в шаблон. Варианты: `false` ← (по умолчанию) `true`
linked_clone логическое значение	Создавать ли связанную копию из шаблона, существующей виртуальной машины или снимка. Если нет, создается полная копия. Это эквивалентно параметру `Use storage-level fast disk clone` в XenCenter. Варианты: `false` ← (по умолчанию) `true`
name псевдонимы: name_label строка	Имя виртуальной машины для работы. У виртуальных машин, работающих на XenServer, не обязательно уникальные имена. Модуль завершится ошибкой, если найдено несколько виртуальных машин с одинаковым именем. В случае нескольких виртуальных машин с одинаковым именем используйте `uuid`, чтобы однозначно указать виртуальную машину для управления. Этот параметр чувствителен к регистру.
name_desc строка	Описание виртуальной машины.
networks псевдонимы: network список / элементы=словарь	Список сетей (в порядке сетевых адаптеров). Все параметры чувствительны к регистру. Имя необходимо для новых сетевых адаптеров. Другие параметры необязательны во всех случаях.
gateway строка	Статический шлюз IPv4.
gateway6 строка	Статический шлюз IPv6.
ip строка	Статический IPv4-адрес (подразумевает `networks[].type=static`). Может содержать префикс в формате `<IPv4 address>/<prefix>` вместо использования `netmask`.
ip6 строка	Статический IPv6-адрес (подразумевает `networks[].type6=static`) с префиксом в формате `<IPv6 address>/<prefix>`.
mac строка	Настройка MAC-адреса интерфейса.
name псевдонимы: name_label строка	Имя сети XenServer, к которой следует подключить сетевой интерфейс.
netmask строка	Статический IPv4-маска подсети, необходимая для `networks[].ip`, если префикс не указан.
type строка	Тип назначения IPv4. Значение `none` означает использование значения по умолчанию для ОС. На некоторых операционных системах это может быть настройка DHCP (например, Windows) или неконфигурированный интерфейс (например, Linux). Варианты: `"none"` `"dhcp"` `"static"`
type6 строка	Тип назначения IPv6. Значение `none` означает использование значения по умолчанию для ОС. Варианты: `"none"` `"dhcp"` `"static"`

END_OF_DOCUMENT_MARKER

password aliases: pass, pwd string	Пароль для подключения к XenServer. Если значение не указано в задаче, вместо него будет использовано значение переменной окружения `XENSERVER_PASSWORD`.
state string	Укажите состояние, в котором должна находиться виртуальная машина. Если `state` установлено в `present` и виртуальная машина существует, убедитесь, что конфигурация виртуальной машины соответствует заданным параметрам. Если `state` установлено в `present` и виртуальная машина не существует, то виртуальная машина развертывается с заданными параметрами. Если `state` установлено в `absent` и виртуальная машина существует, то виртуальная машина удаляется вместе со всеми связанными компонентами. Если `state` установлено в `poweredon` и виртуальная машина не существует, то виртуальная машина развертывается с заданными параметрами и автоматически включается. Варианты: `"present"` ← (по умолчанию) `"absent"` `"poweredon"`
state_change_timeout integer	По умолчанию модуль будет бесконечно ждать получения виртуальной машиной IP-адреса, если `wait_for_ip_address=true`. Если этот параметр установлен в положительное значение, модуль вместо этого будет ожидать указанное количество секунд изменения состояния. В случае превышения времени ожидания модуль выведет сообщение об ошибке. Значение по умолчанию: `0`
template aliases: template_src string	Имя шаблона, существующей виртуальной машины (должна быть выключена) или снимка, который должен использоваться для создания виртуальной машины. Шаблоны/виртуальные машины/снимки на XenServer не обязательно имеют уникальные имена. Модуль завершится ошибкой, если будет найдено несколько шаблонов с одинаковым именем. В случае наличия нескольких шаблонов/виртуальных машин/снимков с одинаковым именем, используйте `template_uuid` для однозначного указания исходного шаблона. Если виртуальная машина уже существует, этот параметр будет проигнорирован. Этот параметр чувствителен к регистру.
template_uuid string	UUID шаблона, существующей виртуальной машины или снимка, который должен использоваться для создания виртуальной машины. Требуется, если имя шаблона не является уникальным.
username aliases: admin, user string	Имя пользователя для подключения к XenServer. Если значение не указано в задаче, вместо него будет использовано значение переменной окружения `XENSERVER_USER`. Значение по умолчанию: `"root"`
uuid string	UUID виртуальной машины для управления, если известен. Это уникальный идентификатор XenServer. Требуется, если имя не является уникальным. Обратите внимание, что предоставленный UUID будет проигнорирован при создании виртуальной машины, поскольку XenServer создает UUID внутренне.
validate_certs boolean	Разрешает подключение, когда SSL-сертификаты недействительны. Установите в `false`, когда сертификаты не являются доверенными. Если значение не указано в задаче, вместо него будет использовано значение переменной окружения `XENSERVER_VALIDATE_CERTS`. Варианты: `false` `true` ← (по умолчанию)
wait_for_ip_address boolean	Ожидать, пока XenServer обнаружит IP-адрес для виртуальной машины. Если `state` установлено в `absent`, этот параметр игнорируется. Для правильной работы требуется предварительная установка XenServer Tools на виртуальной машине. Варианты: `false` ← (по умолчанию) `true`

Атрибуты

Атрибут	Поддержка	Описание
check_mode	Поддержка: полная	Может работать в режиме `check_mode` и возвращать прогноз статуса изменений без изменения целевого объекта.
diff_mode	Поддержка: отсутствует	Возвращает подробную информацию о том, что изменилось (или, возможно, должно измениться в `check_mode`), в режиме diff.

Примечания

Примечание

Минимальная поддерживаемая версия XenServer — 5.6.
Модуль был протестирован с XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 и 8.0.
Для получения Python библиотеки XenAPI просто выполните pip install XenAPI на вашем узле управления Ansible. Библиотека также доступна в SDK Citrix Hypervisor/XenServer (скачивается с веб-сайта Citrix). Скопируйте файл XenAPI.py из SDK в вашу директорию site-packages Python на вашем узле управления Ansible, чтобы использовать его. Последнюю версию библиотеки также можно получить из GitHub: https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI/XenAPI.py
Если схема не указана в hostname, модуль по умолчанию использует http://, так как https:// проблематична в большинстве настроек. Убедитесь, что вы обращаетесь к хосту XenServer в надёжной среде или используйте схему https:// явно.
Для использования схемы https:// для hostname необходимо либо импортировать сертификат хоста в хранилище сертификатов вашей ОС, либо использовать validate_certs=false, что требует библиотеки XenAPI из SDK XenServer 7.2 или новее и Python 2.7.9 или новее.
Настройка сети внутри гостевой ОС с использованием параметров networks[].type, networks[].ip, networks[].gateway и т. д. поддерживается на XenServer 7.0 и новее для гостевых ОС Windows с использованием официальной поддержки агента XenServer Guest для настройки сети. Модуль будет пытаться определить, доступна ли такая поддержка, и использовать её, в противном случае он будет использовать пользовательский метод конфигурации через xenstore. Поскольку агент XenServer Guest поддерживает только типы конфигурации сети None и Static, где None означает интерфейс с DHCP, значения networks[].type и networks[].type6 none и dhcp имеют одинаковый эффект. Более подробная информация: https://www.citrix.com/community/citrix-developer/citrix-hypervisor-developer/citrix-hypervisor-developing-products/citrix-hypervisor-staticip.html
На платформах без официальной поддержки настройки сети внутри гостевой ОС параметры сети будут записаны в ключ xenstore vm-data/networks/<vif_device>. Параметры можно проверить с помощью инструментов xenstore ls и xenstore read на гостевых ОС *nix или через интерфейс WMI на гостевых ОС Windows. Они также находятся в фактах виртуальной машины в ключе instance.xenstore_data, как возвращает модуль. Пользователь должен реализовать скрипты времени загрузки или пользовательского агента, которые будут читать параметры из xenstore и настраивать сеть с заданными параметрами. Обратите внимание, что для того, чтобы данные xenstore стали доступными внутри гостевой системы, требуется перезапуск виртуальной машины, поэтому модуль потребует перезагрузки виртуальной машины, если какой-либо параметр изменён. Это ограничение XenAPI и xenstore. Учитывая эти ограничения, настройка сети через xenstore наиболее полезна для запуска новых развернутых виртуальных машин, гораздо менее — для переконфигурации существующих. Более подробная информация: https://support.citrix.com/article/CTX226713

Примеры

- name: Create a VM from a template
  community.general.xenserver_guest:
    hostname: "{{ xenserver_hostname }}"
    username: "{{ xenserver_username }}"
    password: "{{ xenserver_password }}"
    folder: /testvms
    name: testvm_2
    state: poweredon
    template: CentOS 7
    disks:
    - size_gb: 10
      sr: my_sr
    hardware:
      num_cpus: 6
      num_cpu_cores_per_socket: 3
      memory_mb: 512
    cdrom:
      type: iso
      iso_name: guest-tools.iso
    networks:
    - name: VM Network
      mac: aa:bb:dd:aa:00:14
    wait_for_ip_address: true
  delegate_to: localhost
  register: deploy

- name: Create a VM template
  community.general.xenserver_guest:
    hostname: "{{ xenserver_hostname }}"
    username: "{{ xenserver_username }}"
    password: "{{ xenserver_password }}"
    folder: /testvms
    name: testvm_6
    is_template: true
    disk:
    - size_gb: 10
      sr: my_sr
    hardware:
      memory_mb: 512
      num_cpus: 1
  delegate_to: localhost
  register: deploy

- name: Rename a VM (requires the VM's UUID)
  community.general.xenserver_guest:
    hostname: "{{ xenserver_hostname }}"
    username: "{{ xenserver_username }}"
    password: "{{ xenserver_password }}"
    uuid: 421e4592-c069-924d-ce20-7e7533fab926
    name: new_name
    state: present
  delegate_to: localhost

- name: Remove a VM by UUID
  community.general.xenserver_guest:
    hostname: "{{ xenserver_hostname }}"
    username: "{{ xenserver_username }}"
    password: "{{ xenserver_password }}"
    uuid: 421e4592-c069-924d-ce20-7e7533fab926
    state: absent
  delegate_to: localhost

- name: Modify custom params (boot order)
  community.general.xenserver_guest:
    hostname: "{{ xenserver_hostname }}"
    username: "{{ xenserver_username }}"
    password: "{{ xenserver_password }}"
    name: testvm_8
    state: present
    custom_params:
    - key: HVM_boot_params
      value: { "order": "ndc" }
  delegate_to: localhost

- name: Customize network parameters
  community.general.xenserver_guest:
    hostname: "{{ xenserver_hostname }}"
    username: "{{ xenserver_username }}"
    password: "{{ xenserver_password }}"
    name: testvm_10
    networks:
    - name: VM Network
      ip: 192.168.1.100/24
      gateway: 192.168.1.1
    - type: dhcp
  delegate_to: localhost

Значения возврата

Общие значения возврата описаны здесь, следующие поля уникальны для данного модуля:

Ключ	Описание
изменения список / элементы=строка	Обнаруженные или внесенные изменения в виртуальную машину Возвращается: всегда Пример: `[{"hardware": ["num_cpus"]}, {"disks_changed": [[], ["size"]]}, {"disks_new": [{"name": "new-disk", "name_desc": "", "position": 2, "size_gb": "4", "vbd_userdevice": "2"}]}, {"cdrom": ["type", "iso_name"]}, {"networks_changed": [["mac"]]}, {"networks_new": [{"name": "Pool-wide network associated with eth2", "position": 1, "vif_device": "1"}]}, "need_poweredoff"]`
экземпляр словарь	Метаданные о виртуальной машине Возвращается: всегда Пример: {"cdrom": {"type": "none"}, "customization_agent": "native", "disks": [{"name": "testvm_11-0", "name_desc": "", "os_device": "xvda", "size": 42949672960, "sr": "Local storage", "sr_uuid": "0af1245e-bdb0-ba33-1446-57a962ec4075", "vbd_userdevice": "0"}, {"name": "testvm_11-1", "name_desc": "", "os_device": "xvdb", "size": 42949672960, "sr": "Local storage", "sr_uuid": "0af1245e-bdb0-ba33-1446-57a962ec4075", "vbd_userdevice": "1"}], "domid": "56", "folder": "", "hardware": {"memory_mb": 8192, "num_cpu_cores_per_socket": 2, "num_cpus": 4}, "home_server": "", "is_template": false, "name": "testvm_11", "name_desc": "", "networks": [{"gateway": "192.168.0.254", "gateway6": "fc00::fffe", "ip": "192.168.0.200", "ip6": ["fe80:0000:0000:0000:e9cb:625a:32c5:c291", "fc00:0000:0000:0000:0000:0000:0000:0001"], "mac": "ba:91:3a:48:20:76", "mtu": "1500", "name": "Pool-wide network associated with eth1", "netmask": "255.255.255.128", "prefix": "25", "prefix6": "64", "vif_device": "0"}], "other_config": {"base_template_name": "Windows Server 2016 (64-bit)", "import_task": "OpaqueRef:e43eb71c-45d6-5351-09ff-96e4fb7d0fa5", "install-methods": "cdrom", "instant": "true", "mac_seed": "f83e8d8a-cfdc-b105-b054-ef5cb416b77e"}, "platform": {"acpi": "1", "apic": "true", "cores-per-socket": "2", "device_id": "0002", "hpet": "true", "nx": "true", "pae": "true", "timeoffset": "-25200", "vga": "std", "videoram": "8", "viridian": "true", "viridian_reference_tsc": "true", "viridian_time_ref_count": "true"}, "state": "poweredon", "uuid": "e3c0b2d5-5f05-424e-479c-d3df8b3e7cda", "xenstore_data": {"vm-data": ""}}

Ключ

Описание

изменения

список / элементы=строка

Обнаруженные или внесенные изменения в виртуальную машину

Возвращается: всегда

Пример: [{"hardware": ["num_cpus"]}, {"disks_changed": [[], ["size"]]}, {"disks_new": [{"name": "new-disk", "name_desc": "", "position": 2, "size_gb": "4", "vbd_userdevice": "2"}]}, {"cdrom": ["type", "iso_name"]}, {"networks_changed": [["mac"]]}, {"networks_new": [{"name": "Pool-wide network associated with eth2", "position": 1, "vif_device": "1"}]}, "need_poweredoff"]

экземпляр

словарь

Метаданные о виртуальной машине

Возвращается: всегда

Пример: {"cdrom": {"type": "none"}, "customization_agent": "native", "disks": [{"name": "testvm_11-0", "name_desc": "", "os_device": "xvda", "size": 42949672960, "sr": "Local storage", "sr_uuid": "0af1245e-bdb0-ba33-1446-57a962ec4075", "vbd_userdevice": "0"}, {"name": "testvm_11-1", "name_desc": "", "os_device": "xvdb", "size": 42949672960, "sr": "Local storage", "sr_uuid": "0af1245e-bdb0-ba33-1446-57a962ec4075", "vbd_userdevice": "1"}], "domid": "56", "folder": "", "hardware": {"memory_mb": 8192, "num_cpu_cores_per_socket": 2, "num_cpus": 4}, "home_server": "", "is_template": false, "name": "testvm_11", "name_desc": "", "networks": [{"gateway": "192.168.0.254", "gateway6": "fc00::fffe", "ip": "192.168.0.200", "ip6": ["fe80:0000:0000:0000:e9cb:625a:32c5:c291", "fc00:0000:0000:0000:0000:0000:0000:0001"], "mac": "ba:91:3a:48:20:76", "mtu": "1500", "name": "Pool-wide network associated with eth1", "netmask": "255.255.255.128", "prefix": "25", "prefix6": "64", "vif_device": "0"}], "other_config": {"base_template_name": "Windows Server 2016 (64-bit)", "import_task": "OpaqueRef:e43eb71c-45d6-5351-09ff-96e4fb7d0fa5", "install-methods": "cdrom", "instant": "true", "mac_seed": "f83e8d8a-cfdc-b105-b054-ef5cb416b77e"}, "platform": {"acpi": "1", "apic": "true", "cores-per-socket": "2", "device_id": "0002", "hpet": "true", "nx": "true", "pae": "true", "timeoffset": "-25200", "vga": "std", "videoram": "8", "viridian": "true", "viridian_reference_tsc": "true", "viridian_time_ref_count": "true"}, "state": "poweredon", "uuid": "e3c0b2d5-5f05-424e-479c-d3df8b3e7cda", "xenstore_data": {"vm-data": ""}}

Авторы

Боян Витник (@bvitnik)

Ссылки на коллекцию

© 2012–2018 Michael DeHaan
© 2018–2024 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/xenserver_guest_module.html