SEAPATH libvirt documentation

This page explains how to use the preconfigured guest.xml file provided with SEAPATH.

Configuration

The example inventory available on the project's Ansible GitHub allows you to fully configure the VMs.

The various variables in this Ansible inventory configure the provided template 'guest.xml.j2'. This template is an XML file that defines the configuration details for virtual machines. The Ansible variables customize this template to specify VM characteristics such as names, IP addresses, CPU settings, and more.

The table opposite lists the inventory variables and their description:

For a virtual machines with determinism and performance needs, we recommand to use both the "isolated" and "rt" feature. Refer to the page Scheduling and priorities for more information.

Deploy the VMs

To then deploy our VM, we'll simply call an Ansible playbook which automates the process by issuing all the commands required for deployment, using the inventory defined earlier.

The advantage is that we can define as many different VMs in our inventory, and the playbook will deploy them all, which greatly reduces the user's knowledge requirements.

The procedure for deploying VMs is available here for the Yocto version and here for the Debian version.

Inventory variable	Values	Description

Inventory variable	Values	Description
name, uuid, description		VM identification
vm_template	By default, we use the `guest.xml.j2` file, but it's possible to use another if needed.	A VM template that we're going to customize.
vm_disk		The disk image used to create the VM (built in the previous section). When using cluster, it's managed by vm-manager
local_disk	^disk_file	List of VM disks.
vm_features	^rt	Enable real time tweaks such as vm priority, choice of scheduler, CPU mode, which will be visible to the vm in the same way as the host, etc...
	^isolated	Enables CPU pinning, allowing you to control which physical CPU core the virtual CPU core (vCPU) will run on.
	^dpdk
cpuset		The list of CPU cores to use in the case of an isolated VM.
nb_cpu		In the case of a non-isolated VM, the number of CPU cores to use.
pci_passthrough	^domain	A list containing dictionaries of the PCI devices to pass-through.
	^bus
	^slot
	^function
sriov		A list containing the SRIOV pool to use.
bridges	name	A list containing dictionaries of the bridges to use.
bridges	mac_address	A list containing dictionaries of the bridges to use.
ovs		A list containing dictionaries of the OVS ports to use.
pinned_host		When using cluster, the host to pin the VM.
preferred_host		When using cluster, the host to prefer to run the VM.

Virtual machine and slices

If you configured SEAPATH with machine-rt and machine-nort slices (see Scheduling and priorities), you must put the VM into it. This is done using libvirt resources. The VM will then only have access to the CPU associated with the slice.

Possible values:

/machine/nort
/machine/rt

Example, for a virtual machine with the real-time:

<resource>
    <partition>/machine/rt</partition>
</resource>

CPU tuning

In the project, this element will be used to limit the virtual machine (more details here).

The vcpupin element specifies which host's physical CPUs the domain vCPU will be pinned to. Use this value only for performance driven VMs.
The vcpusched element specifies the scheduler type for a particular vCPU. Use this value only for performance driven VMs.
The emulatorpin element specifies which of host physical CPUs the emulator will be pinned to. The emulator describes the management processes of the VM (watchdog, creation, timers, modification). This value is not useful, most of the time.

If you configured CPU restriction for slices (see Scheduling and priorities), all the CPU ranges that you provide for emulatorpin and vcpupin must be part of the allowed CPUs of the slice where the VM is. By default, the VM is part of the machine slice, but it can be in the machine-rt or machine-nort slice following your configuration.

If you deploy a machine with real time vcpu scheduler, you must set the emulatorpin cpu range. It can be set on the system cpu range or on specific cores.
Remember that, for maximal performance, each vCPU must be scheduled alone on its core. Emulatorpin must then be set on another core.