Ansible Role kvm_vm

This role creates and manages virtual machines (VMs) on a KVM host.

By default, this role requires an OS image that has been modified using cloud-init and sysprep (to provide ssh keys or set the root password). Note: cloud-init and sysprep are only run when the boot disk is re-created.

If you want to create a VM with an existing disk, see the kvm_vm__existing_boot_disk variable.

Mandatory Requirements

• Install Python 3, and the python3-libvirt and python3-lxml modules on the KVM host. This can be done using the linuxfabrik.lfops.python role. If you use the kvm_host Playbook to setup the KVM host, this is automatically done for you.

• Place the base image in the kvm_vm__pool on the KVM host. If kvm_vm__pool is default, you get the storage path by running virsh pool-dumpxml default | grep -i path on the KVM host.

Tags

Tag	What it does	Reload / Restart
kvm_vm	Creates and manages the virtual machine	-
kvm_vm:additional_disks	Creates additional disks. Note that you need to manually attach them to the VM if the VM already exists	-
kvm_vm:resize_disks	Resizes boot and additional disks. If the VM is running, also performs a live virsh blockresize	-
kvm_vm:state	Sets the state of the VM	-

Mandatory Role Variables

Variable	Description
kvm_vm__base_image	The base image file which will be used for the VM. Has to be placed in the kvm_vm__pool storage pool.
kvm_vm__boot_disk_size	The size of the boot disk. On initial creation this is required since we are using a base image. On subsequent runs the boot disk will be grown to this size if it is currently smaller (live resize via virsh blockresize is performed when the VM is running). Shrinking is never attempted. Should either be in bytes, or given using an optional suffix: k or K (kilobyte, 1024), M (megabyte, 1024k) and G (gigabyte, 1024M) and T (terabyte, 1024G) are supported. b is ignored.
kvm_vm__host	The KVM host. Will be used in delegate_to statements, meaning the host should either be in the ansible inventory or reachable via the given value.
kvm_vm__memory	Memory to allocate for the VM, in MiB.
kvm_vm__vcpus	Number of virtual cpus to configure for the VM.

Example:

# mandatory
kvm_vm__base_image: 'rocky8-base-image.qcow2'
kvm_vm__boot_disk_size: '50G'
kvm_vm__host: 'kvm-host.example.com'
kvm_vm__memory: 2048
kvm_vm__vcpus: 2

Optional Role Variables

Variable	Description	Default Value
kvm_vm__additional_disks	A list of additional disks. They will be created in the kvm_vm__pool if they do not exist already. Note: the disk will only be attached to the VM during VM creation, not during subsequent runs. On subsequent runs, existing disks will be grown if size is larger than the current size (live resize via virsh blockresize is performed when the VM is running). Shrinking is never attempted. Subkeys: name: Mandatory, string. The name of the disk. Will be prepended with the kvm_vm__name and suffixed with .qcow2. size: Mandatory, string. The size of the disk, in the same format as kvm_vm__boot_disk_size. pool: Optional, string. Storage pool of the disk.	[]
kvm_vm__autostart	Whether the VM should be started on host boot up or not.	true
kvm_vm__boot	String. See man virt-install for details on --boot.	''
kvm_vm__connect_url	URL for connecting to the hypervisor on the kvm_vm__host.	'qemu:///system'
kvm_vm__existing_additional_disks	A list of existing additional disks. They will not be modified, only added to the VM during creation. The disk have to be placed in the kvm_vm__pool storage pool.	[]
kvm_vm__existing_boot_disk	This allows to provide an already existing boot image, skipping the usage of a base image, and any modification to the disk. The disk has to be placed in the kvm_vm__pool storage pool.	unset
kvm_vm__machine	The machine type to emulate.	unset
kvm_vm__max_memory	The run time maximum memory allocation of the VM. This is the maximum amount of memory that can be hot-plugged.	'{{ kvm_vm__memory }}'
kvm_vm__name	The domain name of the VM.	'{{ inventory_hostname }}'
kvm_vm__network_connections	List of dictionaries of network connections to configure. Currently only supports ethernet devices (no bond/bridges/vlans). Subkeys: * name: Mandatory, string. Name of the network interface. * mac: Optional, string. MAC of the interface. Defaults to a randomly generated MAC starting with 52:54:. * addresses: Optional, list. List of IP addresses to assign. Defaults is unset. * dhcp4: Optional, bool. If dhcp for IPv4 should be enabled or not. Defaults to false. * dhcp6: Optional, bool. If dhcp for IPv6 should be enabled or not. Defaults to false. * gateway4: Optional, string. IPv4 Gateway. Requires setting addresses. Default is unset. * gateway6: Optional, string. IPv6 Gateway. Requires setting addresses. Default is unset. * network_type: Optional, string. Libvirt Network type. Either 'bridge' or 'network'. Defaults to 'network'. * network_name: Optional, string. Libvirt Network name. This is either the name of the bridge or of the virtual network. Defaults to 'default'.	[]
kvm_vm__osinfo	Set the operating system of the VM, will be used to optimise the guest configuration. Have a look at man virt-install.	'detect=on'
kvm_vm__packages	A list of packages which will be injected into the image using virt-customize.	['cloud-init', 'qemu-guest-agent']
kvm_vm__pool	The KVM storage pool for the base image and disks.	'default'
kvm_vm__root_password	The root password of the VM.	unset
kvm_vm__ssh_authorized_keys	A list of keys which will be authorized to connect to the VM via SSH.	[]
kvm_vm__state	The state of the VM. Possible options: * 'absent': Use with caution. Destroys the VM and deletes all storage volumes. * 'destroyed': „hard shutdown“. Immediately terminates the VM. Does not delete any storage volumes. * 'paused': Suspends the VM. It is kept in memory but won’t be scheduled anymore. * 'running' * 'shutdown': Gracefully shuts down the VM.	'running'

Example:

# optional
kvm_vm__additional_disks:
  - name: 'disk1'
    size: '10G'
    pool: 'data1'
kvm_vm__autostart: true
# a more complex `--boot` parameter: boot using UEFI, but without Secure Boot (paths valid for RHEL)
kvm_vm__boot: 'loader=/usr/share/OVMF/OVMF_CODE.secboot.fd,loader.readonly=yes,loader.type=pflash,nvram.template=/usr/share/OVMF/OVMF_VARS.fd,loader_secure=no'
kvm_vm__existing_additional_disks:
  - 'vm1-existing-disk1.qcow2'
  - 'vm1-existing-disk2.qcow2'
kvm_vm__existing_boot_disk: 'vm1-existing-boot.qcow2'
kvm_vm__connect_url: 'qemu:///system'
kvm_vm__machine: 'q35'
kvm_vm__max_memory: '{{ kvm_vm__memory }}'
kvm_vm__name: '{{ inventory_hostname }}'
kvm_vm__network_connections:
  - name: 'eth0'
    addresses:
      - '192.0.2.2'
    gateway4: '192.0.2.1'
kvm_vm__osinfo: 'detect=on'
kvm_vm__packages:
  - 'cloud-init'
  - 'qemu-guest-agent'
kvm_vm__pool: 'default'
kvm_vm__root_password: 'linuxfabrik'
kvm_vm__ssh_authorized_keys: []
kvm_vm__state: 'running'

License

The Unlicense

Author Information

Linuxfabrik GmbH, Zurich