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

Примечание

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

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

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

Чтобы использовать модуль в плейбуке, укажите: community.general.xenserver_guest.

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

Общие сведения

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

Требования

Следующие компоненты требуются на хосте, на котором выполняется этот модуль.

XenAPI

Параметры

Параметр	Комментарии
cdrom dictionary	Конфигурация CD-ROM для VM. Все параметры чувствительны к регистру.
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	Задаёт список пользовательских параметров VM для установки. Полезно опытным пользователям, знакомым с управлением параметрами VM через интерфейс командной строки `xe`. Объект пользовательского значения содержит два поля: `custom_params[].key` и `custom_params[].value` (см. пример ниже).
key string / обязательный	Имя параметра VM.
value any / обязательный	Значение параметра VM.
disks псевдонимы: disk list / elements=dictionary	Список дисков для добавления в VM. Все параметры чувствительны к регистру. Удаление или отключение существующих дисков VM не поддерживается. Для новых дисков необходимо указать либо `disks[].size`, либо один из параметров `disks[].size_[tb,gb,mb,kb,b]`. Для изменения размера диска VM необходимо выключить.
name псевдонимы: name_label string	Имя диска.
name_desc string	Описание диска.
size string	Размер диска с указанием единицы измерения. Допустимые единицы: `b`, `kb`, `mb`, `gb`, `tb`. Для изменения этого параметра VM необходимо выключить. Если единица измерения не указана, размер считается заданным в байтах.
size_b string	Размер диска в байтах.
size_gb string	Размер диска в гигабайтах.
size_kb string	Размер диска в килобайтах.
size_mb string	Размер диска в мегабайтах.
size_tb string	Размер диска в терабайтах.
sr string	Репозиторий хранилища, в котором создаётся диск. Если не указан, используется репозиторий по умолчанию. Нельзя использовать для перемещения диска в другой репозиторий хранилища.
sr_uuid string	UUID репозитория хранилища, в котором создаётся диск. Используйте, если имя репозитория хранилища не уникально.
folder string	Папка назначения для VM. Этот параметр чувствителен к регистру. Пример: `folder=/folder1/folder2`.
force boolean	Игнорировать предупреждения и выполнить действия. Этот параметр полезен для удаления работающей VM или перенастройки параметров VM, требующих её выключения. Варианты: `false` ← (по умолчанию) `true`
hardware dictionary	Управление параметрами оборудования VM. Для изменения этих параметров VM необходимо выключить.
memory_mb integer	Объём памяти в МБ.
num_cpu_cores_per_socket integer	Количество ядер на сокет. `hardware.num_cpus` должно быть кратно `hardware.num_cpu_cores_per_socket`.
num_cpus integer	Количество процессоров.
home_server string	Имя хоста XenServer, являющегося домашним сервером для VM. Этот параметр чувствителен к регистру.
hostname псевдонимы: host, pool string	Имя хоста или IP-адрес хоста XenServer либо главного узла пула XenServer. Если значение не указано в задаче, вместо него используется значение переменной окружения `XENSERVER_HOST`. По умолчанию: `"localhost"`
is_template boolean	Преобразовать VM в шаблон. Варианты: `false` ← (по умолчанию) `true`
linked_clone boolean	Создавать ли связанный клон из шаблона, существующей VM или снимка. Если задано `false`, создаётся полная копия. Это соответствует параметру `Use storage-level fast disk clone` в XenCenter. Варианты: `false` ← (по умолчанию) `true`
name псевдонимы: name_label string	Имя управляемой VM. Имена VM, работающих на XenServer, не обязательно уникальны. Если найдено несколько VM с одинаковым именем, модуль завершится с ошибкой. Если несколько VM имеют одинаковое имя, используйте `uuid`, чтобы однозначно указать VM для управления. Этот параметр чувствителен к регистру.
name_desc string	Описание VM.
networks псевдонимы: network list / elements=dictionary	Список сетей (в порядке следования сетевых карт). Все параметры чувствительны к регистру. Для новых сетевых карт обязательно указать имя. Все остальные параметры во всех случаях необязательны.
gateway string	Статический шлюз IPv4.
gateway6 string	Статический шлюз IPv6.
ip string	Статический адрес IPv4 (подразумевает `networks[].type=static`). Может включать префикс в формате `<IPv4 address>/<prefix>` вместо использования `netmask`.
ip6 string	Статический адрес IPv6 (подразумевает `networks[].type6=static`) с префиксом в формате `<IPv6 address>/<prefix>`.
mac string	Настройка MAC-адреса интерфейса.
name псевдонимы: name_label string	Имя сети XenServer, к которой подключается сетевой интерфейс.
netmask string	Статическая маска подсети IPv4, необходимая для `networks[].ip`, если префикс не указан.
type string	Тип назначения IPv4-адреса. Значение `none` означает, что используется значение по умолчанию для ОС. В некоторых операционных системах это может означать настройку DHCP (например, в Windows) или ненастроенный интерфейс (например, в Linux). Варианты: `"none"` `"dhcp"` `"static"`
type6 string	Тип назначения IPv6-адреса. Значение `none` означает, что используется значение по умолчанию для ОС. Варианты: `"none"` `"dhcp"` `"static"`
password псевдонимы: pass, pwd string	Пароль для подключения к XenServer. Если значение не указано в задаче, вместо него используется значение переменной окружения `XENSERVER_PASSWORD`.
state string	Задаёт требуемое состояние VM. Если для `state` задано значение `present` и VM существует, обеспечить соответствие конфигурации VM указанным параметрам. Если для `state` задано значение `present` и VM не существует, развернуть VM с указанными параметрами. Если для `state` задано значение `absent` и VM существует, удалить VM вместе со связанными компонентами. Если для `state` задано значение `poweredon` и VM не существует, развернуть VM с указанными параметрами и автоматически включить её. Варианты: `"present"` ← (по умолчанию) `"absent"` `"poweredon"`
state_change_timeout integer	По умолчанию модуль бесконечно ожидает получения VM IP-адреса, если задано `wait_for_ip_address=true`. Если для этого параметра задано положительное значение, модуль ожидает изменения состояния указанное количество секунд. При превышении времени ожидания модуль выдаёт сообщение об ошибке. По умолчанию: `0`
template псевдонимы: template_src string	Имя шаблона, существующей VM (должна быть выключена) или снимка, используемого для создания VM. Имена шаблонов/VM/снимков в XenServer не обязательно уникальны. Если найдено несколько шаблонов с одинаковым именем, модуль завершится с ошибкой. Если несколько шаблонов/VM/снимков имеют одинаковое имя, используйте `template_uuid`, чтобы однозначно указать исходный шаблон. Если VM уже существует, этот параметр игнорируется. Этот параметр чувствителен к регистру.
template_uuid string	UUID шаблона, существующей VM или снимка, используемого для создания VM. Обязателен, если имя шаблона не уникально.
username псевдонимы: admin, user string	Имя пользователя для подключения к XenServer. Если значение не указано в задаче, вместо него используется значение переменной окружения `XENSERVER_USER`. По умолчанию: `"root"`
uuid string	UUID управляемой VM, если он известен. Это уникальный идентификатор XenServer. Обязателен, если имя не уникально. Обратите внимание: указанный UUID игнорируется при создании VM, поскольку XenServer создаёт UUID самостоятельно.
validate_certs boolean	Разрешает подключение, если SSL-сертификаты недействительны. Установите значение `false`, если сертификатам нельзя доверять. Если значение не указано в задаче, вместо него используется значение переменной окружения `XENSERVER_VALIDATE_CERTS`. Варианты: `false` `true` ← (по умолчанию)
wait_for_ip_address boolean	Ожидать, пока XenServer обнаружит IP-адрес VM. Если для `state` задано значение `absent`, этот параметр игнорируется. Для корректной работы на VM должны быть предварительно установлены XenServer Tools. Варианты: `false` ← (по умолчанию) `true`

