Skip to content

3. Troubleshooting

Formation suivie via le blog de Stéphane Robert : parcours Kubernetes.

Commandes à exécuter :

Terminal window
kubectl describe deployment nginx -n demo-app
kubectl get events -n demo-app
Ce que vous voyez Ce que ça veut dire Par quoi commencer
ErrImagePull, puis ImagePullBackOff le nœud n’arrive pas à récupérer l’image relire le nom et le tag : une faute de frappe donne exactement cette erreur. Ensuite seulement : image privée sans identifiants, ou registry injoignable
Pending sans événement d’image aucun nœud ne peut accueillir le Pod ressources insuffisantes, ou contrainte de placement

Si ça dure trop longtemps, cherchez au niveau des Finalizers, qui peuvent bloquer la suppression.

Terminal window
# 1. Voir l'état du Pod
kubectl get pod mon-pod -o wide
# 2. Lire les événements
kubectl describe pod mon-pod | tail -20
# 3. Consulter les logs
kubectl logs mon-pod --tail=50
# 4. Entrer dans le conteneur (si possible)
kubectl exec -it mon-pod -- sh
# 5. Surveiller les ressources
kubectl top pod mon-pod
# 6. Ephemeral containers
kubectl debug -it mon-pod --image=busybox:1.36@sha256:<xxx>

Symptôme : le Pod redémarre en boucle.

Causes possibles :

  1. L’application plante au démarrage (erreur de code)
  2. Configuration manquante (variables d’environnement, secrets)
  3. Dépendance non disponible (base de données, API)

Diagnostic :

Terminal window
kubectl logs mon-pod --previous # Logs du crash précédent
kubectl describe pod mon-pod # Voir le exit code

Symptôme : le Pod ne démarre pas et K8S n’arrive pas à télécharger l’image. La séquence relevée sur un cluster est ContainerCreating, puis ErrImagePull au premier échec, puis ImagePullBackOff quand les tentatives s’espacent.

Causes possibles :

  1. Image inexistante ou mal orthographiée
  2. Registry privé sans credentials
  3. Problème réseau

Diagnostic :

Terminal window
kubectl describe pod mon-pod | grep -A 5 "Events"

Symptôme : le Pod reste en Pending sans jamais être placé sur un nœud. Il a bien été accepté par l’API, mais le scheduler n’a trouvé aucun nœud qui lui convienne, ou le kubelet attend encore une ressource.

Causes possibles :

  1. Ressources insuffisantes sur les nœuds
  2. Pas de nœud avec les bons labels/taints
  3. Volume PVC en attente

Diagnostic :

Terminal window
kubectl describe pod mon-pod | grep -A 10 "Events"
kubectl get nodes -o wide
kubectl describe node <nom-du-noeud>

Symptôme : kubectl rollout status ne rend pas la main. C’est le comportement normal de la commande tant que le déploiement progresse ; elle devient un signal d’alerte quand rien ne bouge pendant plusieurs minutes.

Causes possibles :

  1. Image introuvable (ImagePullBackOff)
  2. Ressources insuffisantes (Pending)
  3. Readiness probe qui échoue

Diagnostic :

Terminal window
# Vérifier les conditions
kubectl describe deployment nginx-demo | grep -A5 Conditions
# Voir les événements
kubectl get events --sort-by=.lastTimestamp

Diagnostic :

Terminal window
kubectl get pods -l app=nginx-demo
kubectl describe pod <nom-du-pod>
kubectl logs <nom-du-pod>

Symptôme : Si progressDeadlineSeconds est dépassé, le Deployment passe en condition Progressing: False avec raison ProgressDeadlineExceeded.

Diagnostic :

Terminal window
kubectl describe deployment nginx-demo | grep ProgressDeadlineExceeded
kubectl rollout undo deployment/nginx-demo

Symptôme : kubectl rollout status ne rend pas la main. C’est le comportement normal de la commande tant que le déploiement progresse ; elle devient un signal d’alerte quand rien ne bouge pendant plusieurs minutes.

