Linux and Windows lab VMs on KVM and libvirt, configured by Ansible. OpenTofu creates each VM with
the dmacvicar/libvirt provider and keeps one state file per host. Each VM boots from a base image
stored in a libvirt pool.
- An x86_64 Linux host with a dnf or apt package manager (Fedora, Debian, Ubuntu).
- Hardware virtualization enabled, so that
/dev/kvmexists. - Python 3.
lab host-setup installs QEMU, libvirt, the libguestfs tools, OVMF (UEFI firmware), nftables, and
jq, creates the libvirt pools lab-base and lab-vms, and installs OpenTofu in
/usr/local/bin/tofu.
The lab commands that change libvirt networks also run sudo, setting up passwordless sudo is
recommended.
- Create the virtual environment with
bootstrap/setup-host-venv.sh, and activate the virtual environment withsource .venv/bin/activate. - Install the host prerequisites with
lab host-setup. Add--checkto preview the changes, or add--ask-become-passifsudoneeds a password. - Build the base images with
lab image build [image-name]. - Create the VMs with
lab up [vm-name]. - Configure the VMs with
lab provision [vm-name].
Run the commands through lab (scripts/lab), which is on the PATH once the virtual environment
is activated.
| Command | Action |
|---|---|
lab host-setup [args] |
Install and configure the host prerequisites. The command passes args to ansible-playbook. |
lab image build [--force] [name ...] |
Download the Linux images in images/linux.yml and build the Windows images in images/windows.yml. |
lab image list |
List the base images. |
lab image prune [--delete] |
List old base images that no disk uses. With --delete, the command deletes the old base images. |
lab up [limit] |
Create the VMs, and wait until the VMs accept connections. |
lab provision [limit] [args] |
Run playbooks/main.yml. The command passes args to ansible-playbook. |
lab stop [limit] [--force] |
Shut the VMs down. With --force, the command powers the VMs off. |
lab destroy [limit] [--force] |
Delete the VMs. With --force, the command skips the confirmation. |
lab status |
List the lab VMs. |
lab hosts |
List the inventory hosts and groups. |
A limit is an Ansible host pattern: a host, a group, host1,host2, or a wildcard pattern. Run
lab hosts to list the inventory hosts. When the limit is omitted, up, provision, stop, and
destroy apply to all hosts.
A base image is a read-only qcow2 file named <image>-<YYYYMMDDHHMM>.qcow2 in the lab-base
libvirt pool (/var/lib/libvirt/images/lab-base). The image key of a host selects the newest file
whose name starts with that image name. The VM disks and cloud-init seed ISOs are stored in the
lab-vms pool.
To build every image in the manifests, run lab image build. To build selected images, run
lab image build ubuntu-22.04 windows-2022, for example. The Linux images are the vendor cloud
images listed in images/linux.yml. The Windows images are built from the Microsoft evaluation VHDs
listed in images/windows.yml.
After each build, the command saves a checksum of the inputs that the image was built from in
.lab/images/. For a Linux image, the checksum covers the download URL and hash in
images/linux.yml. For a Windows image, the checksum covers the entries in images/windows.yml and
the files in images/windows/. On the next run, the command skips an image when the checksum is
unchanged since the command built the newest file for that image. If the checksum has changed, or if
you pass --force, the command builds a new image file.
Run lab image prune to list old images that no VM uses. Pass --delete with lab image prune to
delete the old image files.
If you delete .lab/images/, the next lab image build rebuilds every image again. Downloads are
cached in ~/.cache/kvm-lab.
The base Windows roles are forked from jobrean93/ansible-windows. The project retains the original
MIT license, with copyright held by Jordan Borean, in the LICENSE file.