PKR-Lab

60020 - Ansible: Rollen — Hintergründe

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-ansible/6-hintergruende/60020-ansible-rollen.md

Ansible: Rollen — Hintergründe

Begründungen zu den Rollen unter capulus-ansible/roles/, geordnet nach Rolle. Hosts, VMs, Playbook-Reihenfolge und die Rolle
libvirt_host stehen in 60010. Die Rolle argocd steht in
60030. Bedienung der Geräte: 30010,
30020, 300e0.


Kiosk-Geräte

banana_pi_kiosk (Vereinsheim-Alarmmonitor)

Der Pi ist ein reines Display: Chromium zeigt die Redirect-URL des Clusters (argocd/apps/tech/alamos-apager), die
Heartbeat-/Alerting-Logik bleibt im Cluster. Chromium startet bewusst ohne --incognito, damit der einmalige manuelle
AMweb-Login (Passwort plus Verschlüsselungspasswort im Formular) Neustarts übersteht. Bildschirmschoner und Energiesparen sind aus.
Armbian/Debian hat keinen Imager-Schalter für Autologin, die Rolle bildet ihn mit getty-Drop-in, .bash_profile und startx nach.
Ein lokaler Failover-Supervisor schaltet bei Nichterreichbarkeit von alamos-apager auf eine vault-verschlüsselte Fallback-URL um.

Die frühere Raspberry-Pi-Rolle alamos_kiosk samt alarm-kiosks.yml ist entfernt (die Gruppe raspberry_pis war leer, der
Banana Pi hat sie ersetzt).

