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
- QEMU/KVM + libvirt-Pakete installieren
- Konfliktenden dnsmasq-Snippet von libvirt-daemon-system entschaerfen
- Pruefen, ob der Snippet existiert
- Symlink auf das Paket-Original entfernen
- Leeren Platzhalter anlegen (blockt die Neuanlage des Symlinks durch Upgrades)
- Handler sofort ausfuehren (System-dnsmasq moeglichst schnell wieder hochbringen)
- libvirtd aktivieren und starten
- libvirt-guests - Verhalten beim Host-Shutdown und -Boot festlegen
- libvirt-guests - Start nach dnsmasq und Tailscale ordnen (systemd-Drop-in)
- Drop-in-Verzeichnis anlegen
- Drop-in schreiben
- Bridge-Netzwerk einrichten (nur wenn explizit aktiviert)
- Sicherstellen, dass die Bridge-Parameter plausibel sind
- Sicherstellen, dass die physische NIC auf dem Host existiert
- Vorhandene Netplan-Configs finden
- Alte Netplan-Configs entfernen
- Bridge-Netplan-Konfiguration deployen
- Netplan anwenden (Verbindung kann kurz abreissen)
- Warten, bis der Host wieder erreichbar ist (jetzt ueber die Bridge)
- SSH-Verbindung zuruecksetzen
- UFW installiert?
- UFW - Verkehr innerhalb der Bridge (LAN <-> VMs) erlauben
- Storage-Pool-Verzeichnis anlegen
- default-Storage-Pool definieren, falls noch nicht vorhanden
- default-Storage-Pool starten + autostart aktivieren
- Pruefen, ob das Basis-Cloud-Image schon vorhanden ist
- Basis-Cloud-Image herunterladen (nur wenn es fehlt, bestehende Datei wird nie ersetzt)
- Pro VM aus libvirt_host_vms
- Pruefen, ob die VM-Domain bereits existiert
- Eigenstaendige Disk fuer die VM aus dem Basis-Image anlegen (ueberspringt, falls sie schon existiert)
- Disk auf die konfigurierte Groesse vergroessern
- Pruefen, ob die Disk einer bestehenden VM noch ein Backing-File hat
- Warnen, wenn die Disk einer bestehenden VM am Basis-Image haengt
- cloud-init user-data + meta-data + network-config rendern
- cloud-init Seed-ISO erzeugen
- cloud-init-Temp-Dateien aufraeumen
- VM-Domain per virt-install definieren + starten
- Warten, bis die VM per SSH erreichbar ist (erster Boot + cloud-init dauert etwas)
Handler
- system-dnsmasq nach snippet-entschärfung neu starten
- systemd nach libvirt-guests-drop-in neu laden
Templates
bridge-netplan.yaml.j2cloud-init-meta-data.yaml.j2cloud-init-network-config.yaml.j2cloud-init-user-data.yaml.j2
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.