PKR-Lab

a0040 - Troubleshooting

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-ansible/a-betriebssystem/a0040-troubleshooting.md

Troubleshooting

Diese Datei sammelt typische Probleme und ihre Lösungen pro Komponente.


k3s startet nicht

Symptome

Diagnose

# Service-Status
sudo systemctl status k3s

# Aktuelle Logs
sudo journalctl -u k3s --since "10 minutes ago" -n 100

# Vollständige Logs
sudo journalctl -u k3s | tail -200

# Kernel-Anforderungen prüfen
sudo k3s check-config

# Binary prüfen
ls -la /usr/local/bin/k3s
k3s --version

Häufige Ursachen & Fixes

Port 6443 belegt:

sudo ss -tlnp | grep 6443
# Belegt von anderem Prozess → stoppen oder k3s umkonfigurieren

Swap aktiv:

swapon --show
# Falls aktiv:
sudo swapoff -a
sudo sed -i '/ swap / s/^/#/' /etc/fstab

br_netfilter-Modul fehlt:

lsmod | grep br_netfilter
# Falls leer:
sudo modprobe br_netfilter
echo "br_netfilter" | sudo tee /etc/modules-load.d/k3s.conf

ip_forward deaktiviert:

cat /proc/sys/net/ipv4/ip_forward
# Sollte 1 sein. Falls 0:
sudo sysctl -w net.ipv4.ip_forward=1
echo "net.ipv4.ip_forward = 1" | sudo tee /etc/sysctl.d/99-k3s.conf
sudo sysctl --system

YAML-Syntaxfehler in der Config:

cat /etc/rancher/k3s/config.yaml
python3 -c "import yaml; yaml.safe_load(open('/etc/rancher/k3s/config.yaml'))"

k3s neu installieren:

# Deinstallieren
sudo /usr/local/bin/k3s-uninstall.sh

# Re-Install via Ansible
ansible-playbook -i inventory/hosts.yml site.yml --tags k3s --ask-vault-pass

ArgoCD synct nicht

Symptome

Diagnose

# ArgoCD-Pods
kubectl get pods -n argocd

# Server-Logs
kubectl logs -n argocd deployment/argocd-server --tail=100

# Application-Controller-Logs
kubectl logs -n argocd deployment/argocd-application-controller --tail=100

# Repo-Server-Logs
kubectl logs -n argocd deployment/argocd-repo-server --tail=100

# ApplicationSet-Controller-Logs
kubectl logs -n argocd deployment/argocd-applicationset-controller --tail=100

# Apps und Status
kubectl get applications -n argocd
kubectl describe application example-whoami -n argocd

# ApplicationSet
kubectl get applicationsets -n argocd
kubectl describe applicationset home-server-apps -n argocd

Häufige Ursachen & Fixes

Repository nicht erreichbar:

# Im UI: Settings → Repositories → Connection-Status prüfen

# Per kubectl
kubectl get secrets -n argocd -l argocd.argoproj.io/secret-type=repository

# Verbindung aus dem argocd-repo-server-Pod testen
kubectl exec -n argocd deployment/argocd-repo-server -- \
  git ls-remote https://github.com/pkr-lab/capulus-core.git

Privates Repo ohne Credentials:

Credentials hinterlegen wie in ../b-kubernetes-gitops/b0010-argocd.md beschrieben.

Falsche Repo-URL im ApplicationSet:

kubectl get applicationset home-server-apps -n argocd -o yaml | grep repoURL
# URL muss zum echten Repo passen

YAML-Syntaxfehler in App-Manifests:

# Parser-Fehler im Repo-Server
kubectl logs -n argocd deployment/argocd-repo-server | grep -i "error\|ERR"

# Lokal validieren
find argocd/apps/ -name "*.yaml" -exec python3 -c "
import yaml, sys
for f in sys.argv[1:]:
    try:
        yaml.safe_load_all(open(f))
        print(f'OK: {f}')
    except yaml.YAMLError as e:
        print(f'ERROR: {f}: {e}')
