1. Ziel und Abgrenzung

Dieses Dokument ist eine vollständige Troubleshooting-Referenz für Kubernetes. Du nutzt es, wenn ein Cluster, ein Node, ein Add-on oder eine Anwendung nicht wie erwartet funktioniert. Es ist bewusst nicht nur eine Liste einzelner Fehlerbilder. Es beschreibt Vorgehensmodelle, Umgebungsspezifika, Runbooks, Diagnosekommandos, Beweissicherung und Validierung.

1.1. Zielgruppen

1.2. Nicht-Ziele

Dieses Dokument ersetzt keine produktspezifischen Support-Verträge, keine formale Incident-Response-Policy und keine providerseitigen Statusseiten. Es ersetzt auch nicht das Verständnis deiner Plattformarchitektur. Es gibt dir aber einen vollständigen Arbeitsrahmen, damit du nicht planlos einzelne Kommandos ausführst.

1.3. Leitgedanke

Ein Kubernetes-Fehler ist fast nie nur ein Kubernetes-Fehler. Er liegt meistens an einer Schnittstelle:

• Manifest gegen API-Schema,
• gewünschter Zustand gegen tatsächlichen Zustand,
• Scheduler gegen Node-Kapazität,
• Pod gegen Container Runtime,
• Service gegen Labels und Endpoints,
• DNS gegen CoreDNS und Netzwerk,
• Ingress oder Gateway gegen Controller und Load Balancer,
• PVC gegen StorageClass und CSI,
• RBAC gegen Identität,
• Add-on gegen CRDs, Webhooks und Versionen,
• Cloud-Controller gegen IAM, Quotas, Subnetze oder Security Groups.

2. Grundprinzipien für Troubleshooting

2.1. Von außen nach innen prüfen

1. Benutzerpfad: Ist das Problem aus Sicht des Nutzers reproduzierbar?
2. DNS und Routing: Erreicht der Client den richtigen Namen, die richtige IP und den richtigen Port?
3. Ingress, Gateway oder Load Balancer: Kommt Traffic am Cluster an?
4. Service: Hat der Service Endpoints oder EndpointSlices?
5. Pod: Ist der Pod Running und Ready?
6. Container: Startet der Container stabil und hört er auf dem erwarteten Port?
7. Anwendung: Sind Konfiguration, Secrets, Dependencies und Datenzugriff korrekt?
8. Node: Hat der Node Runtime-, CNI-, Storage-, Ressourcen- oder OS-Probleme?
9. Control Plane: Funktionieren API Server, Controller, Scheduler und etcd?
10. Provider: Blockieren Cloud-IAM, Quotas, Subnetze, Firewalls, Routen, Tags oder Limits?

2.2. Erst beobachten, dann ändern

Ändere nicht sofort ein Manifest, nur weil ein Pod fehlschlägt. Sammle zuerst Status, Events, Logs, letzte Änderungen und Umgebungskontext. Ohne Ausgangszustand kannst du später nicht belegen, ob deine Änderung geholfen oder den Fehler nur verschoben hat.

2.3. Ereignisse sind oft wichtiger als Status

kubectl get zeigt dir einen aktuellen Zustand. kubectl describe und kubectl get events zeigen dir, wie Kubernetes zu diesem Zustand gekommen ist. Bei Scheduling-, ImagePull-, Mount-, Probe-, Admission- und Controller-Problemen sind Events häufig die schnellste Fehlerquelle.

2.4. Zwischen Symptom und Ursache trennen

2.5. Minimal reproduzieren

Wenn du nicht weißt, ob das Problem in der App oder in der Plattform liegt, deploye eine minimale Referenz-App und einen Debug-Pod. Funktioniert die Referenz-App, liegt der Fehler wahrscheinlich in App, Manifest, Image, Secret oder Policy. Funktioniert sie nicht, prüfst du Plattformpfad, Netzwerk, DNS, Runtime und Add-ons.

3. Ersttriage in zehn Minuten

Nutze diesen Block, wenn du schnell entscheiden musst, ob du bei Workload, Node, Control Plane, Netzwerk, Storage oder Provider weitermachst.

# 1. Kontext prüfen
kubectl config current-context
kubectl cluster-info
kubectl version

# 2. Clusterzustand grob prüfen
kubectl get nodes -o wide
kubectl get pods -A -o wide --sort-by=.metadata.creationTimestamp
kubectl get events -A --sort-by=.lastTimestamp | tail -100

# 3. Workload und Namespace prüfen
NS=demo
APP=demo
kubectl get all -n "$NS"
kubectl get deploy,rs,sts,ds,job,cronjob -n "$NS"
kubectl get pod -n "$NS" -o wide --show-labels

# 4. Fehlerhafte Pods identifizieren
kubectl get pods -A \
  --field-selector=status.phase!=Running \
  -o wide

# 5. Details, Logs und letzte Logs prüfen
POD=<pod>
kubectl describe pod "$POD" -n "$NS"
kubectl logs "$POD" -n "$NS" --all-containers --tail=200
kubectl logs "$POD" -n "$NS" --all-containers --previous --tail=200

# 6. Netzwerkpfad prüfen
kubectl get svc,endpoints,endpointslices,ingress -n "$NS" -o wide
kubectl get networkpolicy -A

# 7. Storagepfad prüfen
kubectl get storageclass
kubectl get pv,pvc -A

# 8. RBAC prüfen
kubectl auth can-i get pods -n "$NS"
kubectl auth can-i '*' '*' -n "$NS"

3.1. Sofortklassifizierung

4. Entscheidungsbaum

flowchart TD
    A[Problem gemeldet] --> B{kubectl API erreichbar?}
    B -- Nein --> C[Kontext, kubeconfig, VPN, API Server, Provider prüfen]
    B -- Ja --> D{Betrifft es viele Namespaces?}
    D -- Ja --> E{Nodes gesund?}
    E -- Nein --> F[Node, Runtime, CNI, Disk, Zertifikate, Provider]
    E -- Ja --> G{CoreDNS, CNI, CSI oder Admission auffällig?}
    G -- Ja --> H[Add-on Runbook]
    G -- Nein --> I[Control Plane, Quotas, Cloud Limits, globale Policies]
    D -- Nein --> J{Pod vorhanden?}
    J -- Nein --> K[Deployment, ReplicaSet, Job, GitOps, Helm prüfen]
    J -- Ja --> L{Pod Ready?}
    L -- Nein --> M[Scheduling, ImagePull, CrashLoop, Probes, Mounts]
    L -- Ja --> N{Service hat Endpoints?}
    N -- Nein --> O[Labels, Selector, Readiness, EndpointSlices]
    N -- Ja --> P{Traffic erreicht Service?}
    P -- Nein --> Q[DNS, NetworkPolicy, kube-proxy/eBPF, CNI]
    P -- Ja --> R[App, Backend, Datenbank, externe Dependency]

4.1. Datenfluss für HTTP-Probleme

sequenceDiagram
    participant Browser as Browser oder Client
    participant DNS as DNS
    participant LB as Load Balancer
    participant GW as Ingress/Gateway Controller
    participant SVC as Kubernetes Service
    participant EPS as EndpointSlice
    participant Pod as Pod
    participant App as App Container

    Browser->>DNS: Hostname auflösen
    DNS-->>Browser: IP-Adresse
    Browser->>LB: TCP/TLS/HTTP Request
    LB->>GW: Weiterleitung an Controller
    GW->>SVC: Routing nach Host/Path/Route
    SVC->>EPS: Backend-Auswahl
    EPS->>Pod: Pod-IP und Port
    Pod->>App: Container-Port
    App-->>Browser: Antwort oder Fehler

4.2. Regel für schnelle Eingrenzung

• HTTP 404 deutet oft auf falsche Ingress-/Gateway-Route oder falschen Host hin.
• HTTP 503 deutet oft auf fehlende oder nicht bereite Backends hin.
• Connection refused deutet oft auf falschen Port, nicht laufenden Listener oder Node-/Port-Mapping-Problem hin.
• Timeout deutet oft auf Firewall, NetworkPolicy, Route, CNI, Load Balancer oder Providerproblem hin.
• TLS-Fehler deutet oft auf Zertifikat, SNI, Secret, Trust Store oder Controller-Konfiguration hin.

5. Umgebungsmatrix

6. Diagnosewerkzeuge

6.1. Kubernetes-CLI

kubectl version
kubectl cluster-info
kubectl config get-contexts
kubectl api-resources
kubectl api-versions
kubectl explain deployment.spec.template.spec.containers
kubectl get --raw='/readyz?verbose'
kubectl get --raw='/livez?verbose'
kubectl get --raw='/metrics' | head

6.2. Workload-Diagnose

kubectl get pod -A -o wide
kubectl describe pod <pod> -n <namespace>
kubectl logs <pod> -n <namespace> --all-containers --tail=200
kubectl logs <pod> -n <namespace> --all-containers --previous --tail=200
kubectl exec -it <pod> -n <namespace> -- sh
kubectl debug -it <pod> -n <namespace> --image=nicolaka/netshoot --target=<container>

6.3. Node-Diagnose

kubectl describe node <node>
kubectl get events -A --field-selector involvedObject.kind=Node --sort-by=.lastTimestamp
kubectl top nodes
kubectl top pods -A
ssh <node>
systemctl status kubelet containerd crio
journalctl -u kubelet -n 300 --no-pager
journalctl -u containerd -n 300 --no-pager
crictl info
crictl ps -a
crictl pods
crictl logs <container-id>

6.4. Netzwerkdiagnose

kubectl get svc,endpoints,endpointslices -A -o wide
kubectl get ingress -A
kubectl get gateway,httproute -A
kubectl get networkpolicy -A
kubectl run netshoot -n default --rm -it --restart=Never --image=nicolaka/netshoot -- bash
kubectl run dnsutils -n default --rm -it --restart=Never --image=registry.k8s.io/e2e-test-images/agnhost:2.39 -- nslookup kubernetes.default

