# ovirt_vm – Module to manage Virtual Machines in oVirt/RHV

- Synopsis
- Requirements
- Parameters
- Notes
- Examples
- Return Values
- Status

## 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

The below requirements are needed on the host that executes this module.

- python >= 2.7
- ovirt-engine-sdk-python >= 4.3.0

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
affinity_group_mappings - added in 2.5 |  | Mapper which maps affinity name between VM's OVF and the destination affinity this VM should be registered to, relevant when `state` is registered.
affinity_label_mappings - added in 2.5 |  | Mapper which maps affinity label name between VM's OVF and the destination label this VM should be registered to, relevant when `state` is registered.

allow_partial_import
boolean
added in 2.4

Choices:
- no
- yes

Boolean indication whether to allow partial registration of Virtual Machine when `state` is registered.

auth dictionary / required |  | Dictionary with values needed to create HTTP/HTTPS connection to oVirt:
| ca_file string |  | 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.
| headers dictionary |  | Dictionary of HTTP headers to be added to each API call.
| hostname string |  | A string containing the hostname of the server, usually something like `server.example.com`. Default value is set by `OVIRT_HOSTNAME` environment variable. Either `url` or `hostname` is required.

insecure
boolean

Choices:
- no
- yes

A boolean flag that indicates if the server TLS certificate and host name should be checked.

kerberos
boolean

Choices:
- no
- yes

A boolean flag indicating if Kerberos authentication should be used instead of the default basic authentication.

| password string / required |  | The password of the user. Default value is set by `OVIRT_PASSWORD` environment variable.
| token string |  | Token to be used instead of login with username/password. Default value is set by `OVIRT_TOKEN` environment variable.
| url string |  | A string containing the API URL of the server, usually something like `https://server.example.com/ovirt-engine/api`. Default value is set by `OVIRT_URL` environment variable. Either `url` or `hostname` is required.
| username string / required |  | The name of the user, something like admin@internal. Default value is set by `OVIRT_USERNAME` environment variable.

ballooning_enabled
boolean
added in 2.5

Choices:
- no
- yes

If true, use memory ballooning.
Memory balloon is a guest device, which may be used to re-distribute / reclaim the host memory based on VM needs in a dynamic way. In this way it's possible to create memory over commitment states.

boot_devices
-

Choices:
- cdrom
- hd
- network

List of boot devices which should be used to boot. For example `[ cdrom, hd ]`.
Default value is set by oVirt/RHV engine.

boot_menu
boolean
added in 2.5

Choices:
- no
- yes

True enable menu to select boot device, False to disable it. By default is chosen by oVirt/RHV engine.

cd_iso
-

ISO file from ISO storage domain which should be attached to Virtual Machine.
If you have multiple ISO disks with the same name use disk ID to specify which should be used or use `storage_domain` to filter disks.
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
boolean

Choices:
- no ←
- yes

If yes 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
boolean

Choices:
- no ←
- yes

If yes 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 - |  | Dictionary with values for Unix-like Virtual Machine initialization using cloud init.
| authorized_ssh_keys - |  | Use this SSH keys to login to Virtual Machine.
| custom_script - |  | Cloud-init script which will be executed on Virtual Machine when deployed. This is appended to the end of the cloud-init script generated by any other options.
| dns_search - |  | DNS search domains to be configured on Virtual Machine.
| dns_servers - |  | DNS servers to be configured on Virtual Machine.
| host_name - |  | Hostname to be set to Virtual Machine when deployed.

nic_boot_protocol
-

Choices:
- none
- dhcp
- static

Set boot protocol of the network interface of Virtual Machine.

nic_boot_protocol_v6
-
added in 2.9

Choices:
- none
- dhcp
- static

Set boot protocol of the network interface of Virtual Machine.

