This role configures and creates (or destroys) VMs on a KVM hypervisor.
The host should have Virtualization Technology (VT) enabled and should be preconfigured with libvirt/KVM.
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 is volume. Options include block, file, network and
volume.
libvirt_volume_default_format: Format for volumes created by the role.
Default is qcow2. Options include raw, qcow2, vmdk. See man virsh
for the full range.
libvirt_volume_default_device: Control how device appears in guest OS.
Defaults to disk. Options include cdrom and disk.
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 if libvirt_cpu_mode or
vm.cpu_mode is undefined.
libvirt_vm_arch: CPU architecture, default is x86_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 to localtime.
libvirt_vm_trust_guest_rx_filters: Whether to trust guest receive filters.
This gets mapped to the trustGuestRxFilters attribute of VM interfaces.
Default is false
libvirt_vms: list of VMs to be created/destroyed. Each one may have the
following attributes:
state: set to present to create or absent to destroy the VM.
Defaults to present.
name: the name to assign to the VM.
uuid: the UUID to manually assign to the VM. If specified, neither
uuid_deterministic nor libvirt_vm_default_uuid_deterministic are used.
uuid_deterministic: overrides default set in
libvirt_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 is None if
libvirt_vm_engine is kvm, otherwise pc-1.0.
cpu_mode: Virtual machine CPU mode. Default is host-passthrough if
libvirt_vm_engine is kvm, otherwise host-model. Can be set to none
to not configure a cpu mode.
clock_offset: Overrides default set in libvirt_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
enable_guest_virtio: If true enables guest virtio device for use with
Qemu guest agent
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 for libvirt_volume_default_type are valid here. Default
is libvirt_volume_default_type.pool: Name or UUID of the storage pool from which the volume should be
allocated. Required when type is volume.name: Name to associate with the volume being created; For file type volumes include extension if you would like volumes created with one.file_path: Where the image of file type volumes should be placed; defaults to libvirt_volume_default_images_pathdevice: Control how device appears in guest OS. All options for
libvirt_volume_default_device are valid here. Default is
libvirt_volume_default_type.capacity: volume capacity, can be suffixed with k, M, G, T, P or E when type is network or MB,GB,TB, etc when type is disk (required when type is disk or network)auth: Authentication details should they be required. If auth is required, username, type, and uuid or usage will need to be supplied. uuid and usage should not be both supplied.source: Where the remote volume comes from when type is network. protocol, name and hosts_list should be supplied. port is optional.format: Format of the volume. All options for
libvirt_volume_default_format are valid here. Default is
libvirt_volume_default_format.image: (optional) a URL to an image with which the volume is initalised (full copy).checksum: (optional) checksum of the image 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 and backing_image are mutually exclusive options.target: (optional) Manually influence type and order of volumesdev: (optional) Block device path when type is block.remote_src: (optional) When type is file or block, specify wether image 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 the macvtap driver.network: Name of the network to which an interface should be
attached. Must be specified if and only if the interface type is
network.mac: "Hardware" address of the virtual instance, if absent one is createdsource: A dict defining the host interface to which this
VM interface should be attached. Must be specified if and only if the
interface type is direct. Includes the following attributes:
dev: The name of the host interface to which this VM interface
should be attached.mode: options include vepa, bridge, private and
passthrough. See man virsh for more details. Default is
vepa.trust_guest_rx_filters: Whether to trust guest receive filters.
This gets mapped to the trustGuestRxFilters attribute of VM
interfaces. Default is libvirt_vm_trust_guest_rx_filters.model: The name of the interface model. Eg. e1000 or ne2k_pci, if undefined
it defaults to virtio.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 with ua- to be compliant (aliases without ua- are ignored by libvirt.
If undefined it defaults to libvirt managed vnetX.console_log_enabled: if true, log console output to a file at the
path specified by console_log_path, instead of to a PTY. If
false, direct terminal output to a PTY at serial port 0. Default is
false.
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
is true.
autostart: Whether to start the VM when the host starts up. Default is
true.
boot_firmware: Can be one of: bios, or efi. Defaults to bios.
xml_file: Optionally supply a modified XML template. Base customisation
off the default vm.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.
If using qcow2 format drives qemu-img (in qemu-utils package) is required.
---
- 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'