Pod crasht? Een troubleshooting checklist

Een pod die crasht geeft je zelden meteen de echte oorzaak. Kubernetes heeft de informatie, maar die zit verspreid over events, logs en resource-beschrijvingen. Dit is de volgorde waarin je ze afwerkt.

Stap 1: bekijk de events

Begin altijd met de events in de namespace:

kubectl get events -n <namespace> --sort-by='.lastTimestamp'

Events verdwijnen na een uur, dus doe dit snel als het incident net speelt. Je ziet hier image pull-fouten, scheduling-problemen en probe-failures al opduiken voordat je verder kijkt.

Stap 2: beschrijf de pod

kubectl describe pod <pod-naam> -n <namespace>

De output is lang, maar de secties die tellen zijn de Conditions, de Events onderaan, en de State per container. Let op statussen als OOMKilled, Error, CrashLoopBackOff en ImagePullBackOff. Die wijzen elk naar een andere oorzaak.

OOMKilled betekent dat de container meer geheugen gebruikte dan het resources.limits.memory-veld toestaat. Kubernetes doodt de container zonder waarschuwing.

ImagePullBackOff betekent dat Kubernetes de image niet kan ophalen. Controleer de image-naam (inclusief tag), het imagePullSecret, en of het registry bereikbaar is vanuit het cluster.

Stap 3: logs van de huidige en vorige run

Voor een draaiende of net gecrashe container:

kubectl logs <pod-naam> -n <namespace>
kubectl logs <pod-naam> -n <namespace> --previous

--previous is de vlag die mensen vergeten. Die geeft je de logs van de vorige container-run, de run die gecrasht is. Zonder die vlag zie je soms alleen de bootlogs van de nieuwe instantie die nog aan het starten is.

Als er meerdere containers in de pod zitten, voeg -c <container-naam> toe.

Stap 4: check de resource limits

Als je OOMKilled zag in stap 2, open dan de deployment of statefulset en kijk naar:

resources:
  requests:
    memory: "128Mi"
  limits:
    memory: "256Mi"

Een container die meer nodig heeft dan het limiet krijgt, wordt gekilld. Verhoog het limiet of profile de applicatie op geheugengebruik. Requests bepalen scheduling, limits bepalen wanneer Kubernetes ingrijpt.

Stap 5: liveness en readiness probes

Probes die te agressief zijn geconfigureerd, zorgen voor onnodige restarts. Kijk in de pod-spec naar initialDelaySeconds, periodSeconds en failureThreshold. Een applicatie die 30 seconden nodig heeft om te starten maar een initialDelaySeconds van 10 heeft, gaat gegarandeerd crashen.

livenessProbe bepaalt of de container herstart wordt. readinessProbe bepaalt of de pod verkeer ontvangt. Als je alleen een liveness probe hebt, controleert Kubernetes niet of de app echt klaar is voor verkeer.

Stap 6: init containers

Als de pod nooit de Running-staat bereikt, kan een init container vastzitten. Check:

kubectl describe pod <pod-naam> -n <namespace>

Onder Init Containers zie je de status. Als er een init container in Error of OOMKilled staat, los die eerst op. De main container start pas als alle init containers succesvol zijn afgesloten.

Stap 7: storage mounts

Een pod die niet start door een storage-probleem geeft je een Pending-staat of een fout in de events over een PVC die niet gebonden is. Controleer:

kubectl get pvc -n <namespace>

Een PVC in Pending betekent dat er geen PV beschikbaar is, of dat de StorageClass niet bestaat of niet correct is geconfigureerd. Een PVC in Bound maar met de verkeerde access mode zorgt voor fouten op het moment dat de pod probeert te mounten.

De meest voorkomende patronen

• CrashLoopBackOff na een deploy: bijna altijd een configuratiefout (verkeerde env-variabele, ontbrekend secret, verkeerde database-URL).
• OOMKilled kort na start: de applicatie heeft meer geheugen nodig dan gedacht, of er is een memory leak.
• ImagePullBackOff: verkeerde tag, private registry zonder secret, of een netwerk-policy die het registry blokkeert.
• Pod blijft Pending: onvoldoende resources op de nodes, of een node selector die nergens op matcht.

Als je Kubernetes-troubleshooting gestructureerd wilt leren, inclusief hands-on met echte clusters, bekijk dan het trainingsaanbod op ict-trainingen.com.

Elke pod-crash heeft een verklaring. Je hoeft alleen te weten waar je die moet zoeken.