ovirt_vms - Module to manage Virtual Machines in oVirt/RHV

New in version 2.2.

Synopsis

  • This module manages whole lifecycle of the Virtual Machine(VM) in oVirt/RHV. Since VM can hold many states in oVirt/RHV, 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
allow_partial_import
(added in 2.4)
no
Boolean indication whether to allow partial registration of Virtual Machine when state is registered.
auth
yes
Dictionary with values needed to create HTTP/HTTPS connection to oVirt:
username[required] - The name of the user, something like admin@internal. Default value is set by OVIRT_USERNAME environment variable.
password[required] - The password of the user. Default value is set by OVIRT_PASSWORD environment variable.
url[required] - A string containing the base URL of the server, usually something like `https://server.example.com/ovirt-engine/api`. Default value is set by OVIRT_URL environment variable.
token - Token to be used instead of login with username/password. Default value is set by OVIRT_TOKEN environment variable.
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. Default value is set by OVIRT_CAFILE environment variable.
kerberos - A boolean flag indicating if Kerberos authentication should be used instead of the default basic authentication.
headers - Dictionary of HTTP headers to be added to each API call.
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/RHV 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.
cloud_init_nics
(added in 2.3)
no
List of dictionaries representing network interafaces to be setup by cloud init.
This option is used, when user needs to setup more network interfaces via cloud init.
If one network interface is enough, user should use cloud_init nic_* parameters. cloud_init nic_* parameters are merged with cloud_init_nics parameters.
Dictionary can contain following values:
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.
comment
(added in 2.3)
no
Comment of the Virtual Machine.
cpu_cores
no
Number of virtual CPUs cores of the Virtual Machine. Default value is set by oVirt/RHV engine.
cpu_shares
no
Set a CPU shares for this Virtual Machine. Default value is set by oVirt/RHV engine.
cpu_sockets
no
Number of virtual CPUs sockets of the Virtual Machine. Default value is set by oVirt/RHV 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/RHV engine.
description
(added in 2.3)
no
Description of the Virtual Machine.
disk_format
(added in 2.4)
no cow
  • cow
  • raw
Specify format of the disk.
If (cow) format is used, disk will by created as sparse, so space will be allocated for the volume as needed, also known as thin provision.
If (raw) format is used, disk storage will be allocated right away, also known as preallocated.
Note that this option isn't idempotent as it's not currently possible to change format of the disk via API.
This parameter is considered only when template and storage domain is provided.
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.
fetch_nested
(added in 2.3)
no
If True the module will fetch additional data from the API.
It will fetch IDs of the VMs disks, snapshots, etc. User can configure to fetch other attributes of the nested entities by specifying nested_attributes.
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/RHV 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 Virtual Machine to manage.
initrd_path
(added in 2.3)
no
Path to an initial ramdisk to be used with the kernel specified by kernel_path option.
Ramdisk image must be stored on either the ISO domain or on the host's storage.
instance_type
(added in 2.3)
no
Name of virtual machine's hardware configuration.
By default no instance type is used.
kernel_params
(added in 2.3)
no
Kernel command line parameters (formatted as string) to be used with the kernel specified by kernel_path option.
kernel_path
(added in 2.3)
no
Path to a kernel image used to boot the virtual machine.
Kernel image must be stored on either the ISO domain or on the host's storage.
kvm
(added in 2.3)
no
Dictionary of values to be used to connect to kvm and import a virtual machine to oVirt.
Dictionary can contain following values:
name - The name of the KVM virtual machine.
username - The username to authenticate against the KVM.
password - The password to authenticate against the KVM.
url - The URL to be passed to the virt-v2v tool for conversion. For example: qemu:///system. This is required paramater.
drivers_iso - The name of the ISO containing drivers that can be used during the virt-v2v conversion process.
sparse - Specifies the disk allocation policy of the resulting virtual machine: true for sparse, false for preallocated. Default value is true.
storage_domain - Specifies the target storage domain for converted disks. This is required parameter.
lease
(added in 2.4)
no
Name of the storage domain this virtual machine lease reside on.
Note: Supported since oVirt 4.1.
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 Virtual Machine to manage. If VM don't exists name is required. Otherwise id or name can be used.
nested_attributes
(added in 2.3)
no
Specifies list of the attributes which should be fetched from the API.
This parameter apply only when fetch_nested is true.
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/RHV engine.
poll_interval
no 3
Number of the seconds the module waits until another poll request on entity status is sent.
serial_policy
(added in 2.3)
no
Specify a serial number policy for the Virtual Machine.
Following options are supported:
vm - Sets the Virtual Machine's UUID as its serial number.
host - Sets the host's UUID as the Virtual Machine's serial number.
custom - Allows you to specify a custom serial number in serial_policy_value.
serial_policy_value
(added in 2.3)
no
Allows you to specify a custom serial number.
This parameter is used only when serial_policy is custom.
state
no present
  • running
  • stopped
  • present
  • absent
  • suspended
  • next_run
  • registered