6.5. Storage-Diagnose

kubectl get storageclass
kubectl get pv,pvc -A -o wide
kubectl describe pvc <pvc> -n <namespace>
kubectl get volumeattachment
kubectl get csidriver
kubectl get pods -A | grep -i csi

6.6. Security-Diagnose

kubectl auth whoami
kubectl auth can-i get pods -n <namespace>
kubectl auth can-i '*' '*' --as system:serviceaccount:<namespace>:<serviceaccount>
kubectl get role,rolebinding -n <namespace>
kubectl get clusterrole,clusterrolebinding
kubectl get validatingwebhookconfiguration,mutatingwebhookconfiguration
kubectl get validatingadmissionpolicy,validatingadmissionpolicybinding

6.7. Linux- und Netzwerktools

ip addr
ip route
ip neigh
ss -tulpn
ss -antp
resolvectl status || cat /etc/resolv.conf
nft list ruleset || iptables-save
journalctl -xe --no-pager
dmesg -T | tail -200
df -h
findmnt
free -m
uptime

6.8. Cloud-CLI

# AWS EKS
aws eks describe-cluster --name <cluster> --region <region>
aws eks update-kubeconfig --name <cluster> --region <region>
aws eks list-addons --cluster-name <cluster>
aws ec2 describe-security-groups --group-ids <sg-id>

# Azure AKS
az aks show -g <resource-group> -n <cluster>
az aks get-credentials -g <resource-group> -n <cluster> --overwrite-existing
az aks nodepool list -g <resource-group> --cluster-name <cluster>
az network nsg rule list -g <resource-group> --nsg-name <nsg>

# Google GKE
gcloud container clusters describe <cluster> --region <region>
gcloud container clusters get-credentials <cluster> --region <region>
gcloud container operations list --region <region>
gcloud compute firewall-rules list

7. Standard-Datensammlung

7.1. Minimaler Support-Bundlesatz

Sammle diese Informationen, bevor du eine Änderung ausführst:

TS=$(date -u +%Y%m%dT%H%M%SZ)
OUT="k8s-debug-$TS"
mkdir -p "$OUT"

kubectl version -o yaml > "$OUT/version.yaml" 2>&1 || true
kubectl cluster-info > "$OUT/cluster-info.txt" 2>&1 || true
kubectl config current-context > "$OUT/current-context.txt" 2>&1 || true
kubectl get nodes -o wide > "$OUT/nodes.txt" 2>&1 || true
kubectl describe nodes > "$OUT/nodes-describe.txt" 2>&1 || true
kubectl get pods -A -o wide > "$OUT/pods-wide.txt" 2>&1 || true
kubectl get events -A --sort-by=.lastTimestamp > "$OUT/events.txt" 2>&1 || true
kubectl get ns -o yaml > "$OUT/namespaces.yaml" 2>&1 || true
kubectl get svc,endpoints,endpointslices -A -o wide > "$OUT/network.txt" 2>&1 || true
kubectl get ingress -A -o yaml > "$OUT/ingress.yaml" 2>&1 || true
kubectl get gateway,httproute -A -o yaml > "$OUT/gateway-api.yaml" 2>&1 || true
kubectl get storageclass,pv,pvc -A -o yaml > "$OUT/storage.yaml" 2>&1 || true
kubectl get networkpolicy -A -o yaml > "$OUT/networkpolicies.yaml" 2>&1 || true
kubectl get validatingwebhookconfiguration,mutatingwebhookconfiguration -o yaml > "$OUT/webhooks.yaml" 2>&1 || true
kubectl get crd > "$OUT/crds.txt" 2>&1 || true

tar -czf "$OUT.tar.gz" "$OUT"
echo "$OUT.tar.gz"

7.2. Namespace-spezifische Sammlung

NS=<namespace>
TS=$(date -u +%Y%m%dT%H%M%SZ)
OUT="k8s-debug-$NS-$TS"
mkdir -p "$OUT"

kubectl get all -n "$NS" -o wide > "$OUT/all-wide.txt" 2>&1 || true
kubectl get all -n "$NS" -o yaml > "$OUT/all.yaml" 2>&1 || true
kubectl get events -n "$NS" --sort-by=.lastTimestamp > "$OUT/events.txt" 2>&1 || true
kubectl get configmap,secret,sa,role,rolebinding -n "$NS" -o yaml > "$OUT/config-security.yaml" 2>&1 || true
kubectl get pvc -n "$NS" -o yaml > "$OUT/pvc.yaml" 2>&1 || true
kubectl get ingress,gateway,httproute,networkpolicy -n "$NS" -o yaml > "$OUT/networking.yaml" 2>&1 || true

for pod in $(kubectl get pod -n "$NS" -o name | sed 's#pod/##'); do
  kubectl describe pod "$pod" -n "$NS" > "$OUT/pod-$pod-describe.txt" 2>&1 || true
  kubectl logs "$pod" -n "$NS" --all-containers --tail=500 > "$OUT/pod-$pod-logs.txt" 2>&1 || true
  kubectl logs "$pod" -n "$NS" --all-containers --previous --tail=500 > "$OUT/pod-$pod-logs-previous.txt" 2>&1 || true
done

tar -czf "$OUT.tar.gz" "$OUT"

7.3. Was du nicht unkontrolliert sammeln solltest

• Secrets im Klartext,
• produktive Tokens,
• vollständige kubeconfigs mit Client-Zertifikaten,
• personenbezogene Daten aus Logs,
• Datenbankdumps,
• TLS-Private-Keys,
• Kundennamen und interne Hostnamen, wenn das Bundle extern weitergegeben wird.

7.4. Redaction vor Weitergabe

# Vorsicht: immer an einer Kopie arbeiten.
cp -r k8s-debug-<timestamp> k8s-debug-redacted
find k8s-debug-redacted -type f -name '*.yaml' -o -name '*.txt' | while read -r f; do
  sed -i \
    -e 's/[A-Za-z0-9_\.-]*@[A-Za-z0-9_\.-]*/REDACTED_EMAIL/g' \
    -e 's/password:.*/password: REDACTED/g' \
    -e 's/token:.*/token: REDACTED/g' \
    -e 's/client-key-data:.*/client-key-data: REDACTED/g' \
    "$f"
done

8. Sicherheits- und Beweissicherung

8.1. Bei möglichem Security Incident

Wenn du einen Security Incident vermutest, stabilisierst du nicht nur technisch. Du sicherst Beweise und minimierst Veränderung am kompromittierten System.

1. Incident-ID erzeugen.
2. Zeitpunkt, Melder, Symptome und Scope dokumentieren.
3. Betroffene Namespaces, Pods, Nodes, ServiceAccounts und Images erfassen.
4. Logs, Events, Audit-Logs und Container-Metadaten sichern.
5. Netzwerkzugriff begrenzen, ohne Beweise zu vernichten.
6. Tokens und Secrets rotieren, wenn Missbrauch wahrscheinlich ist.
7. Workload neu aus vertrauenswürdiger Quelle ausrollen.
8. Policy-Lücke schließen.

8.2. Keine blinde Bereinigung

Führe bei einem verdächtigen Pod nicht sofort kubectl delete pod aus, wenn forensische Informationen wichtig sind. Sammle zuerst:

NS=<namespace>
POD=<pod>
kubectl get pod "$POD" -n "$NS" -o yaml > incident-pod.yaml
kubectl describe pod "$POD" -n "$NS" > incident-pod-describe.txt
kubectl logs "$POD" -n "$NS" --all-containers --timestamps --tail=-1 > incident-pod-logs.txt
kubectl logs "$POD" -n "$NS" --all-containers --previous --timestamps --tail=-1 > incident-pod-logs-previous.txt
kubectl get events -n "$NS" --sort-by=.lastTimestamp > incident-events.txt
kubectl get sa,role,rolebinding -n "$NS" -o yaml > incident-rbac.yaml

8.3. Isolieren statt löschen

Bei aktivem Missbrauch kannst du eine restriktive NetworkPolicy anwenden, den Service selector entfernen oder den Deployment-Replica-Count auf null setzen. Welche Maßnahme passt, hängt davon ab, ob Verfügbarkeit oder Beweissicherung wichtiger ist.

# Schnelle Isolation eines Namespace, wenn dein CNI NetworkPolicies durchsetzt.
kubectl apply -n <namespace> -f - <<'EOF'
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: emergency-default-deny
spec:
  podSelector: {}
  policyTypes:
    - Ingress
    - Egress
EOF

9. API-, kubeconfig- und kubectl-Probleme

9.1. kubectl nutzt den falschen Kontext

Symptome

• Ressourcen fehlen angeblich.
• Du arbeitest im falschen Cluster.
• kubectl zeigt alte Clusterinformationen.

Diagnose

kubectl config get-contexts
kubectl config current-context
kubectl config view --minify
kubectl cluster-info

Maßnahmen

kubectl config use-context <context>
kubectl config set-context --current --namespace=<namespace>

Validierung

kubectl get ns
kubectl auth whoami

9.2. API Server nicht erreichbar

Symptome

• Unable to connect to the server.
• i/o timeout.
• connection refused.
• x509: certificate signed by unknown authority.

Diagnose

kubectl cluster-info
kubectl get --raw='/readyz?verbose'
kubectl config view --minify --raw
curl -k https://<api-server>:6443/readyz
nc -vz <api-server> 6443

Bei kubeadm-Control-Plane:

sudo crictl ps -a | grep kube-apiserver
sudo crictl logs <apiserver-container-id>
sudo journalctl -u kubelet -n 300 --no-pager
sudo ls -l /etc/kubernetes/manifests/

Häufige Ursachen

• falsche kubeconfig,
• VPN oder Firewall blockiert,
• API Server Pod startet nicht,
• Zertifikat abgelaufen,
• Load-Balancer-Endpoint falsch,
• Cloud-Control-Plane nicht verfügbar,
• lokale kind/minikube/k3d-Container gestoppt.