| nic_gateway - |  | If boot protocol is static, set this gateway to network interface of Virtual Machine.
| nic_gateway_v6 - added in 2.9 |  | If boot protocol is static, set this gateway to network interface of Virtual Machine. For IPv6 addresses the value is an integer in the range of 0-128, which represents the subnet prefix.
| nic_ip_address - |  | If boot protocol is static, set this IP address to network interface of Virtual Machine.
| nic_ip_address_v6 - added in 2.9 |  | If boot protocol is static, set this IP address to network interface of Virtual Machine.
| nic_name - |  | Set name to network interface of Virtual Machine.
| nic_netmask - |  | If boot protocol is static, set this netmask to network interface of Virtual Machine.
| nic_netmask_v6 - added in 2.9 |  | If boot protocol is static, set this netmask to network interface of Virtual Machine.

nic_on_boot
boolean

Choices:
- no
- yes

If True network interface will be set to start on boot.

regenerate_ssh_keys
boolean

Choices:
- no
- yes

If True SSH keys will be regenerated on Virtual Machine.

| root_password - |  | Password to be set for user specified by `user_name` parameter.
| timezone - |  | Timezone to be set to Virtual Machine when deployed.
| user_name - |  | Username to be used to set password to Virtual Machine when deployed.
cloud_init_nics - |  | List of dictionaries representing network interfaces 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.
| nic_boot_protocol - |  | Set boot protocol of the network interface of Virtual Machine. Can be one of `none`, `dhcp` or `static`.
| nic_boot_protocol_v6 - added in 2.9 |  | Set boot protocol of the network interface of Virtual Machine. Can be one of `none`, `dhcp` or `static`.
| nic_gateway - |  | If boot protocol is static, set this gateway to network interface of Virtual Machine.
| nic_gateway_v6 - added in 2.9 |  | If boot protocol is static, set this gateway to network interface of Virtual Machine. For IPv6 addresses the value is an integer in the range of 0-128, which represents the subnet prefix.
| nic_ip_address - |  | If boot protocol is static, set this IP address to network interface of Virtual Machine.
| nic_ip_address_v6 - added in 2.9 |  | If boot protocol is static, set this IP address to network interface of Virtual Machine.
| nic_name - |  | Set name to network interface of Virtual Machine.
| nic_netmask - |  | If boot protocol is static, set this netmask to network interface of Virtual Machine.
| nic_netmask_v6 - added in 2.9 |  | If boot protocol is static, set this netmask to network interface of Virtual Machine.

nic_on_boot
boolean

Choices:
- no
- yes

If True network interface will be set to start on boot.

cloud_init_persist
boolean
added in 2.5

Choices:
- no ←
- yes

If yes the `cloud_init` or `sysprep` parameters will be saved for the virtual machine and the virtual machine won't be started as run-once.
aliases: sysprep_persist

cluster - |  | Name of the cluster, where Virtual Machine should be created. Required if creating VM.
cluster_mappings - added in 2.5 |  | Mapper which maps cluster name between VM's OVF and the destination cluster this VM should be registered to, relevant when `state` is registered. Cluster mapping is described by the following dictionary:
| dest_name - |  | The name of the destination cluster.
| source_name - |  | The name of the source cluster.
comment - |  | Comment of the Virtual Machine.
cpu_cores - |  | Number of virtual CPUs cores of the Virtual Machine. Default value is set by oVirt/RHV engine.
cpu_mode - added in 2.5 |  | CPU mode of the virtual machine. It can be some of the following: host_passthrough, host_model or custom. For host_passthrough CPU type you need to set `placement_policy` to pinned. If no value is passed, default value is set by oVirt/RHV engine.
cpu_pinning - added in 2.5 |  | CPU Pinning topology to map virtual machine CPU to host CPU. CPU Pinning topology is a list of dictionary which can have following values:
| cpu - |  | Number of the host CPU.
| vcpu - |  | Number of the virtual machine CPU.
cpu_shares - |  | Set a CPU shares for this Virtual Machine. Default value is set by oVirt/RHV engine.
cpu_sockets - |  | Number of virtual CPUs sockets of the Virtual Machine. Default value is set by oVirt/RHV engine.
cpu_threads - added in 2.5 |  | Number of threads per core of the Virtual Machine. Default value is set by oVirt/RHV engine.
custom_compatibility_version - added in 2.7 |  | Enables a virtual machine to be customized to its own compatibility version. If '`custom_compatibility_version`' is set, it overrides the cluster's compatibility version for this particular virtual machine.
custom_properties - added in 2.5 |  | Properties sent to VDSM to configure various hooks. Custom properties is a list of dictionary which can have following values:
| name - |  | Name of the custom property. For example: hugepages, vhost, sap_agent, etc.
| regexp - |  | Regular expression to set for custom property.
| value - |  | Value to set for custom property.

