Libvirt VM
This role configures and creates (or destroys) VMs on a KVM hypervisor.
Requirements
The host should have Virtualization Technology (VT) enabled and should be preconfigured with libvirt/KVM.
Role Variables
-
libvirt_vm_default_console_log_dir
: The default directory in which to store VM console logs, if a VM-specific log file path is not given. Default is "/var/log/libvirt-consoles". -
libvirt_vm_default_uuid_deterministic
: Whether UUID should be calculated by hashing the VM name. If not, the UUID is randomly generated by libvirt when the VM is defined. Default is False. -
libvirt_vm_image_cache_path
: The directory in which to cache downloaded images. Default is "/tmp/". -
libvirt_volume_default_images_path
: Directory in which instance images are stored. Default is '/var/lib/libvirt/images'. -
libvirt_volume_default_type
: What type of backing volume does the instance use? Default isvolume
. Options includeblock
,file
,network
andvolume
. -
libvirt_volume_default_format
: Format for volumes created by the role. Default isqcow2
. Options includeraw
,qcow2
,vmdk
. Seeman virsh
for the full range. -
libvirt_volume_default_device
: Control how device appears in guest OS. Defaults todisk
. Options includecdrom
anddisk
. -
libvirt_vm_engine
: virtualisation engine. If not set, the role will attempt to auto-detect the optimal engine to use. -
libvirt_vm_emulator
: path to emulator binary. If not set, the role will attempt to auto-detect the correct emulator to use. -
libvirt_cpu_mode_default
: The default CPU mode iflibvirt_cpu_mode
orvm.cpu_mode
is undefined. -
libvirt_vm_arch
: CPU architecture, default isx86_64
. -
libvirt_vm_uri
: Override the libvirt connection URI. See the libvirt docs docs for more details. -
libvirt_vm_virsh_default_env
: Variables contained within this dictionary are added to the environment used when executing virsh commands. -
libvirt_vm_clock_offset
. If defined the instances clock offset is set to the provided value. When undefined sync is set tolocaltime
. -
libvirt_vm_trust_guest_rx_filters
: Whether to trust guest receive filters. This gets mapped to thetrustGuestRxFilters
attribute of VM interfaces. Default isfalse
-
libvirt_vms
: list of VMs to be created/destroyed. Each one may have the following attributes:-
state
: set topresent
to create orabsent
to destroy the VM. Defaults topresent
. -
name
: the name to assign to the VM. -
uuid
: the UUID to manually assign to the VM. If specified, neitheruuid_deterministic
norlibvirt_vm_default_uuid_deterministic
are used. -
uuid_deterministic
: overrides default set inlibvirt_vm_default_uuid_deterministic
-
memory_mb
: the memory to assign to the VM, in megabytes. -
vcpus
: the number of VCPU cores to assign to the VM. -
machine
: Virtual machine type. Default isNone
iflibvirt_vm_engine
iskvm
, otherwisepc-1.0
. -
cpu_mode
: Virtual machine CPU mode. Default ishost-passthrough
iflibvirt_vm_engine
iskvm
, otherwisehost-model
. Can be set to none to not configure a cpu mode. -
clock_offset
: Overrides default set inlibvirt_vm_clock_offset
-
enable_vnc
: If true enables VNC listening on localhost for use with VirtManager and similar tools -
enable_spice
: If true enables SPICE listening for use with Virtual Machine Manager and similar tools -
volumes
: a list of volumes to attach to the VM. Each volume is defined with the following dict:type
: What type of backing volume does the instance use? All options forlibvirt_volume_default_type
are valid here. Default islibvirt_volume_default_type
.pool
: Name or UUID of the storage pool from which the volume should be allocated. Required whentype
isvolume
.name
: Name to associate with the volume being created; Forfile
type volumes include extension if you would like volumes created with one.file_path
: Where the image offile
type volumes should be placed; defaults tolibvirt_volume_default_images_path
device
: Control how device appears in guest OS. All options forlibvirt_volume_default_device
are valid here. Default islibvirt_volume_default_type
.capacity
: volume capacity, can be suffixed with k, M, G, T, P or E when type isnetwork
or MB,GB,TB, etc when type isdisk
(required when type isdisk
ornetwork
)auth
: Authentication details should they be required. If auth is required,username
,type
, anduuid
orusage
will need to be supplied.uuid
andusage
should not be both supplied.source
: Where the remote volume comes from when type isnetwork
.protocol
,name
andhosts_list
should be supplied.port
is optional.format
: Format of the volume. All options forlibvirt_volume_default_format
are valid here. Default islibvirt_volume_default_format
.image
: (optional) a URL to an image with which the volume is initalised (full copy).checksum
: (optional) checksum of theimage
to avoid download when it's not necessary.backing_image
: (optional) name of the backing volume which is assumed to already be the same pool (copy-on-write).image
andbacking_image
are mutually exclusive options.target
: (optional) Manually influence type and order of volumesdev
: (optional) Block device path when type isblock
.remote_src
: (optional) When type isfile
orblock
, specify wetherimage
points to a remote file (true) or a file local to the host that launched the playbook (false). Defaults to true.
-
usb_devices
: a list of usb devices to present to the vm from the host.Each usb device is defined with the following dict:
vendor
: The vendor id of the USB device.product
: The product id of the USB device.
Note - Libvirt will error if the VM is provisioned and the USB device is not attached.
To obtain the vendor id and product id of the usb device from the host running as sudo / root with the usb device plugged in run
lsusb -v
. Example below with an attached Sandisk USB Memory Stick with vendor id:0x0781
and product id:0x5567
lsusb -v | grep -A4 -i sandisk idVendor 0x0781 SanDisk Corp. idProduct 0x5567 Cruzer Blade bcdDevice 1.00 iManufacturer 1 iProduct 2
-
interfaces
: a list of network interfaces to attach to the VM. Each network interface is defined with the following dict:-
type
: The type of the interface. Possible values:network
: Attaches the interface to a named Libvirt virtual network. This is the default value.direct
: Directly attaches the interface to one of the host's physical interfaces, using themacvtap
driver.
-
network
: Name of the network to which an interface should be attached. Must be specified if and only if the interfacetype
isnetwork
. -
mac
: "Hardware" address of the virtual instance, if absent one is created -
source
: A dict defining the host interface to which this VM interface should be attached. Must be specified if and only if the interfacetype
isdirect
. Includes the following attributes:dev
: The name of the host interface to which this VM interface should be attached.mode
: options includevepa
,bridge
,private
andpassthrough
. Seeman virsh
for more details. Default isvepa
.
-
trust_guest_rx_filters
: Whether to trust guest receive filters. This gets mapped to thetrustGuestRxFilters
attribute of VM interfaces. Default islibvirt_vm_trust_guest_rx_filters
. -
model
: The name of the interface model. Eg.e1000
orne2k_pci
, if undefined it defaults tovirtio
. -
alias
: An optional interface alias. This can be used to tie specific network configuration to persistent network devices via name. The user defined alias is always prefixed withua-
to be compliant (aliases withoutua-
are ignored by libvirt. If undefined it defaults to libvirt managedvnetX
.
-
-
console_log_enabled
: iftrue
, log console output to a file at the path specified byconsole_log_path
, instead of to a PTY. Iffalse
, direct terminal output to a PTY at serial port 0. Default isfalse
. -
console_log_path
: Path to console log file. Default is{{ libvirt_vm_default_console_log_dir }}/{{ name }}-console.log
. -
start
: Whether to immediately start the VM after defining it. Default istrue
. -
autostart
: Whether to start the VM when the host starts up. Default istrue
. -
boot_firmware
: Can be one of:bios
, orefi
. Defaults tobios
. -
xml_file
: Optionally supply a modified XML template. Base customisation off the defaultvm.xml.j2
template so as to include the expected jinja expressions the role uses.
-
N.B. the following variables are deprecated: libvirt_vm_state
,
libvirt_vm_name
, libvirt_vm_memory_mb
, libvirt_vm_vcpus
,
libvirt_vm_engine
, libvirt_vm_machine
, libvirt_vm_cpu_mode
,
libvirt_vm_volumes
, libvirt_vm_interfaces
and
libvirt_vm_console_log_path
. If the variable libvirt_vms
is left unset, its
default value will be a singleton list containing a VM specification using
these deprecated variables.
Dependencies
If using qcow2 format drives qemu-img (in qemu-utils package) is required.
Example Playbook
---
- name: Create VMs
hosts: hypervisor
roles:
- role: stackhpc.libvirt-vm
libvirt_vms:
- state: present
name: 'vm1'
memory_mb: 512
vcpus: 2
volumes:
- name: 'data1'
device: 'disk'
format: 'qcow2'
capacity: '400GB'
pool: 'my-pool'
- name: 'debian-10.2.0-amd64-netinst.iso'
type: 'file'
device: 'cdrom'
format: 'raw'
target: 'hda' # first device on ide bus
- name: 'networkfs'
type: 'network'
format: 'raw'
capacity: '50G'
auth:
username: 'admin'
type: 'ceph'
usage: 'rbd-pool'
source:
protocol: 'rbd'
name: 'rbd/volume'
hosts_list:
- 'mon1.example.org'
- 'mon2.example.org'
- 'mon3.example.org'
- type: 'block'
format: 'raw'
dev: '/dev/sda'
interfaces:
- network: 'br-datacentre'
usb_devices:
- vendor: '0x0781'
product: '0x5567'
- state: present
name: 'vm2'
memory_mb: 1024
vcpus: 1
volumes:
- name: 'data2'
device: 'disk'
format: 'qcow2'
capacity: '200GB'
pool: 'my-pool'
- name: 'filestore'
type: 'file'
file_path: '/srv/cloud/images'
capacity: '900GB'
interfaces:
- type: 'direct'
source:
dev: 'eth123'
mode: 'private'
- type: 'bridge'
source:
dev: 'br-datacentre'
Author Information
- Mark Goddard ([email protected])