9.3. API ist langsam

Diagnose

kubectl get --raw='/readyz?verbose'
kubectl get --raw='/metrics' | grep -E 'apiserver_request_duration|apiserver_current_inflight_requests' | head -50
kubectl get events -A --sort-by=.lastTimestamp | tail -100

Ursachen

• zu viele Watcher,
• langsame oder blockierende Admission Webhooks,
• etcd-Latenz,
• API-Priority-and-Fairness-Drosselung,
• große CRDs oder Controller mit zu vielen Requeues,
• Cloud-API-Rate-Limits.

9.4. kubectl apply schlägt wegen Schema oder Admission fehl

kubectl apply --server-side --dry-run=server -f manifest.yaml
kubectl diff -f manifest.yaml
kubectl explain <kind>.spec
kubectl get validatingwebhookconfiguration,mutatingwebhookconfiguration
kubectl get events -A --sort-by=.lastTimestamp | tail -50

Wenn die Fehlermeldung von einem Webhook kommt, prüfst du den Webhook-Service:

kubectl get validatingwebhookconfiguration <name> -o yaml
kubectl get svc,endpoints -n <webhook-namespace>
kubectl logs -n <webhook-namespace> deploy/<webhook-deployment>

10. Workload-Troubleshooting

10.1. Pod-Zustände verstehen

10.2. Logs richtig lesen

# Aktuelle Logs
kubectl logs <pod> -n <namespace> --all-containers --tail=200

# Logs des vorherigen Containerstarts
kubectl logs <pod> -n <namespace> --all-containers --previous --tail=200

# Logs eines Deployments
kubectl logs deploy/<deployment> -n <namespace> --all-containers --tail=200

# Logs mit Zeitstempeln
kubectl logs <pod> -n <namespace> --timestamps --all-containers

10.3. Exit Codes

10.4. Container startet lokal, aber nicht in Kubernetes

Prüfe Unterschiede zwischen lokalem Docker-Run und Kubernetes:

• Environment Variables,
• Working Directory,
• Entrypoint und Args,
• User und Dateirechte,
• read-only Root Filesystem,
• Capabilities,
• Secrets und ConfigMaps,
• Service DNS,
• Netzwerkpolicy,
• Ressourcenlimits,
• Zeitzone und Locale,
• Architektur des Images (amd64, arm64).

kubectl get pod <pod> -n <namespace> -o jsonpath='{.spec.containers[*].image}{"\n"}'
kubectl get pod <pod> -n <namespace> -o yaml | sed -n '/containers:/,/volumes:/p'
kubectl exec -it <pod> -n <namespace> -- env | sort
kubectl exec -it <pod> -n <namespace> -- id
kubectl exec -it <pod> -n <namespace> -- pwd
kubectl exec -it <pod> -n <namespace> -- ls -la

10.5. Ephemeral Debug Container

Wenn ein Image kein Shell-Tool enthält, nutzt du kubectl debug:

kubectl debug -it pod/<pod> -n <namespace> \
  --image=nicolaka/netshoot \
  --target=<container> \
  -- bash

Nicht jeder Cluster erlaubt Ephemeral Containers. Admission Policies, Pod Security, RBAC oder alte Kubernetes-Versionen können das blockieren.

11. Scheduling-, Ressourcen- und Autoscaling-Probleme

11.1. Scheduler-Events lesen

kubectl describe pod <pod> -n <namespace> | sed -n '/Events:/,$p'
kubectl get events -n <namespace> --sort-by=.lastTimestamp | grep -i -E 'FailedScheduling|Insufficient|taint|affinity|preempt'

11.2. Ressourcenlage prüfen

kubectl top nodes
kubectl top pods -A --sort-by=cpu
kubectl top pods -A --sort-by=memory
kubectl describe node <node> | sed -n '/Allocated resources:/,/Events:/p'
kubectl get resourcequota,limitrange -A

11.3. Häufige Scheduling-Ursachen

11.4. HPA skaliert nicht

kubectl get hpa -A
kubectl describe hpa <hpa> -n <namespace>
kubectl top pod -n <namespace>
kubectl get apiservice v1beta1.metrics.k8s.io -o yaml
kubectl logs -n kube-system deploy/metrics-server --tail=200

Ursachen:

• Metrics Server fehlt oder ist nicht bereit,
• Pods haben keine CPU-Requests,
• HPA-Metrik ist falsch referenziert,
• Custom Metrics Adapter fehlt,
• stabilizationWindowSeconds verzögert Skalierung,
• Cluster Autoscaler kann keine Nodes ergänzen,
• PodDisruptionBudget oder Quota blockieren indirekt.

11.5. Cluster Autoscaler oder Node Autoscaling reagiert nicht

Prüfe:

kubectl -n kube-system get deploy | grep -i autoscaler
kubectl -n kube-system logs deploy/cluster-autoscaler --tail=300
kubectl get pods -A | grep Pending
kubectl describe pod <pending-pod> -n <namespace>

Cloud-spezifisch:

• AWS: Auto Scaling Group, Launch Template, IAM, Subnetze, Tags.
• Azure: VMSS, Quotas, Node-Pool-Modus, Zonen.
• GCP: Instance Group, Quotas, Reservations, Autopilot-Constraints.

12. Netzwerk-, DNS-, Service-, Ingress- und Gateway-Probleme

12.1. Netzwerkpfad systematisch prüfen

NS=<namespace>
APP=<app-label>
SVC=<service>

kubectl get pod -n "$NS" -l app="$APP" -o wide --show-labels
kubectl get svc "$SVC" -n "$NS" -o wide
kubectl get endpoints "$SVC" -n "$NS" -o yaml
kubectl get endpointslices -n "$NS" -l kubernetes.io/service-name="$SVC" -o yaml
kubectl get networkpolicy -n "$NS" -o yaml

12.2. Service ohne Endpoints

Ein Service routet nicht zu Pods, wenn sein Selector keine passenden und bereiten Pods findet.

kubectl get svc <service> -n <namespace> -o yaml | yq '.spec.selector'
kubectl get pods -n <namespace> --show-labels
kubectl get endpoints <service> -n <namespace>
kubectl describe pod <pod> -n <namespace> | grep -A20 Conditions

Prüfe:

• Labels passen exakt zu Selector?
• Pods sind Ready?
• Service-Port und targetPort korrekt?
• Named Port existiert im Pod?
• EndpointSlices werden durch Controller erzeugt?

12.3. DNS prüfen

kubectl run dnsutils -n default --rm -it --restart=Never \
  --image=registry.k8s.io/e2e-test-images/agnhost:2.39 \
  -- nslookup kubernetes.default

kubectl run netshoot -n default --rm -it --restart=Never \
  --image=nicolaka/netshoot -- bash

# Im Debug-Pod:
cat /etc/resolv.conf
nslookup kubernetes.default.svc.cluster.local
nslookup <service>.<namespace>.svc.cluster.local
dig <service>.<namespace>.svc.cluster.local

CoreDNS prüfen:

kubectl -n kube-system get deploy,po,svc,endpoints -l k8s-app=kube-dns
kubectl -n kube-system logs deploy/coredns --tail=200
kubectl -n kube-system get configmap coredns -o yaml

12.4. NetworkPolicy blockiert Traffic

Prüfe zuerst, ob dein CNI NetworkPolicies überhaupt durchsetzt. Ohne unterstützendes CNI ist eine NetworkPolicy nur ein API-Objekt ohne Enforcement.

kubectl get networkpolicy -A
kubectl describe networkpolicy <policy> -n <namespace>
kubectl get pod -n <namespace> --show-labels

Typische Fehler:

• Default-Deny ohne DNS-Egress-Ausnahme,
• falscher podSelector,
• falscher namespaceSelector,
• Labels fehlen,
• Egress zu externen APIs fehlt,
• Service Mesh mTLS und NetworkPolicy widersprechen sich,
• Policy wurde in falschem Namespace angelegt.

12.5. Ingress funktioniert nicht

kubectl get ingress -A
kubectl describe ingress <ingress> -n <namespace>
kubectl get ingressclass
kubectl get svc,endpoints -n <namespace>
kubectl logs -n ingress-nginx deploy/ingress-nginx-controller --tail=300
curl -v -H 'Host: <host>' http://<ingress-ip>/<path>

Prüfe:

• Ingress Controller läuft?
• ingressClassName passt?
• DNS zeigt auf richtige IP?
• Host und Path passen zur Anfrage?
• Service-Port verweist auf existierenden Port?
• TLS Secret liegt im selben Namespace wie Ingress?
• Load Balancer oder NodePort ist erreichbar?

12.6. Gateway API funktioniert nicht

kubectl get gatewayclass,gateway,httproute,grpcroutes,tlsroute -A
kubectl describe gateway <gateway> -n <namespace>
kubectl describe httproute <route> -n <namespace>
kubectl get events -A --sort-by=.lastTimestamp | grep -i -E 'gateway|route|listener|accepted|resolved'

Prüfe Conditions:

• Accepted,
• Programmed,
• ResolvedRefs,
• Listener-Konflikte,
• falsche parentRefs,
• Cross-Namespace-Referenzen ohne ReferenceGrant,
• GatewayClass ohne Controller.

12.7. MTU- und Fragmentierungsprobleme

Symptome:

• kleine Requests funktionieren, große Requests hängen,
• TLS Handshake bricht ab,
• Service Mesh zeigt sporadische Timeouts,
• nur bestimmte Node-zu-Node-Pfade betroffen.

Diagnose:

ip link
ping -M do -s 1472 <ziel-ip>
tracepath <ziel-ip>
kubectl run netshoot --rm -it --image=nicolaka/netshoot -- bash

Prüfe Overlay-CNI, VPN, Cloud-VPC, WireGuard, VXLAN, Geneve, IPsec und Provider-Limits.

13. Storage-, CSI- und Datenprobleme

13.1. PVC bleibt Pending