delete_protected
boolean

Choices:
- no
- yes

If yes Virtual Machine will be set as delete protected.
If no Virtual Machine won't be set as delete protected.
If no value is passed, default value is set by oVirt/RHV engine.

description - |  | Description of the Virtual Machine.

disk_format
-
added in 2.4

Choices:
- 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 - |  | List of disks, which should be attached to Virtual Machine. Disk is described by following dictionary.

activate
boolean

Choices:
- no
- yes

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_disk module instead.

bootable
boolean

Choices:
- no
- yes

True if the disk should be bootable, default is non bootable.

| id - |  | ID of the disk. Either `name` or `id` is required.

interface
-

Choices:
- virtio ←
- ide

Interface of the disk.

| name - |  | Name of the disk. Either `name` or `id` is required.
domain_mappings - added in 2.5 |  | Mapper which maps aaa domain name between VM's OVF and the destination aaa domain this VM should be registered to, relevant when `state` is registered. The aaa domain mapping is described by the following dictionary:
| dest_name - |  | The name of the destination aaa domain.
| source_name - |  | The name of the source aaa domain.

exclusive
boolean
added in 2.8

Choices:
- no
- yes

When `state` is exported this parameter indicates if the existing VM with the same name should be overwritten.

export_domain - added in 2.8 |  | When `state` is exportedthis parameter specifies the name of the export storage domain.
export_ova - added in 2.8 |  | Dictionary of values to be used to export VM as OVA.
| directory - |  | The name of the directory where the OVA has to be exported.
| filename - |  | The name of the exported OVA file.
| host - |  | The name of the destination host where the OVA has to be exported.

fetch_nested
boolean

Choices:
- no
- yes

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
boolean

Choices:
- no ←
- yes

Please check to Synopsis to more detailed description of force parameter, it can behave differently in different situations.

force_migrate
boolean
added in 2.8

Choices:
- no
- yes

If true, the VM will migrate when placement_policy=user-migratable but not when placement_policy=pinned.

graphical_console - added in 2.5 |  | Assign graphical console to the virtual machine.

headless_mode
boolean

Choices:
- no
- yes

If true disable the graphics console for this virtual machine.

| protocol - |  | Graphical protocol, a list of spice, vnc, or both.

high_availability
boolean

Choices:
- no
- yes

If yes Virtual Machine will be set as highly available.
If no Virtual Machine won't be set as highly available.
If no value is passed, default value is set by oVirt/RHV engine.

high_availability_priority - added in 2.5 |  | Indicates the priority of the virtual machine inside the run and migration queues. Virtual machines with higher priorities will be started and migrated before virtual machines with lower priorities. The value is an integer between 0 and 100. The higher the value, the higher the priority. If no value is passed, default value is set by oVirt/RHV engine.
host - |  | 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.
host_devices - added in 2.7 |  | Single Root I/O Virtualization - technology that allows single device to expose multiple endpoints that can be passed to VMs host_devices is an list which contain dictionary with name and state of device
id - |  | ID of the Virtual Machine to manage.
initrd_path - |  | 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 - |  | Name of virtual machine's hardware configuration. By default no instance type is used.
io_threads - added in 2.5 |  | Number of IO threads used by virtual machine. 0 means IO threading disabled.
kernel_params - |  | Kernel command line parameters (formatted as string) to be used with the kernel specified by `kernel_path` option.

