Kubernetes troubleshooting

Fiche express
Type	Méthodologie de diagnostic Kubernetes
Axes	Cluster/nœuds · Pods/applications · Réseau/DNS
Voir aussi	Kubernetes fs · Kubernetes draining · Kubernetes rancher

Diagnostiquer un incident Kubernetes revient presque toujours à descendre par couches successives : d'abord vérifier que le cluster lui-même est sain (nœuds, control plane), puis que le pod concerné démarre et tourne correctement, enfin que le réseau et la résolution de noms fonctionnent comme attendu entre services. Cette page rassemble les commandes de base pour chacun de ces trois axes.

Niveau cluster et nœuds

# Vue d'ensemble : version, composants, événements récents
kubectl cluster-info dump

# État détaillé d'un nœud (ressources, conditions, taints, événements)
kubectl describe node <nom-du-nœud>

# Santé des composants système
kubectl get pods -n kube-system

# Journal du kubelet sur le nœud lui-même
sudo journalctl -u kubelet
kubectl logs -n kube-system <pod-kube-apiserver>

Un taint présent sur un nœud (visible via describe node) explique souvent à lui seul pourquoi aucun pod n'y est planifié — à rapprocher des tolérances (tolerations) attendues côté pod.

Niveau pod / application

La séquence classique — décrire, puis lire les logs, puis entrer dans le conteneur — couvre la majorité des cas :

kubectl apply -f pod.yml
kubectl get pods
kubectl describe pod <nom-du-pod>          # événements : image manquante, échec de probe, OOMKilled...
kubectl logs <nom-du-pod> -c <conteneur>   # -c nécessaire dès qu'il y a plusieurs conteneurs dans le pod

# Exécuter une commande ponctuelle dans un conteneur
kubectl exec <nom-du-pod> -c <conteneur> -- ls

# Shell interactif
kubectl exec <nom-du-pod> -c <conteneur> --stdin --tty -- /bin/sh

Pour une image minimaliste sans shell ni outils de diagnostic (distroless, par exemple), kubectl exec ne suffit pas : les ephemeral containers (kubectl debug) permettent d'attacher temporairement un conteneur de debug (avec curl, netstat...) au pod ciblé sans le redémarrer.

Exemple : erreur applicative révélée par les logs

Un scénario fréquent est une application qui ne parvient pas à joindre un service dépendant :

kubectl describe deployment -n <namespace> <nom-app>
kubectl get pods -n <namespace>
kubectl describe pod -n <namespace> <nom-du-pod>
kubectl logs -n <namespace> <nom-du-pod> -c <conteneur>

Si les logs montrent des tentatives de connexion en échec vers un nom de service court (par exemple backend-db) alors que ce service vit dans un autre namespace que le pod appelant, la résolution DNS courte échoue silencieusement : par défaut, CoreDNS ne résout un nom court qu'à l'intérieur du namespace du client. La correction consiste à qualifier le nom pleinement : <service>.<namespace>.svc.cluster.local plutôt que <service> seul — un des pièges DNS les plus fréquents en environnement multi-namespace.

Niveau réseau / DNS

# Santé de kube-proxy
kubectl get pods -n kube-system
kubectl logs -n kube-system <pod-kube-proxy>

Pour isoler un problème réseau (résolution DNS, connectivité inter-pods, filtrage par NetworkPolicy), il est courant de déployer un pod outillé pour le diagnostic — l'image netshoot regroupe curl, dig, tcpdump, nslookup et d'autres outils réseau qu'une image applicative minimale n'embarque pas :

kubectl exec --stdin --tty <pod-netshoot> -- /bin/sh
curl <nom-du-service>
ping <nom-du-service>
nslookup <nom-du-service>

Voir aussi

• Kubernetes fs — diagnostic spécifique à un système de fichiers saturé
• Kubernetes draining — un pod bloqué en Pending après un drain se diagnostique avec les mêmes outils
• Kubernetes rancher — dépannage côté control plane (certificats, quorum) sur RKE2