Атрибуты

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

Примечания

Примечание

Минимальная поддерживаемая версия XenServer — 5.6.
Модуль протестирован с XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 и 8.0.
Чтобы получить библиотеку XenAPI Python, просто запустите 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 agent. Модуль пытается определить, доступна ли такая поддержка, и использовать её; в противном случае он использует собственный способ настройки через xenstore. Поскольку XenServer Guest agent поддерживает только типы сетевой конфигурации None и Static, где None означает интерфейс, настроенный на DHCP, значения networks[].type и networks[].type6 none и dhcp имеют одинаковый эффект. Подробнее: https://web.archive.org/web/20180218110151/https://xenserver.org/blog/entry/set-windows-guest-vm-static-ip-address-in-xenserver.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

Возвращаемые значения

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

Ключ	Описание
changes список / элементы=строка	Обнаруженные или внесённые изменения в ВМ. Возвращается: всегда Пример: `[{"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"]`
instance словарь	Метаданные о ВМ. Возвращается: всегда Пример: {"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": ""}}

Ключ

Описание

changes

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

Обнаруженные или внесённые изменения в ВМ.

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

Пример: [{"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"]

instance

словарь

Метаданные о ВМ.

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

Пример: {"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": ""}}

Авторы

Bojan Vitnik (@bvitnik)

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

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