kubectl get pvc -n <namespace>
kubectl describe pvc <pvc> -n <namespace>
kubectl get storageclass -o yaml
kubectl get events -n <namespace> --sort-by=.lastTimestamp

Ursachen:

• keine Default-StorageClass,
• falscher storageClassName,
• dynamische Provisionierung nicht verfügbar,
• CSI Controller läuft nicht,
• Cloud-Quota erschöpft,
• Zone/Topology passt nicht,
• AccessMode nicht unterstützt,
• VolumeBindingMode WaitForFirstConsumer wartet auf Scheduling.

13.2. Pod hängt in ContainerCreating wegen Mount

kubectl describe pod <pod> -n <namespace> | sed -n '/Events:/,$p'
kubectl describe pvc <pvc> -n <namespace>
kubectl get pv <pv> -o yaml
kubectl get volumeattachment
kubectl get pods -A | grep -i csi

Achte auf Events wie:

• FailedMount,
• Unable to attach or mount volumes,
• Multi-Attach error,
• timed out waiting for the condition,
• permission denied,
• no such file or directory.

13.3. Multi-Attach-Fehler

Ein RWO-Volume kann oft nicht gleichzeitig auf mehreren Nodes read-write gemountet werden.

kubectl get pod -n <namespace> -o wide | grep <app>
kubectl get volumeattachment | grep <pv>
kubectl describe volumeattachment <name>

Maßnahmen:

• Workload kontrolliert auf einen Node verschieben,
• hängende Attachments prüfen,
• StatefulSet statt Deployment verwenden,
• AccessMode und StorageBackend prüfen,
• im Notfall Provider-spezifisches Detach nur nach Datenkonsistenzprüfung.

13.4. Daten sind nach Pod-Neustart weg

Prüfe, ob du wirklich Persistenz nutzt:

kubectl get pod <pod> -n <namespace> -o yaml | yq '.spec.volumes'
kubectl get pvc -n <namespace>

Typische Ursachen:

• emptyDir statt PVC,
• lokale Pfade in Container-Filesystem,
• StatefulSet ohne volumeClaimTemplates,
• Helm-Werte deaktivieren Persistenz,
• falscher Namespace geprüft,
• Restore in falschen Cluster erfolgt.

13.5. CSI-Controller oder Node-Plugin defekt

kubectl get csidriver
kubectl get pods -A | grep -i csi
kubectl logs -n <csi-namespace> deploy/<csi-controller> --tail=300
kubectl logs -n <csi-namespace> ds/<csi-node> --tail=300
kubectl get events -A --sort-by=.lastTimestamp | grep -i csi

Prüfe Cloud-IAM, Secret für Storage-Backend, Node-Permissions, Kernel-Module, Multipath, NFS-Erreichbarkeit, iSCSI, Ceph-Monitore, Longhorn-Engine, Rook-Ceph-Status oder Provider-Quota.

14. Node-, Runtime- und Betriebssystemprobleme

14.1. Node NotReady

kubectl get nodes -o wide
kubectl describe node <node>
kubectl get events -A --field-selector involvedObject.kind=Node --sort-by=.lastTimestamp

Auf dem Node:

systemctl status kubelet --no-pager
journalctl -u kubelet -n 300 --no-pager
systemctl status containerd crio docker --no-pager
journalctl -u containerd -n 300 --no-pager
crictl info
crictl ps -a
ip addr
ip route
df -h
free -m

14.2. Node Conditions

14.3. Container Runtime defekt

sudo crictl info
sudo crictl ps -a
sudo crictl images
sudo crictl pods
sudo journalctl -u containerd -n 300 --no-pager
sudo journalctl -u crio -n 300 --no-pager

Maßnahmen:

• Runtime-Service neu starten, wenn sicher vertretbar,
• Disk säubern,
• Image-Pull-Probleme lösen,
• Registry-Mirror prüfen,
• cgroup-Treiber-Konsistenz zwischen kubelet und Runtime prüfen,
• Kernel- und OverlayFS-Probleme prüfen.

14.4. DiskPressure beheben

df -h
df -ih
sudo du -xh /var/lib/containerd /var/log /var/lib/kubelet 2>/dev/null | sort -h | tail -40
sudo crictl images
sudo crictl ps -a

Sichere Maßnahmen:

# Nur ungenutzte Images löschen; vorher Impact prüfen.
sudo crictl rmi --prune
sudo journalctl --vacuum-time=7d

Nicht blind löschen:

• /var/lib/kubelet/pods,
• Datenverzeichnisse von CSI/Longhorn/Rook,
• etcd-Datenverzeichnis,
• produktive App-Daten.

14.5. CNI auf dem Node defekt

Symptome:

• Pods bleiben in ContainerCreating,
• FailedCreatePodSandBox,
• Node NetworkUnavailable,
• Pod-zu-Pod-Traffic gestört,
• DNS-Time-outs.

kubectl get pods -A -o wide | grep -i -E 'calico|cilium|flannel|weave|antrea|canal'
ls -l /etc/cni/net.d/
ls -l /opt/cni/bin/
journalctl -u kubelet -n 300 --no-pager | grep -i cni

14.6. Zeit- und NTP-Probleme

Zeitversatz verursacht TLS-, Token-, Lease-, etcd- und TTL-Probleme.

timedatectl
chronyc tracking || true
journalctl -u systemd-timesyncd -n 100 --no-pager || true

Symptome:

• Zertifikate erscheinen noch nicht gültig oder abgelaufen,
• Nodes erneuern Leases nicht sauber,
• Jobs werden unerwartet bereinigt,
• etcd-Wahlen häufen sich,
• OIDC-Token werden abgelehnt.

15. Control-Plane-, etcd- und kubeadm-Probleme

15.1. kubeadm-Control-Plane prüfen

sudo ls -l /etc/kubernetes/manifests
sudo crictl ps -a | grep -E 'kube-apiserver|kube-controller-manager|kube-scheduler|etcd'
sudo crictl logs <container-id>
sudo journalctl -u kubelet -n 500 --no-pager
kubectl get componentstatuses 2>/dev/null || true
kubectl get --raw='/readyz?verbose'
kubectl get --raw='/livez?verbose'

15.2. Static Pods starten nicht

Static Pods werden vom kubelet aus /etc/kubernetes/manifests gelesen. Wenn API Server oder etcd nicht starten, prüfe:

• YAML-Syntax,
• Zertifikatspfade,
• HostPath-Mounts,
• Datei- und Verzeichnisrechte,
• etcd-Datenverzeichnis,
• Port-Konflikte,
• Node-Zeit,
• Container Runtime.

15.3. etcd ist nicht gesund

export ETCDCTL_API=3
sudo etcdctl \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  endpoint health

sudo etcdctl \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  endpoint status --write-out=table

Prüfe:

• Quorum,
• Disk-Latenz,
• verfügbare Inodes,
• Zertifikate,
• Netzwerk zwischen Control-Plane-Nodes,
• Snapshots und Datenverzeichnis,
• Uhrzeit.

15.4. Zertifikate abgelaufen

sudo kubeadm certs check-expiration
sudo openssl x509 -in /etc/kubernetes/pki/apiserver.crt -noout -dates

Maßnahmen bei kubeadm:

sudo kubeadm certs renew all
sudo systemctl restart kubelet

Danach kubeconfigs prüfen und ggf. neu verteilen:

sudo kubeadm kubeconfig user --client-name kubernetes-admin > admin.conf

15.5. kubeadm-Upgrade fehlgeschlagen

kubeadm upgrade plan
kubectl get nodes
kubectl drain <node> --ignore-daemonsets --delete-emptydir-data
sudo apt-mark unhold kubeadm kubelet kubectl
sudo apt-get update
sudo apt-get install -y kubeadm=<version>
sudo kubeadm upgrade apply <version>
sudo apt-get install -y kubelet=<version> kubectl=<version>
sudo systemctl daemon-reload
sudo systemctl restart kubelet
kubectl uncordon <node>

Wichtig:

• Minor-Versionen nicht überspringen.
• Erst Control Plane, dann Worker Nodes.
• Vorher etcd-Backup erstellen.
• CNI-, CSI- und Add-on-Kompatibilität prüfen.
• Version-Skew beachten.

15.6. Scheduler scheduled nicht

kubectl -n kube-system get pod -l component=kube-scheduler -o wide
kubectl -n kube-system logs -l component=kube-scheduler --tail=300
kubectl get events -A --sort-by=.lastTimestamp | grep -i scheduling

Bei statischem kubeadm-Scheduler:

sudo crictl ps -a | grep kube-scheduler
sudo crictl logs <scheduler-container-id>
sudo cat /etc/kubernetes/manifests/kube-scheduler.yaml

16. Add-on-, Operator-, Helm- und GitOps-Probleme

16.1. Add-on-Grundcheck

kubectl get pods -A | grep -E 'coredns|metrics-server|ingress|gateway|cert-manager|external-dns|prometheus|grafana|loki|argocd|flux|calico|cilium|flannel|rook|longhorn|velero'
kubectl get crd | grep -E 'cert-manager|gateway|prometheus|argoproj|fluxcd|kyverno|cilium|rook|longhorn|velero'
kubectl get events -A --sort-by=.lastTimestamp | tail -200

16.2. CRD fehlt oder Version passt nicht

Symptome:

• no matches for kind,
• Helm-Install schlägt fehl,
• Controller verarbeitet Ressourcen nicht,
• GitOps meldet dry-run failed.

Diagnose:

kubectl api-resources | grep -i <kind>
kubectl get crd | grep -i <domain>
kubectl explain <kind> --api-version=<group>/<version>

16.3. Helm-Release fehlgeschlagen

helm list -A
helm status <release> -n <namespace>
helm history <release> -n <namespace>
helm get values <release> -n <namespace>
helm get manifest <release> -n <namespace>
helm template <release> <chart> -n <namespace> -f values.yaml > rendered.yaml
kubectl apply --dry-run=server -f rendered.yaml