Causes possibles :

  1. Image introuvable (ImagePullBackOff)
  2. Ressources insuffisantes (Pending)
  3. Readiness probe qui échoue

Diagnostic :

Terminal window
# Vérifier les conditions
kubectl describe deployment nginx-demo | grep -A5 Conditions
# Voir les événements
kubectl get events --sort-by=.lastTimestamp
Symptôme Cause probable Solution
Rollout bloqué à « Waiting » Nouveaux Pods pas Ready Vérifier les logs et les probes
ProgressDeadlineExceeded Rollout n’avance plus depuis X secondes Investiguer les Pods, éventuellement rollback
Pods en CrashLoopBackOff Erreur dans la nouvelle image Rollback immédiat
Rollout très lent maxUnavailable: 0 + ressources limitées Augmenter maxSurge ou les ressources
Historique vide revisionHistoryLimit: 0 Augmenter la limite
Rollback échoue Deployment pausé kubectl rollout resume d’abord
Anciens Pods qui ne disparaissent pas terminationGracePeriodSeconds trop long Réduire ou vérifier que l’app gère SIGTERM

Symptôme : Endpoints: <none> dans kubectl describe svc.

Causes possibles : le selector ne correspond à aucun libellé, ou bien les Pods sont sélectionnés mais pas Ready. L’EndpointSlice tranche en une commande, là où describe reste muet.

Diagnostic :

Terminal window
kubectl get pods --show-labels
kubectl get svc nginx-service -o jsonpath='{.spec.selector}'
kubectl get endpointslice -l kubernetes.io/service-name=nginx-service

Symptôme : curl nginx-service : timeout ou connexion refusée.

Causes possibles : le targetPort ne correspond pas au port de l’application.

Diagnostic :

Terminal window
kubectl describe svc nginx-service | grep TargetPort
kubectl exec -it nginx-pod -- netstat -tlnp

Symptôme : le nom du Service ne se résout plus du tout, y compris en FQDN.

Diagnostic :

Terminal window
kubectl -n kube-system get pods -l k8s-app=kube-dns
kubectl run dns-test --image=busybox:1.37@sha256:9db7b59979c38555a39def84a31fb98b5296952f9e3afd4f6f11f05b07adfab0 --rm -it --restart=Never -- nslookup kubernetes

Les trois vérifications précédentes partent de l’API. Celle-ci se place du point de vue d’un Pod, c’est-à-dire exactement là où votre application échoue. Une image outillée évite de découvrir que le conteneur applicatif n’a ni curl ni dig.

Diagnostic :

Terminal window
kubectl run debug --image=nicolaka/netshoot:v0.16@sha256:b09d9b21381f47a79b3cbcb30da25266dc17186ea00ae65e99fdc51396f48e70 --rm -it --restart=Never -- bash

Depuis ce Pod : curl, nslookup, dig, tcpdump. Commencez par curl http://<service> : si la page arrive, le problème n’est pas réseau.

Terminal window
kubectl get configmap app-settings # Vérifie l'existence du ConfigMap
kubectl get configmap app-settings -o jsonpath='{.data.APP_ENV}' # Vérifie l'existence de la clé
kubectl describe pod myapp-xxx | grep -A5 "Environment\|Mounts" # Vérifie que le Pod référence bien le bon ConfigMap
Erreur Cause Solution
CreateContainerConfigError ConfigMap ou clé introuvable Vérifier le nom et la clé
Variable vide Clé mal orthographiée kubectl describe cm pour vérifier
Fichier non mis à jour subPath utilisé Éviter subPath, ou redémarrer le Pod
Terminal window
kubectl get pod <nom> \
-o jsonpath='{.status.containerStatuses[0].state.waiting.message}'
configmap "nexiste-pas" not found
couldn't find key CLE-QUI-NEXISTE-PAS in ConfigMap lab-cm/bon

La première ligne signale un ConfigMap absent, la seconde un ConfigMap présent mais amputé de la clé demandée. Dans les deux cas, le Pod reste bloqué en CreateContainerConfigError et ne démarre jamais.

Utile surtout en débogage :

envFrom:
- configMapRef:
name: surcharge-debug
optional: true