Should the Virtual Machine be running/stopped/present/absent/suspended/next_run/registered. When state is registered and the unregistered VM's name belongs to an already registered in engine VM in the same DC then we fail to register the unregistered template.
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.
registered is supported since 2.4
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/RHV engine.
storage_domain
(added in 2.4)
no
Name of the storage domain where all template disks should be created.
This parameter is considered only when template is provided.
**IMPORTANT**
This parameter is not idempotent, if the VM exists and you specfiy different storage domain, disk won't move.
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.
timezone
(added in 2.3)
no
Sets time zone offset of the guest hardware clock.
For example: Etc/GMT
type
no
  • server
  • desktop
Type of the Virtual Machine. Default value is set by oVirt/RHV 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.
vmware
(added in 2.3)
no
Dictionary of values to be used to connect to VMware and import a virtual machine to oVirt.
Dictionary can contain following values:
username - The username to authenticate against the VMware.
password - The password to authenticate against the VMware.
url - The URL to be passed to the virt-v2v tool for conversion. For example: vpx://wmware_user@vcenter-host/DataCenter/Cluster/esxi-host?no_verify=1
drivers_iso - The name of the ISO containing drivers that can be used during the virt-v2v conversion process.
sparse - Specifies the disk allocation policy of the resulting virtual machine: true for sparse, false for preallocated. Default value is true.
storage_domain - Specifies the target storage domain for converted disks. This is required parameter.
wait
no
True if the module should wait for the entity to get into desired state.
xen
(added in 2.3)
no
Dictionary of values to be used to connect to XEN and import a virtual machine to oVirt.
Dictionary can contain following values:
url - The URL to be passed to the virt-v2v tool for conversion. For example: xen+ssh://[email protected]. This is required paramater.
drivers_iso - The name of the ISO containing drivers that can be used during the virt-v2v conversion process.
sparse - Specifies the disk allocation policy of the resulting virtual machine: true for sparse, false for preallocated. Default value is true.
storage_domain - Specifies the target storage domain for converted disks. This is required parameter.

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

# Register VM
ovirt_vms:
    state: registered
    storage_domain: mystorage
    cluster: mycluster
    name: myvm

# Register VM using id
ovirt_vms:
    state: registered
    storage_domain: mystorage
    cluster: mycluster
    id: 1111-1111-1111-1111

# Register VM, allowing partial import
ovirt_vms:
    state: registered
    storage_domain: mystorage
    allow_partial_import: "True"
    cluster: mycluster
    id: 1111-1111-1111-1111

# 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 cloud init, with multiple network interfaces:
ovirt_vms:
  name: rhel7_4
  template: rhel7
  cluster: mycluster
  cloud_init_nics:
    - nic_name: eth0
      nic_boot_protocol: dhcp
      nic_on_boot: true
    - nic_name: eth1
      nic_boot_protocol: static
      nic_ip_address: 10.34.60.86
      nic_netmask: 255.255.252.0
      nic_gateway: 10.34.63.254
      nic_on_boot: true

# 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

# Import virtual machine from VMware:
ovirt_vms:
    state: stopped
    cluster: mycluster
    name: vmware_win10
    timeout: 1800
    poll_interval: 30
    vmware:
      url: vpx://[email protected]/Folder1/Cluster1/2.3.4.5?no_verify=1
      name: windows10
      storage_domain: mynfs
      username: user
      password: password

# create vm from template and create all disks on specific storage domain
ovirt_vms:
  name: vm_test
  cluster: mycluster
  template: mytemplate
  storage_domain: mynfs
  nics:
    - name: nic1

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

Return Values

Common return values are documented here 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/RHV instance at following url: http://ovirt.github.io/ovirt-engine-api-model/master/#types/vm.
On success if VM is found. dict

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.
  • 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

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.4/ovirt_vms_module.html