Maßnahmen:

helm rollback <release> <revision> -n <namespace>
helm upgrade --install <release> <chart> -n <namespace> -f values.yaml --atomic --timeout 10m

16.4. Argo CD Sync oder Health fehlerhaft

kubectl -n argocd get applications.argoproj.io
kubectl -n argocd describe application <app>
kubectl -n argocd logs deploy/argocd-application-controller --tail=300
kubectl -n argocd logs deploy/argocd-repo-server --tail=300
argocd app get <app>
argocd app diff <app>
argocd app sync <app> --dry-run

Prüfe:

• Repo-Zugriff,
• Pfad und Branch,
• Helm/Kustomize-Werte,
• CRD-Reihenfolge,
• Namespace-Erstellung,
• Sync Waves,
• Resource Hooks,
• RBAC der Argo-CD-Controller-Identität,
• Drift durch manuelle Änderungen.

16.5. Flux-Reconciliation fehlerhaft

flux get sources all -A
flux get kustomizations -A
flux get helmreleases -A
flux logs --all-namespaces --tail=200
kubectl -n flux-system logs deploy/source-controller --tail=200
kubectl -n flux-system logs deploy/kustomize-controller --tail=200
kubectl -n flux-system logs deploy/helm-controller --tail=200

16.6. cert-manager stellt kein Zertifikat aus

kubectl get certificate,certificaterequest,order,challenge -A
kubectl describe certificate <cert> -n <namespace>
kubectl describe challenge <challenge> -n <namespace>
kubectl logs -n cert-manager deploy/cert-manager --tail=300

Prüfe:

• Issuer/ClusterIssuer Ready,
• DNS-01/HTTP-01-Erreichbarkeit,
• IngressClass,
• ACME-Rate-Limits,
• Secret-Namespace,
• Clock-Skew,
• externe DNS-Zone und Credentials.

17. Security-, RBAC-, Admission- und Secret-Probleme

17.1. Forbidden systematisch debuggen

kubectl auth whoami
kubectl auth can-i <verb> <resource> -n <namespace>
kubectl auth can-i <verb> <resource> -n <namespace> --as <user-or-serviceaccount>
kubectl get role,rolebinding -n <namespace> -o yaml
kubectl get clusterrole,clusterrolebinding -o yaml

ServiceAccount-Format:

kubectl auth can-i get pods -n demo --as system:serviceaccount:demo:app

Prüfe:

• Role existiert?
• RoleBinding bindet richtige Identität?
• Namespace stimmt?
• ClusterRoleBinding nötig oder zu breit?
• Ressource liegt in API-Gruppe?
• Subresource benötigt, etwa pods/log, pods/exec, deployments/scale?

17.2. Admission Webhook blockiert Ressourcen

kubectl get validatingwebhookconfiguration,mutatingwebhookconfiguration
kubectl describe validatingwebhookconfiguration <name>
kubectl get svc,endpoints -n <webhook-namespace>
kubectl logs -n <webhook-namespace> deploy/<webhook-controller> --tail=300
kubectl get events -A --sort-by=.lastTimestamp | grep -i webhook

Typische Fehler:

• Webhook-Service hat keine Endpoints,
• CA Bundle falsch,
• Timeout zu niedrig,
• failurePolicy: Fail blockiert bei Ausfall,
• Webhook matcht zu viele Ressourcen,
• NetworkPolicy blockiert API Server zum Webhook,
• Zertifikat des Webhooks abgelaufen.

17.3. Pod Security Admission blockiert Pod

kubectl get ns <namespace> --show-labels
kubectl describe pod <pod> -n <namespace>
kubectl get events -n <namespace> --sort-by=.lastTimestamp | grep -i 'podsecurity\|restricted\|baseline'

Prüfe Felder wie:

• runAsNonRoot,
• allowPrivilegeEscalation,
• capabilities.drop,
• seccompProfile,
• hostNetwork, hostPID, hostIPC,
• privileged,
• hostPath,
• readOnlyRootFilesystem.

17.4. Secret fehlt oder falscher Key

kubectl get secret -n <namespace>
kubectl describe pod <pod> -n <namespace> | grep -A20 -i secret
kubectl get secret <secret> -n <namespace> -o jsonpath='{.data}'

Fehlerbilder:

• CreateContainerConfigError,
• secret not found,
• couldn't find key,
• App startet, aber meldet Authentifizierungsfehler,
• Helm hat Secret in anderem Namespace erstellt,
• External Secrets Operator hat Sync-Fehler.

17.5. Image-Signatur oder Policy blockiert Rollout

Prüfe Kyverno, Gatekeeper, Sigstore/Cosign-Verifikation oder eigene Admission-Controller:

kubectl get clusterpolicy,policy -A 2>/dev/null || true
kubectl get constrainttemplates,constraints -A 2>/dev/null || true
kubectl get events -A --sort-by=.lastTimestamp | grep -i -E 'policy|admission|cosign|signature|verify'

18. Observability-, Monitoring-, Logging- und Alerting-Probleme

18.1. Metriken fehlen

kubectl top nodes
kubectl top pods -A
kubectl get apiservice | grep metrics
kubectl describe apiservice v1beta1.metrics.k8s.io
kubectl -n kube-system logs deploy/metrics-server --tail=300

Ursachen:

• Metrics Server fehlt,
• kubelet TLS oder Auth blockiert,
• Nodes nicht erreichbar,
• Aggregated APIService nicht verfügbar,
• Firewall blockiert Port 10250,
• Zertifikat passt nicht,
• Managed-Provider hat eigenes Monitoring anders konfiguriert.

18.2. Prometheus scraped Targets nicht

kubectl -n monitoring get pod,svc,servicemonitor,podmonitor,prometheusrule
kubectl -n monitoring port-forward svc/prometheus-operated 9090:9090

Prüfe in Prometheus:

• Status > Targets,
• ServiceMonitor-Label-Selector,
• Namespace-Selector,
• Port-Name im Service,
• TLS- und Auth-Einstellungen,
• NetworkPolicy,
• RBAC für Prometheus.

18.3. Grafana zeigt keine Daten

kubectl -n monitoring get pod,svc,secret,configmap | grep -i grafana
kubectl -n monitoring logs deploy/grafana --tail=200

Prüfe:

• Datasource-URL,
• Service-Name,
• Auth Secret,
• TLS Trust,
• Dashboards ConfigMaps,
• Zeitbereich im Dashboard,
• PromQL-Query.

18.4. Logs fehlen

kubectl get pods -A | grep -i -E 'fluent|promtail|alloy|vector|otel|loki|elastic|opensearch'
kubectl logs -n <logging-namespace> ds/<agent> --tail=300
kubectl logs -n <logging-namespace> deploy/<backend> --tail=300

Prüfe:

• schreibt die App auf stdout/stderr?
• Node-Agent läuft auf allen Nodes?
• Log-Pfad der Runtime passt?
• RBAC des Agents reicht?
• Backend erreichbar?
• Tenant, Label, Index oder Stream falsch?
• Retention löscht früher als erwartet?
• Cloud Logging API oder Agent deaktiviert?

18.5. Alerts feuern nicht

kubectl -n monitoring get prometheusrule,alertmanagerconfig
kubectl -n monitoring logs deploy/alertmanager-main --tail=200 2>/dev/null || true
kubectl -n monitoring logs statefulset/alertmanager-main --tail=200 2>/dev/null || true

Prüfe:

• PrometheusRule wird geladen?
• Expression liefert Daten?
• for-Dauer noch nicht abgelaufen?
• Alertmanager-Routing passt?
• Silence aktiv?
• Inhibition unterdrückt Alarm?
• Receiver-Secret korrekt?
• Egress zu Slack, Teams, PagerDuty oder SMTP erlaubt?

19. Backup-, Restore- und Disaster-Recovery-Probleme

19.1. Backup-Fähigkeit prüfen

Kubernetes-Backup besteht aus mehreren Schichten:

19.2. Velero-Backup fehlerhaft

velero backup get
velero backup describe <backup> --details
velero backup logs <backup>
velero restore get
velero restore describe <restore> --details
kubectl -n velero logs deploy/velero --tail=300

Prüfe:

• Object-Storage-Credentials,
• Bucket/Container erreichbar,
• Volume-Snapshot-Plugin installiert,
• CRDs vorhanden,
• Namespace-Filter,
• Resource-Excludes,
• Restic/Kopia Node Agent,
• Cloud-API-Quotas,
• IAM/RBAC.

19.3. etcd-Restore schlägt fehl

Prüfe vor dem Restore:

• Snapshot-Integrität,
• Kubernetes-Version,
• etcd-Version,
• Cluster-ID und Member-ID,
• Zertifikate,
• Datenverzeichnis,
• Static-Pod-Manifeste,
• Quorum-Plan.

ETCDCTL_API=3 etcdctl snapshot status snapshot.db --write-out=table

Restore ist eine kontrollierte Wiederherstellung, kein Live-Fix. In HA-Clustern brauchst du einen konsistenten Plan für alle Control-Plane-Nodes.

19.4. Restore erfolgreich, aber App funktioniert nicht

Prüfe:

• CRDs vor CRs wiederhergestellt?
• Secrets im richtigen Namespace?
• ServiceAccount-Tokens neu generiert?
• PVs korrekt gebunden?
• DNS- und Ingress-Namen zeigen auf neuen Cluster?
• ExternalDNS hat Records aktualisiert?
• Zertifikate und Issuer funktionieren?
• Datenbankmigrationen kompatibel?
• App erwartet alte Cluster-IP oder Node-IP?

20. Upgrade-, Patch- und Wartungsprobleme

20.1. Upgrade-Vorprüfung

kubectl get nodes -o wide
kubectl get pods -A -o wide
kubectl get pdb -A
kubectl get apiservice
kubectl get crd
kubectl get events -A --sort-by=.lastTimestamp | tail -100
kubectl api-resources --verbs=list -o name | xargs -n 1 kubectl get --ignore-not-found -A >/dev/null

