PKR-Lab

Rolle `libvirt_host`

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-ansible/rollen/libvirt_host.md

Rolle libvirt_host

KVM/libvirt, Bridge br0, legt prod-vm bzw. entw-vm an.

Läuft gegen controlplane-0, worker-1
Tags libvirt-host, virtualization
Quellcode roles/libvirt_host

Variablen

Defaults aus defaults/main.yml. Überschreiben in group_vars/ oder host_vars/.

Variable Default Bedeutung
libvirt_host_enabled false –
libvirt_host_configure_bridge false –
libvirt_host_bridge_name br0 –
libvirt_host_bridge_interface {{ ansible_default_ipv4.interface }} –
libvirt_host_static_ip {{ ansible_default_ipv4.address }} –
libvirt_host_gateway {{ ansible_default_ipv4.gateway }} –
libvirt_host_prefix_length {{ network_prefix_length \| default(24) }} –
libvirt_host_dns {{ network_dns \| default(['1.1.1.1', '8.8.8.8']) }} –
libvirt_host_pool_dir /var/lib/libvirt/images –
libvirt_host_base_image_url https://cloud-images.ubuntu.com/releases/resolute/release-20260927/ubuntu-26.04-server-… –
libvirt_host_base_image_sha256 8800651811af9a85465ad1d552add729947bb16488dddb4a9b5305a3d97332b2 –
libvirt_host_base_image_name ubuntu-26.04-server-cloudimg-amd64.img –
libvirt_host_guests_on_boot start –
libvirt_host_guests_on_shutdown shutdown –
libvirt_host_guests_shutdown_timeout 300 –
libvirt_host_admin_ssh_public_key `` –
libvirt_host_vms [] –

Ablauf

  1. QEMU/KVM + libvirt-Pakete installieren
  2. Konfliktenden dnsmasq-Snippet von libvirt-daemon-system entschaerfen
  3. Pruefen, ob der Snippet existiert
  4. Symlink auf das Paket-Original entfernen
  5. Leeren Platzhalter anlegen (blockt die Neuanlage des Symlinks durch Upgrades)
  6. Handler sofort ausfuehren (System-dnsmasq moeglichst schnell wieder hochbringen)
  7. libvirtd aktivieren und starten
  8. libvirt-guests - Verhalten beim Host-Shutdown und -Boot festlegen
  9. libvirt-guests - Start nach dnsmasq und Tailscale ordnen (systemd-Drop-in)
  10. Drop-in-Verzeichnis anlegen
  11. Drop-in schreiben
  12. Bridge-Netzwerk einrichten (nur wenn explizit aktiviert)
  13. Sicherstellen, dass die Bridge-Parameter plausibel sind
  14. Sicherstellen, dass die physische NIC auf dem Host existiert
  15. Vorhandene Netplan-Configs finden
  16. Alte Netplan-Configs entfernen
  17. Bridge-Netplan-Konfiguration deployen
  18. Netplan anwenden (Verbindung kann kurz abreissen)
  19. Warten, bis der Host wieder erreichbar ist (jetzt ueber die Bridge)
  20. SSH-Verbindung zuruecksetzen
  21. UFW installiert?
  22. UFW - Verkehr innerhalb der Bridge (LAN <-> VMs) erlauben
  23. Storage-Pool-Verzeichnis anlegen
  24. default-Storage-Pool definieren, falls noch nicht vorhanden
  25. default-Storage-Pool starten + autostart aktivieren
  26. Pruefen, ob das Basis-Cloud-Image schon vorhanden ist
  27. Basis-Cloud-Image herunterladen (nur wenn es fehlt, bestehende Datei wird nie ersetzt)
  28. Pro VM aus libvirt_host_vms
  29. Pruefen, ob die VM-Domain bereits existiert
  30. Eigenstaendige Disk fuer die VM aus dem Basis-Image anlegen (ueberspringt, falls sie schon existiert)
  31. Disk auf die konfigurierte Groesse vergroessern
  32. Pruefen, ob die Disk einer bestehenden VM noch ein Backing-File hat
  33. Warnen, wenn die Disk einer bestehenden VM am Basis-Image haengt
  34. cloud-init user-data + meta-data + network-config rendern
  35. cloud-init Seed-ISO erzeugen
  36. cloud-init-Temp-Dateien aufraeumen
  37. VM-Domain per virt-install definieren + starten
  38. Warten, bis die VM per SSH erreichbar ist (erster Boot + cloud-init dauert etwas)

Handler

Templates


Fehlersuche

Allgemeines Vorgehen bei Rollen: ansible-playbook <playbook>.yml --limit <host> --tags <tag> --check --diff -vvv zeigt Änderungen ohne sie anzuwenden (make <ziel>-check bei den Playbooks mit Dry-Run). Die Rollenübersicht mit Make-Zielen: Rollen.

sudo systemctl status libvirtd libvirt-guests
virsh list --all; virsh net-list --all
ip -br link; ip -br addr; cat /etc/netplan/*.yaml
sudo journalctl -u libvirtd -n 100 --no-pager
Symptom Ursache Lösung
Playbook bricht ab: libvirt_host_bridge_interface (…) darf nicht die Bridge selbst sein Interface-Variable zeigt auf br0 libvirt_host_bridge_interface und libvirt_host_static_ip explizit in host_vars/<host>/vars.yml setzen
Playbook bricht ab: Interface "<name>" existiert auf <host> nicht falscher NIC-Name; die Bridge würde ohne Uplink angelegt und den Host vom LAN trennen mit ip -br link den richtigen Namen ermitteln
Host nach der Bridge-Umstellung nicht erreichbar Netplan-Wechsel (riskant, im Makefile als eigenes Ziel libvirt-bridge) Konsole am Gerät, sudo netplan try; Wartungsfenster und Rollback-Plan vorab
dnsmasq startet nicht (Port 53 belegt) libvirt-dnsmasq-Snippet kollidiert Die Rolle ersetzt das Paket-Snippet durch einen leeren Platzhalter, dnsmasq
VM startet nicht oder ist nicht erreichbar Basis-Image, cloud-init, Bridge virsh list --all, virsh console <vm>, 60010
VM nach Host-Neustart nicht oben libvirt-guests-Reihenfolge (nach dnsmasq und Tailscale) systemctl status libvirt-guests, Drop-in der Rolle

Allgemeine Fehlersuche: Host-Troubleshooting, zentrale Fehlersuche.

Alle Rollen