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.

The role does not currently support resizing the VM.

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
kvm_vm	Creates and manages the virtual machine
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 to which the boot disk will be resized. This is required since we are using a base image. 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. 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.	[]
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__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'
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__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