PKR-Lab

Ansible-Rollen

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

Ansible-Rollen

Übersicht aller Rollen von capulus-ansible. Je Rolle gibt es eine Seite mit Variablen, Ablauf, Handlern, Templates und Dateien. Die Seiten werden aus defaults/main.yml und tasks/ erzeugt und beschreiben den Stand des Repos.

Rolle Läuft gegen Zweck
alert_caller externe VM alert-caller-vm, Vereinsheim-Pi Telefon-Alarm: Webhook-Server, Piper-Ansage, baresip-Anruf
argocd controlplane-0 (Hub), entw-vm ArgoCD per Helm, Bootstrap-ApplicationSet und -Projects, Namespace-Labels, NetworkPolicies
banana_pi_kiosk Banana Pi Chromium-Kiosk, Heartbeat-Timer und WoL-Agent
cluster_power_manager controlplane-0 weckt Worker per WoL, fährt sie per SSH wieder herunter
cluster_power_manager_target controlplane-1, worker-1 autorisiert den Shutdown-Schlüssel, beschränkt auf poweroff
common controlplane-0, prod-vm, entw-vm Basis-OS, UFW, Pakete, sysctl, chrony, Swap aus, optional statische IP
crowdsec controlplane-0 Brute-Force-Schutz für SSH und Traefik-Logs
cups_print_server controlplane-0 Druckserver, QPDL-Treiber-Build, zweite Warteschlange
disable_eee controlplane-0, controlplane-1, worker-1 Energy Efficient Ethernet dauerhaft deaktivieren (Realtek-NIC-Link-Drops)
homeserver_ca Banana Pi, alle Hosts mit journal_upload über HTTPS legt die Homeserver-Root-CA in den System-Vertrauensspeicher
dnsmasq controlplane-0 Split-DNS *.homeserver (inkl. *.dev.homeserver → ENTW und PROD-Einzelhosts), Weiterleitung an Pi-hole
journal_upload alle Ansible-Hosts journald → VictoriaLogs
k3s controlplane-0, prod-vm, entw-vm Kubernetes-Server und Helm, je Cluster eigene CIDRs
k3s_agent worker-1 (Voraussetzungen und Firewall auch für controlplane-1) Cluster-Beitritt (TECH) per Join-Token vom Control-Plane
k3s_reboot_guard controlplane-0, controlplane-1 gibt Neustarts und Upgrades der k3s-Server nur bei gesundem Peer und etcd frei
libvirt_host controlplane-0, worker-1 KVM/libvirt, Bridge br0, legt prod-vm bzw. entw-vm an
nightly_worker_wake controlplane-0 01:00-Timer: Worker wecken, Update anstoßen, wieder herunterfahren
node_exporter prod-vm, entw-vm, Banana Pi, Kiosks Host-Metriken für Nicht-k3s-Hosts bzw. VMs
ntfy_publisher alle Knoten und Kiosks Meldungen der Watchdogs und Host-Skripte per HTTPS an ntfy, mit Root-CA und Publisher-Token
ollama_pc ollama-pc Ollama auf dem Desktop-PC: Installation, systemd-Override, WoL über NetworkManager, Resume-Hook, GPU-Dienste, UFW
infotafel_poweroff Infotafel (xibo_displays) Erlaubt n8n, den Pi per SSH (forced command) herunterzufahren
power_agent controlplane-0 HTTP-API für Helligkeit, Wake und Shutdown aus der iOS-App
resource_watchdog alle Knoten und Kiosks Selbst-Abschaltung bei Dauerlast
restic_backup ollama-pc Tägliches Restic-Backup des Home-Verzeichnisses mit Aufbewahrung und Integritätsprüfung (aus, bis aktiviert)
semaphore_bootstrap controlplane-0 Projekte, Inventories, Templates und Zeitpläne in Semaphore per REST-API
semaphore_secrets controlplane-0 Bootstrap-Secret für den Semaphore-Pod
semaphore_targets alle verwalteten Hosts SSH-Pubkey von Semaphore in authorized_keys
smartctl_exporter controlplane-0, controlplane-1, worker-1 S.M.A.R.T.-Werte der physischen Platten
ssh_hardening alle verwalteten Hosts Schlüsselbasierter SSH-Zugang (Passwort-Login aus)
tailscale controlplane-0, controlplane-1, worker-1, xibosignage-Displays, Banana Pi, alert-caller-VM WireGuard-Mesh-VPN, Auth-Key aus Ansible Vault; nur der homeserver ist Subnet-Router
thermal_watchdog alle Knoten und Kiosks Selbst-Abschaltung bei Übertemperatur
vaultwarden_restore controlplane-0 Wiederherstellung der Vaultwarden-Daten aus dem NAS-Backup
vmagent Tailscale-only-Hosts (Banana Pi) Metriken-Push per remote-write
wake_on_lan controlplane-1, worker-1 ethtool wol g bei jedem Boot
wireguard_backup controlplane-0 Notfall-Tunnel, falls die Tailscale-Control-Plane ausfällt
worker_apt_update controlplane-1, worker-1 apt-Update der Worker (haben keine common-Rolle)
xibo_kiosk xibosignage-Displays Sync-Timer mit lokalem Bilder-Cache, Chromium-Slideshow-Kiosk in eigener X11-Sitzung