Prüfe zusätzlich:

• Version-Skew,
• deprecated APIs,
• CNI/CSI/Ingress-Kompatibilität,
• Add-on-Versionen,
• Webhooks,
• PDBs,
• Node-Kapazität für Drain,
• Backup-Status,
• Rollback- oder Ersatzcluster-Strategie.

20.2. Drain hängt

kubectl drain <node> --ignore-daemonsets --delete-emptydir-data --timeout=10m
kubectl get pods -A -o wide --field-selector spec.nodeName=<node>
kubectl get pdb -A
kubectl describe pdb <pdb> -n <namespace>

Ursachen:

• PodDisruptionBudget erlaubt keine Eviction,
• Singleton-Pod ohne Replikat,
• lokaler emptyDir-State,
• DaemonSet ignorieren vergessen,
• StatefulSet kann nicht umziehen,
• finalizer blockiert Löschung,
• toleration hält Pod auf dem Node.

20.3. CNI-Upgrade bricht Netzwerk

Vorher:

kubectl get nodes -o wide
kubectl get pods -A -o wide | grep -i -E 'cilium|calico|flannel|antrea|canal'
kubectl get networkpolicy -A

Während/nachher:

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -200
kubectl run netshoot --rm -it --image=nicolaka/netshoot -- bash

Validiere:

• Pod-zu-Service,
• Pod-zu-Pod über Nodes,
• DNS,
• NetworkPolicy-Enforcement,
• NodePort/LoadBalancer,
• Ingress/Gateway,
• Service Mesh.

20.4. API-Deprecations

kubectl api-resources
kubectl get --raw /metrics | grep apiserver_requested_deprecated_apis || true

Nutze außerdem Manifest-Scanning in CI:

kubectl apply --dry-run=server -f manifests/
pluto detect-files -d manifests/ 2>/dev/null || true
kubent 2>/dev/null || true

21. Umgebungsspezifisches Troubleshooting

21.1. WSL2 unter Windows 11

WSL-Probleme liegen oft nicht in Kubernetes selbst, sondern in der Kombination aus Windows-Host, WSL-Distribution, Docker Desktop, NAT/Mirrored Networking, Firewall, DNS und Hosts-Datei.

21.1.1. Grundcheck

PowerShell:

wsl -l -v
wsl --status
wsl --version
docker version
docker context ls
Test-NetConnection localhost -Port 80
Get-Content C:\Windows\System32\drivers\etc\hosts

WSL:

uname -a
cat /etc/os-release
cat /etc/wsl.conf
cat /mnt/c/Users/$USER/.wslconfig 2>/dev/null || true
ip addr
ip route
cat /etc/resolv.conf
ss -tulpn
docker version
docker context ls
kubectl config get-contexts

21.1.2. Edge erreicht lokale Endpunkte nicht

Wenn Edge auf Windows läuft, müssen Hostname und Port aus Windows erreichbar sein. Ein Hostname nur in /etc/hosts innerhalb von WSL hilft Edge nicht.

Prüfe Windows-Hosts-Datei aus WSL:

sudo powershell.exe -Command "Start-Process notepad C:\\Windows\\System32\\drivers\\etc\\hosts -Verb runAs"
cat /mnt/c/Windows/System32/drivers/etc/hosts

Typischer Eintrag für lokale Ingress-Tests:

127.0.0.1 demo.local api.demo.local grafana.demo.local

Wenn dein Cluster über eine Minikube-IP oder VM-IP erreichbar ist, trage diese IP ein:

192.168.56.20 demo.local api.demo.local

Prüfung:

Resolve-DnsName demo.local
Test-NetConnection demo.local -Port 80
curl.exe -v http://demo.local/

21.1.3. WSL-Port ist aus Windows nicht erreichbar

Prüfe, ob der Prozess in WSL auf 0.0.0.0 oder 127.0.0.1 lauscht:

ss -tulpn | grep -E ':80|:443|:8080|:3000'

Prüfe Windows Firewall und Portproxy nur, wenn die automatische localhost-Weiterleitung nicht greift:

netsh interface portproxy show all
Get-NetFirewallRule | ? DisplayName -Match "WSL|Docker|Kubernetes"

WSL neu starten:

wsl --shutdown

21.1.4. Docker Desktop WSL Integration defekt

docker ps
docker info
ls -l /var/run/docker.sock

Prüfe in Docker Desktop:

• WSL Integration aktiv,
• richtige Distribution aktiviert,
• Ressourcenlimit ausreichend,
• Kubernetes-Cluster nicht parallel im falschen Kontext.

21.2. kind

21.2.1. Cluster startet nicht

kind version
kind get clusters
docker ps -a
docker logs <kind-node-container>
kind export logs ./kind-logs

Prüfe:

• Docker läuft,
• genug CPU/RAM/Disk,
• Port 6443 frei,
• Proxy/Registry erreichbar,
• Node-Image-Version passt,
• Docker-Netz nicht kollidiert.

21.2.2. Ingress oder Service ist nicht erreichbar

kind-Ports müssen beim Erstellen gesetzt werden:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
    extraPortMappings:
      - containerPort: 80
        hostPort: 80
        protocol: TCP
      - containerPort: 443
        hostPort: 443
        protocol: TCP

Nachträglich kannst du Docker-Port-Mappings nicht sauber an denselben Node-Container anhängen. Erstelle den Cluster neu, wenn der Port fehlt.

kind delete cluster --name workshop
kind create cluster --name workshop --config kind.yaml

21.3. minikube

21.3.1. Startprobleme

minikube version
minikube status
minikube start --driver=docker
minikube logs --file=minikube.log
minikube profile list

Prüfe:

• passender Driver,
• Virtualisierung aktiv,
• Docker/Podman/VirtualBox/VMware erreichbar,
• genug CPU/RAM,
• Proxy und Registry,
• alter Profilzustand.

21.3.2. LoadBalancer oder Ingress nicht erreichbar

minikube tunnel
minikube service list
minikube addons list
minikube addons enable ingress
minikube ip
kubectl get ingress -A

Für lokale Hostnamen:

<minikube-ip> demo.local api.demo.local

Unter Windows gehört dieser Eintrag in C:\Windows\System32\drivers\etc\hosts, wenn Edge verwendet wird.

21.4. k3d

k3d cluster list
k3d kubeconfig get <cluster>
docker ps --format 'table {{.Names}}\t{{.Ports}}\t{{.Status}}'
docker logs k3d-<cluster>-serverlb

Ports über den Load-Balancer veröffentlichen:

k3d cluster create workshop \
  --servers 1 \
  --agents 2 \
  --port "80:80@loadbalancer" \
  --port "443:443@loadbalancer"

Typische Fehler:

• Port-Mapping fehlt,
• Traefik automatisch installiert, aber falsch erwartet,
• Registry nicht verbunden,
• Docker-Netz kollidiert,
• kubeconfig zeigt auf alten Cluster.

21.5. Docker Desktop Kubernetes

docker version
docker info
kubectl config get-contexts
kubectl config use-context docker-desktop
kubectl get nodes

Typische Maßnahmen:

• Kubernetes in Docker Desktop zurücksetzen,
• Ressourcenlimit erhöhen,
• alte LoadBalancer/Ingress-Tests löschen,
• Kontext korrigieren,
• Docker Desktop neu starten.

21.6. Lokale VM, Vagrant und Remote-VM

ip addr
ip route
ss -tulpn
sudo ufw status verbose || true
sudo firewall-cmd --list-all || true
sudo systemctl status kubelet containerd
sudo journalctl -u kubelet -n 300 --no-pager

Vagrant:

vagrant status
vagrant ssh <node>
vagrant provision <node>
vagrant reload
vagrant destroy -f

Prüfe:

• NAT/Bridged/Host-only-Netz,
• IP-Adressen der Nodes,
• Host-Firewall,
• VM-Firewall,
• DNS,
• Snapshot-Stand,
• Provider-Netzwerk,
• MTU,
• Ports 6443, 2379-2380, 10250, 30000-32767.

21.7. Bare Metal

ip link
ethtool <nic>
dmesg -T | grep -i -E 'error|firmware|link|nvme|disk|xfs|ext4|oom'
lsblk
smartctl -a /dev/<disk> 2>/dev/null || true
journalctl -u kubelet -n 300 --no-pager

Prüfe:

• BIOS/UEFI und Virtualisierung,
• VLAN und Switch-Port,
• MTU,
• DHCP oder statische IPs,
• DNS und NTP,
• RAID/Controller,
• Disk-Latenz für etcd,
• BMC/IPMI/iDRAC/iLO,
• Kernel-Module für Storage oder CNI.

21.8. k3s, RKE2 und k0s

k3s:

sudo systemctl status k3s
sudo journalctl -u k3s -n 300 --no-pager
sudo k3s kubectl get nodes
sudo k3s kubectl -n kube-system get pods

RKE2:

sudo systemctl status rke2-server rke2-agent
sudo journalctl -u rke2-server -n 300 --no-pager
sudo /var/lib/rancher/rke2/bin/kubectl get nodes --kubeconfig /etc/rancher/rke2/rke2.yaml

k0s:

sudo k0s status
sudo k0s kubectl get nodes
sudo journalctl -u k0scontroller -n 300 --no-pager
sudo journalctl -u k0sworker -n 300 --no-pager

Prüfe Token, Server-URL, Zertifikate, Firewall, Embedded-etcd-Zustand, Add-on-Defaults, CNI und Ingress-Controller.

21.9. Talos

Talos hat keine normale SSH-Fehleranalyse. Du nutzt talosctl.

talosctl version
talosctl health --nodes <node-ip> --endpoints <endpoint-ip>
talosctl service kubelet --nodes <node-ip>
talosctl logs kubelet --nodes <node-ip>
talosctl logs containerd --nodes <node-ip>
talosctl dmesg --nodes <node-ip>
talosctl get members --nodes <control-plane-ip>
talosctl etcd status --nodes <control-plane-ip>
talosctl kubeconfig --nodes <control-plane-ip>