kernel_params_persist
boolean
added in 2.8

Choices:
- no
- yes

If true `kernel_params`, `initrd_path` and `kernel_path` will persist in virtual machine configuration, if False it will be used for run once.

kernel_path - |  | 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 - |  | Dictionary of values to be used to connect to kvm and import a virtual machine to oVirt.
| drivers_iso - |  | The name of the ISO containing drivers that can be used during the virt-v2v conversion process.
| name - |  | The name of the KVM virtual machine.
| password - |  | The password to authenticate against the KVM.

sparse
boolean

Choices:
- no
- yes ←

Specifies the disk allocation policy of the resulting virtual machine. true for sparse, false for preallocated.

| storage_domain - |  | Specifies the target storage domain for converted disks. This is required parameter.
| url - |  | The URL to be passed to the virt-v2v tool for conversion. For example qemu:///system. This is required parameter.
| username - |  | The username to authenticate against the KVM.
lease - added in 2.4 |  | Name of the storage domain this virtual machine lease reside on. Pass an empty string to remove the lease. NOTE - Supported since oVirt 4.1.

lun_mappings
-
added in 2.5

Mapper which maps lun between VM's OVF and the destination lun this VM should contain, relevant when `state` is registered. lun_mappings is described by the following dictionary: - `logical_unit_id`: The logical unit number to identify a logical unit, - `logical_unit_port`: The port being used to connect with the LUN disk. - `logical_unit_portal`: The portal being used to connect with the LUN disk. - `logical_unit_address`: The address of the block storage host. - `logical_unit_target`: The iSCSI specification located on an iSCSI server - `logical_unit_username`: Username to be used to connect to the block storage host. - `logical_unit_password`: Password to be used to connect to the block storage host. - `storage_type`: The storage type which the LUN reside on (iscsi or fcp)

memory - |  | 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 - |  | 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.
memory_max - added in 2.5 |  | Upper bound of virtual machine memory up to which memory hot-plug can be performed. Prefix uses IEC 60027-2 standard (for example 1GiB, 1024MiB). Default value is set by engine.

migrate
boolean
added in 2.8

Choices:
- no
- yes

If true, the VM will migrate to any available host.

name - |  | Name of the Virtual Machine to manage. If VM don't exists `name` is required. Otherwise `id` or `name` can be used.
nested_attributes list |  | Specifies list of the attributes which should be fetched from the API. This parameter apply only when `fetch_nested` is true.

next_run
boolean
added in 2.8

Choices:
- no
- yes

If true, the update will not be applied to the VM immediately and will be only applied when virtual machine is restarted.
NOTE - If there are multiple next run configuration changes on the VM, the first change may get reverted if this option is not passed.

nics - |  | List of NICs, which should be attached to Virtual Machine. NIC is described by following dictionary.

interface
-

Choices:
- virtio ←
- e1000
- rtl8139

Type of the network interface.

| 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_nic module instead.
| name - |  | Name of the NIC.
| profile_name - |  | Profile name where NIC should be attached.
numa_nodes - added in 2.6 |  | List of vNUMA Nodes to set for this VM and pin them to assigned host's physical NUMA node. Each vNUMA node is described by following dictionary:
| cores list / required |  | List of VM CPU cores indexes to be included in this NUMA node.
| index - / required |  | The index of this NUMA node.
| memory - / required |  | Memory size of the NUMA node in MiB.
| numa_node_pins list |  | List of physical NUMA node indexes to pin this virtual NUMA node to.

numa_tune_mode
-
added in 2.6

Choices:
- interleave
- preferred
- strict

Set how the memory allocation for NUMA nodes of this VM is applied (relevant if NUMA nodes are set for this VM).
It can be one of the following: interleave, preferred or strict.
If no value is passed, default value is set by oVirt/RHV engine.

operating_system
-

