Nutzung
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-ansible/nutzung.md
Nutzung
Alle Befehle laufen im Verzeichnis von capulus-ansible. Das Vault-Passwort wird bei jedem Lauf abgefragt (VAULT_OPTS ?= --ask-vault-pass); mit make … VAULT_OPTS="--vault-password-file ~/.vault_pass" geht es auch ohne Rückfrage.
Typische Abläufe
| Aufgabe | Befehl |
|---|---|
| Erreichbarkeit prüfen | make ping |
| Änderungen ansehen, ohne sie anzuwenden | make check bzw. make <ziel>-check |
| Eine Rolle gezielt ausrollen | make <rolle> (z. B. make dnsmasq, make argocd, make power-agent) |
| Alles ausrollen | make install |
| Worker einbinden oder aktualisieren | make controlplane-1, make worker-1 |
| PROD- oder ENTW-Cluster ausrollen | make prod, make entw |
| Vault-Variablen bearbeiten | make vault-edit (Klartext mit inline verschlüsselten Werten), make vault-encrypt-string NAME=<variable>, make user-inventory-edit |
| ArgoCD-Bootstrap in capulus-core neu erzeugen | make render-bootstrap CORE_DIR=../capulus-core |
| Lint | make lint |
Direkter Aufruf mit Tags:
ansible-playbook -i inventory/hosts.yml site.yml --tags k3s --ask-vault-pass
ansible-playbook -i inventory/hosts.yml site.yml --skip-tags tailscale --ask-vault-pass
ansible-playbook -i inventory/hosts.yml entw.yml --limit entw-vm --check --diff
Die Tags je Rolle stehen auf den Rollen-Seiten.
Alle Make-Targets
| Target | Wirkung |
|---|---|
make help |
Show this help. |
make deps |
Install required Ansible Galaxy collections. |
make ping |
Verify Ansible can reach the server. |
make check |
Dry-run the full playbook (no changes applied). |
make ssh-hardening |
Apply the ssh_hardening role (key-only SSH) on the k3s servers, worker-1, prod-vm, entw-vm, the kiosk Pis, ollama-pc and alert-caller-vm. |
make install |
Provision the home server end-to-end. |
make common |
Run only the common role (base OS, firewall, packages). |
make crowdsec |
Run only the crowdsec role (SSH + Traefik brute-force protection). |
make dnsmasq |
Run only the dnsmasq role (split-DNS for *.homeserver). |
make tailscale |
Run only the tailscale role (VPN). |
make k3s |
Run only the k3s role (Kubernetes + Helm) on controlplane-0. |
make k3s-agent |
Run only the k3s-agent role on worker-1 (requires controlplane-0 k3s running). |
make argocd |
Run only the argocd role (GitOps controller). |
make semaphore |
Bootstrap Semaphore Secret on the home-server. |
make semaphore-targets |
Push Semaphore SSH key to all managed targets. |
make semaphore-bootstrap |
Provision Projects/Inventories/Templates in Semaphore via API. |
make semaphore-bootstrap-local |
Bootstrap Semaphore natively on the home server (no SSH). |
make controlplane-1 |
Deploy k3s node + watchdogs on controlplane-1 (192.168.178.95). |
make controlplane-1-check |
Dry-run the controlplane-1 playbook (no changes applied). |
make worker-1 |
Deploy k3s agent + watchdogs on worker-1 (192.168.178.96). |
make worker-1-check |
Dry-run the worker-1 playbook (no changes applied). |
make prod |
Deploy PROD-Cluster (k3s) in der KVM-VM auf controlplane-0 (192.168.178.99, docs/4-planung/40080 Phase 2.5). VM muss laufen (make libvirt-host). |
make prod-check |
Dry-run des PROD-Playbooks. |
make entw |
Deploy ENTW-Cluster (k3s + ArgoCD) in der KVM-VM auf worker-1 (192.168.178.100, docs/4-planung/40080 Phase 1.2). VM muss laufen (make worker-1-libvirt-host). |
make entw-check |
Dry-run des ENTW-Playbooks. |
make cluster-power-manager |
Re-deploy only the cluster_power_manager role on controlplane-0 (WoL scale-up/down). |
make power-agent |
Re-deploy only the power_agent role on controlplane-0 (brightness + manual WoL/poweroff HTTP API). |
make cups-print-server |
Re-deploy only the cups_print_server role on controlplane-0 (USB-Drucker per IPP/AirPrint). |
make libvirt-host |
Re-deploy only the libvirt_host role (PROD-VM, docs/4-planung/40080 Baustein 5). Braucht libvirt_host_enabled: true in group_vars/all.yml. |
make libvirt-bridge |
NUR das Bridge-Netzwerk (libvirt_host, riskant - siehe Rollenkommentar). Erst mit Wartungsfenster + Rollback-Plan. |
make worker-1-libvirt-host |
Re-deploy only the libvirt_host role auf worker-1 (ENTW-VM, docs/4-planung/40080 Phase 1). Braucht libvirt_host_enabled: true in host_vars/worker-1/vars.yml. |
make worker-1-libvirt-bridge |
NUR das Bridge-Netzwerk auf worker-1 (weniger kritisch als controlplane-0, aber trotzdem bewusster Schritt). |
make k3s-servers-update |
apt-Update und Neustart der k3s-Server nacheinander (nur mit gesundem etcd-Peer, von der Workstation). |
make k3s-servers-update-check |
Dry-run des Server-Updates (keine Änderungen). |
make k3s-upgrade |
k3s auf die Version aus k3s_version heben: erst die Server nacheinander, dann die Agents. |
make k3s-upgrade-check |
Dry-run des k3s-Upgrades (keine Änderungen). |
make nightly-worker-wake |
Re-deploy only the nightly_worker_wake role on controlplane-0 (01:00 Uhr WoL+Update+Poweroff-Zyklus). |
make worker-apt-update |
Manuelles apt-Update auf controlplane-1 + worker-1 (läuft normalerweise nachts automatisch über nightly-worker-wake). |
make xibo-kiosks |
xibosignage-Displays einrichten (Raspberry Pi 3B+, Bilder-Slideshow, Tailscale). |
make xibo-kiosks-check |
Dry-run des xibosignage-Displays-Playbooks (keine Änderungen). |
make banana-pi-kiosks |
Banana-Pi-Alarmmonitore einrichten (Armbian, ALAMOS AMweb + Server-Fallback). |
make banana-pi-kiosks-check |
Dry-run des Banana-Pi-Alarmmonitor-Playbooks (keine Änderungen). |
make banana-pi-kiosks-restart-session |
tty1-Session auf den Banana-Pi-Alarmmonitoren erzwungen neu starten (laedt bereits deployte Skripte/Configs neu ein, ohne dass ein Playbook-Diff noetig ist). |
make alert-caller |
Telefon-Alarmierung einrichten (alert-caller: baresip, Piper, Tailscale auf der externen VM). |
make alert-caller-check |
Dry-run des alert-caller-Playbooks (keine Änderungen). |
make alert-caller-pi |
Notfall-Caller (feste Ansage, ruft bei ausbleibendem Watchdog an) auf dem Vereinsheim-Pi einrichten. |
make alert-caller-pi-check |
Dry-run des Pi-Notfall-Callers (keine Änderungen). |
make lint |
Lint YAML and Ansible. |
make render-bootstrap |
Regenerate argocd/bootstrap/ in a capulus-core checkout: make render-bootstrap CORE_DIR=/path/to/capulus-core |
make vault-edit |
group_vars/all.yml im Editor öffnen (Klartext mit inline verschlüsselten !vault-Werten). |
make vault-encrypt-string |
Einen Wert für group_vars/host_vars verschlüsseln: make vault-encrypt-string NAME= |
make user-inventory-edit |
Edit the encrypted Immich/Vaultwarden user inventory (docs/4-planung/40080, Baustein 7). First run: ansible-vault create $(USER_INVENTORY_FILE). |
make vaultwarden-restore |
Vaultwarden-Daten aus der NAS-Backup-PVC wiederherstellen (ueberschreibt Live-Daten!). Erst mit FORCE_RESTORE=true bestaetigen. |
make clean |
Remove cached collections and temp artifacts. |
Semaphore
Semaphore läuft im TECH-Cluster und führt dieselben Playbooks per Zeitplan oder Klick aus. Die Rolle semaphore_bootstrap legt Projekte, Inventories, Templates und Zeitpläne per API an. Die Projekte lesen dieses Repo (semaphore_ansible_repo_url), die Playbook-Pfade sind site.yml, controlplane-1.yml und so weiter. Hintergrund: b0030 Semaphore.
ArgoCD-Bootstrap erzeugen
argocd/bootstrap/ in capulus-core ist generiert. Änderungen an den App-Listen (argocd_platform_apps, argocd_workloads_apps in roles/argocd/defaults/main.yml) oder an den Templates der Rolle argocd werden so übernommen:
make render-bootstrap CORE_DIR=../capulus-core
Ohne CORE_DIR bricht das Target mit einer Fehlermeldung ab. Anschließend in capulus-core committen.
Fehlersuche
Rollenspezifische Meldungen stehen auf den Rollen-Seiten, die Erstinstallation behandelt a0040.
| Symptom | Ursache | Lösung |
|---|---|---|
make render-bootstrap bricht ab |
CORE_DIR nicht gesetzt oder zeigt nicht auf einen capulus-core-Checkout |
make render-bootstrap CORE_DIR=../capulus-core |
Decryption failed oder Attempting to decrypt but no vault secrets found |
Vault-Passwort falsch oder nicht angegeben | --ask-vault-pass bzw. VAULT_OPTS="--vault-password-file …" |
UNREACHABLE! |
Host aus (zum Beispiel Worker nachts), Netz, SSH-Schlüssel | make ping, ssh <host>, Cluster Power Manager |
REMOTE HOST IDENTIFICATION HAS CHANGED |
host_key_checking = True, Host neu installiert |
alten Eintrag aus ~/.ssh/known_hosts entfernen (ssh-keygen -R <host>) |
| Tags greifen nicht | falscher Tag, Rolle nicht im Playbook | Tags der Rollenseite verwenden, ansible-playbook … --list-tags |
| Lauf ist langsam oder liefert veraltete Werte | Fakten-Cache (1 Stunde) | rm -rf ~/.cache/ansible-facts |
make lint rot |
yamllint oder ansible-lint | Meldung lesen, .yamllint und .ansible-lint beachten |
ModuleNotFoundError/Unknown collection |
Collections fehlen | make deps |
| Semaphore-Lauf scheitert, lokal klappt es | SSH-Schlüssel von Semaphore nicht auf dem Ziel, Vault-Passwort in Semaphore | Semaphore, semaphore_targets |
make vaultwarden-restore verweigert |
Schutz vor Überschreiben | FORCE_RESTORE=true nur bei Disaster Recovery |