" {} +

ArgoCD-Server-Pod nicht ready:

kubectl rollout status deployment/argocd-server -n argocd
kubectl describe pod -n argocd -l app.kubernetes.io/name=argocd-server

Manuellen Sync erzwingen:

# Per CLI
argocd app sync example-whoami --force

# Per kubectl (Annotation triggert Refresh)
kubectl patch application example-whoami -n argocd \
  --type merge \
  -p '{"metadata": {"annotations": {"argocd.argoproj.io/refresh": "hard"}}}'

Tailscale verbindet nicht

Symptome

Diagnose

# tailscaled-Service
sudo systemctl status tailscaled

# Logs
sudo journalctl -u tailscaled --since "10 minutes ago" -n 100

# Netz-Diagnostik
tailscale netcheck

# Status
tailscale status

# Auth-Probleme
sudo journalctl -u tailscaled | grep -i "auth\|error\|fail"

Häufige Ursachen & Fixes

Ungültiger oder abgelaufener Auth-Key:

# Mit neuem Key reconnecten
sudo tailscale up --authkey=tskey-auth-NEUER_KEY --reset

tailscaled-Service läuft nicht:

sudo systemctl enable --now tailscaled
sudo systemctl restart tailscaled

Firewall blockt Tailscale-UDP:

# UFW-Regeln
sudo ufw status verbose | grep -i "41641\|tailscale"

# Tailscale freigeben
sudo ufw allow 41641/udp comment "Tailscale WireGuard"

Nur DERP-Relay (keine Direktverbindung):

Wenn tailscale netcheck keine direkten Pfade meldet, nutzt Tailscale DERP-Relays.
Funktioniert, hat aber höhere Latenz. Löst sich meist von selbst.

tailscale netcheck
# Achten auf "No direct connection to X"

Re-Authentifizieren:

sudo tailscale up --force-reauth
# Der angezeigten URL folgen

Falsche IP angezeigt:

tailscale ip -4
# Muss zur Anzeige im Admin-Panel passen

Pod hängt in Pending

Symptome

Diagnose

# Pod-Details, Events am Ende beachten
kubectl describe pod <pod-name> -n <namespace>

# Node-Resources
kubectl describe node homeserver
kubectl top nodes

Häufige Ursachen & Fixes

Zu wenig Ressourcen:

# Allocatable vs. Requests
kubectl describe node homeserver | grep -A10 "Allocatable:"
kubectl describe node homeserver | grep -A10 "Allocated resources:"

# Was zieht Speicher/CPU?
kubectl top pods -A --sort-by=memory
kubectl top pods -A --sort-by=cpu

PVC nicht gebunden:

kubectl get pvc -A
# Falls STATUS "Pending":
kubectl describe pvc <pvc-name> -n <namespace>

# local-path-Provisioner
kubectl logs -n kube-system -l app=local-path-provisioner

Tolerations/Affinity/NodeSelector greifen nicht:

kubectl describe pod <pod-name> -n <namespace> | grep -A10 "Node-Selectors\|Tolerations\|Events"

Image-Pull-Fehler (ImagePullBackOff / ErrImagePull):

kubectl describe pod <pod-name> -n <namespace> | grep -A5 "Events"
# Bei „image not found" oder „registry unreachable":
# - Image-Name/-Tag prüfen
# - Internet vom Node prüfen
# - Private Registry → imagePullSecrets prüfen

Storage-Probleme

Symptome

Diagnose

# PVCs und PVs
kubectl get pvc -A
kubectl get pv
kubectl describe pvc <name> -n <namespace>
kubectl describe pv <name>

# local-path-Provisioner
kubectl get pods -n kube-system -l app=local-path-provisioner
kubectl logs -n kube-system -l app=local-path-provisioner

# Storage-Verzeichnis am Host
sudo ls -la /var/lib/rancher/k3s/storage/
sudo df -h /var/lib/rancher/k3s/storage/

Häufige Ursachen & Fixes

Disk voll:

