3. Troubleshooting
Formation suivie via le blog de Stéphane Robert : parcours Kubernetes.
Le Deployment reste à 0/1
Section titled “Le Deployment reste à 0/1”Commandes à exécuter :
kubectl describe deployment nginx -n demo-appkubectl 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 |
Le namespace reste en Terminating
Section titled “Le namespace reste en Terminating”Si ça dure trop longtemps, cherchez au niveau des Finalizers, qui peuvent bloquer la suppression.
Debug d’un Pod
Section titled “Debug d’un Pod”# 1. Voir l'état du Podkubectl get pod mon-pod -o wide
# 2. Lire les événementskubectl describe pod mon-pod | tail -20
# 3. Consulter les logskubectl logs mon-pod --tail=50
# 4. Entrer dans le conteneur (si possible)kubectl exec -it mon-pod -- sh
# 5. Surveiller les ressourceskubectl top pod mon-pod
# 6. Ephemeral containerskubectl debug -it mon-pod --image=busybox:1.36@sha256:<xxx>CrashLoopBackOff
Section titled “CrashLoopBackOff”Symptôme : le Pod redémarre en boucle.
Causes possibles :
- L’application plante au démarrage (erreur de code)
- Configuration manquante (variables d’environnement, secrets)
- Dépendance non disponible (base de données, API)
Diagnostic :
kubectl logs mon-pod --previous # Logs du crash précédentkubectl describe pod mon-pod # Voir le exit codeImagePullBackOff
Section titled “ImagePullBackOff”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 :
- Image inexistante ou mal orthographiée
- Registry privé sans credentials
- Problème réseau
Diagnostic :
kubectl describe pod mon-pod | grep -A 5 "Events"Pending (bloqué)
Section titled “Pending (bloqué)”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 :
- Ressources insuffisantes sur les nœuds
- Pas de nœud avec les bons labels/taints
- Volume PVC en attente
Diagnostic :
kubectl describe pod mon-pod | grep -A 10 "Events"kubectl get nodes -o widekubectl describe node <nom-du-noeud>Debug d’un Deployment
Section titled “Debug d’un Deployment”Le rollout est bloqué
Section titled “Le rollout est bloqué”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 :
- Image introuvable (ImagePullBackOff)
- Ressources insuffisantes (Pending)
- Readiness probe qui échoue
Diagnostic :
# Vérifier les conditionskubectl describe deployment nginx-demo | grep -A5 Conditions
# Voir les événementskubectl get events --sort-by=.lastTimestampLes Pods ne démarrent pas
Section titled “Les Pods ne démarrent pas”Diagnostic :
kubectl get pods -l app=nginx-demokubectl describe pod <nom-du-pod>kubectl logs <nom-du-pod>Timeout de mise à jour
Section titled “Timeout de mise à jour”Symptôme : Si progressDeadlineSeconds est dépassé, le Deployment passe en condition Progressing: False avec raison ProgressDeadlineExceeded.
Diagnostic :
kubectl describe deployment nginx-demo | grep ProgressDeadlineExceededkubectl rollout undo deployment/nginx-demoDebug d’un ReplicaSet
Section titled “Debug d’un ReplicaSet”Le rollout est bloqué
Section titled “Le rollout est bloqué”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 :
- Image introuvable (ImagePullBackOff)
- Ressources insuffisantes (Pending)
- Readiness probe qui échoue
Diagnostic :
# Vérifier les conditionskubectl describe deployment nginx-demo | grep -A5 Conditions
# Voir les événementskubectl get events --sort-by=.lastTimestampRécapitulatif rollout et rollback
Section titled “Récapitulatif rollout et rollback”| 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 |
Debug d’un Service
Section titled “Debug d’un Service”Aucun endpoint
Section titled “Aucun endpoint”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 :
kubectl get pods --show-labelskubectl get svc nginx-service -o jsonpath='{.spec.selector}'kubectl get endpointslice -l kubernetes.io/service-name=nginx-servicetargetPort incorrect
Section titled “targetPort incorrect”Symptôme : curl nginx-service : timeout ou connexion refusée.
Causes possibles : le targetPort ne correspond pas au port de l’application.
Diagnostic :
kubectl describe svc nginx-service | grep TargetPortkubectl exec -it nginx-pod -- netstat -tlnpDNS défaillant
Section titled “DNS défaillant”Symptôme : le nom du Service ne se résout plus du tout, y compris en FQDN.
Diagnostic :
kubectl -n kube-system get pods -l k8s-app=kube-dnskubectl run dns-test --image=busybox:1.37@sha256:9db7b59979c38555a39def84a31fb98b5296952f9e3afd4f6f11f05b07adfab0 --rm -it --restart=Never -- nslookup kubernetesTest depuis un Pod de debug
Section titled “Test depuis un Pod de debug”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 :
kubectl run debug --image=nicolaka/netshoot:v0.16@sha256:b09d9b21381f47a79b3cbcb30da25266dc17186ea00ae65e99fdc51396f48e70 --rm -it --restart=Never -- bashDepuis ce Pod : curl, nslookup, dig, tcpdump. Commencez par curl http://<service> : si la page arrive, le problème n’est pas réseau.
Debug d’un ConfigMap
Section titled “Debug d’un ConfigMap”Vérifier la référence
Section titled “Vérifier la référence”kubectl get configmap app-settings # Vérifie l'existence du ConfigMapkubectl 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 ConfigMapErreurs fréquentes
Section titled “Erreurs fréquentes”| 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 |
kubectl get pod <nom> \ -o jsonpath='{.status.containerStatuses[0].state.waiting.message}'configmap "nexiste-pas" not foundcouldn't find key CLE-QUI-NEXISTE-PAS in ConfigMap lab-cm/bonLa 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.
Rendre une référence facultative
Section titled “Rendre une référence facultative”Utile surtout en débogage :
envFrom:- configMapRef: name: surcharge-debug optional: true