How mstovenour/virt-compose works
Project type and purpose
• This is a CLI‐driven, config‐driven orchestration tool for KVM virtual machines (“virt-compose”), analogous to Docker Compose but for VMs.
• It provides lifecycle management (install, start, shutdown, undefine) and USB passthrough via udev/systemd integration.
Main components
a. Configuration store
• Global config: virt-compose.yaml
• Per-VM definitions: /etc/virt-compose/vm/{vm_name}/{vm_name}.yaml
b. CLI entry point
• virt-compose.sh (invoked by user or systemd)
• Parses YAML via yq, invokes libvirt/qemu utilities
c. External tools & hypervisor
• yq (YAML parsing)
• virt-install, virsh, qemu-utils, xorriso
• libvirt daemon / qemu-kvm
d. Systemd services
• virt-compose.service (host boot/shutdown → start-all/shutdown-all)
• virt-compose-{vm}@.service (triggered by udev on USB add/remove → attach/detach)
e. udev rules
• Watches USB host device events → invokes systemd unit for attach/detach
Relationships & data flows
• User or systemd invokes “virt-compose [action]” → CLI reads YAML →
• install: builds cloud-init ISO, writes systemd-@ service unit
• start/shutdown: generates udev rules, calls virsh attach/start or shutdown/detach
• On host boot, systemd: virt-compose.service → virt-compose start-all → virsh start + udev rule generation
• On USB event, udev → systemd-@ service → virt-compose attach/device → virsh attach-device
• Hypervisor (libvirt/qemu) manages actual VM lifecycle & USB devices
Architectural patterns & design principles
• Configuration-driven orchestration
• Event-driven integration: udev → systemd → CLI
• Modular CLI commands mapped 1:1 to lifecycle operations
• Separation of concerns:
• config parsing (yq)
• VM provisioning (virt-install)
• runtime operations (virsh attach/start/shutdown)
• service management (systemd units)