Operating system of the Virtual Machine.
Default value is set by oVirt/RHV engine.
Possible values: debian_7, freebsd, freebsdx64, other, other_linux, other_linux_kernel_4, other_linux_ppc64, other_linux_s390x, other_ppc64, other_s390x, rhcos_x64, rhel_3, rhel_3x64, rhel_4, rhel_4x64, rhel_5, rhel_5x64, rhel_6, rhel_6_9_plus_ppc64, rhel_6_ppc64, rhel_6x64, rhel_7_ppc64, rhel_7_s390x, rhel_7x64, rhel_8x64, rhel_atomic7x64, sles_11, sles_11_ppc64, sles_12_s390x, ubuntu_12_04, ubuntu_12_10, ubuntu_13_04, ubuntu_13_10, ubuntu_14_04, ubuntu_14_04_ppc64, ubuntu_16_04_s390x, windows_10, windows_10x64, windows_2003, windows_2003x64, windows_2008, windows_2008R2x64, windows_2008x64, windows_2012R2x64, windows_2012x64, windows_2016x64, windows_2019x64, windows_7, windows_7x64, windows_8, windows_8x64, windows_xp

placement_policy - added in 2.5 |  | The configuration of the virtual machine's placement policy. If no value is passed, default value is set by oVirt/RHV engine. Placement policy can be one of the following values:
| migratable - |  | Allow manual and automatic migration.
| pinned - |  | Do not allow migration.
| user_migratable - |  | Allow manual migration only.
poll_interval integer | Default: 3 | Number of the seconds the module waits until another poll request on entity status is sent.
quota_id - added in 2.5 |  | Virtual Machine quota ID to be used for disk. By default quota is chosen by oVirt/RHV engine.

reassign_bad_macs
boolean
added in 2.5

Choices:
- no
- yes

Boolean indication whether to reassign bad macs when `state` is registered.

rng_device - added in 2.5 |  | Random number generator (RNG). You can choose of one the following devices urandom, random or hwrng. In order to select hwrng, you must have it enabled on cluster first. /dev/urandom is used for cluster version >= 4.1, and /dev/random for cluster version <= 4.0
role_mappings - added in 2.5 |  | Mapper which maps role name between VM's OVF and the destination role this VM should be registered to, relevant when `state` is registered. Role mapping is described by the following dictionary:
| dest_name - |  | The name of the destination role.
| source_name - |  | The name of the source role.

serial_console
boolean
added in 2.5

Choices:
- no
- yes

True enable VirtIO serial console, False to disable it. By default is chosen by oVirt/RHV engine.

serial_policy
-

Choices:
- vm
- host
- custom

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 - |  | Allows you to specify a custom serial number. This parameter is used only when `serial_policy` is custom.

smartcard_enabled
boolean
added in 2.5

Choices:
- no
- yes

If true, use smart card authentication.

snapshot_name - added in 2.9 |  | Snapshot to clone VM from. Snapshot with description specified should exist. You have to specify `snapshot_vm` parameter with virtual machine name of this snapshot.
snapshot_vm - added in 2.9 |  | Source VM to clone VM from. VM should have snapshot specified by `snapshot`. If `snapshot_name` specified `snapshot_vm` is required.

soundcard_enabled
boolean
added in 2.5

Choices:
- no
- yes

If true, the sound card is added to the virtual machine.

sso
boolean
added in 2.5

Choices:
- no
- yes

True enable Single Sign On by Guest Agent, False to disable it. By default is chosen by oVirt/RHV engine.

state
-

Choices:
- absent
- next_run
- present ←
- registered
- running
- stopped
- suspended
- exported

Should the Virtual Machine be running/stopped/present/absent/suspended/next_run/registered/exported. 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 state will create/update VM and don't change its state if it already exists.
running state will create/update VM and start it.
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.
exported state will export the VM to export domain or as OVA.
registered is supported since 2.4.

stateless
boolean

Choices:
- no
- yes

