Try SpotterManages virtual machines running on Citrix Hypervisor/XenServer host or pool
| "added in version" 2.8 of ansible.builtin"
Authors: Bojan Vitnik (@bvitnik) <bvitnik@mainstream.rs>
preview | supported by community
pipInstall with pip install ansible==2.9.27
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.
- name: Create a VM from a template
xenserver_guest:
hostname: "{{ xenserver_hostname }}"
username: "{{ xenserver_username }}"
password: "{{ xenserver_password }}"
validate_certs: no
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: yes
delegate_to: localhost
register: deploy
- name: Create a VM template
xenserver_guest:
hostname: "{{ xenserver_hostname }}"
username: "{{ xenserver_username }}"
password: "{{ xenserver_password }}"
validate_certs: no
folder: /testvms
name: testvm_6
is_template: yes
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)
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
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)
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
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
name:
aliases:
- name_label
description:
- 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 C(uuid) to uniquely specify VM to manage.
- This parameter is case sensitive.
required: true
type: str
uuid:
description:
- 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.
type: str
cdrom:
description:
- A CD-ROM configuration for the VM.
- All parameters are case sensitive.
- 'Valid parameters are:'
- ' - C(type) (string): The type of CD-ROM, valid options are C(none) or C(iso). With
C(none) the CD-ROM device will be present but empty.'
- ' - C(iso_name) (string): The file name of an ISO image from one of the XenServer
ISO Libraries (implies C(type: iso)). Required if C(type) is set to C(iso).'
type: dict
disks:
aliases:
- disk
description:
- A list of disks to add to VM.
- All parameters are case sensitive.
- Removing or detaching existing disks of VM is not supported.
- 'Required parameters per entry:'
- ' - C(size_[tb,gb,mb,kb,b]) (integer): Disk storage size in specified unit. VM needs
to be shut down to reconfigure this parameter.'
- 'Optional parameters per entry:'
- ' - C(name) (string): Disk name. You can also use C(name_label) as an alias.'
- ' - C(name_desc) (string): Disk description.'
- ' - C(sr) (string): Storage Repository to create disk on. If not specified, will
use default SR. Cannot be used for moving disk to other SR.'
- ' - C(sr_uuid) (string): UUID of a SR to create disk on. Use if SR name is not unique.'
type: list
force:
default: false
description:
- 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.
type: bool
state:
choices:
- present
- absent
- poweredon
default: present
description:
- Specify the state VM should be in.
- If C(state) is set to C(present) and VM exists, ensure the VM configuration conforms
to given parameters.
- If C(state) is set to C(present) and VM does not exist, then VM is deployed with
given parameters.
- If C(state) is set to C(absent) and VM exists, then VM is removed with its associated
components.
- If C(state) is set to C(poweredon) and VM does not exist, then VM is deployed with
given parameters and powered on automatically.
type: str
folder:
description:
- Destination folder for VM.
- This parameter is case sensitive.
- 'Example:'
- ' folder: /folder1/folder2'
type: str
hardware:
description:
- Manage VM's hardware parameters. VM needs to be shut down to reconfigure these parameters.
- 'Valid parameters are:'
- ' - C(num_cpus) (integer): Number of CPUs.'
- ' - C(num_cpu_cores_per_socket) (integer): Number of Cores Per Socket. C(num_cpus)
has to be a multiple of C(num_cpu_cores_per_socket).'
- ' - C(memory_mb) (integer): Amount of memory in MB.'
type: dict
hostname:
aliases:
- host
- pool
default: localhost
description:
- 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 C(XENSERVER_HOST)
will be used instead.
type: str
networks:
aliases:
- network
description:
- A list of networks (in the order of the NICs).
- All parameters are case sensitive.
- 'Required parameters per entry:'
- ' - C(name) (string): Name of a XenServer network to attach the network interface
to. You can also use C(name_label) as an alias.'
- 'Optional parameters per entry (used for VM hardware):'
- ' - C(mac) (string): Customize MAC address of the interface.'
- 'Optional parameters per entry (used for OS customization):'
- ' - C(type) (string): Type of IPv4 assignment, valid options are C(none), C(dhcp)
or C(static). Value C(none) means whatever is default for OS. On some operating
systems it could be DHCP configured (e.g. Windows) or unconfigured interface (e.g.
Linux).'
- ' - C(ip) (string): Static IPv4 address (implies C(type: static)). Can include prefix
in format <IPv4 address>/<prefix> instead of using C(netmask).'
- ' - C(netmask) (string): Static IPv4 netmask required for C(ip) if prefix is not
specified.'
- ' - C(gateway) (string): Static IPv4 gateway.'
- ' - C(type6) (string): Type of IPv6 assignment, valid options are C(none), C(dhcp)
or C(static). Value C(none) means whatever is default for OS. On some operating
systems it could be DHCP configured (e.g. Windows) or unconfigured interface (e.g.
Linux).'
- ' - C(ip6) (string): Static IPv6 address (implies C(type6: static)) with prefix
in format <IPv6 address>/<prefix>.'
- ' - C(gateway6) (string): Static IPv6 gateway.'
type: list
password:
aliases:
- pass
- pwd
description:
- The password to use for connecting to XenServer.
- If the value is not specified in the task, the value of environment variable C(XENSERVER_PASSWORD)
will be used instead.
type: str
template:
aliases:
- template_src
description:
- 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 C(template_uuid)
to uniquely specify source template.
- If VM already exists, this setting will be ignored.
- This parameter is case sensitive.
type: str
username:
aliases:
- admin
- user
default: root
description:
- The username to use for connecting to XenServer.
- If the value is not specified in the task, the value of environment variable C(XENSERVER_USER)
will be used instead.
type: str
name_desc:
description:
- VM description.
type: str
home_server:
description:
- Name of a XenServer host that will be a Home Server for the VM.
- This parameter is case sensitive.
type: str
is_template:
default: false
description:
- Convert VM to template.
type: bool
linked_clone:
default: false
description:
- Whether to create a Linked Clone from the template, existing VM or snapshot. If
no, will create a full copy.
- This is equivalent to C(Use storage-level fast disk clone) option in XenCenter.
type: bool
custom_params:
description:
- Define a list of custom VM params to set on VM.
- Useful for advanced users familiar with managing VM params trough xe CLI.
- A custom value object takes two fields C(key) and C(value) (see example below).
type: list
template_uuid:
description:
- 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.
type: str
validate_certs:
default: true
description:
- Allows connection when SSL certificates are not valid. Set to C(false) when certificates
are not trusted.
- If the value is not specified in the task, the value of environment variable C(XENSERVER_VALIDATE_CERTS)
will be used instead.
type: bool
wait_for_ip_address:
default: false
description:
- Wait until XenServer detects an IP address for the VM. If C(state) is set to C(absent),
this parameter is ignored.
- This requires XenServer Tools to be preinstalled on the VM to work properly.
type: bool
state_change_timeout:
default: 0
description:
- 'By default, module will wait indefinitely for VM to accquire an IP address if C(wait_for_ip_address:
yes).'
- 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.
type: int
changes:
description: Detected or made changes to VM
returned: always
sample:
- 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
type: list
instance:
description: Metadata about the VM
returned: always
sample:
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: ''
type: dict