Hintergründe und Fallstricke: 60020 Ansible-Rollen.


Fehlersuche je Rolle

Jede Rollenseite hat am Ende einen Abschnitt „Fehlersuche“ mit den Diagnosebefehlen (Dienst, Log, Konfiguration), den Fehlermeldungen aus den assert- und fail-Aufgaben der Rolle und typischen Symptomen. Das übergeordnete Kapitel ist die zentrale Fehlersuche, die Host-Probleme der Erstinstallation stehen im Troubleshooting.

Allgemeines Vorgehen

cd capulus-ansible
make ping                                   # erreicht Ansible den Host?
make <ziel>-check                           # Dry-Run (zum Beispiel controlplane-1-check, prod-check, entw-check)
ansible-playbook <playbook>.yml --limit <host> --tags <tag> --check --diff -vvv
ansible-playbook <playbook>.yml --limit <host> --start-at-task "<Aufgabenname>"
make lint                                   # yamllint und ansible-lint
Schritt Prüfung
1 Fehlermeldung der Aufgabe lesen: Bei assert/fail steht die Ursache im Text (Tabellen auf den Rollenseiten)
2 Variablen: ansible-inventory --host <host> --yaml zeigt die wirksamen Werte inklusive group_vars und host_vars (verschlüsselte Werte bleiben verschlüsselt)
3 Vault: ansible-vault view group_vars/all.yml (Passwort nötig). Fehlt es, scheitern Aufgaben mit verschlüsselten Variablen
4 Verbindung: ssh <host>, host_key_checking = True meldet geänderte Host-Schlüssel
5 Auf dem Host: systemctl status <dienst>, journalctl -u <dienst> (Dienste je Rolle siehe unten)
6 Fakten-Cache zurücksetzen, wenn alte Werte stören: rm -rf ~/.cache/ansible-facts (Cache 1 Stunde)

Rollen, Make-Ziele und Dienste

Rolle Make-Ziel (in capulus-ansible) Dienst oder Prüfpunkt
common make common ufw, chrony, unattended-upgrades
ssh_hardening make ssh-hardening sshd -t, /etc/ssh/sshd_config.d/
tailscale make tailscale tailscaled
dnsmasq make dnsmasq dnsmasq
crowdsec make crowdsec crowdsec, crowdsec-firewall-bouncer
k3s make k3s, make prod, make entw k3s
k3s_agent make k3s-agent, make worker-1 k3s-agent
argocd make argocd, make render-bootstrap CORE_DIR=… Namespace argocd
libvirt_host make libvirt-host, make worker-1-libvirt-host, make libvirt-bridge (riskant) libvirtd, libvirt-guests
semaphore_secrets, semaphore_targets, semaphore_bootstrap make semaphore, make semaphore-targets, make semaphore-bootstrap Namespace semaphore
cluster_power_manager, cluster_power_manager_target make cluster-power-manager, make controlplane-1/worker-1 cluster-power-manager
nightly_worker_wake, worker_apt_update make nightly-worker-wake, make worker-apt-update nightly-worker-wake.timer
power_agent make power-agent power-agent
wake_on_lan, disable_eee in den Worker-Playbooks enable-wol, disable-eee
thermal_watchdog, resource_watchdog, ntfy_publisher in den Host-Playbooks thermal-watchdog, resource-watchdog@*, /etc/ntfy-publisher/
node_exporter, smartctl_exporter, vmagent, journal_upload in den Host-Playbooks prometheus-node-exporter, prometheus-smartctl-exporter, vmagent, systemd-journal-upload
cups_print_server make cups-print-server cups, avahi-daemon
banana_pi_kiosk, xibo_kiosk make banana-pi-kiosks, make xibo-kiosks banana-pi-wol-agent, xibosignage-kiosk
alert_caller make alert-caller, make alert-caller-pi alert-caller
wireguard_backup in site.yml wg-quick@wg-backup
vaultwarden_restore make vaultwarden-restore FORCE_RESTORE=true (überschreibt Live-Daten) Namespace vaultwarden