community.general.xenserver_guest module – Manages virtual machines running on Citrix Hypervisor/XenServer host or pool
Note
This module is part of the community.general collection (version 9.5.1).
You might already have this collection installed if you are using the ansible package.
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.general.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.general.xenserver_guest.
Synopsis
This module can be used to create new virtual machines from templates or other virtual machines, modify various virtual machine components like network and disk, rename a virtual machine and remove a virtual machine with associated components.
Requirements
The below requirements are needed on the host that executes this module.
XenAPI
Parameters
Parameter |
Comments |
|---|---|
A CD-ROM configuration for the VM. All parameters are case sensitive. |
|
The file name of an ISO image from one of the XenServer ISO Libraries (implies Required if |
|
The type of CD-ROM. With Choices:
|
|
Define a list of custom VM params to set on VM. Useful for advanced users familiar with managing VM params through xe CLI. A custom value object takes two fields |
|
VM param name. |
|
VM param value. |
|
A list of disks to add to VM. All parameters are case sensitive. Removing or detaching existing disks of VM is not supported. New disks are required to have either a VM needs to be shut down to reconfigure disk size. |
|
Disk name. |
|
Disk description. |
|
Disk size with unit. Unit must be: If no unit is specified, size is assumed to be in bytes. |
|
Disk size in bytes. |
|
Disk size in gigabytes. |
|
Disk size in kilobytes. |
|
Disk size in megabytes. |
|
Disk size in terabytes. |
|
Storage Repository to create disk on. If not specified, will use default SR. Cannot be used for moving disk to other SR. |
|
UUID of a SR to create disk on. Use if SR name is not unique. |
|
Destination folder for VM. This parameter is case sensitive. Example: folder: /folder1/folder2 |
|
Ignore warnings and complete the actions. This parameter is useful for removing VM in running state or reconfiguring VM params that require VM to be shut down. Choices:
|
|
Manage VM’s hardware parameters. VM needs to be shut down to reconfigure these parameters. |
|
Amount of memory in MB. |
|
Number of Cores Per Socket. |
|
Number of CPUs. |
|
Name of a XenServer host that will be a Home Server for the VM. This parameter is case sensitive. |
|
The hostname or IP address of the XenServer host or XenServer pool master. If the value is not specified in the task, the value of environment variable Default: |
|
Convert VM to template. Choices:
|
|
Whether to create a Linked Clone from the template, existing VM or snapshot. If no, will create a full copy. This is equivalent to Choices:
|
|
Name of the VM to work with. VMs running on XenServer do not necessarily have unique names. The module will fail if multiple VMs with same name are found. In case of multiple VMs with same name, use This parameter is case sensitive. |
|
VM description. |
|
A list of networks (in the order of the NICs). All parameters are case sensitive. Name is required for new NICs. Other parameters are optional in all cases. |
|
Static IPv4 gateway. |
|
Static IPv6 gateway. |
|
Static IPv4 address (implies |
|
Static IPv6 address (implies |
|
Customize MAC address of the interface. |
|
Name of a XenServer network to attach the network interface to. |
|
Static IPv4 netmask required for |
|
Type of IPv4 assignment. Value On some operating systems it could be DHCP configured (e.g. Windows) or unconfigured interface (e.g. Linux). Choices:
|
|
Type of IPv6 assignment. Value Choices:
|
|
The password to use for connecting to XenServer. If the value is not specified in the task, the value of environment variable |
|
Specify the state VM should be in. If If If If Choices:
|
|
By default, module will wait indefinitely for VM to acquire an IP address if If this parameter is set to positive value, the module will instead wait specified number of seconds for the state change. In case of timeout, module will generate an error message. Default: |
|
Name of a template, an existing VM (must be shut down) or a snapshot that should be used to create VM. Templates/VMs/snapshots on XenServer do not necessarily have unique names. The module will fail if multiple templates with same name are found. In case of multiple templates/VMs/snapshots with same name, use If VM already exists, this setting will be ignored. This parameter is case sensitive. |
|
UUID of a template, an existing VM or a snapshot that should be used to create VM. It is required if template name is not unique. |
|
The username to use for connecting to XenServer. If the value is not specified in the task, the value of environment variable Default: |
|
UUID of the VM to manage if known. This is XenServer’s unique identifier. It is required if name is not unique. Please note that a supplied UUID will be ignored on VM creation, as XenServer creates the UUID internally. |
|
Allows connection when SSL certificates are not valid. Set to If the value is not specified in the task, the value of environment variable Choices:
|
|
Wait until XenServer detects an IP address for the VM. If This requires XenServer Tools to be preinstalled on the VM to work properly. Choices:
|
Attributes
Attribute |
Support |
Description |
|---|---|---|
Support: full |
Can run in |
|
Support: none |
Will return details on what has changed (or possibly needs changing in |
Notes
Note
Minimal supported version of XenServer is 5.6.
Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0.
To acquire XenAPI Python library, just run
pip install XenAPIon your Ansible Control Node. The library can also be found inside Citrix Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the XenAPI.py file from the SDK to your Python site-packages on your Ansible Control Node to use it. Latest version of the library can also be acquired from GitHub: https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI/XenAPI.pyIf no scheme is specified in
hostname, module defaults tohttp://becausehttps://is problematic in most setups. Make sure you are accessing XenServer host in trusted environment or usehttps://scheme explicitly.To use
https://scheme forhostnameyou have to either import host certificate to your OS certificate store or usevalidate_certs=falsewhich requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.Network configuration inside a guest OS, by using
networks[].type,networks[].ip,networks[].gatewayetc. parameters, is supported on XenServer 7.0 or newer for Windows guests by using official XenServer Guest agent support for network configuration. The module will try to detect if such support is available and utilize it, else it will use a custom method of configuration via xenstore. Since XenServer Guest agent only support None and Static types of network configuration, where None means DHCP configured interface,networks[].typeandnetworks[].type6valuesnoneanddhcphave same effect. More info here: https://www.citrix.com/community/citrix-developer/citrix-hypervisor-developer/citrix-hypervisor-developing-products/citrix-hypervisor-staticip.htmlOn platforms without official support for network configuration inside a guest OS, network parameters will be written to xenstore
vm-data/networks/<vif_device>key. Parameters can be inspected by usingxenstore lsandxenstore readtools on \*nix guests or through WMI interface on Windows guests. They can also be found in VM factsinstance.xenstore_datakey as returned by the module. It is up to the user to implement a boot time scripts or custom agent that will read the parameters from xenstore and configure network with given parameters. Take note that for xenstore data to become available inside a guest, a VM restart is needed hence module will require VM restart if any parameter is changed. This is a limitation of XenAPI and xenstore. Considering these limitations, network configuration through xenstore is most useful for bootstrapping newly deployed VMs, much less for reconfiguring existing ones. More info here: https://support.citrix.com/article/CTX226713
Examples
- 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
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
Detected or made changes to VM Returned: always Sample: |
|
Metadata about the VM Returned: always Sample: |