PKR-Lab

60010 - Ansible: Hosts, VMs und Playbooks — Hintergründe

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/6-hintergruende/60010-ansible-hosts-und-playbooks.md

Ansible: Hosts, VMs und Playbooks — Hintergründe

Begründungen zu capulus-ansible/host_vars/, capulus-ansible/group_vars/, capulus-ansible/inventory/, den Playbooks in ansible/
und zur Rolle libvirt_host. Was läuft und wie man es bedient, steht in
a0030 und 40080;
zum Vorfall mit dem Basis-Image siehe 50010.
Übersicht dieser Kategorie: 60000.


ansible.cfg: Host-Keys, Fact-Cache


Inventar

Aufbau von capulus-ansible/inventory/hosts.yml:

Stelle Begründung
controlplane-0 und controlplane-1 sind Mitglieder von semaphore_targets Semaphore kann so dieses Repo auch gegen die Control-Planes selbst ausrollen (rekursives Template „Deploy Home Server“, b0030). Alle Mitglieder von semaphore_targets bekommen den öffentlichen Semaphore-SSH-Schlüssel in authorized_keys, damit die UI Playbooks gegen sie ausführen kann.
ugreen_nas steht nur zur Dokumentation im Inventar Das UGREEN NAS (RAID1, NFS-Export für die nas-StorageClass, 20000) läuft mit der eigenen Firmware UGOS. Es läuft kein Playbook dagegen, RAID und NFS werden von Hand über die Web-UI eingerichtet. Der Eintrag dient als Referenz (DNS, spätere Backup-Rolle auf einer extern angeschlossenen Platte).
entw und prod Eigenständige k3s-Server in KVM-VMs (ENTW auf worker-1, PROD auf dem Homeserver). Die Hintergründe stehen unten bei ENTW und PROD, die Planung in 40080 (Baustein 5).
ansible_user: pela bei infotafel und vereinsheim-alarmmonitor So heißt der Benutzer auf diesen Geräten, die Raspberry-Pi-OS-Konvention pi gilt hier nicht. xibo_kiosk_user: pela überschreibt deshalb den Rollen-Default pi. Für andere Benutzer als pi legt Raspberry Pi OS keinen NOPASSWD-Sudoers-Eintrag an, das Fehlerbild steht in 300e0.
ansible_host von vereinsheim-alarmmonitor ist die Tailscale-IP Das Gerät wurde vorzeitig auf Phase 2 umgestellt, weil der LAN-Pfad zum Pi defekt war. Die Re-Provisionierung geht deshalb nur noch per make banana-pi-kiosks aus dem Tailnet, nicht über die Semaphore-UI (30020).

Namensschema: Inventar-Host, Gruppen und k3s-Nodename

Planung und Entscheidungen: 400a0.

Begriff Wert Begründung
Inventar-Hosts im TECH-Cluster controlplane-0 (.94), controlplane-1 (.95), worker-1 (.96) Kubernetes und Linux erlauben keine Großbuchstaben, in Docs und Anzeigen steht „ControlPlane-0/1/2“
Gruppen k3s_servers (alle Server), k3s_primary (nur controlplane-0), k3s_agents (nur worker-1) k3s_primary ersetzt homeservers überall dort, wo genau ein Host gemeint ist (site.yml, Delegationen, Uncordon-Plays)
k3s-Nodename Variable k3s_node_name, Standard inventory_hostname; controlplane-0 setzt homeserver Ein k3s-Nodename lässt sich nicht ändern. Eine Umbenennung wäre ein neuer Node, local-path-PVs und Chart-nodeSelector zeigen auf den alten Namen. Die Entscheidung dazu steht im Planungsdoc (AP6)
k3s_server_host controlplane-0, gesetzt in group_vars/k3s_servers.yml und group_vars/k3s_agents.yml Der Wert im Vault (group_vars/all.yml) nennt noch den alten Hostnamen. Gruppenvariablen einer Kindgruppe schlagen die von all, so braucht es keine Vault-Änderung
Semaphore-Projekt für ControlPlane-1 heißt vorerst weiter worker-0 (Template Deploy worker-0) nightly_worker_wake sucht Projekt und Template nach dem Namen des Workers. Die Umbenennung folgt, wenn ControlPlane-1 aus dem nächtlichen Zyklus genommen wird
DNS dnsmasq löst controlplane-0, controlplane-1 auf; homeserver und worker-0 bleiben als Übergangs-Alias Das Alias homeserver deckt auch alle Subdomains *.homeserver ab und bleibt dauerhaft. Der Alias worker-0 kann entfallen, wenn nichts mehr den alten Namen nutzt

