20070 - Zentrale Fehlersuche — von Symptom zur richtigen Anleitung
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/2-betrieb-hardware/20070-troubleshooting-zentral.md
Zentrale Fehlersuche — von Symptom zur richtigen Anleitung
Einstiegsseite für Störungen im gesamten Capulus-Umfeld: Cluster, Apps, Hosts, CI/CD, iOS-App, Werkzeuge und Website. Sie führt vom Symptom über eine feste Reihenfolge zur passenden Detailseite. Jede Detailseite hat einen eigenen Abschnitt „Fehlersuche“ (je nach Seite auch „Troubleshooting“ oder „Fehlerbehebung“) mit Meldungen, Ursachen und Lösungen.
Die ersten fünf Minuten
Vor dem Suchen in einzelnen Docs lohnt dieser Ablauf. Er grenzt die Ebene ein, auf der der Fehler liegt (von außen nach innen).
| Schritt | Frage | Befehl oder Ort |
|---|---|---|
| 1 | Läuft der Cluster, und sind die Nodes bereit? | kubectl get nodes (Zugriff je Cluster: a0010), k3s: Fehlersuche |
| 2 | Ist ArgoCD grün? Welche App ist rot? | cubi argocd (cubi: ArgoCD) oder kubectl -n argocd get applications |
| 3 | Läuft der Pod? | cubi kubernetes (cubi: Kubernetes), kubectl -n <ns> get pods, describe, logs |
| 4 | Ist der Name auflösbar und der Port erreichbar? | dig +short <host>, curl -vk https://<host>/, DNS, Ports |
| 5 | Stimmen Zertifikat und Secrets? | Internes TLS, Sealed Secrets |
| 6 | Hat sich vor kurzem etwas geändert? | letzte Merges und Promotions: cubi github (GitHub), Promotion-Kette |
| 7 | Hilft ein Blick in Logs und Alarme? | VictoriaLogs und Grafana (Logging), ntfy-Alarme (ntfy) |
Nützliche Dauerbefehle (im Cluster mit dem Problem):
kubectl get pods -A | grep -v -e Running -e Completed # alles, was nicht läuft
kubectl get events -A --sort-by=.lastTimestamp | tail -30 # letzte Ereignisse
kubectl -n <ns> describe pod <pod> # Events unten lesen
kubectl -n <ns> logs <pod> --previous --tail=100 # Log des vorherigen Starts
kubectl -n argocd get applications.argoproj.io | grep -v 'Synced.*Healthy'
Symptom → Anleitung
Cluster, GitOps und Netzwerk
| Symptom | Mögliche Ursache | Weiter |
|---|---|---|
kubectl verbindet nicht |
k3s aus, falscher Kontext, kubeconfig | k3s |
Worker NotReady oder fehlt |
Worker ist aus (nachts gewollt), Netz, k3s-agent |
k3s, Cluster Power Manager, Nightly Update |
| Neue App erscheint nicht in ArgoCD | Ordner, ApplicationSet, AppProject | ArgoCD, AppProjects |
App OutOfSync, Degraded, Unknown |
Manifeste, Controller-Änderungen, Pod-Fehler | ArgoCD, cubi: ArgoCD |
| Änderung wird zurückgesetzt | Self-Heal, ApplicationSet, übergeordnete App | cubi: Features |
PROD-Apps fehlen oder Cluster prod nicht erreichbar |
Cluster-Registrierung im Hub | PROD im TECH-Hub |
| App-Umzug nach PROD hakt | Kopier-Job, Daten, DNS | App-Umzug |
| ENTW-App oder ENTW-ArgoCD | eigene Instanz, Branch entw |
ENTW-ArgoCD |
Pod Pending oder PVC Pending |
Ressourcen, StorageClass, NAS | k3s, NAS-Speicher |
HPA zeigt <unknown> oder skaliert nicht |
Metrics-Server, Requests | HPA |
SealedSecret wird nicht entschlüsselt, Pod CreateContainerConfigError |
falscher Cluster oder Name, Schlüssel fehlt | Sealed Secrets |
Host nicht auflösbar (*.homeserver) |
DNS-Weg, dnsmasq, Tailscale-Split-DNS | DNS, Tailscale |
Pods lösen *.homeserver nicht auf |
CoreDNS-Erweiterung | CoreDNS |
| Zertifikatswarnung im Browser | Root-CA nicht installiert, Host nicht in SAN, Zertifikat abgelaufen | Internes TLS, Traefik |
404 page not found oder Redirect-Schleife |
Ingress, Traefik-Konfiguration | Traefik |
192.168.178.200 antwortet nicht |
MetalLB | MetalLB |
| Dienst von außen (Internet) nicht erreichbar | Cloudflare Tunnel | Tunnel, Deploy |
| Pod erreicht anderen Namespace nicht (Timeout) | NetworkPolicy | Network Policies |
| VPN, Subnet-Routen, Tailscale-Login | Auth-Key, ACL, Dienst | Tailscale, WireGuard-Backup |
| Ports, wer lauscht wo | Port-Übersicht | Ports |
| Werbung blockiert oder DNS-Probleme durch Pi-hole | Blocklisten, Update | Pi-hole, Incident 50020 |
Alarme, Monitoring und Logs
| Symptom | Mögliche Ursache | Weiter |
|---|---|---|
| Alarm kommt nicht aufs Telefon | Alertmanager-Route, ntfy-bridge, ntfy-Token, iOS-App | ntfy-bridge, ntfy |
| Kein Anruf bei schweren Ausfällen | alert-caller, SIP | Telefon-Alarm |
| Keine Alarme zu ArgoCD oder Backups | Regeln, Routing | GitOps- und Backup-Alerts |
| Metriken oder Dashboards leer | VictoriaMetrics, Scrapes | Monitoring, Monitoring: Hintergründe, Hardware-Monitoring |
| Logs fehlen in Grafana | journal_upload, Collector |
Logging, Rolle journal_upload |
| Status-Page oder Uptime-Kuma-Monitore falsch | Monitore, Slug, CORS | Uptime Kuma |
| NAS-Platte rot, Homeserver nicht erreichbar | RAID, NFS | NAS-Speicher, Incident 50000 |
| Backup fehlt oder zu alt | CronJob, restic, NAS | NAS-Backup, GitOps- und Backup-Alerts |
CI/CD, Releases und Secrets
| Symptom | Mögliche Ursache | Weiter |
|---|---|---|
| CI rot (lint, kubeconform, go, token register, gitleaks) | Code, Schema, Register | CI-Lint, Skripte und Workflows |
Push auf main abgelehnt, PR nicht mergebar |
Branch-Schutz | Branch-Schutz |
| Kein PR aus ENTW | Promotion, CI auf entw, Konflikt |
ENTW-Promotion |
| Versionen wandern nicht von ENTW nach TECH und PROD | Gate, ArgoCD-Token, Tailnet | Promotion-Kette, Tailscale-Runner |
| Image wird nicht gebaut oder nicht ausgerollt | Pfadfilter, Registry, Bump-PR | Images bauen |
| Kein Release, Changelog fehlt | Commit-Format, Rechte | Release-Automatisierung, github-workflows |
| Renovate-PRs fehlen | Zeitplan, Token | Renovate |
| GitLab-Spiegel veraltet | Mirror-Token | GitLab-Mirror |
| Neue Version eines Fremdprojekts wird nicht gemeldet | Release-Watcher | GitHub Release Watcher |
| Argo-Workflow-Lauf scheitert | Artefaktspeicher, Rechte | Argo Workflows, Garage |
| Security-Issue oder CodeQL-Befund | Alerts | CodeQL und Dependabot |
| Token läuft ab, Rotation | Token-Register | Secrets-Rotation, cubi: Tokens |
| Docs im Wiki nicht aktuell | wiki-docs-sync | wiki-sync |
Apps und Dienste
| App | Detailseite (Fehlersuche) |
|---|---|
| Zammad | 30000 |
| Alarmmonitor-Kiosks (ALAMOS) | 30010, Vereinsheim-Alarmmonitor, Windows-PC |
| Infotafel-Kiosk | Infotafel |
| Wiki.js | 30030 |
| MediaMTX | 30040 |
| Paperless-ngx | 30050 |
| n8n | 30070 |
| Uptime Kuma | 30080 |
| Monitoring (VictoriaMetrics, Grafana, Alertmanager) | 300q0 |
| Rhein-Dashboard | 30090 |
| Vaultwarden | 300a0 |
| Nextcloud | 300b0 |
| Immich | 300c0 |
| carplay-api | 300d0, Komponente |
| Xibo Signage | 300e0 |
| pacman | 300f0, Komponente |
| Ollama | 300g0 |
| ALAMOS-Einsatz nach Zammad | 300h0 |
| alamos-relay | 300i0 |
| Logging | 300j0 |
| isc-news-bot | 300k0 |
| Instagram-Post per Mail | 300l0 |
| ISC Urkunden melden | 300m0 |
| Headlamp | 300n0 |
| kubeseal-webgui | 300o0 |
| Garage | 300p0 |
| ntfy | 10010 |
| ntfy-bridge | 10030 |
| lldap | d0072 |
| Beispiel-Apps (demo-app, whoami) | b0090 |
Hosts und Provisionierung (capulus-ansible)
| Symptom | Weiter |
|---|---|
| Playbook scheitert, Erstinstallation | Troubleshooting, Rollen: Fehlersuche |
| Semaphore läuft nicht | Semaphore |
| Brute-Force-Schutz, CrowdSec | CrowdSec |
| Drucker (CUPS) | Drucker |
| Secrets-at-Rest und Audit-Log | Secrets-Encryption |
| Kiosk-Geräte (Banana Pi, Xibo, ALAMOS) | Rollen, Vereinsheim-Alarmmonitor |
Weitere Projekte
Vorgehen bei Vorfällen
- Eingrenzen: Welche Ebene? (Netz, DNS, Ingress, Pod, Daten, Secret, Abhängigkeit). Von außen nach innen prüfen.
- Nichts zerstören: erst lesen (
get,describe,logs), dann ändern. Bei GitOps-Apps Änderungen über Git machen, weil Self-Heal manuelle Änderungen zurücksetzt. Für Tests Auto-Sync kontrolliert abschalten (cubi: Auto-Sync). - Dokumentieren: bei größeren Vorfällen einen Bericht nach Typ C (TEMPLATE) unter 5-incidents bzw. für Sicherheitsvorfälle unter
7-security-incidents/anlegen. - Regel ableiten: Erkenntnisse gehören als Begründung in die Hintergründe (60000).
Beispiele für ausgewertete Vorfälle: Incident 12.08.2026, NAS-Platte rot, PROD-VM-Basis-Image ersetzt, Pi-hole-Update und DNS-Deadlock.