ovirt_vms - Module to manage Virtual Machines in oVirt.

New in version 2.2.

Synopsis

This module manages whole lifecycle of the Virtual Machine(VM) in oVirt. Since VM can hold many states in oVirt, this see notes to see how the states of the VM are handled.

Requirements (on host that executes module)

• python >= 2.7
• ovirt-engine-sdk-python >= 4.0.0

Options

parameter	required	default	choices	comments
auth	yes			Dictionary with values needed to create HTTP/HTTPS connection to oVirt: username[required] - The name of the user, something like `admin@internal`. password[required] - The password of the user. url[required] - A string containing the base URL of the server, usually something like `https://server.example.com/ovirt-engine/api`. token - Token to be used instead of login with username/password. insecure - A boolean flag that indicates if the server TLS certificate and host name should be checked. ca_file - A PEM file containing the trusted CA certificates. The certificate presented by the server will be verified using these CA certificates. If `ca_file` parameter is not set, system wide CA certificate store is used. kerberos - A boolean flag indicating if Kerberos authentication should be used instead of the default basic authentication.
boot_devices	no			List of boot devices which should be used to boot. Choices network, hd and cdrom. For example: ['cdrom', 'hd']. Default value is set by oVirt engine.
cd_iso	no			ISO file from ISO storage domain which should be attached to Virtual Machine. If you pass empty string the CD will be ejected from VM. If used with state running or present and VM is running the CD will be attached to VM. If used with state running or present and VM is down the CD will be attached to VM persistently.
clone	no			If True then the disks of the created virtual machine will be cloned and independent of the template. This parameter is used only when state is running or present and VM didn't exist before.
clone_permissions	no			If True then the permissions of the template (only the direct ones, not the inherited ones) will be copied to the created virtual machine. This parameter is used only when state is running or present and VM didn't exist before.
cloud_init	no			Dictionary with values for Unix-like Virtual Machine initialization using cloud init: host_name - Hostname to be set to Virtual Machine when deployed. timezone - Timezone to be set to Virtual Machine when deployed. user_name - Username to be used to set password to Virtual Machine when deployed. root_password - Password to be set for user specified by user_name parameter. authorized_ssh_keys - Use this SSH keys to login to Virtual Machine. regenerate_ssh_keys - If True SSH keys will be regenerated on Virtual Machine. custom_script - Cloud-init script which will be executed on Virtual Machine when deployed. dns_servers - DNS servers to be configured on Virtual Machine. dns_search - DNS search domains to be configured on Virtual Machine. nic_boot_protocol - Set boot protocol of the network interface of Virtual Machine. Can be one of None, DHCP or Static. nic_ip_address - If boot protocol is static, set this IP address to network interface of Virtual Machine. nic_netmask - If boot protocol is static, set this netmask to network interface of Virtual Machine. nic_gateway - If boot protocol is static, set this gateway to network interface of Virtual Machine. nic_name - Set name to network interface of Virtual Machine. nic_on_boot - If True network interface will be set to start on boot.
cluster	no			Name of the cluster, where Virtual Machine should be created. Required if creating VM.
cpu_cores	no			Number of virtual CPUs cores of the Virtual Machine. Default value is set by oVirt engine.
cpu_shares	no			Set a CPU shares for this Virtual Machine. Default value is set by oVirt engine.
cpu_sockets	no			Number of virtual CPUs sockets of the Virtual Machine. Default value is set by oVirt engine.
delete_protected	no			If True Virtual Machine will be set as delete protected. If False Virtual Machine won't be set as delete protected. If no value is passed, default value is set by oVirt engine.
disks	no			List of disks, which should be attached to Virtual Machine. Disk is described by following dictionary: name - Name of the disk. Either name or id is reuqired. id - ID of the disk. Either name or id is reuqired. interface - Interface of the disk, either virtio or IDE, default is virtio. bootable - True if the disk should be bootable, default is non bootable. activate - True if the disk should be activated, default is activated. Note: This parameter is used only when state is running or present and is able to only attach disks. To manage disks of the VM in more depth please use ovirt_disks module instead.
force	no			Please check to Synopsis to more detailed description of force parameter, it can behave differently in different situations.
high_availability	no			If True Virtual Machine will be set as highly available. If False Virtual Machine won't be set as highly available. If no value is passed, default value is set by oVirt engine.
host	no			Specify host where Virtual Machine should be running. By default the host is chosen by engine scheduler. This parameter is used only when state is running or present.
id	no			ID of the the Virtual Machine to manage.
memory	no			Amount of memory of the Virtual Machine. Prefix uses IEC 60027-2 standard (for example 1GiB, 1024MiB). Default value is set by engine.
memory_guaranteed	no			Amount of minimal guaranteed memory of the Virtual Machine. Prefix uses IEC 60027-2 standard (for example 1GiB, 1024MiB). memory_guaranteed parameter can't be lower than memory parameter. Default value is set by engine.
name	no			Name of the the Virtual Machine to manage. If VM don't exists name is required. Otherwise id or name can be used.
nics	no			List of NICs, which should be attached to Virtual Machine. NIC is described by following dictionary: name - Name of the NIC. profile_name - Profile name where NIC should be attached. interface - Type of the network interface. One of following: virtio, e1000, rtl8139, default is virtio. mac_address - Custom MAC address of the network interface, by default it's obtained from MAC pool. Note: This parameter is used only when state is running or present and is able to only create NICs. To manage NICs of the VM in more depth please use ovirt_nics module instead.
operating_system	no		rhel_6_ppc64 other freebsd windows_2003x64 windows_10 rhel_6x64 rhel_4x64 windows_2008x64 windows_2008R2x64 debian_7 windows_2012x64 ubuntu_14_04 ubuntu_12_04 ubuntu_13_10 windows_8x64 other_linux_ppc64 windows_2003 other_linux windows_10x64 windows_2008 rhel_3 rhel_5 rhel_4 other_ppc64 sles_11 rhel_6 windows_xp rhel_7x64 freebsdx64 rhel_7_ppc64 windows_7 rhel_5x64 ubuntu_14_04_ppc64 sles_11_ppc64 windows_8 windows_2012R2x64 windows_2008r2x64 ubuntu_13_04 ubuntu_12_10 windows_7x64	Operating system of the Virtual Machine. Default value is set by oVirt engine.
poll_interval	no	3		Number of the seconds the module waits until another poll request on entity status is sent.
state	no	present	running stopped present absent suspended next_run	Should the Virtual Machine be running/stopped/present/absent/suspended/next_run. present and running are equal states. next_run state updates the VM and if the VM has next run configuration it will be rebooted. Please check notes to more detailed description of states.
stateless	no			If True Virtual Machine will be set as stateless. If False Virtual Machine will be unset as stateless. If no value is passed, default value is set by oVirt engine.
sysprep	no			Dictionary with values for Windows Virtual Machine initialization using sysprep: host_name - Hostname to be set to Virtual Machine when deployed. active_directory_ou - Active Directory Organizational Unit, to be used for login of user. org_name - Organization name to be set to Windows Virtual Machine. domain - Domain to be set to Windows Virtual Machine. timezone - Timezone to be set to Windows Virtual Machine. ui_language - UI language of the Windows Virtual Machine. system_locale - System localization of the Windows Virtual Machine. input_locale - Input localization of the Windows Virtual Machine. windows_license_key - License key to be set to Windows Virtual Machine. user_name - Username to be used for set password to Windows Virtual Machine. root_password - Password to be set for username to Windows Virtual Machine.
template	no			Name of the template, which should be used to create Virtual Machine. Required if creating VM. If template is not specified and VM doesn't exist, VM will be created from Blank template.
template_version (added in 2.3)	no			Version number of the template to be used for VM. By default the latest available version of the template is used.
timeout	no	180		The amount of time in seconds the module should wait for the instance to get into desired state.
type	no		server desktop	Type of the Virtual Machine. Default value is set by oVirt engine.
use_latest_template_version (added in 2.3)	no			Specify if latest template version should be used, when running a stateless VM. If this parameter is set to true stateless VM is created.
wait	no			True if the module should wait for the entity to get into desired state.