Prüfe:

• Endpoint und Node-Adresse,
• Machine Config,
• Bootstrap-Zustand,
• Zertifikate,
• etcd-Member,
• Netzwerk und DNS,
• Disk-Auswahl,
• Control-Plane- und Worker-Rollen.

22. Cloud-spezifisches Troubleshooting

22.1. AWS EKS

Grundcheck

aws sts get-caller-identity
aws eks describe-cluster --name <cluster> --region <region>
aws eks update-kubeconfig --name <cluster> --region <region>
kubectl get nodes -o wide
kubectl get pods -A -o wide
aws eks list-addons --cluster-name <cluster> --region <region>

Häufige EKS-Fehler

kubectl -n kube-system get ds aws-node
kubectl -n kube-system logs ds/aws-node --tail=300
kubectl -n kube-system get deploy coredns
kubectl get nodes -o custom-columns=NAME:.metadata.name,ZONE:.metadata.labels.topology\.kubernetes\.io/zone,INSTANCE:.metadata.labels.node\.kubernetes\.io/instance-type

22.2. Azure AKS

az account show
az aks show -g <rg> -n <cluster>
az aks get-credentials -g <rg> -n <cluster> --overwrite-existing
az aks nodepool list -g <rg> --cluster-name <cluster>
kubectl get nodes -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -100

Häufige AKS-Fehler:

• Managed Identity hat keine Rechte,
• Node Pool Upgrade hängt an PDBs,
• Azure CNI Subnet hat keine freien IPs,
• Standard Load Balancer oder NSG blockiert,
• Disk CSI oder File CSI fehlen,
• Private Cluster wird außerhalb des Netzes angesprochen,
• Quota für VM-Familie erschöpft.

az aks nodepool show -g <rg> --cluster-name <cluster> -n <nodepool>
az vmss list -g <node-resource-group> -o table
az network nsg list -g <node-resource-group> -o table

22.3. Google GKE

gcloud auth list
gcloud config list
gcloud container clusters describe <cluster> --region <region>
gcloud container clusters get-credentials <cluster> --region <region>
gcloud container operations list --region <region>
kubectl get nodes -o wide

Häufige GKE-Fehler:

• IAM-Rolle fehlt,
• VPC-native IP-Ranges erschöpft,
• Autopilot lehnt Pod-Spezifikation ab,
• Workload Identity falsch gebunden,
• Cloud Logging API deaktiviert,
• Firewall-Regeln blockieren,
• Ingress/Gateway Controller hat keine Berechtigung oder falsche Annotation,
• Persistent Disk CSI Zone passt nicht.

gcloud compute firewall-rules list
gcloud compute networks subnets describe <subnet> --region <region>
gcloud container node-pools list --cluster <cluster> --region <region>

22.4. DigitalOcean DOKS, Linode LKE, Oracle OKE, IBM IKS

Diese Provider unterscheiden sich in CLI und Managed-Add-ons, aber die Fehlerklassen ähneln sich:

• kubeconfig und API-Zugriff,
• Node-Pool-Zustand,
• Cloud-Firewall,
• LoadBalancer-Controller,
• CSI-Driver,
• Quotas,
• Registry-Zugriff,
• private Cluster-Netze,
• Version-Kompatibilität.

Allgemeines Muster:

kubectl get nodes -o wide
kubectl get pods -A -o wide
kubectl get svc -A -o wide
kubectl get pvc -A
kubectl get events -A --sort-by=.lastTimestamp | tail -200

22.5. OpenShift/OKD

oc whoami
oc status
oc get clusterversion
oc get co
oc get nodes
oc get pods -A -o wide
oc adm must-gather

Häufige Fehler:

• ClusterOperator Degraded,
• MachineConfigPool hängt,
• SCC blockiert Pods,
• Route oder Router-Probleme,
• ImageStream oder Registry-Probleme,
• Operator Lifecycle Manager blockiert Installation,
• etcd Operator meldet Quorum- oder Disk-Probleme.

23. Runbook-Katalog nach Symptomen

Die folgenden Runbooks sind bewusst wiederholbar aufgebaut: Symptom, Ursachen, Diagnose, Maßnahmen und Validierung. Nutze sie als Checkliste im Incident oder als Übung im Workshop.

23.1. API Server nicht erreichbar

Symptom
kubectl liefert Timeout, Connection Refused oder TLS-Fehler.

Häufige Ursachen

• falscher Kontext.
• VPN oder Firewall blockiert.
• API Server Pod down.
• Load-Balancer-Endpoint falsch.
• Zertifikat abgelaufen.

Diagnose

kubectl cluster-info
kubectl get --raw='/readyz?verbose'
nc -vz <api-server> 6443
kubectl config view --minify --raw

Maßnahmen

• Kontext korrigieren.
• Netzpfad prüfen.
• Control-Plane-Logs prüfen.
• Zertifikate prüfen.
• Providerstatus prüfen.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.2. kubectl meldet Forbidden

Symptom
API erreichbar, aber Aktion wird verweigert.

Häufige Ursachen

• falscher User.
• fehlendes RoleBinding.
• falscher Namespace.
• Subresource fehlt.
• Cloud-IAM und RBAC verwechselt.

Diagnose

kubectl auth whoami
kubectl auth can-i <verb> <resource> -n <namespace>
kubectl get role,rolebinding -n <namespace> -o yaml

Maßnahmen

• RoleBinding ergänzen.
• Subresource erlauben.
• ServiceAccount korrigieren.
• ClusterRoleBinding vermeiden, wenn Namespace-Role reicht.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.3. Pod Pending

Symptom
Pod wurde erstellt, aber nicht auf einem Node gestartet.

Häufige Ursachen

• zu wenig CPU oder Memory.
• PVC ungebunden.
• Taint ohne Toleration.
• NodeSelector falsch.
• Affinity nicht erfüllbar.

Diagnose

kubectl describe pod <pod> -n <namespace>
kubectl get nodes -o wide
kubectl get pvc -n <namespace>
kubectl get events -n <namespace> --sort-by=.lastTimestamp

Maßnahmen

• Requests anpassen.
• Kapazität erweitern.
• PVC/StorageClass korrigieren.
• Toleration oder NodeSelector prüfen.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.4. Pod ContainerCreating hängt

Symptom
Pod ist geplant, aber Container wird nicht fertig erstellt.

Häufige Ursachen

• Image-Pull langsam.
• Volume-Mount fehlerhaft.
• CNI Sandbox fehlerhaft.
• Runtime hängt.
• Secret oder ConfigMap fehlt.

Diagnose

kubectl describe pod <pod> -n <namespace>
journalctl -u kubelet -n 300 --no-pager
crictl ps -a
kubectl get events -n <namespace> --sort-by=.lastTimestamp

Maßnahmen

• Mount-Fehler lösen.
• CNI prüfen.
• Runtime neu prüfen.
• Image/Secret korrigieren.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.5. ImagePullBackOff

Symptom
Kubernetes kann das Container Image nicht ziehen.

Häufige Ursachen

• Image-Name falsch.
• Tag fehlt.
• Registry nicht erreichbar.
• ImagePullSecret falsch.
• Rate Limit.
• falsche Architektur.

Diagnose

kubectl describe pod <pod> -n <namespace>
kubectl get secret -n <namespace>
crictl pull <image>
docker manifest inspect <image>

Maßnahmen

• Image korrigieren.
• Secret neu erstellen.
• Registry-Netzwerk prüfen.
• Digest pinnen.
• Architektur prüfen.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.6. CrashLoopBackOff

Symptom
Container startet, beendet sich und wird wieder neu gestartet.

Häufige Ursachen

• App-Fehler.
• Config fehlt.
• Secret fehlt.
• falscher Entrypoint.
• Dependency nicht erreichbar.
• Liveness Probe tötet App.

Diagnose

kubectl logs <pod> -n <namespace> --previous
kubectl describe pod <pod> -n <namespace>
kubectl get deploy <deploy> -n <namespace> -o yaml

Maßnahmen

• Exit Code auswerten.
• Config/Secret prüfen.
• Probe entschärfen.
• Dependency prüfen.
• Rollback durchführen.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.7. OOMKilled

Symptom
Container wurde wegen Speicherverbrauch beendet.

Häufige Ursachen

• Memory-Limit zu niedrig.
• Memory-Leak.
• zu großer Cache.
• Sidecar-Verbrauch.
• Node MemoryPressure.

Diagnose

kubectl describe pod <pod> -n <namespace>
kubectl top pod <pod> -n <namespace>
kubectl top nodes
kubectl logs <pod> -n <namespace> --previous

Maßnahmen

• Memory-Profil prüfen.
• Limit/Request anpassen.
• Cache konfigurieren.
• Leak beheben.
• Node-Kapazität erweitern.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.8. Readiness bleibt false

Symptom
Pod läuft, bekommt aber keinen Service-Traffic.

Häufige Ursachen

• Probe-Pfad falsch.
• Port falsch.
• App braucht länger.
• Dependency fehlt.
• TLS/Auth in Probe falsch.

Diagnose

kubectl describe pod <pod> -n <namespace>
kubectl exec -it <pod> -n <namespace> -- wget -S -O- http://127.0.0.1:<port>/<path>
kubectl get endpoints <svc> -n <namespace>

Maßnahmen

• Probe korrigieren.
• InitialDelay anpassen.
• Dependency bereitstellen.
• Service-TargetPort prüfen.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.9. Liveness Probe verursacht Neustarts

Symptom
Pod startet immer wieder, obwohl App grundsätzlich laufen könnte.

Häufige Ursachen

• Probe zu aggressiv.
• Startphase nicht abgedeckt.
• falscher Pfad.
• Timeout zu kurz.
• CPU throttling.

Diagnose

