Atelier de diagnostic guidé
Appliquer une méthode structurée de diagnostic pas à pas face à un pod qui ne démarre pas.
À retenir
- Une méthode en couches (statut, événements, logs, ressources) est plus efficace qu'une liste de commandes au hasard.
- La section Events de `kubectl describe pod` révèle souvent la cause avant même les logs applicatifs.
- L'option `--previous` sur `kubectl logs` est indispensable en CrashLoopBackOff.
- readinessProbe et livenessProbe distincts évitent des cascades de redémarrages inutiles.
Une méthode plutôt qu'une liste de commandes
Face à un pod en échec, la tentation est de multiplier les commandes kubectl au hasard. Une méthode structurée en couches est plus efficace : d'abord l'état déclaratif (le pod existe-t-il, quel est son statut), puis les événements du cluster, puis les logs applicatifs, enfin les ressources sous-jacentes (nœud, réseau, stockage).
Étape 1 — État et statut
kubectl get pods -o wide donne le statut, le nœud d'affectation et le nombre de redémarrages. Les statuts les plus fréquents à interpréter :
| Statut | Signification probable |
|---|---|
| Pending | Pas de nœud disponible avec assez de ressources, ou volume non provisionné |
| ImagePullBackOff | Image introuvable, tag erroné ou identifiants de registre invalides |
| CrashLoopBackOff | L'application démarre puis s'arrête, souvent en erreur |
| OOMKilled | Le conteneur a dépassé sa limite mémoire (cgroup) |
Étape 2 — Événements
kubectl describe pod <nom> affiche la section Events, chronologique, qui révèle souvent directement la cause : échec de scheduling par manque de ressources, échec de montage de volume, ou probe de santé qui échoue.
Point clé
la section Events est souvent plus riche que les logs applicatifs pour les pannes de démarrage, car elle capture les décisions du control plane avant même que le conteneur applicatif ne s'exécute.
Étape 3 — Logs
kubectl logs <pod> --previous récupère les logs de l'instance précédente d'un conteneur qui a redémarré — indispensable en CrashLoopBackOff puisque les logs du conteneur actuel peuvent être vides ou tronqués.
Attention
oublier --previous est l'erreur la plus fréquente en diagnostic Kubernetes : on inspecte les logs d'un conteneur qui vient de redémarrer et qui n'a encore rien écrit, ce qui fait croire à tort à un problème "sans logs".
Étape 4 — Ressources sous-jacentes
Si le pod reste Pending, vérifiez la capacité des nœuds (kubectl describe node) et l'existence d'un PersistentVolumeClaim bloqué. Un pod peut également être refusé par des contraintes de placement (taints/tolerations, affinités) mal alignées avec les labels des nœuds.
Sur le terrain
documentez chaque incident résolu sous forme de fiche courte (symptôme observé → commande de diagnostic → cause racine → correctif) ; sur un cluster partagé par plusieurs équipes, ce runbook réduit fortement le temps moyen de résolution des incidents récurrents.
Astuce
activez systématiquement des health checks (readinessProbe et livenessProbe) distincts : un service qui répond à sa probe de liveness mais échoue à sa probe de readiness reste dans le cluster sans recevoir de trafic, ce qui évite une cascade de redémarrages inutiles.