Examples

# Examples don't contain auth parameter for simplicity,
# look at ovirt_auth module to see how to reuse authentication:

# Creates a new Virtual Machine from template named 'rhel7_template'
ovirt_vms:
    state: present
    name: myvm
    template: rhel7_template

# Creates a stateless VM which will always use latest template version:
ovirt_vms:
    name: myvm
    template: rhel7
    cluster: mycluster
    use_latest_template_version: true

# Creates a new server rhel7 Virtual Machine from Blank template
# on brq01 cluster with 2GiB memory and 2 vcpu cores/sockets
# and attach bootable disk with name rhel7_disk and attach virtio NIC
ovirt_vms:
    state: present
    cluster: brq01
    name: myvm
    memory: 2GiB
    cpu_cores: 2
    cpu_sockets: 2
    cpu_shares: 1024
    type: server
    operating_system: rhel_7x64
    disks:
      - name: rhel7_disk
        bootable: True
    nics:
      - name: nic1

# Run VM with cloud init:
ovirt_vms:
    name: rhel7
    template: rhel7
    cluster: Default
    memory: 1GiB
    high_availability: true
    cloud_init:
      nic_boot_protocol: static
      nic_ip_address: 10.34.60.86
      nic_netmask: 255.255.252.0
      nic_gateway: 10.34.63.254
      nic_name: eth1
      nic_on_boot: true
      host_name: example.com
      custom_script: |
        write_files:
         - content: |
             Hello, world!
           path: /tmp/greeting.txt
           permissions: '0644'
      user_name: root
      root_password: super_password