Nicht umbenannt werden die DNS-Zonen und Tiers *.homeserver, die Root-CA homeserver-root-ca, die Cloudflare-Tunnelnamen, die CRD-Gruppe capulus.homeserver, das Metrik-Label clusterLabel: homeserver sowie Repo- und App-Namen.

ENTW-Cluster (entw-vm)

Entscheidung Begründung
Eigenständiger k3s-Server, kein Beitritt zu TECH, eigene ArgoCD-Instanz auf dem Branch entw Die ENTW-Instanz kennt keinen anderen Cluster. TECH und PROD lesen main und dort nur argocd/apps/tech/* bzw. argocd/apps/prod/*.
Ein ApplicationSet home-server-apps-entw, Projekt entw erlaubt jeden Namespace Jeder neue Ordner unter argocd/apps/entw/ wird ohne weitere Freigabe deployt. Das ist gewollt, die VM ist eine Trainingsumgebung.
Kein Tailscale, kein CrowdSec, keine Watchdogs Die VM ist absichtlich verwundbar (Trainings-/Pentest-Umgebung) und soll keinen Tailscale-Schlüssel tragen (Entscheidung 2026-09-18).
Erreichbarkeit über den Subnet-Router homeserver (192.168.178.0/24) Die Tailscale-ACL lässt sich auf das Ziel 192.168.178.100 beschränken.
Kein Audit-Log, kein RAM-Schutz Wegwerf-Cluster mit 12 GiB. Das Tuning des Hauptclusters (system-reserved 1Gi usw.) passt nicht.
VM mit 3 vCPU / 12 GiB RAM / 20 GiB Disk worker-1 hat 4 vCPU und rund 15 GiB RAM. Der Rest bleibt für Host-OS und Hypervisor-Overhead (Sizing-Begründung der PROD-VM: Baustein 5 in 40080). Zur Disk siehe worker-1: Speicher.
argocd_platform_apps / argocd_workloads_apps in host_vars/entw-vm steuern nur noch security-tier-Label und Tier-NetworkPolicy der dort gelisteten Namespaces (Bestand) Neue Apps bekommen keine Policy (Trainingsumgebung). Was deployt wird, entscheidet allein der Ordner argocd/apps/entw/.

Die statische IP setzt cloud-init (Rolle libvirt_host), deshalb steht in host_vars network_configure_static_ip: false.

PROD-Cluster (prod-vm)

DNS von PROD-VM und Homeserver

Stelle Begründung
dns: der prod-vm zeigt nur auf network_static_ip (dnsmasq des Homeservers) dnsmasq löst *.homeserver (tech/prod/dev) auf und leitet den Rest an Pi-hole. Mit 1.1.1.1 als Zweitserver würde CoreDNS in PROD zufällig gegen einen Resolver fragen, der *.homeserver nicht kennt. Abhängigkeit: Fällt dnsmasq oder Pi-hole aus, verliert die PROD-VM ihr DNS.
dnsmasq leitet an Pi-hole (NodePort), Pi-hole an die Fritz!Box Jedes Gerät, das dnsmasq als DNS nutzt, bekommt automatisch Werbeblocking, ohne Router-Konfiguration.
*.dev.homeserver → ENTW-VM; einzeln umgezogene PROD-Hosts (dnsmasq_prod_vm_hosts) → PROD-VM Die spezifischere Domain bzw. der exakte Host gewinnt gegenüber address=/homeserver/. Alle anderen *.prod.homeserver-Namen bleiben bis zu ihrem Umzug auf dem Hauptcluster (.94).
Rolle dnsmasq: Neustart bei Fehlern, ohne Start-Limit Das Debian-Unit hat kein Restart=. Stürzt dnsmasq beim Start ab (Konflikt bind-interfaces/bind-dynamic durch den libvirt-Snippet, Vorfälle 2026-09-18 und 2026-09-24), bleibt er bis zum nächsten Eingriff tot, und damit das DNS des ganzen LANs und der PROD-VM. Ohne Start-Limit, sonst gibt systemd nach fünf Versuchen auf.
Handler-Reihenfolge in dnsmasq/handlers Handler laufen in der Reihenfolge der Datei: erst systemd neu laden (Drop-ins), dann dnsmasq neu starten, damit der Neustart die neuen Unit-Einstellungen bekommt.

Rolle libvirt_host

Grundentscheidungen

Bridge-Umbau (Tag libvirt-bridge, hohes Risiko)

Der Umbau baut die physische NIC in die Linux-Bridge br0 ein und verschiebt die Host-IP darauf. Ein Fehler trennt den Host
vom Netz. Für den Homeserver (einziges Interface, keine Out-of-Band-Konsole, 24/7-Single-Point-of-Failure) ist das hochriskant,
für worker-1 weniger. Deshalb:

Regel Grund
Eigener Tag libvirt-bridge, nie Teil eines generischen make install Der Task darf nicht versehentlich mitlaufen. Nur mit Wartungsfenster und Rollback-Plan ausführen.
Bridge-Parameter (libvirt_host_bridge_interface, libvirt_host_static_ip) explizit in host_vars pinnen Nach einem Teil-Setup liefern die Default-Route-Facts br0 bzw. die DHCP-Adresse (.67 auf worker-1). Die Bridge würde sich dann selbst enslaven bzw. die falsche IP bekommen (Vorfall worker-1, 2026-09-19).
Die Rolle prüft, dass die NIC existiert, bevor eine Netplan-Datei angefasst wird Der Homeserver-NIC hieß eno1, heißt seit dem Boot vom 2026-09-11 aber enp4s0 (Kernel/initramfs vergibt den Namen neu, mit ip -br link prüfen). Ein falscher Name legte am 2026-09-20 die Bridge ohne Uplink an und trennte den Homeserver vom LAN.
Abbruch vor dem Löschen alter Netplan-Configs, wenn die Facts schon auf br0 zeigen Nach einem Teil-Setup würde sich die Bridge sonst selbst enslaven.
SSH-ControlMaster-Verbindung nach netplan apply zurücksetzen Die gecachte Verbindung ist danach tot und würde minutenlang hängen.
UFW-Regel für geroutete Pakete Mit geladenem br_netfilter (k3s/Flannel) laufen Bridge-Pakete durch iptables, und UFW verwirft geroutete Pakete standardmäßig (deny (routed)). Das LAN erreichte die VM dann nur per ICMP, TCP lief ins Timeout (Vorfall prod-vm, 2026-09-19).
disable_eee_interface auf die physische NIC setzen (libvirt_host_bridge_interface) Die Rollen-Default (ansible_default_ipv4.interface) liefert nach dem Umbau br0, dort scheitert ethtool --set-eee (Vorfall 2026-09-20). EEE gibt es nur an der physischen NIC.

dnsmasq-Snippet von libvirt-daemon-system

libvirt-daemon-system legt /etc/dnsmasq.d/libvirt-daemon mit bind-interfaces an. Das kollidiert mit dem bewusst auf
bind-dynamic gestellten System-dnsmasq („cannot set --bind-interfaces and --bind-dynamic“). Am 2026-09-18 legte das den
System-dnsmasq des Homeservers komplett lahm, also echter DNS-Ausfall für das ganze LAN. Libvirts eigener dnsmasq für virbr0
braucht den Snippet nicht, der Ausschluss von virbr0 passiert bei bind-dynamic implizit über die vorhandene
interface=/listen-address-Allowlist.

Basis-Image und VM-Disks

worker-1: Speicher

Die ENTW-VM bekommt dauerhaft 20 GiB: Die Root-Partition von worker-1 hat nur 31 GiB frei (57 GiB gesamt, df -h vom
2026-09-18). Eine zweite, 465 GiB große Platte (/dev/sda) wurde geprüft und verworfen: Beim Formatieren traten wiederholt
„Input/output error“ und hostbyte=DID_BAD_TARGET im Kernel-Log auf (Bus-/Verbindungsebene, smartctl kann die Platte nicht
einmal auslesen) — zu unzuverlässig für VM-Storage.


Worker-Nodes und ihre Playbooks

worker-0: DNS und Tailscale

Reihenfolge in controlplane-1.yml / worker-1.yml

Seit der NAS-gestützten nas-StorageClass sind beide Worker reine k3s-Compute-Nodes. Die frühere HDD-Rolle (sda) und die
Docker-Compose-Dienste (Paperless-ngx, TinyTeller) sind entfallen, beide laufen als ArgoCD-App. Die Reihenfolge ist zwingend:

Schritt Rolle Warum an dieser Stelle
1 worker_apt_update Sonst bekommt der Node nie ein OS-Update (keine common-Rolle). Setzt bei Bedarf Fallback-DNS und muss deshalb vor tailscale laufen, das für die eigene Paketinstallation funktionierendes DNS braucht. Läuft normalerweise nachts um 01:00 über nightly_worker_wake.
2 tailscale Ansible-verwaltet (Vorfall worker-0, siehe oben), mit eigenem, vault-verschlüsseltem tailscale_auth_key.
3 k3s_agent Braucht einen laufenden k3s-Server auf dem Homeserver (.94).
4 disable_eee Vorfall 2026-09-02 auf dem Homeserver: EEE verursachte einen Link-Drop ohne Selbstheilung.
5 thermal_watchdog, resource_watchdog Automatischer Shutdown bei Übertemperatur bzw. anhaltend hoher CPU/RAM-Last.
6 journal_upload Der DaemonSet victoria-logs-collector liest nur Container-Logs, nicht das journald des Nodes.
6b smartctl_exporter S.M.A.R.T.-Werte für Grafana.
7 wake_on_lan Damit cluster_power_manager den Node aus dem ausgeschalteten Zustand wecken kann.
8 cluster_power_manager_target Autorisiert den auf dem Homeserver erzeugten Shutdown-Key, beschränkt auf poweroff. Setzt voraus, dass site.yml schon gegen den Homeserver gelaufen ist, sonst existiert der Public Key dort noch nicht.
9 Uncordon Stellt sicher, dass der Node schedulbar bleibt (macht kubectl drain/cordon aus Wartungsschritten rückgängig).
10 (nur worker-1) libvirt_host ENTW-VM. Wird über host_vars/worker-1 aktiviert (seit 2026-09-18) und erbt nicht automatisch den globalen Schalter.

In site.yml muss cluster_power_manager vor den Worker-Playbooks laufen (er erzeugt das SSH-Schlüsselpaar für den
Shutdown). semaphore_targets verteilt danach den Semaphore-SSH-Key auf alle Ziele (wird übersprungen, wenn im Inventar keine Ziele
stehen), und semaphore_bootstrap legt anschließend Projekte, Keys, Repositories, Inventories und Templates über die REST-API an,
damit die UI ohne Klicks benutzbar ist.

Firewall (UFW, Rolle common)

Die Rolle common setzt die Regeln, die Variablen stehen in capulus-ansible/roles/common/defaults/main.yml. Der homeserver überschreibt sie in host_vars/homeserver/vars.yml, alle anderen Hosts behalten die
bisherigen Defaults (pauschale Freigabe für LAN und Tailnet, 6443 nur aus dem LAN).

Variable Bedeutung homeserver
common_ufw_lan_allow_all pauschale Regel „alles aus dem LAN“ false
common_ufw_tailnet_allow_all pauschale Regel „alles aus 100.64.0.0/10“ false
common_ufw_k3s_api_sources Quellen für 6443 LAN, Tailnet, 10.99.99.0/24 (WireGuard-Notzugang)
common_ufw_trusted_hosts Hosts mit Vollzugriff (nur wenn die LAN-Pauschale aus ist) worker-0, worker-1, NAS, prod-vm, entw-vm
common_ufw_lan_services Ports, die das restliche LAN erreichen darf CUPS 631, SANE 6566

Zugang und Notfallzugang