Diagnostiquer un CrashLoopBackOff Kubernetes

CrashLoopBackOff signifie qu’un conteneur plante, redémarre, puis replante en boucle. Kubernetes augmente le délai entre chaque redémarrage (10 s → 20 s → 40 s → … → 5 min max) pour éviter de surcharger le nœud. Ce guide vous donne une méthodologie en 4 étapes pour identifier la cause et corriger le problème.

Ce que vous allez apprendre

• Comprendre le mécanisme du backoff exponentiel et pourquoi Kubernetes augmente le délai entre les redémarrages
• Identifier les 6 causes principales d’un CrashLoopBackOff
• Appliquer une méthodologie de diagnostic reproductible en 4 étapes
• Utiliser kubectl logs --previous et kubectl describe pod pour trouver la cause réelle
• Reproduire et corriger un CrashLoopBackOff sur un cluster de test

Prérequis

• Un cluster Kubernetes fonctionnel (v1.28+)
• kubectl configuré et connecté au cluster
• Des droits de lecture sur les pods, événements et logs
• Connaissances de base sur les Pods et les probes

Qu’est-ce qu’un CrashLoopBackOff ?

CrashLoopBackOff n’est pas une phase du Pod. C’est un état d’attente visible dans la colonne STATUS de kubectl get pods lorsqu’un conteneur échoue puis redémarre en boucle avec backoff. Selon le moment où vous observez le Pod, sa phase peut rester Running, mais ce n’est pas systématique — le point clé est qu’un conteneur redémarre en boucle.

Analogie simple

Imaginez un employé qui arrive le matin, tombe immédiatement de sa chaise, et qu’on lui dit “repose-toi, réessaie dans 10 secondes”. Puis 20 secondes. Puis 40. C’est le backoff exponentiel : Kubernetes espace les tentatives pour ne pas aggraver le problème.

Le backoff exponentiel

Quand un conteneur plante, le kubelet applique un délai croissant avant chaque nouveau redémarrage :

Tentative	Délai avant redémarrage	Temps total écoulé
1re	10 secondes	10 s
2e	20 secondes	30 s
3e	40 secondes	1 min 10 s
4e	80 secondes	2 min 30 s
5e	160 secondes	5 min 10 s
6e+	300 secondes (maximum)	+5 min par tentative

Glissez pour voir

Si le conteneur reste stable pendant 10 minutes, le compteur de backoff est réinitialisé.

Nouveautés Kubernetes v1.35

À partir des versions récentes de Kubernetes, deux feature gates peuvent modifier le comportement par défaut :

• ReduceDefaultCrashLoopBackOffDecay : fonctionnalité alpha désactivée par défaut, qui réduit le backoff à 1 s initial puis 60 s maximum.
• KubeletCrashLoopBackOffMax : fonctionnalité bêta à partir de Kubernetes 1.35, activée par défaut sur les versions concernées, qui permet de configurer un plafond personnalisé via crashLoopBackOff.maxContainerRestartPeriod dans la configuration du kubelet.

Les 6 causes principales

Voici les causes les plus fréquentes rencontrées en pratique :

#	Cause	Symptôme typique	Où chercher
1	Erreur applicative	Exception, panic, segfault dans les logs	kubectl logs
2	Configuration manquante	Variable d’env absente, fichier de config introuvable	kubectl describe pod (env, volumes)
3	OOMKilled	Le conteneur dépasse sa limite mémoire	kubectl describe pod → Last State: OOMKilled
4	Probe mal configurée (liveness ou startup)	Unhealthy, Killing, redémarrages répétés	kubectl describe pod → Events, définition des probes
5	Commande ou entrypoint invalide	Le conteneur s’arrête immédiatement avec exit code 126 ou 127	kubectl describe pod, kubectl logs --previous
6	Dépendance externe indisponible	La base de données ou l’API n’est pas accessible	kubectl logs (timeout, connection refused)

Glissez pour voir

OOMKilled : pas forcément visible dans les logs

Quand un conteneur est tué par le kernel pour dépassement mémoire (OOMKill), le processus est interrompu brutalement. Les logs applicatifs ne montrent souvent rien — c’est dans kubectl describe pod que vous verrez Reason: OOMKilled.

Méthodologie de diagnostic en 4 étapes

1. Identifier le pod en CrashLoopBackOff

   Listez les pods et repérez ceux dont le STATUS est CrashLoopBackOff ou dont le compteur RESTARTS augmente :

   kubectl get pods -A | grep -E 'CrashLoop|Error|BackOff'

   Notez le nom du pod, son namespace et le nombre de RESTARTS.

