community.general.xenserver_guest_powerstate module – Manages power states of 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_powerstate.
Synopsis
This module can be used to power on, power off, restart or suspend virtual machine and gracefully reboot or shutdown guest OS of virtual machine.
Requirements
The below requirements are needed on the host that executes this module.
XenAPI
Parameters
Parameter |
Comments |
|---|---|
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: |
|
Name of the VM to manage. 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. |
|
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 Choices:
|
|
By default, module will wait indefinitely for VM to change state or 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: |
|
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. |
|
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. 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: nowhich requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.
Examples
- name: Power on VM
community.general.xenserver_guest_powerstate:
hostname: "{{ xenserver_hostname }}"
username: "{{ xenserver_username }}"
password: "{{ xenserver_password }}"
name: testvm_11
state: powered-on
delegate_to: localhost
register: facts
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
Metadata about the VM Returned: always Sample: |