PKR-Lab

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

Projekt Detailseite
cubi Debugging und Fehlersuche
capulus-ios Debugging und Fehlersuche
EDV-Kretzer (Website) Debugging und Fehlersuche
ui-terminal-config Debugging und Fehlersuche
DocFlowEngine Debugging und Fehlersuche
PowerShell-Skripte Debugging und Fehlersuche, git-pull-push
github-workflows Nutzung

Vorgehen bei Vorfällen

  1. Eingrenzen: Welche Ebene? (Netz, DNS, Ingress, Pod, Daten, Secret, Abhängigkeit). Von außen nach innen prüfen.
  2. 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).
  3. 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.
  4. 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.