kubectl describe pod <pod> -n <namespace>
kubectl logs <pod> -n <namespace> --previous
kubectl get pod <pod> -n <namespace> -o yaml | yq '.spec.containers[].livenessProbe'

Maßnahmen

• Startup Probe ergänzen.
• Timeout/Period erhöhen.
• Pfad korrigieren.
• Ressourcen anpassen.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.10. InitContainer hängt

Symptom
InitContainer beendet sich nicht oder schlägt wiederholt fehl.

Häufige Ursachen

• Migration hängt.
• Dependency fehlt.
• Secret fehlt.
• Netzwerk blockiert.
• ImagePull-Fehler.

Diagnose

kubectl describe pod <pod> -n <namespace>
kubectl logs <pod> -n <namespace> -c <init-container>
kubectl get pod <pod> -n <namespace> -o yaml

Maßnahmen

• Init-Log auswerten.
• Dependency testen.
• Timeout definieren.
• Idempotenz sicherstellen.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.11. Deployment-Rollout hängt

Symptom
Neue ReplicaSets werden nicht vollständig bereit.

Häufige Ursachen

• neue Pods nicht ready.
• PDB/Quota.
• maxUnavailable/maxSurge.
• Image oder Config defekt.
• Admission blockiert.

Diagnose

kubectl rollout status deploy/<deploy> -n <namespace>
kubectl rollout history deploy/<deploy> -n <namespace>
kubectl describe deploy <deploy> -n <namespace>
kubectl get rs,pod -n <namespace> -l app=<app>

Maßnahmen

• fehlerhafte ReplicaSet-Pods prüfen.
• Rollback.
• Strategy anpassen.
• Quota/Kapazität prüfen.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.12. StatefulSet hängt

Symptom
Ein ordinaler Pod blockiert weitere Pods.

Häufige Ursachen

• PVC/Mount-Fehler.
• Readiness eines früheren Ordinals.
• DNS Headless Service.
• Datenmigration.
• PodManagementPolicy.

Diagnose

kubectl get sts,pod,pvc -n <namespace>
kubectl describe sts <sts> -n <namespace>
kubectl describe pod <sts>-0 -n <namespace>

Maßnahmen

• ersten fehlerhaften Ordinal-Pod lösen.
• PVC prüfen.
• Readiness korrigieren.
• Datenkonsistenz prüfen.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.13. DaemonSet läuft nicht auf allen Nodes

Symptom
DaemonSet-Pods fehlen auf bestimmten Nodes.

Häufige Ursachen

• Taints.
• NodeSelector.
• Affinity.
• HostPort-Konflikt.
• OS/Architektur passt nicht.

Diagnose

kubectl get ds -A
kubectl describe ds <ds> -n <namespace>
kubectl get nodes --show-labels

Maßnahmen

• Tolerations ergänzen.
• Selector korrigieren.
• HostPort prüfen.
• Multi-Arch-Image verwenden.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.14. Job schlägt fehl

Symptom
Job erreicht keine erfolgreiche Completion.

Häufige Ursachen

• Exit Code.
• BackoffLimit erreicht.
• Deadline überschritten.
• Secret fehlt.
• Datenmigration nicht idempotent.

Diagnose

kubectl get job -n <namespace>
kubectl describe job <job> -n <namespace>
kubectl logs job/<job> -n <namespace> --all-containers

Maßnahmen

• Fehlerlog auswerten.
• Backoff/Deadline anpassen.
• Job idempotent machen.
• Datenzustand prüfen.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.15. CronJob läuft nicht

Symptom
Geplanter Job wird nicht erzeugt oder zu spät ausgeführt.

Häufige Ursachen

• Schedule falsch.
• Suspend=true.
• ConcurrencyPolicy.
• StartDeadlineSeconds.
• Zeitzone.
• Controller gestört.

Diagnose

kubectl get cronjob -n <namespace>
kubectl describe cronjob <cronjob> -n <namespace>
kubectl get jobs -n <namespace>

Maßnahmen

• Schedule korrigieren.
• Suspend deaktivieren.
• Timezone prüfen.
• ConcurrencyPolicy prüfen.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.16. Service hat keine Endpoints

Symptom
Service existiert, routet aber zu keinem Pod.

Häufige Ursachen

• Selector passt nicht.
• Pods nicht ready.
• falscher Namespace.
• EndpointSlice-Controller.
• Readiness Gate.

Diagnose

kubectl get svc,endpoints,endpointslices -n <namespace>
kubectl get pods -n <namespace> --show-labels
kubectl describe pod <pod> -n <namespace>

Maßnahmen

• Labels/Selector korrigieren.
• Readiness lösen.
• Service-Port prüfen.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.17. ClusterIP timeout

Symptom
Service hat Endpoints, aber ClusterIP antwortet nicht.

Häufige Ursachen

• NetworkPolicy.
• kube-proxy/eBPF.
• CNI.
• falscher targetPort.
• App lauscht nicht.

Diagnose

kubectl run netshoot --rm -it --image=nicolaka/netshoot -- bash
kubectl get endpointslices -n <namespace>
kubectl get networkpolicy -A

Maßnahmen

• Policy anpassen.
• CNI/kube-proxy prüfen.
• targetPort korrigieren.
• App-Port prüfen.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.18. DNS im Cluster defekt

Symptom
Service-Namen lassen sich nicht auflösen.

Häufige Ursachen

• CoreDNS down.
• NetworkPolicy blockiert DNS.
• CoreDNS ConfigMap falsch.
• NodeLocal DNS Cache.
• resolv.conf defekt.

Diagnose

kubectl -n kube-system get pods -l k8s-app=kube-dns
kubectl -n kube-system logs deploy/coredns --tail=200
kubectl run dnsutils --rm -it --image=registry.k8s.io/e2e-test-images/agnhost:2.39 -- nslookup kubernetes.default

Maßnahmen

• CoreDNS skalieren.
• DNS-Egress erlauben.
• ConfigMap korrigieren.
• CNI prüfen.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.19. Ingress 404

Symptom
Ingress-Controller antwortet, aber Route passt nicht.

Häufige Ursachen

• Host falsch.
• Path falsch.
• IngressClass falsch.
• Default Backend.
• Annotation falsch.

Diagnose

kubectl describe ingress <ingress> -n <namespace>
curl -H 'Host: <host>' http://<ip>/<path>
kubectl logs -n <ingress-namespace> deploy/<controller> --tail=300

Maßnahmen

• Host/Path korrigieren.
• IngressClass setzen.
• DNS/Hosts-Datei prüfen.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.20. Ingress 503

Symptom
Ingress findet keine bereiten Backends.

Häufige Ursachen

• Service ohne Endpoints.
• Pods nicht ready.
• targetPort falsch.
• Backend-Protokoll falsch.
• NetworkPolicy.

Diagnose

kubectl get svc,endpoints,endpointslices -n <namespace>
kubectl describe ingress <ingress> -n <namespace>
kubectl describe pod <pod> -n <namespace>

Maßnahmen

• Endpoints herstellen.
• Readiness lösen.
• Port/Protocol korrigieren.
• Policy erlauben.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.21. Gateway API Route nicht akzeptiert

Symptom
HTTPRoute oder Gateway wird nicht programmiert.

Häufige Ursachen

• GatewayClass ohne Controller.
• ParentRef falsch.
• Listener-Konflikt.
• ReferenceGrant fehlt.
• Service-Referenz falsch.

Diagnose

kubectl get gatewayclass,gateway,httproute -A
kubectl describe gateway <gateway> -n <namespace>
kubectl describe httproute <route> -n <namespace>

Maßnahmen

• Conditions lesen.
• Controller installieren.
• ParentRefs korrigieren.
• ReferenceGrant ergänzen.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.22. TLS-Zertifikat falsch

Symptom
Browser oder Client meldet Zertifikatsfehler.

Häufige Ursachen

• falsches Secret.
• CN/SAN passt nicht.
• Issuer defekt.
• alte Zertifikatskette.
• SNI falsch.

Diagnose

kubectl get secret <tls-secret> -n <namespace> -o yaml
openssl s_client -connect <host>:443 -servername <host> -showcerts
kubectl get certificate,order,challenge -A

Maßnahmen

• Zertifikat neu ausstellen.
• Secret referenzieren.
• DNS/SNI korrigieren.
• Trust Store prüfen.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.23. PVC Pending

Symptom
Claim wird nicht gebunden.

Häufige Ursachen

• StorageClass fehlt.
• CSI fehlt.
• Quota.
• Topology.
• AccessMode.

Diagnose

kubectl describe pvc <pvc> -n <namespace>
kubectl get storageclass -o yaml
kubectl get pods -A | grep -i csi

Maßnahmen

• StorageClass setzen.
• CSI installieren.
• Quota erhöhen.
• Topology/Zone prüfen.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide

Umgebungshinweise

• In lokalen Container-Clustern wie kind oder k3d prüfst du zusätzlich Docker-Container, Port-Mappings und Docker-Netzwerke.
• In WSL prüfst du zusätzlich Windows-Firewall, Windows-Hosts-Datei und Docker-Desktop-Integration.
• In Remote-VMs und Bare Metal prüfst du zusätzlich OS-Firewall, Routing, VLAN, MTU, DNS und NTP.
• In Managed Kubernetes prüfst du zusätzlich Provider-Events, IAM, Quotas, Subnetze, Load Balancer und Managed Add-ons.

23.24. Volume Mount schlägt fehl

Symptom
Pod hängt wegen Volume-Fehler.

Häufige Ursachen

• Secret/ConfigMap fehlt.
• PV nicht attachbar.
• Permission denied.
• Multi-Attach.
• Node-Plugin defekt.

Diagnose

kubectl describe pod <pod> -n <namespace>
kubectl get volumeattachment
kubectl logs -n <csi-ns> ds/<csi-node> --tail=200

Maßnahmen

• fehlende Ressource erstellen.
• Attachment lösen.
• Permissions korrigieren.
• CSI prüfen.

Validierung

kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl get nodes -o wide