ovirt_vm – Module to manage Virtual Machines in oVirt/RHV
ovirt_vm – 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.
Aliases: ovirt_vms
Requirements
The below requirements are needed on the host that executes this module.
- python >= 2.7
- ovirt-engine-sdk-python >= 4.2.4
Parameters
Parameter | Choices/Defaults | Comments |
---|---|---|
affinity_group_mappings - added in 2.5 |
Mapper which maps affinty name between VM's OVF and the destination affinity this VM should be registered to, relevant when | |
affinity_label_mappings - added in 2.5 |
Mappper which maps affinity label name between VM's OVF and the destination label this VM should be registered to, relevant when | |
allow_partial_import boolean added in 2.4 |
|
Boolean indication whether to allow partial registration of Virtual Machine when |
auth - / required |
Dictionary with values needed to create HTTP/HTTPS connection to oVirt:
| |
ballooning_enabled boolean added in 2.5 |
|
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 - |
|
List of boot devices which should be used to boot. For example Default value is set by oVirt/RHV engine. |
boot_menu boolean added in 2.5 |
|
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 pass empty string the CD will be ejected from VM. If used with If used with | |
clone boolean |
|
If yes then the disks of the created virtual machine will be cloned and independent of the template. This parameter is used only when |
clone_permissions boolean |
|
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 |
cloud_init - |
Dictionary with values for Unix-like Virtual Machine initialization using cloud init.
| |
cloud_init_nics - added in 2.3 |
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 Dictionary can contain following values.
| |
cloud_init_persist boolean added in 2.5 |
|
If true the
|
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
| |
comment - added in 2.3 |
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 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_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 virtual CPUs sockets 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_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:
| |
delete_protected boolean |
|
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 - added in 2.3 |
Description of the Virtual Machine. | |
disk_format - added in 2.4 |
|
Specify format of the disk. If If 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 |
disks - |
List of disks, which should be attached to Virtual Machine. Disk is described by following dictionary.
NOTE - This parameter is used only when | |
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
| |
fetch_nested boolean added in 2.3 |
|
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 |
force boolean |
|
Please check to Synopsis to more detailed description of force parameter, it can behave differently in different situations. |
graphical_console - added in 2.5 |
Assign graphical console to the virtual machine. Graphical console is a dictionary which can have following values:
| |
high_availability boolean |
|
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 | |
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 dictinary with name and state of device | |
id - |
ID of the Virtual Machine to manage. | |
initrd_path - added in 2.3 |
Path to an initial ramdisk to be used with the kernel specified by Ramdisk image must be stored on either the ISO domain or on the host's storage. | |
instance_type - added in 2.3 |
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 - added in 2.3 |
Kernel command line parameters (formatted as string) to be used with the kernel specified by | |
kernel_path - added in 2.3 |
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 |
Dictionary of values to be used to connect to kvm and import a virtual machine to oVirt. Dictionary can contain following values.
| |
lease - added in 2.4 |
Name of the storage domain this virtual machine lease reside on. 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 | |
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).
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. | |
name - |
Name of the Virtual Machine to manage. If VM don't exists | |
nested_attributes - added in 2.3 |
Specifies list of the attributes which should be fetched from the API. This parameter apply only when | |
nics - |
List of NICs, which should be attached to Virtual Machine. NIC is described by following dictionary.
NOTE - This parameter is used only when | |
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:
| |
numa_tune_mode - added in 2.6 |
|
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_ppc64, other_ppc64, rhel_3, rhel_4, rhel_4x64, rhel_5, rhel_5x64, rhel_6, rhel_6x64, rhel_6_ppc64, rhel_7x64, rhel_7_ppc64, sles_11, sles_11_ppc64, ubuntu_12_04, ubuntu_12_10, ubuntu_13_04, ubuntu_13_10, ubuntu_14_04, ubuntu_14_04_ppc64, windows_10, windows_10x64, windows_2003, windows_2003x64, windows_2008, windows_2008x64, windows_2008r2x64, windows_2008R2x64, windows_2012x64, windows_2012R2x64, 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. Placement policy can be one of the following values:
If no value is passed, default value is set by oVirt/RHV engine. | |
poll_interval - |
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 |
|
Boolean indication whether to reassign bad macs when |
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
| |
serial_console boolean added in 2.5 |
|
True enable VirtIO serial console, False to disable it. By default is chosen by oVirt/RHV engine. |
serial_policy - added in 2.3 |
|
Specify a serial number policy for the Virtual Machine. Following options are supported.
|
serial_policy_value - added in 2.3 |
Allows you to specify a custom serial number. This parameter is used only when | |
smartcard_enabled boolean added in 2.5 |
|
If true, use smart card authentication. |
soundcard_enabled boolean added in 2.5 |
|
If true, the sound card is added to the virtual machine. |
sso boolean added in 2.5 |
|
True enable Single Sign On by Guest Agent, False to disable it. By default is chosen by oVirt/RHV engine. |
state - |
|
Should the Virtual Machine be running/stopped/present/absent/suspended/next_run/registered. When 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. registered is supported since 2.4. |
stateless boolean |
|
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 IMPORTANT - This parameter is not idempotent, if the VM exists and you specfiy different storage domain, disk won't move. | |
sysprep - |
Dictionary with values for Windows Virtual Machine initialization using sysprep.
| |
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 - added in 2.3 |
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 |
|
If true, in addition return remote_vv_file inside vm dictionary, which contains compatible content for remote-viewer application. Works only |
timeout - |
Default: 180 |
The amount of time in seconds the module should wait for the instance to get into desired state. |
timezone - added in 2.3 |
Sets time zone offset of the guest hardware clock. For example | |
type - |
|
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 |
|
True enable USB support, False to disable it. By default is chosen by oVirt/RHV engine. |
use_latest_template_version boolean added in 2.3 |
|
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 - added in 2.3 |
Dictionary of values to be used to connect to VMware and import a virtual machine to oVirt. Dictionary can contain following values.
| |
vnic_profile_mappings - added in 2.5 |
Mapper which maps an external virtual NIC profile to one that exists in the engine when
| |
wait boolean |
|
True 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:
| |
xen - added in 2.3 |
Dictionary of values to be used to connect to XEN and import a virtual machine to oVirt. Dictionary can contain following values.
|
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 stoppedstate
, and If user passforce
parameter set to true we forcibly stop the VM in any state. If user don’t passforce
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 suspendedstate
, 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 absentstate
, 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.2.4
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
- 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
- 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: 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://[email protected]/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 viever to VM
- block:
- name: Create a ticket for console for a running VM
ovirt_vms:
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
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)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.7/modules/ovirt_vm_module.html