Stelle Begründung
Fallback-URL steht in /etc/banana-pi-kiosk/supervisor.env (0640, root:<kiosk-user>), nicht im Skript Das Skript liegt mit 0755 unter /usr/local/bin und wäre für jeden Nutzer lesbar. Der Supervisor läuft als Kiosk-User aus .xinitrc (kein systemd-Dienst), daher source statt EnvironmentFile. Der Task läuft mit no_log und diff: false.
Supervisor startet immer im Normalbetrieb Die erste Prüfung im Loop korrigiert das innerhalb von POLL_SECONDS × FAIL_THRESHOLD, falls der Cluster beim Boot des Pi schon nicht erreichbar ist.
Supervisor startet Chromium neu, wenn es abgestürzt ist Im aktuellen Modus, ohne auf die nächste Zustandsänderung zu warten.
Periodischer Neustart (REFRESH_SECONDS, 0 deaktiviert) Sicherheitsnetz gegen eine lautlos hängengebliebene In-Page-Live-Aktualisierung.
Heartbeat-Skript: Fehlschlag ohne Folgen Schlägt der Request fehl (Cluster/DNS kurz weg), passiert nichts weiter: Der lokale Supervisor kümmert sich unabhängig um die Browser-Umschaltung, der Timer steuert nur den zentralen ntfy-Ausfall-Alarm.
Täglicher Neustart startet nur die tty1-Session (getty → startx → X/openbox/Chromium), kein reboot Auf dem Banana Pi M2 Ultra (Armbian „Community Supported“) ist der Warm-Reset-Pfad unzuverlässig: Der Pi blieb nach einem echten Reboot einmal komplett aus und war nur per physischem Stromzyklus wieder erreichbar. Das Vereinsheim hängt nur per Tailscale dran, ohne LAN-Fallback. Der Session-Neustart räumt Chromium-Zustand und Speicher genauso auf, ohne das Kernel-/Firmware-Risiko.
Timer ohne Persistent=true Er soll nur zur geplanten Uhrzeit auslösen und nicht nachholen, falls der Pi da gerade aus war (sonst würde er direkt beim nächsten Hochfahren erneut neu starten).
make banana-pi-kiosks-restart-session Der Handler „getty@tty1 neu laden“ läuft nur bei Ansible-changed. Liegt das Skript schon korrekt auf der Platte (z. B. weil ein früherer Lauf es geschrieben hat, bevor der notify existierte), meldet der Task ok, und der längst laufende Prozess bleibt mit veralteten Werten (z. B. BASE_URL) im Speicher, weil er sich nicht selbst neu einliest. Das Target erzwingt den Neustart unabhängig von einem Playbook-Diff und braucht kein Vault-Passwort, da der Ad-hoc-Befehl keine verschlüsselten Variablen referenziert.
Screenshot-Skript nur manuell per SSH, kein Timer/Dienst (kein x11vnc, kein Cron) Nur für die Sichtprüfung (30020, „Sichtprüfung ohne physischen Zugriff“). Läuft als Kiosk-User (gleicher User wie die X-Session auf :0), daher kein XAUTHORITY-Handling.
Wake-on-LAN-Skript nur manuell per SSH Der Pi ist per Tailscale erreichbar (Semaphore und n8n haben keinen Pfad zu Tailscale-Peers), broadcastet das Magic Packet aber lokal. Das funktioniert nur, wenn Zielgerät und Pi im selben L2-Segment hängen (keine Client-/AP-Isolation im Router oder Repeater).
WoL-HTTP-Agent (banana-pi-wol-agent.py) direkt am Pi Dünner HTTP-Wrapper um banana-pi-wol.sh, damit die iOS-App ein Magic Packet ins Standort-LAN auslösen kann. Er spiegelt strukturell power-agent.py, ist aber sonst unabhängig: Der power-agent läuft im LAN des Homeservers und wird vom carplay-api-Pod gerufen, dieser hier läuft im reinen Tailscale-Netz des Pi und wird direkt von der App gerufen, weil der carplay-api-Pod keine Route zu Tailscale-Peers hat (40020). Er kennt keine MACs, Gültigkeit des Ziels und MAC-Lookup bleiben in banana-pi-wol.sh / banana_pi_kiosk_wol_devices, er reicht nur den Alias weiter. Er lauscht auf banana_pi_kiosk_wol_agent_bind_address: Im Standard 0.0.0.0, für den Alarmmonitor per host_vars auf seine Tailscale-Adresse (ansible_host), damit das Vereinsheim-LAN den Port nicht erreicht. Steht ansible_host auf einer LAN-Adresse (Ersteinrichtung), lauscht der Agent dort statt am Tailnet. Timeouts, Body-Grenze und systemd-Härtung wie beim power_agent. TLS schaltet banana_pi_kiosk_wol_agent_tls_enabled ein (Zertifikat und Schlüssel als Vault-Variablen, die Rolle legt sie mit 0600 ab, der Schlüssel mit no_log; fehlt eines, bricht ein assert ab). Der Agent aktiviert TLS nur, wenn TLS_CERT und TLS_KEY gesetzt sind, ohne diese Werte läuft er wie vorher mit HTTP, das ist der Rollback-Schalter. Mindestens TLS 1.2. Der Handshake läuft im Handler-Thread mit dem 10-Sekunden-Timeout und nicht im Accept-Loop, sonst könnte ein Client, der nur verbindet und nichts sendet, den ganzen Agent blockieren. Fehlgeschlagene Handshakes (Klartext-Client, Scanner) landen als eine Logzeile im Journal statt als Traceback. Das Zertifikat ist von Hand ausgestellt (365 Tage, Ablauf im Token-Register), weil cert-manager es nicht auf den Pi verteilen kann: d0040.

xibo_kiosk (Raspberry Pi 3 B+, Bilder-Slideshow)

Kein echter Xibo-Player, denn Xibo unterstützt den Raspberry Pi nicht offiziell (300e0).
Stattdessen holt der Pi die Bilder aus dem NFS-Ordner xibosignage-display in einen lokalen Cache, und Chromium zeigt sie im
Kiosk-Modus per file://. Ablauf und Betrieb: 300e8.


Energie und Schutz der Hardware

cluster_power_manager, cluster_power_manager_target und wake_on_lan

