Skip to main content
← back to extensions

Libvirt

@taylor/libvirtv2026.10.24.2· AGPL-3.0-or-later· 2d agoBEHAVIORSWORKFLOWSACCEPTED WARNINGS
01README

Set up an Ubuntu host to run KVM/QEMU virtual machines with libvirt, the way the kvm-training deck does it, with the check/apply pattern @adam/cfgmgmt uses: host (the QEMU, libvirt and virtinst packages, and the user added to libvirt and kvm), pool (directory storage pools), network (nat, bridge, macvtap or routed), vm (Ubuntu Server guests from the release's cloud image, checked against SHA256SUMS and configured by cloud-init, with their address from qemu-guest-agent, and snapshots) and uplink, which says which of those can work on the host and why: Wi-Fi can't be bridged, a host that is itself a VM needs its hypervisor's help, and Docker can block bridged traffic. Every type runs on the host itself, as a swamp worker step, or over SSH with cfgmgmt's nodeHost arguments; workflows for both are included.

02Behaviors5
@taylor/libvirt/hostv2026.10.24.2libvirt_host.ts
fn check()
Read the host's packages and the user's groups and save what apply would change; changes nothing
fn apply()
Install the missing packages and add the user to the missing groups

Resources

state(infinite)— The host's release, /dev/kvm, packages and the user's groups, and whether they match
@taylor/libvirt/uplinkv2026.10.24.2libvirt_uplink.ts
fn check()
Read the uplink and save which ways of connecting guests can work; fails when mode can't. Changes nothing.

Resources

state(infinite)— The host's interfaces, uplink and network manager, which ways of connecting guests can work, and netplan mistakes
@taylor/libvirt/poolv2026.10.24.2libvirt_pool.ts
fn check()
Read the pool and save what apply would change; changes nothing
fn apply()
Define, build, start and autostart the pool, or with ensure: absent stop and undefine it

Resources

state(infinite)— The pool's type, target, and whether it's running and autostarted
@taylor/libvirt/networkv2026.10.24.2libvirt_network.ts
fn check()
Read the network, and the uplink for bridge and macvtap, and save what apply would change; changes nothing
fn apply()
Define, start and autostart the network, redefining it if it differs, or with ensure: absent stop and undefine it

Resources

state(infinite)— The network's mode, bridge or interface, address, and whether it's active and autostarted
@taylor/libvirt/vmv2026.10.24.2libvirt_vm.ts
fn check()
Read the VM and save what apply would change; changes nothing
fn apply()
Create the VM from the cloud image, or start it, and wait for its address; with ensure: absent shut it down and remove it with its storage

Resources

state(infinite)— The VM's state, memory, CPUs, network, MAC and address, and whether they match
snapshots(infinite)— The VM's snapshots and the current one
03Workflows6
@taylor/kvm-host-check7cdff513-e280-499b-afdd-b737abcdd4ed

Check a KVM host against the kvm-training setup on a swamp worker labelled role=kvm-host; changes nothing

kvm-hostRuns on the KVM host itself, through a swamp worker
1.uplink— Can guests connect this way on this host?
2.host— QEMU, libvirt and virtinst, and the user in libvirt and kvm
3.pool-default— Disk images in /var/lib/libvirt/images
4.pool-iso— ISOs in /var/lib/libvirt/iso
5.network— The libvirt network guests attach to
@taylor/kvm-host-applybe581847-17ec-4417-a5f1-3a24a2f1bca6

Set up a KVM host the kvm-training way on a swamp worker labelled role=kvm-host: packages, groups, image and ISO pools, and a libvirt network on the uplink

kvm-hostRuns on the KVM host itself, through a swamp worker
1.uplink— Can guests connect this way on this host?
2.host— QEMU, libvirt and virtinst, and the user in libvirt and kvm
3.pool-default— Disk images in /var/lib/libvirt/images
4.pool-iso— ISOs in /var/lib/libvirt/iso
5.network— The libvirt network guests attach to
@taylor/kvm-host-check-ssh2a111367-cb4b-49bf-9307-34133683444c

Check a KVM host against the kvm-training setup over SSH, with nothing installed on the host; changes nothing

kvm-hostRuns where swamp runs, reaching the KVM host over SSH
1.uplink— Can guests connect this way on this host?
2.host— QEMU, libvirt and virtinst, and the user in libvirt and kvm
3.pool-default— Disk images in /var/lib/libvirt/images
4.pool-iso— ISOs in /var/lib/libvirt/iso
5.network— The libvirt network guests attach to
@taylor/kvm-host-apply-ssh315b6941-deeb-4f17-a55e-be9b6f50715d

Set up a KVM host the kvm-training way over SSH, with nothing installed on the host: packages, groups, image and ISO pools, and a libvirt network on the uplink

kvm-hostRuns where swamp runs, reaching the KVM host over SSH
1.uplink— Can guests connect this way on this host?
2.host— QEMU, libvirt and virtinst, and the user in libvirt and kvm
3.pool-default— Disk images in /var/lib/libvirt/images
4.pool-iso— ISOs in /var/lib/libvirt/iso
5.network— The libvirt network guests attach to
@taylor/kvm-vm1dd15256-1b96-43f6-ac34-3de8f9540ebc

Create, start or remove an Ubuntu Server VM the kvm-training way on a swamp worker labelled role=kvm-host

vmRuns on the KVM host itself, through a swamp worker
1.vm— The VM, created from the cloud image and waited on until it has an address
@taylor/kvm-vm-ssh802c314d-0f8f-4e99-853b-68f45c6509da

Create, start or remove an Ubuntu Server VM the kvm-training way over SSH, with nothing installed on the host

vmRuns where swamp runs, reaching the KVM host over SSH
1.vm— The VM, created from the cloud image and waited on until it has an address
04Stats
A
100 / 100
Downloads
4
Archive size
103.0 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Docs keep secrets in a vault1/1earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned
Repository
https://github.com/taylorific/swampworks

06Platforms
07Labels
#libvirt#kvm#qemu#virsh#virtualization#ubuntu