If yes Virtual Machine will be set as stateless.
If no 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 |  | 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 specify different storage domain, disk won't move.
sysprep - |  | Dictionary with values for Windows Virtual Machine initialization using sysprep.
| active_directory_ou - |  | Active Directory Organizational Unit, to be used for login of user.
| domain - |  | Domain to be set to Windows Virtual Machine.
| host_name - |  | Hostname to be set to Virtual Machine when deployed.
| input_locale - |  | Input localization of the Windows Virtual Machine.
| org_name - |  | Organization name to be set to Windows Virtual Machine.
| root_password - |  | Password to be set for username to Windows Virtual Machine.
| system_locale - |  | System localization of the Windows Virtual Machine.
| timezone - |  | Timezone to be set to Windows Virtual Machine.
| ui_language - |  | UI language of the Windows Virtual Machine.
| user_name - |  | Username to be used for set password to Windows Virtual Machine.
| windows_license_key - |  | License key to be set to Windows Virtual Machine.
template - |  | 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 - |  | Version number of the template to be used for VM. By default the latest available version of the template is used.

ticket
boolean
added in 2.7

Choices:
- no
- yes

If true, in addition return remote_vv_file inside vm dictionary, which contains compatible content for remote-viewer application. Works only `state` is running.

timeout integer | Default: 180 | The amount of time in seconds the module should wait for the instance to get into desired state.
timezone - |  | Sets time zone offset of the guest hardware clock. For example `Etc/GMT`

type
-

Choices:
- desktop
- server
- high_performance

Type of the Virtual Machine.
Default value is set by oVirt/RHV engine.
high_performance is supported since Ansible 2.5 and oVirt/RHV 4.2.

usb_support
boolean
added in 2.5

Choices:
- no
- yes

True enable USB support, False to disable it. By default is chosen by oVirt/RHV engine.

use_latest_template_version
boolean

Choices:
- no
- yes

Specify if latest template version should be used, when running a stateless VM.
If this parameter is set to yes stateless VM is created.

vmware - |  | Dictionary of values to be used to connect to VMware and import a virtual machine to oVirt.
| drivers_iso - |  | The name of the ISO containing drivers that can be used during the virt-v2v conversion process.
| password - |  | The password to authenticate against the VMware.

sparse
boolean

Choices:
- no
- yes ←

Specifies the disk allocation policy of the resulting virtual machine. true for sparse, false for preallocated.

| storage_domain - |  | Specifies the target storage domain for converted disks. This is required parameter.
| 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
| username - |  | The username to authenticate against the VMware.
vnic_profile_mappings - added in 2.5 |  | Mapper which maps an external virtual NIC profile to one that exists in the engine when `state` is registered. vnic_profile is described by the following dictionary:
| source_network_name - |  | The network name of the source network.
| source_profile_name - |  | The profile name related to the source network.
| target_profile_id - |  | The id of the target profile id to be mapped to in the engine.

wait
boolean

Choices:
- no
- yes ←

`yes` if the module should wait for the entity to get into desired state.

watchdog - added in 2.5 |  | Assign watchdog device for the virtual machine. Watchdogs is a dictionary which can have following values:
| action - |  | Watchdog action to be performed when watchdog is triggered. For example: none, reset, poweroff, pause or dump.
| model - |  | Model of the watchdog device. For example: i6300esb, diag288 or null.
xen - |  | Dictionary of values to be used to connect to XEN and import a virtual machine to oVirt.
| drivers_iso - |  | The name of the ISO containing drivers that can be used during the virt-v2v conversion process.

sparse
boolean

Choices:
- no
- yes ←

Specifies the disk allocation policy of the resulting virtual machine. true for sparse, false for preallocated.

| storage_domain - |  | Specifies the target storage domain for converted disks. This is required parameter.
| url - |  | The URL to be passed to the virt-v2v tool for conversion. For example xen+ssh://root@zen.server. This is required parameter.

## 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.
- If you update a VM parameter that requires a reboot, the oVirt engine always creates a new snapshot for the VM, and an Ansible playbook will report this as changed.
- 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.3.0

