xenserver_guest – Manages virtual machines running on Citrix Hypervisor/XenServer host or pool¶
New in version 2.8.
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.
- python >= 2.6
- XenAPI
Parameters¶
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.py
- If 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.
- 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.html
- On 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 trough 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 trough xenstore is most useful for bootstraping 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
  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
Return Values¶
Common return values are documented here, the following are the fields unique to this module:
Status¶
- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]
Authors¶
- Bojan Vitnik (@bvitnik) <bvitnik@mainstream.rs>
Hint
If you notice any issues in this documentation, you can edit this document to improve it.