df -h /
# Aufräumen:
sudo journalctl --vacuum-size=1G
sudo docker system prune  # falls Docker installiert

local-path-Provisioner läuft nicht:

kubectl rollout restart deployment/local-path-provisioner -n kube-system

Falsche StorageClass im PVC:

kubectl get storageclass
# Default ist "local-path" — PVC sollte das nutzen:
# spec.storageClassName: local-path

PV an falsche Claim gebunden:

kubectl get pvc <name> -n <namespace> -o yaml | grep volumeName
kubectl get pv <pv-name> -o yaml | grep claimRef

Netzwerk-Probleme

Symptome

Diagnose

# Flannel
kubectl get pods -n kube-system -l app=flannel
kubectl logs -n kube-system -l app=flannel

# CoreDNS
kubectl get pods -n kube-system -l k8s-app=kube-dns
kubectl logs -n kube-system -l k8s-app=kube-dns

# DNS-Auflösung aus einem Pod
kubectl run dns-test --image=busybox:1.28 --rm -it --restart=Never -- nslookup kubernetes.default

# Pod-zu-Pod
kubectl run ping-test --image=busybox:1.28 --rm -it --restart=Never -- ping -c3 <pod-ip>

# Services
kubectl get svc -A
kubectl describe svc <name> -n <namespace>

# Endpoints
kubectl get endpoints <svc-name> -n <namespace>

Häufige Ursachen & Fixes

Flannel-VXLAN blockiert (Firewall):

# UDP 8472 muss offen sein
sudo ufw allow 8472/udp comment "Flannel VXLAN"

br_netfilter nicht geladen:

lsmod | grep br_netfilter
# Falls leer:
sudo modprobe br_netfilter

Traefik routet nicht:

kubectl get pods -n kube-system -l app.kubernetes.io/name=traefik
kubectl logs -n kube-system -l app.kubernetes.io/name=traefik
kubectl get svc -n kube-system traefik

# Ingress-Details
kubectl describe ingress <name> -n <namespace>
kubectl get ingress <name> -n <namespace> -o yaml | grep ingressClassName

Service ohne Endpoints:

kubectl get endpoints <svc-name> -n <namespace>
# Falls leer: laufen die Pods und matchen die Labels?
kubectl get pods -n <namespace> -l <selector-key>=<selector-value>

Ansible-Playbook-Fehler

Häufige Ursachen

SSH-Verbindung verweigert:

# SSH testen
ssh -i ~/.ssh/id_rsa [email protected] "echo connected"

# Inventory
ansible -i inventory/hosts.yml homeserver -m ping

sudo verlangt Passwort:

# Auf dem Server NOPASSWD-sudo eintragen
ssh [email protected]
echo "ubuntu ALL=(ALL) NOPASSWD:ALL" | sudo tee /etc/sudoers.d/ubuntu-nopasswd

Galaxy-Collection fehlt:

ansible-galaxy collection install -r requirements.yml --force

Falsches Vault-Passwort:

# Bei "Decryption failed" wurde das falsche Passwort eingegeben.
# Falls das Passwort komplett verloren ist, Secret neu verschlüsseln:
ansible-vault encrypt_string 'tskey-auth-DEIN_KEY' --name 'tailscale_auth_key'

Multi-Cluster (PROD / ENTW)

Alle Abschnitte oben gelten für den TECH-Cluster. Für PROD und ENTW kommen diese Fälle dazu
(Überblick: a0010):