2. Lire les logs du conteneur crashé

   La commande la plus importante est kubectl logs --previous, qui affiche les logs de l’exécution précédente (celle qui a planté) :

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

   Si le pod contient plusieurs conteneurs, précisez le conteneur :

   kubectl logs <pod> -n <namespace> -c <conteneur> --previous

   Cherchez des indices : Exception, Error, panic, Traceback, connection refused, OOM, permission denied.

3. Inspecter la description du pod

   kubectl describe pod <pod> -n <namespace>

   Les sections à regarder en priorité :

   • Last State : la raison de l’arrêt précédent (OOMKilled, Error, Completed)
   • Exit Code : 0 = arrêt normal, 1 = erreur applicative, 137 = OOMKilled ou SIGKILL, 139 = segfault
   • Events : Unhealthy (probe échouée), BackOff, Pulling
   • Containers → Args/Command : la commande de démarrage est-elle correcte ?
   • Containers → Env : les variables d’environnement sont-elles présentes ?
   • Containers → Mounts : les volumes sont-ils montés correctement ?

4. Corriger et vérifier

   Selon la cause identifiée :

   Cause	Action corrective
   Erreur applicative	Corriger le code ou la config, redéployer
   Config manquante	Ajouter le ConfigMap/Secret, vérifier les noms
   OOMKilled	Augmenter resources.limits.memory
   Probe mal configurée	Augmenter initialDelaySeconds, timeoutSeconds, ou ajouter une startup probe
   Commande/entrypoint invalide	Vérifier command: et args: dans le manifeste
   Dépendance externe	Vérifier la connectivité, ajouter un init container

   Glissez pour voir

   Après correction, vérifiez que le pod est stable :

   kubectl get pods -n <namespace> -w

   Le flag -w (watch) permet de suivre l’évolution en temps réel. Le pod doit passer à Running et le compteur de RESTARTS ne doit plus augmenter.

Exemple pratique : reproduire un CrashLoopBackOff

Pour bien comprendre le mécanisme, créons volontairement un pod qui crashe.

Cas 1 : erreur applicative (exit code 1)

apiVersion: v1
kind: Pod
metadata:
  name: crash-exit-error
  namespace: default
spec:
  restartPolicy: Always
  containers:
    - name: app
      image: busybox:1.37
      command: ["sh", "-c", "echo 'Application démarrée'; sleep 2; echo 'Erreur fatale!'; exit 1"]

kubectl apply -f- <<'EOF'
apiVersion: v1
kind: Pod
metadata:
  name: crash-exit-error
  namespace: default
spec:
  restartPolicy: Always
  containers:
    - name: app
      image: busybox:1.37
      command: ["sh", "-c", "echo 'Application démarrée'; sleep 2; echo 'Erreur fatale!'; exit 1"]
EOF

Attendez 30 secondes puis observez :

kubectl get pods crash-exit-error -w

Vous verrez le STATUS passer de Running à Error puis à CrashLoopBackOff, avec le compteur RESTARTS qui augmente.

Diagnostic :

# Logs de l'exécution qui a crashé
kubectl logs crash-exit-error --previous

# Description avec exit code
kubectl describe pod crash-exit-error | grep -A5 "Last State"

Cas 2 : OOMKilled (dépassement mémoire)

Pour provoquer un vrai OOMKill, le conteneur doit allouer de la mémoire au-delà de sa limite. Un simple dd vers /dev/null consomme du CPU, pas de la RAM. Voici un exemple qui alloue réellement de la mémoire avec un tail grossier :

kubectl apply -f- <<'EOF'
apiVersion: v1
kind: Pod
metadata:
  name: crash-oom
  namespace: default
spec:
  restartPolicy: Always
  containers:
    - name: app
      image: python:3.13-slim
      command: ["python3", "-c", "data = []; [data.append('x' * 10**6) for _ in range(500)]"]
      resources:
        limits:
          memory: "50Mi"
EOF

Le script Python alloue des blocs de 1 Mo en boucle jusqu’à dépasser la limite de 50 Mi, ce qui déclenche un OOMKill.

Diagnostic :

kubectl describe pod crash-oom | grep -A5 "Last State"

Vous verrez Reason: OOMKilled et Exit Code: 137.

Nettoyage

kubectl delete pod crash-exit-error crash-oom --force --grace-period=0

Les exit codes essentiels

