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 |