PKR-Lab

Konfiguration

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-ansible/konfiguration.md

Konfiguration

Konfigurationsdateien

Datei / Ordner Inhalt
ansible.cfg Defaults: Inventory inventory/hosts.yml, roles_path = roles, Fakt-Cache, SSH-Pipelining, host_key_checking = True
requirements.yml Galaxy-Collections (ansible.posix, community.general, kubernetes.core, community.docker)
inventory/hosts.yml Hosts und Gruppen
group_vars/all.yml gemeinsame Variablen, Semaphore-Projekte, Vault-Werte
group_vars/<gruppe>.yml Werte je Gruppe (banana_pis, xibo_displays, alert_callers, alert_caller_pi)
group_vars/user_inventory_vault.yml komplett verschlüsselte Nutzerliste (Immich/Vaultwarden)
host_vars/<host>/vars.yml Werte je Host; vault.yml daneben enthält !vault-Werte
files/homeserver-root-ca.pem Kopie der Root-CA aus capulus-core (pki/)
.yamllint, .ansible-lint Lint-Konfiguration
.gitleaks.toml Secret-Scan; erlaubt die öffentlichen APT-Key-Fingerprints
renovate.json Renovate: GitHub-Actions-Digests und die Helm-Version der Rolle k3s

Wichtige Variablen in group_vars/all.yml

Variable Bedeutung
hostname, timezone Hostname und Zeitzone des Homeservers
auto_upgrade, auto_reboot_if_required Auto-Upgrade-Verhalten, siehe unten
k3s_channel, k3s_version k3s-Release-Kanal (stable) bzw. fester Pin
k3s_pod_cidr, k3s_service_cidr Netze des TECH-Clusters; PROD und ENTW setzen eigene in host_vars
k3s_secrets_encryption_enabled, k3s_audit_log_* Secrets-Verschlüsselung at rest und Audit-Log (d0050)
k3s_kubelet_* Speicherschutz und Eviction-Schwellen des Kubelet
helm_version, argocd_version leer = jeweils aktuelle Version, sonst Pin
argocd_repo_url, argocd_repo_revision Quell-Repo von ArgoCD (capulus-core) und Branch
semaphore_ansible_repo_url Repo, das Semaphore für die Playbooks nutzt (diese Repo); Default in roles/semaphore_bootstrap/defaults/main.yml
semaphore_projects Semaphore-Projekte, Templates und Zeitpläne
local_subnet, prod_vm_ip, entw_vm_ip LAN-Subnetz und VM-Adressen
dnsmasq_prod_vm_hosts interne Hosts, die dnsmasq auf die PROD-VM auflöst
network_configure_static_ip, network_* optionale statische IP
libvirt_host_enabled, libvirt_host_configure_bridge KVM und Bridge br0
cups_print_server_* Druckserver (Gerät, Treiber, Warteschlangen)
wireguard_backup_port UDP-Port des Notfall-Tunnels

Rollenspezifische Variablen stehen auf den Rollen-Seiten.

Secrets (Ansible Vault)

Secrets stehen als !vault-Werte direkt in den YAML-Dateien (tailscale_auth_key, semaphore_vault_password, ntfy_publisher_token, vault_alert_caller_*, vault_n8n_nightly_webhook_token, vault_vm_write_auth_*, vault_logs_write_auth_*, SMB-Zugang des Scanners) oder komplett verschlüsselt (user_inventory_vault.yml). Neu verschlüsseln:

ansible-vault encrypt_string 'WERT' --name 'variablenname'

Neue Tokens und Passwörter werden zusätzlich in ops/token-register.yaml von capulus-core eingetragen (Feld stored_in mit Präfix capulus-ansible:).

Abhängigkeiten zu capulus-core

Variable Default Zweck
alert_caller_core_ref v3.49.0 Tag von capulus-core, aus dem die alert-caller-Quellen geladen werden
alert_caller_core_files drei Einträge Pfad und SHA-256 je Datei (caller.py, libre-sips-route.patch, baresip-srtp-no-gcm.patch)
alert_caller_core_cache_dir ~/.cache/capulus-ansible/alert-caller-<ref> lokaler Cache auf dem Steuerrechner
capulus_core_dir – Zielverzeichnis für make render-bootstrap (Parameter CORE_DIR)

Wird alert_caller_core_ref angehoben, müssen die Prüfsummen in alert_caller_core_files mit sha256sum der Dateien aus dem neuen Tag aktualisiert werden.

Auto-Upgrade

auto_upgrade: true (Default) hält bei jedem Playbook-Run den gesamten Stack aktuell:

Komponente Mechanismus
APT-Pakete apt dist-upgrade + unattended-upgrades für tägliche Sicherheits-Patches
Tailscale state: latest für das tailscale-Paket
k3s Folgt k3s_channel (Default stable), pin via k3s_version
Helm Re-Run des offiziellen Installers bei neuem Release
ArgoCD helm upgrade --install ohne --version, pin via argocd_version
Reboot Auto-Reboot wenn APT /var/run/reboot-required setzt (togglebar via auto_reboot_if_required)

Für reproduzierbare Builds: auto_upgrade: false in ansible/group_vars/all.yml.


Fehlersuche

Symptom Ursache Lösung
Variable hat nicht den erwarteten Wert Vorrang: host_vars vor group_vars/<gruppe> vor group_vars/all, Rollen-Defaults zuletzt ansible-inventory -i inventory/hosts.yml --host <host> --yaml zeigt die wirksamen Werte
!vault-Wert wird nicht entschlüsselt Vault-Passwort passt nicht zu dem Passwort, mit dem der Wert verschlüsselt wurde ansible-vault view, ggf. neu verschlüsseln (ansible-vault encrypt_string)
Root-CA-Prüfung in der CI rot files/homeserver-root-ca.pem weicht von pki/homeserver-root-ca.pem in capulus-core ab Datei aus capulus-core kopieren
Platzhalter wie CHANGE_ME im Lauf Variable nicht gesetzt Werte in group_vars/all.yml oder host_vars/<host>/vars.yml setzen
Neuer Host ohne Wirkung nicht in der richtigen Inventory-Gruppe inventory/hosts.yml und Playbook-Zielgruppe abgleichen
gitleaks meldet Treffer Secret im Klartext oder neuer öffentlicher Fingerprint Secret entfernen und rotieren, öffentliche Werte in .gitleaks.toml freigeben

Rollen-Fehler: Rollen. Allgemeine Fehlersuche: zentrale Fehlersuche.