Control-Planes sind kein Ziel. cluster_power_manager_workers enthält nur Worker, die per WoL gesteuert werden dürfen (heute worker-1). controlplane-0 und controlplane-1 sind etcd-Mitglieder: Ein Poweroff nähme bei zwei Mitgliedern die API mit. Damit auch bereits verteilte Zugänge verschwinden, entfernt cluster_power_manager_target mit cluster_power_manager_target_enabled: false den Shutdown-Schlüssel und die sudoers-Freigabe (auf controlplane-1 gesetzt). Der Eintrag cluster-power-manager@homeserver im Schlüsselkommentar bleibt, er ist ein Name, kein Host.

nightly_worker_wake und worker_apt_update

power_agent

Privilegierter HTTP-Agent auf dem Homeserver-Host, nicht im Cluster. Er erledigt, was der carplay-api-Pod bewusst nicht darf:
Bildschirmhelligkeit (sysfs), manuelles Wake-on-LAN und Poweroff für worker-0/worker-1 sowie den eigenen Poweroff des Homeservers.

ollama_pc

Desktop-PC mit Ollama (300g0). Der PC ist kein Cluster-Knoten und nicht im Playbook site.yml, sondern in der Gruppe ollama_pcs mit eigenem Playbook ollama-pc.yml.

thermal_watchdog und resource_watchdog

Server nur mit Alarm. resource_watchdog_action (poweroff oder notify) unterscheidet Worker von den k3s-Servern. group_vars/k3s_servers.yml setzt notify: Bei 90 % CPU/RAM über 300 s kommt eine ntfy-Meldung (Priorität 5, höchstens einmal je resource_watchdog_alert_repeat_seconds), der Host bleibt in Betrieb. Der Homeserver hat zuvor selbst abgeschaltet, das hätte bei etcd ein Mitglied entfernt. Schutz vor echtem Ressourcendruck liefern auf den Servern die Kubelet-Reserven und die Eviction-Schwelle (k3s_kubelet_*) sowie thermal_watchdog bei Überhitzung.


Metriken, Logs und Zugang

vmagent, node_exporter und smartctl_exporter

Namensschema und Variablenvorrang

Der Inventar-Host und der k3s-Nodename sind getrennt: k3s_node_name (Standard inventory_hostname) speist node-name in der k3s-Config, die Vault-abhängige Variable hostname ist dafür nicht mehr zuständig. Ein k3s-Nodename lässt sich nicht ändern, eine Umbenennung wäre ein neuer Node mit verwaisten local-path-PVs. Deshalb setzt controlplane-0 weiter k3s_node_name: homeserver.

k3s_server_host und k3s_version des TECH-Clusters setzen group_vars/k3s_servers.yml und group_vars/k3s_agents.yml, beide aus k3s_cluster_server_host und k3s_cluster_version in group_vars/all.yml (eine Quelle). Eine Elterngruppe k3s_cluster wäre naheliegender, die statischen Inventories in Semaphore kennen sie aber nicht; dort fiele k3s_version auf den Leerwert aus all zurück und k3s würde auf den neuesten Stand des Kanals gehoben. PROD und ENTW behalten den Leerwert aus all. Details: 60010.

k3s_agent: Host-Firewall

k3s_agent_ufw_enable (Standard false, auf worker-1 true) schaltet UFW auf einem Worker scharf: Vollzugriff nur für k3s_agent_ufw_trusted_hosts (controlplane-0, controlplane-1), SSH aus dem LAN, Tailscale 41641/udp, Flannel aus dem LAN, Pod- und Service-Netz, default deny. Mit k3s_agent_ufw_vm_bridge: br0 kommt ufw route allow in on br0 out on br0 dazu: worker-1 betreibt die ENTW-VM über die Bridge, und weil net.bridge.bridge-nf-call-iptables=1 gesetzt ist, läuft deren Verkehr durch die iptables-FORWARD-Kette; ohne diese Regel (deny routed) wäre die VM vom LAN getrennt. Ohne den Schalter legt die Rolle nur die Regeln an, aktiviert aber UFW nie; bis zum 2026-10-18 stand worker-1 deshalb mit „inactive“ da, obwohl die Regeln vorgemerkt waren und ufw laut systemd active meldete. Vor dem Einschalten auf einem Worker: Backup von /etc/ufw, Rollback-Timer (systemd-run --on-active=15min ufw disable), danach zweite SSH-Session und Prüfung von Node-Status, Exportern und (worker-1) der ENTW-VM. Tailscale-Verkehr läuft über ts-input vor UFW und ist von den Regeln nicht betroffen. Auf worker-0 (ohne VM-Bridge, aber mit Docker-Containern) ist der Schalter ebenfalls an; die Rolle entfernt dort die älteren offenen Regeln (LAN mit Vollzugriff, SSH von überall, kubelet aus dem LAN). Dockers veröffentlichte Ports (3002, 3003, 8001, 18080) laufen über Dockers eigene NAT-/FORWARD-Regeln und sind von den UFW-Eingangsregeln unabhängig.