## Examples

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

    - name: Creates a new Virtual Machine from template named 'rhel7_template'
      ovirt_vm:
        state: present
        name: myvm
        template: rhel7_template
        cluster: mycluster

    - name: Register VM
      ovirt_vm:
        state: registered
        storage_domain: mystorage
        cluster: mycluster
        name: myvm

    - name: Register VM using id
      ovirt_vm:
        state: registered
        storage_domain: mystorage
        cluster: mycluster
        id: 1111-1111-1111-1111

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

    - name: Register VM with vnic profile mappings and reassign bad macs
      ovirt_vm:
        state: registered
        storage_domain: mystorage
        cluster: mycluster
        id: 1111-1111-1111-1111
        vnic_profile_mappings:
        - source_network_name: mynetwork
          source_profile_name: mynetwork
          target_profile_id: 3333-3333-3333-3333
        - source_network_name: mynetwork2
          source_profile_name: mynetwork2
          target_profile_id: 4444-4444-4444-4444
        reassign_bad_macs: "True"

    - name: Register VM with mappings
      ovirt_vm:
        state: registered
        storage_domain: mystorage
        cluster: mycluster
        id: 1111-1111-1111-1111
        role_mappings:
          - source_name: Role_A
            dest_name: Role_B
        domain_mappings:
          - source_name: Domain_A
            dest_name: Domain_B
        lun_mappings:
          - source_storage_type: iscsi
            source_logical_unit_id: 1IET_000d0001
            source_logical_unit_port: 3260
            source_logical_unit_portal: 1
            source_logical_unit_address: 10.34.63.203
            source_logical_unit_target: iqn.2016-08-09.brq.str-01:omachace
            dest_storage_type: iscsi
            dest_logical_unit_id: 1IET_000d0002
            dest_logical_unit_port: 3260
            dest_logical_unit_portal: 1
            dest_logical_unit_address: 10.34.63.204
            dest_logical_unit_target: iqn.2016-08-09.brq.str-02:omachace
        affinity_group_mappings:
          - source_name: Affinity_A
            dest_name: Affinity_B
        affinity_label_mappings:
          - source_name: Label_A
            dest_name: Label_B
        cluster_mappings:
          - source_name: cluster_A
            dest_name: cluster_B

    - name: Creates a stateless VM which will always use latest template version
      ovirt_vm:
        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_vm:
        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

    # Change VM Name
    - ovirt_vm:
        id: 00000000-0000-0000-0000-000000000000
        name: "new_vm_name"

    - name: Run VM with cloud init
      ovirt_vm:
        name: rhel7
        template: rhel7
        cluster: Default
        memory: 1GiB
        high_availability: true
        high_availability_priority: 50  # Available from Ansible 2.5
        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

    - name: Run VM with cloud init, with multiple network interfaces
      ovirt_vm:
        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
        # IP version 6 parameters are supported since ansible 2.9
        - nic_name: eth2
          nic_boot_protocol_v6: static
          nic_ip_address_v6: '2620:52:0:2282:b898:1f69:6512:36c5'
          nic_gateway_v6: '2620:52:0:2282:b898:1f69:6512:36c9'
          nic_netmask_v6: '120'
          nic_on_boot: true
        - nic_name: eth3
          nic_on_boot: true
          nic_boot_protocol_v6: dhcp

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

    - name: Migrate/Run VM to/on host named 'host1'
      ovirt_vm:
        state: running
        name: myvm
        host: host1

    - name: Migrate VM to any available host
      ovirt_vm:
        state: running
        name: myvm
        migrate: true

    - name: Change VMs CD
      ovirt_vm:
        name: myvm
        cd_iso: drivers.iso

    - name: Eject VMs CD
      ovirt_vm:
        name: myvm
        cd_iso: ''

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

    - name: Stop vm
      ovirt_vm:
        state: stopped
        name: myvm

    - name: Upgrade memory to already created VM
      ovirt_vm:
        name: myvm
        memory: 4GiB

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

    # Create/update a VM to run with two vNUMA nodes and pin them to physical NUMA nodes as follows:
    # vnuma index 0-> numa index 0, vnuma index 1-> numa index 1
    - name: Create a VM to run with two vNUMA nodes
      ovirt_vm:
        name: myvm
        cluster: mycluster
        numa_tune_mode: "interleave"
        numa_nodes:
        - index: 0
          cores: [0]
          memory: 20
          numa_node_pins: [0]
        - index: 1
          cores: [1]
          memory: 30
          numa_node_pins: [1]

    - name: Update an existing VM to run without previously created vNUMA nodes (i.e. remove all vNUMA nodes+NUMA pinning setting)
      ovirt_vm:
        name: myvm
        cluster: mycluster
        state: "present"
        numa_tune_mode: "interleave"
        numa_nodes:
        - index: -1

    # 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_vm:
        state: next_run
        name: myvm
        boot_devices:
          - network

    - name: Import virtual machine from VMware
      ovirt_vm:
        state: stopped
        cluster: mycluster
        name: vmware_win10
        timeout: 1800
        poll_interval: 30
        vmware:
          url: vpx://user@1.2.3.4/Folder1/Cluster1/2.3.4.5?no_verify=1
          name: windows10
          storage_domain: mynfs
          username: user
          password: password

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

    - name: Remove VM, if VM is running it will be stopped
      ovirt_vm:
        state: absent
        name: myvm

    # Defining a specific quota for a VM:
    # Since Ansible 2.5
    - ovirt_quotas_facts:
        data_center: Default
        name: myquota
    - ovirt_vm:
        name: myvm
        sso: False
        boot_menu: True
        usb_support: True
        serial_console: True
        quota_id: "{{ ovirt_quotas[0]['id'] }}"

    - name: Create a VM that has the console configured for both Spice and VNC
      ovirt_vm:
        name: myvm
        template: mytemplate
        cluster: mycluster
        graphical_console:
          protocol:
            - spice
            - vnc

    # Execute remote viewer to VM
    - block:
      - name: Create a ticket for console for a running VM
        ovirt_vm:
          name: myvm
          ticket: true
          state: running
        register: myvm

      - name: Save ticket to file
        copy:
          content: "{{ myvm.vm.remote_vv_file }}"
          dest: ~/vvfile.vv

      - name: Run remote viewer with file
        command: remote-viewer ~/vvfile.vv

    # Default value of host_device state is present
    - name: Attach host devices to virtual machine
      ovirt_vm:
        name: myvm
        host: myhost
        placement_policy: pinned
        host_devices:
          - name: pci_0000_00_06_0
          - name: pci_0000_00_07_0
            state: absent
          - name: pci_0000_00_08_0
            state: present

    - name: Export the VM as OVA
      ovirt_vm:
        name: myvm
        state: exported
        cluster: mycluster
        export_ova:
            host: myhost
            filename: myvm.ova
            directory: /tmp/

    - name: Clone VM from snapshot
      ovirt_vm:
        snapshot_vm: myvm
        snapshot_name: myvm_snap
        name: myvm_clone
        state: present

    - name: Import external ova VM
      ovirt_vm:
        cluster: mycluster
        name: myvm
        host: myhost
        timeout: 1800
        poll_interval: 30
        kvm:
          name: myvm
          url: ova:///path/myvm.ova
          storage_domain: mystorage

## Return Values

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

Key | Returned | Description
--- | --- | ---
id string | On success if VM is found. | ID of the VM which is managed Sample: 7de90f31-222c-436c-a1ca-7e655bd5b60c

vm
dictionary

On success if VM is found.

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. Additionally when user sent ticket=true, this module will return also remote_vv_file parameter in vm dictionary, which contains remote-viewer compatible file to open virtual machine console. Please note that this file contains sensible information.

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Ondra Machacek (@machacekondra)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.