# Run VM with sysprep:
ovirt_vms:
    name: windows2012R2_AD
    template: windows2012R2
    cluster: Default
    memory: 3GiB
    high_availability: true
    sysprep:
      host_name: windowsad.example.com
      user_name: Administrator
      root_password: SuperPassword123

# Migrate/Run VM to/on host named 'host1'
ovirt_vms:
    state: running
    name: myvm
    host: host1

# Change Vm's CD:
ovirt_vms:
    name: myvm
    cd_iso: drivers.iso

# Eject Vm's CD:
ovirt_vms:
    name: myvm
    cd_iso: ''

# Boot VM from CD:
ovirt_vms:
    name: myvm
    cd_iso: centos7_x64.iso
    boot_devices:
        - cdrom

# Stop vm:
ovirt_vms:
    state: stopped
    name: myvm

# Upgrade memory to already created VM:
ovirt_vms:
    name: myvm
    memory: 4GiB

# Hot plug memory to already created and running VM:
# (VM won't be restarted)
ovirt_vms:
    name: myvm
    memory: 4GiB

# When change on the VM needs restart of the VM, use next_run state,
# The VM will be updated and rebooted if there are any changes.
# If present state would be used, VM won't be restarted.
ovirt_vms:
    state: next_run
    name: myvm
    boot_devices:
      - network

# Remove VM, if VM is running it will be stopped:
ovirt_vms:
    state: absent
    name: myvm

Return Values

Common return values are documented here common_return_values, the following are the fields unique to this module:

name	description	returned	type	sample
id	ID of the VM which is managed	On success if VM is found.	str	7de90f31-222c-436c-a1ca-7e655bd5b60c
vm	Dictionary of all the VM attributes. VM attributes can be found on your oVirt instance at following url: https://ovirt.example.com/ovirt-engine/api/model#types/vm.	On success if VM is found.

Notes

Note

If VM is in UNASSIGNED or UNKNOWN state before any operation, the module will fail. If VM is in IMAGE_LOCKED state before any operation, we try to wait for VM to be DOWN. If VM is in SAVING_STATE state before any operation, we try to wait for VM to be SUSPENDED. If VM is in POWERING_DOWN state before any operation, we try to wait for VM to be UP or DOWN. VM can get into UP state from POWERING_DOWN state, when there is no ACPI or guest agent running inside VM, or if the shutdown operation fails. When user specify UP state, we always wait to VM to be in UP state in case VM is MIGRATING, REBOOTING, POWERING_UP, RESTORING_STATE, WAIT_FOR_LAUNCH. In other states we run start operation on VM. When user specify stopped state, and If user pass force parameter set to true we forcibly stop the VM in any state. If user don’t pass force parameter, we always wait to VM to be in UP state in case VM is MIGRATING, REBOOTING, POWERING_UP, RESTORING_STATE, WAIT_FOR_LAUNCH. If VM is in PAUSED or SUSPENDED state, we start the VM. Then we gracefully shutdown the VM. When user specify suspended state, we always wait to VM to be in UP state in case VM is MIGRATING, REBOOTING, POWERING_UP, RESTORING_STATE, WAIT_FOR_LAUNCH. If VM is in PAUSED or DOWN state, we start the VM. Then we suspend the VM. When user specify absent state, we forcibly stop the VM in any state and remove it.

Note

In order to use this module you have to install oVirt Python SDK. To ensure it’s installed with correct version you can create the following task: pip: name=ovirt-engine-sdk-python version=4.0.0

This is an Extras Module

For more information on what this means please read modules_extra

For help in developing on modules, should you be so inclined, please read community, developing_test_pr and developing_modules.