Symptom Ursache / Prüfung Fix
https://<app>.prod.homeserver liefert 404 oder die falsche App, obwohl die App in PROD läuft Der Host löst auf den TECH-Traefik (.94) statt auf die PROD-VM (.99) auf: dig +short <host> @192.168.178.94 Host in dnsmasq_prod_vm_hosts (capulus-ansible/group_vars/all.yml) eintragen, make dnsmasq
Application prod-<app> steht auf InvalidSpecError/Unknown, Meldung „destination … not permitted in project 'prod'“ Namespace fehlt in argocd/bootstrap-prod/appproject.yaml (oder wurde dort ergänzt, aber nicht im Hub angewendet) Datei im TECH-Hub anwenden (kubectl apply -f argocd/bootstrap-prod/appproject.yaml), dann kubectl -n argocd annotate application prod-<app> argocd.argoproj.io/refresh=hard --overwrite
Für einen neuen PROD-Ordner entsteht keine prod-<app>-Application Reiner Manifest-Ordner (ohne Chart.yaml) fehlt in home-server-apps-prod, oder der Ordner liegt noch nicht auf main (die ApplicationSets lesen main) path in argocd/bootstrap-prod/applicationset.yaml ergänzen und im Hub anwenden; Ordner mergen
SealedSecret in PROD bleibt ohne Secret, Controller meldet „no key could decrypt secret“ Mit dem TECH-Schlüssel versiegelt, jeder Cluster hat eigene Schlüssel Für den PROD-Controller neu versiegeln (scripts/reseal-for-prod.sh, Kopf des Skripts)
SSH (22) auf prod-vm läuft ins Timeout, Ping geht UFW auf dem homeserver verwirft geroutete Bridge-Pakete (mit br_netfilter laufen sie durch die FORWARD-Kette) Regel ufw route allow in on br0 out on br0 — die Rolle libvirt_host setzt sie, make libvirt-host erneut ausführen
homeserver ist nach einem Neustart eingeschaltet, aber im LAN nicht erreichbar (ARP INCOMPLETE, „no route to host“, auch .99) Der NIC-Name hat sich geändert (network_interface zeigt auf ein nicht existierendes Interface), Netplan hat br0 ohne physischen Port angelegt Per Konsole oder IPv6-SSH (ssh ubuntu@fe80::…%<NIC>) /etc/netplan/99-libvirt-bridge.yaml korrigieren; Vorgehen mit Rollback-Timer in 40080, Phase 1.2. Vorbeugung: libvirt_host prüft das Interface per assert, nach jeder Netzwerkumstellung einen Reboot-Test machen
Pods in PROD lösen *.homeserver nicht auf Die PROD-VM nutzt ausschließlich den dnsmasq des homeservers als Resolver; steht dnsmasq/Pi-hole, hat PROD kein DNS systemctl status dnsmasq auf dem homeserver, Pi-hole-Pod in TECH prüfen
ENTW-ArgoCD zeigt eine neue App nicht Der Ordner liegt nicht auf dem Branch entw (ENTW liest nicht main) Ordner per PR auf entw bringen, b0050
kubectl auf dem homeserver zeigt keine PROD-Pods Falscher Cluster: die PROD-Ressourcen liegen in der prod-vm ssh [email protected] 'sudo k3s kubectl get pods -A'; die Applications selbst siehst du im Hub (kubectl -n argocd get applications \| grep '^prod-')

Nützliche Debug-Kommandos

System-weiter Status

# Alle nicht-laufenden Pods
kubectl get pods -A --field-selector=status.phase!=Running,status.phase!=Succeeded

# Aktuelle Cluster-Events
kubectl get events -A --sort-by='.lastTimestamp' | tail -30

# Node-Conditions
kubectl describe node homeserver | grep -A20 "Conditions:"

# System-Ressourcen
free -h && df -h && uptime

# journald-Errors
sudo journalctl -p err --since "1 hour ago"

Quick-Health-Check-Skript

#!/bin/bash
echo "=== Node Status ==="
kubectl get nodes

echo ""
echo "=== Pod Status ==="
kubectl get pods -A

echo ""
echo "=== Tailscale Status ==="
tailscale status

echo ""
echo "=== ArgoCD Apps ==="
kubectl get applications -n argocd 2>/dev/null || echo "ArgoCD nicht installiert"

echo ""
echo "=== Disk-Verbrauch ==="
df -h /

echo ""
echo "=== Memory ==="
free -h

Speichern als /home/ubuntu/healthcheck.sh, ausführen mit bash /home/ubuntu/healthcheck.sh.