journal_upload

semaphore_bootstrap, semaphore_secrets und semaphore_targets

wireguard_backup

Kernel-WireGuard über wg-quick, unabhängig von Tailscale (Userspace tailscale0 samt Tailscales Koordinations- und
DERP-Servern). Er dient nur als Notzugang, falls die Tailscale-Control-Plane ausfällt (c0011).


Alarmierung

alert_caller

Telefon-Alarm für eine externe VM (noch nicht ausgerollt, heute läuft der Caller als Pod, siehe 60040): systemd-Dienst alert-caller (Python, nur Standardbibliothek), der Alertmanager-Webhooks in einen Anruf per SIP verwandelt. caller.py liegt
im Chart argocd/apps/tech/alert-caller/src/ und wird von der Rolle von dort kopiert (eine Quelle für beide Betriebsarten). Playbook capulus-ansible/alert-caller.yml, Inventar-Gruppe alert_callers, Make-Targets alert-caller und alert-caller-check.
Bedienung, Einrichtung und Testplan: 10020. Routing und Regeln: 60060.

Sonstiges

k3s: embedded etcd

Planung und Runbook: 400a0.

k3s: Modus der Kubeconfig

k3s: Templates k3s-config.yaml.j2 und audit-policy.yaml.j2

cups_print_server

Macht einen USB-Drucker am Homeserver per CUPS im Heimnetz und Tailnet verfügbar (IPP/AirPrint für Handys und Tablets, IPP für Windows/Linux, Anleitung in
20040). Der Name der Druckerwarteschlange erscheint in CUPS-/IPP-URLs und darf deshalb keine Leerzeichen oder
Sonderzeichen enthalten. Der QPDL-Community-Treiber für die Samsung-Serie M2020/M2026 ist optional und wird gebaut. Die Warteschlange wird erst angelegt, sobald Device-URI und PPD
bekannt sind, dafür gibt es Debug-Tasks, die beides ermitteln.

crowdsec

Die Reihenfolge ist zwingend (d0020): Zuerst wird CrowdSec (LAPI und Agent) installiert, den Firewall-Bouncer installiert die Rolle erst danach, wenn
CrowdSec läuft. LAN und Tailscale stehen auf der Whitelist, damit sich niemand selbst aussperrt.

libvirt_host: Bridge-Netplan

Die übrigen Hintergründe zur Rolle stehen in 60010.

Installer und Prüfsummen (Incident 017)

Frühere Fassungen der Rollen luden Skripte und Archive ohne Prüfsumme und starteten sie als root: get.k3s.io, get-helm-3 vom Branch main, install.crowdsec.net, den vmutils-Tarball und das Cloud-Image.
Ein Kompromiss der Auslieferung hätte Codeausführung auf den Control-Plane- und Worker-Hosts bedeutet. Die Änderungen wirken erst beim nächsten Lauf der jeweiligen Rolle, bestehende Installationen bleiben unberührt.