Les exit codes aident à identifier rapidement la nature du crash :

Exit code	Signification	Cause probable
0	Arrêt normal	Le conteneur s’est terminé volontairement — si restartPolicy: Always, il sera relancé
1	Erreur générique	Bug applicatif, exception non gérée
2	Mauvais usage de commande shell	Commande ou argument invalide dans command:
126	Permission denied	Le binaire n’est pas exécutable
127	Command not found	Le binaire n’existe pas dans l’image
137	SIGKILL (128 + 9)	Processus tué par SIGKILL — souvent un OOMKill, mais pas exclusivement
139	SIGSEGV (128 + 11)	Segmentation fault dans l’application
143	SIGTERM (128 + 15)	Arrêt gracieux demandé par Kubernetes

Glissez pour voir

Formule rapide

Pour les codes > 128 : le signal reçu = exit code - 128. Exemple : 137 - 128 = 9 → signal KILL → probablement un OOMKill.

Cas particuliers

CrashLoopBackOff avec logs vides

Si kubectl logs --previous ne retourne rien, c’est souvent que le conteneur a planté avant de produire un output. Causes possibles :

• Le binaire n’existe pas dans l’image (exit code 127)
• Le point d’entrée n’est pas exécutable (exit code 126)
• OOMKill immédiat (exit code 137)

Dans ce cas, utilisez kubectl describe pod pour lire l’exit code et les événements.

CrashLoopBackOff causé par une liveness probe

Si les événements montrent Unhealthy suivi de Killing, le conteneur fonctionne mais la liveness probe considère qu’il est mort :

Warning  Unhealthy  10s  kubelet  Liveness probe failed: HTTP probe failed with statuscode: 503
Normal   Killing    10s  kubelet  Container app failed liveness probe, will be restarted

La solution est de revoir la configuration de la probe :

• Augmenter initialDelaySeconds si l’application met du temps à démarrer
• Augmenter timeoutSeconds si le endpoint est lent
• Utiliser une startup probe pour les démarrages longs

Consultez le guide sur les probes Kubernetes pour les bonnes pratiques de configuration.

CrashLoopBackOff sur un init container

Les init containers s’exécutent une fois avant le conteneur principal. Si un init container crashe, le pod n’atteint jamais l’état Running et vous verrez Init:CrashLoopBackOff dans le STATUS.

Diagnostic identique, en précisant le conteneur :

kubectl logs <pod> -c <init-container> --previous

Dépannage rapide

Symptôme	Première action	Commande
CrashLoopBackOff avec RESTARTS élevés	Lire les logs précédents	kubectl logs <pod> --previous
Exit code 137, pas de logs	Vérifier la mémoire	kubectl describe pod <pod> → chercher OOMKilled
Exit code 127	Vérifier l’image et la commande	kubectl describe pod <pod> → section Containers
Events Unhealthy + Killing	La probe tue le conteneur	Revoir livenessProbe dans le manifeste
Init:CrashLoopBackOff	L’init container crashe	kubectl logs <pod> -c <init-container> --previous
Logs montrent “connection refused”	Dépendance externe absente	Vérifier le Service/Endpoint cible

Glissez pour voir

À retenir

• CrashLoopBackOff n’est pas une phase du Pod — c’est un état d’attente entre deux redémarrages, avec un délai qui double à chaque crash (10 s → 300 s max)
• kubectl logs --previous est votre commande principale : elle affiche les logs de l’exécution qui a planté
• kubectl describe pod révèle l’exit code, les événements et la configuration — indispensable quand les logs sont vides
• Exit code 137 = processus tué par SIGKILL, souvent un OOMKill (mais pas exclusivement) — vérifiez avec kubectl describe pod puis augmentez resources.limits.memory si c’est confirmé
• Exit code 127 = le binaire n’existe pas dans l’image — vérifiez la commande et le tag de l’image
• Si les events montrent Unhealthy → Killing, c’est la liveness probe qui tue le conteneur, pas un crash applicatif
• Après correction, surveillez le pod avec kubectl get pods -w et vérifiez que les RESTARTS ne reprennent pas

Prochaines étapes

Observer la santé d'un cluster Les 5 commandes essentielles pour vérifier l'état de votre cluster Kubernetes.

Configurer les Probes Évitez les CrashLoopBackOff causés par des probes mal configurées.

Gérer les ressources (Requests et Limits) Dimensionnez correctement la mémoire et le CPU pour éviter les OOMKill.

×

📖 Voir la documentation →