Quelle Rolle Schutz Wo gepflegt Erneuern
k3s-Installer (Server und Agent) k3s, k3s_agent URL auf einen Commit von k3s-io/k3s plus checksum: k3s_installer_url, k3s_installer_sha256 in group_vars/all.yml (gemeinsam für beide Rollen) gh api 'repos/k3s-io/k3s/commits?path=install.sh&per_page=1' --jq '.[0].sha', dann curl -sL https://raw.githubusercontent.com/k3s-io/k3s/<sha>/install.sh \| sha256sum
Helm 3 k3s Tarball von get.helm.sh, Prüfsumme live aus <Tarball>.sha256sum k3s_helm_release in roles/k3s/defaults/main.yml, Renovate öffnet den PR nur die Version ändern (Renovate oder von Hand)
vmutils-Tarball vmagent checksum: je Architektur vmagent_sha256 in roles/vmagent/defaults/main.yml bei einer neuen vmagent_version: Tarball laden, sha256sum bilden und eintragen
Ollama-Installationsskript ollama_pc Release-Tag plus checksum: ollama_pc_version, ollama_pc_install_script_sha256 in roles/ollama_pc/defaults/main.yml curl -sL https://raw.githubusercontent.com/ollama/ollama/v<version>/scripts/install.sh \| sha256sum
Ubuntu-Cloud-Image libvirt_host datiertes Verzeichnis release-<Datum> plus checksum: libvirt_host_base_image_url, libvirt_host_base_image_sha256 in roles/libvirt_host/defaults/main.yml Hash steht in https://cloud-images.ubuntu.com/releases/resolute/release-<Datum>/SHA256SUMS
Tailscale-APT-Schlüssel tailscale Fingerprint wird bei jedem Lauf geprüft tailscale_signing_key_fingerprint in roles/tailscale/defaults/main.yml gpg --show-keys --with-colons --fingerprint <Datei> (Zeile fpr)
CrowdSec-APT-Schlüssel crowdsec Schlüssel von packagecloud.io, Fingerprint wird bei jedem Lauf geprüft, Repository ohne Installationsskript crowdsec_repo_key_fingerprint in roles/crowdsec/defaults/main.yml wie Tailscale

common: ArgoCD-NodePort in UFW

ArgoCD hat keinen NodePort mehr (argocd_server_nodeport_enabled: false, siehe 60030). Die Rolle common löscht deshalb die früheren
UFW-Freigaben für 30080 (LAN, Tailnet, WireGuard-Notzugang) und 30443. Die Regeln hatten auch vorher nichts begrenzt, weil NodePort-Verkehr an UFW vorbeiläuft
(c0030).

ssh_hardening

Härtung aus dem Host-Audit vom 2026-11-14

vaultwarden_restore

Die Rolle stellt db.sqlite3, rsa_key.pem, Attachments und Sends aus der vaultwarden-backup-PVC (nachts vom Backup-CronJob auf
der NAS gefüllt) auf die vaultwarden-data-PVC zurück (300a0, 20010).

libvirt_host: Prüfungen im Dry-Run

Im Check-Mode führt ansible.builtin.command nichts aus, meldet aber rc: 0 mit leerer Ausgabe. virsh dominfo galt damit für jede VM als erfolgreich, und from_json auf der leeren Ausgabe von qemu-img info ließ make check abbrechen. Beide Befehle sind rein lesend und laufen deshalb mit check_mode: false; die Warnung zum Backing-File prüft zusätzlich, ob die Ausgabe leer ist. Allgemein gilt: Lesende command-Tasks, deren Ergebnis spätere Bedingungen steuern, brauchen check_mode: false, sonst bewertet der Dry-Run einen erfundenen Erfolg.

Review-Befunde vom 2026-11-15

tailscale: Wiederholungen beim Paket-Server

pkgs.tailscale.com (CloudFront) setzt Verbindungen zeitweise zurück (Connection reset by peer, Lese-Timeout), über IPv4 wie IPv6, vom Homeserver wie vom Arbeitsrechner. Auch bei vorhandenem Schlüssel fragt get_url mit force: false den Server jedes Mal an, ob sich die Datei geändert hat, ein einzelner Abbruch ließ so ganze make check-Läufe scheitern. Schlüssel-Download, APT-Repository und Paketinstallation wiederholen deshalb bis zu fünfmal im Abstand von zehn Sekunden (retries/until … is succeeded). Die Prüfung des Schlüssel-Fingerprints danach bleibt unverändert.

Konventionen der Linter-Konfiguration

Begründungen zu .ansible-lint und .yamllint stehen in 600a0.