Méthode de diagnostic d'un incident Kubernetes

Face à un incident Kubernetes, commencez toujours par le même réflexe : qualifier le niveau du problème — cluster, nœud, pod ou réseau — puis descendez méthodiquement. Ce guide vous donne une approche systématique en 4 niveaux avec les commandes kubectl adaptées à chaque situation. Vous pourrez localiser la cause d’un incident en quelques minutes au lieu de chercher au hasard.

Ce que vous allez apprendre

• Appliquer une méthode de triage en 4 niveaux : cluster → nœud → pod → réseau
• Maîtriser les 4 commandes de diagnostic essentielles : get, describe, logs, events
• Utiliser kubectl debug avec les conteneurs éphémères pour inspecter un pod en cours d’exécution
• Diagnostiquer les problèmes de Service : DNS, EndpointSlices, kube-proxy

Prérequis

• Un cluster Kubernetes fonctionnel (v1.28+)
• kubectl configuré et connecté au cluster
• Des droits de lecture sur les nœuds, pods, événements, logs et services
• Avoir suivi le guide Observer la santé du cluster
• Connaissances de base sur les Services et le DNS dans Kubernetes

Pourquoi une méthode reproductible ?

Sous pression, le réflexe naturel est de chercher directement dans les logs du pod suspect. C’est souvent une perte de temps : si le problème vient du nœud (disque plein, kubelet en panne) ou du réseau (Service mal configuré, DNS cassé), les logs du pod ne montreront rien d’utile.

Une méthode structurée permet de :

• Éliminer rapidement les niveaux qui fonctionnent
• Localiser la couche responsable avant de creuser
• Communiquer clairement l’état du diagnostic à l’équipe
• Reproduire la même démarche à chaque incident

Analogie simple

Diagnostiquer un incident Kubernetes fonctionne comme un médecin qui examine un patient : on commence par les signes vitaux (le cluster respire-t-il ?), puis on descend vers les organes (nœuds), les cellules (pods) et enfin la circulation (réseau). On ne commence jamais par une IRM si la tension n’a pas été prise.

Vue d’ensemble : les 4 niveaux de diagnostic

Niveau	Question à se poser	Commandes principales
1. Cluster	Le cluster est-il accessible et sain ?	kubectl cluster-info, kubectl get nodes
2. Nœud	Un nœud est-il en difficulté ?	kubectl describe node, kubectl top nodes
3. Pod	Pourquoi ce pod ne fonctionne pas ?	kubectl describe pod, kubectl logs, kubectl debug
4. Réseau	Le trafic arrive-t-il au bon endroit ?	kubectl get svc, kubectl get endpointslices, DNS check

Glissez pour voir

La règle : commencer par le haut et descendre. Si le niveau 1 est sain, passer au 2. Si le 2 est sain, passer au 3, etc.

Niveau 1 : le cluster est-il accessible ?

Avant toute chose, vérifiez que vous pouvez communiquer avec l’API server et que les nœuds sont opérationnels.

Vérifier l’accès au cluster

kubectl cluster-info

Résultat attendu :

Kubernetes control plane is running at https://192.168.122.50:6443
CoreDNS is running at https://192.168.122.50:6443/api/v1/namespaces/kube-system/services/coredns:dns/proxy

Si cette commande échoue, le problème est en amont de Kubernetes : réseau, kubeconfig, VPN, certificat expiré. Vérifiez votre fichier ~/.kube/config et la connectivité réseau vers l’API server.

Vérifier l’état des nœuds

kubectl get nodes

Status	Signification	Action
Tous Ready	Le cluster reste globalement accessible, mais cela ne suffit pas à exclure un problème control plane, kube-system ou réseau. Continuer le triage selon le symptôme	Vérifier kube-system et /readyz
Un nœud NotReady	Problème sur ce nœud → passer au niveau 2	Inspecter le nœud
Un nœud SchedulingDisabled	Maintenance en cours (cordon)	Normal si planifié
Aucune réponse	API server injoignable	Vérifier le plan de contrôle

Glissez pour voir

Vérifier les composants du plan de contrôle

kubectl get pods -n kube-system -o wide

Vérifiez que etcd, kube-apiserver, kube-controller-manager et kube-scheduler sont en état Running avec RESTARTS à 0 (ou très faible).

Pour un diagnostic plus fin :

kubectl get --raw='/readyz?verbose' | grep -E '\[(\+|\-)\]'

Chaque ligne [+] confirme un sous-système fonctionnel. Une ligne [-] signale un composant en échec.

API server accessible ≠ cluster sain

L’API server peut répondre alors qu’etcd est dégradé ou que le controller-manager ne tourne plus. Vérifiez toujours les pods kube-system et les endpoints /readyz.

Niveau 2 : inspecter un nœud en difficulté

Si un nœud est NotReady ou SchedulingDisabled de manière inattendue, inspectez-le en détail.

Lire les conditions du nœud

kubectl describe node <nom-du-noeud>

La section Conditions révèle la cause. Voici les signaux d’alerte :

Condition	Valeur anormale	Cause probable
Ready	False ou Unknown	Kubelet arrêté, réseau coupé, nœud surchargé
MemoryPressure	True	Mémoire insuffisante, pods trop gourmands
DiskPressure	True	Disque plein (nodefs, imagefs ou inodes)
PIDPressure	True	Trop de processus sur le nœud
NetworkUnavailable	True	Plugin CNI non fonctionnel

Glissez pour voir

Vérifier la consommation du nœud

kubectl top nodes

Si un nœud affiche CPU ou mémoire proches de 100 %, les pods peuvent être en train d’être évincés ou incapables de démarrer.

Vérifier les événements récents du nœud

kubectl events --for node/<nom-du-noeud> --types=Warning

Les événements Warning sur un nœud peuvent révéler des problèmes de disque, de kubelet ou de réseau que les conditions ne montrent pas encore.

Quand le nœud est injoignable

Si le nœud est NotReady et que vous ne pouvez pas y accéder en SSH, le problème est probablement matériel ou réseau (panne, kernel panic, VM arrêtée). Les pods qui y tournaient seront progressivement considérés comme perdus et replanifiés par leurs contrôleurs, après les délais de tolérance du control plane (5 minutes par défaut).

Niveau 3 : diagnostiquer un pod

C’est le niveau le plus fréquent. Le triage commence par identifier l’état du pod, puis on choisit la bonne commande selon le symptôme.

Identifier l’état du pod

kubectl get pods -n <namespace> -o wide

Status observé	Signification	Prochaine action
Pending	Le pod n’est pas encore planifié ou pas encore prêt à démarrer	kubectl describe pod → voir Events (scheduling)
ContainerCreating	Le conteneur est en cours de création	Attendre, puis kubectl describe pod si ça persiste
Running	Au moins un conteneur tourne	Vérifier si l’application répond réellement
CrashLoopBackOff	Un conteneur échoue puis redémarre en boucle	kubectl logs --previous, kubectl describe pod
ImagePullBackOff	L’image ne peut pas être téléchargée	kubectl describe pod → Events (pull errors)
Error	Un conteneur s’est arrêté avec une erreur	kubectl logs --previous, kubectl describe pod

Glissez pour voir

OOMKilled n’apparaît pas dans ce tableau car ce n’est pas un statut de pod au même titre que Pending ou Running. C’est une raison de terminaison du conteneur, visible dans kubectl describe pod sous Last State. Si vous voyez des redémarrages fréquents avec OOMKilled, augmentez limits.memory.

Les 4 commandes de diagnostic de base

Les commandes fondamentales sont kubectl get, describe, logs et events. Elles couvrent la majorité des diagnostics. kubectl exec et kubectl debug complètent ensuite pour l’inspection interactive.

1. kubectl describe pod — la vue complète

   kubectl describe pod <pod> -n <namespace>

   Sections à lire en priorité :

   • Events : messages du scheduler, du kubelet, des probes
   • Last State : raison de l’arrêt précédent (OOMKilled, Error, etc.)
   • Exit Code : indice sur la nature du crash
   • Containers → Env / Mounts : configuration du conteneur
   • Conditions : PodScheduled, Initialized, ContainersReady, Ready

2. kubectl logs — les logs applicatifs

   # Logs du conteneur actuel
   kubectl logs <pod> -n <namespace>
   
   # Logs de l'exécution précédente (celle qui a crashé)
   kubectl logs <pod> -n <namespace> --previous
   
   # Pod multi-conteneur : préciser le conteneur
   kubectl logs <pod> -n <namespace> -c <conteneur> --previous
   
   # Les 50 dernières lignes seulement
   kubectl logs <pod> -n <namespace> --tail=50

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

3. kubectl events — les événements filtrés

   # Événements d'un pod spécifique
   kubectl events --for pod/<pod> -n <namespace>
   
   # Événements Warning du namespace
   kubectl events -n <namespace> --types=Warning

   Les événements complètent les logs en montrant ce que Kubernetes a fait (scheduling, pull d’image, kill par une probe, éviction).

4. kubectl exec — entrer dans le conteneur

   kubectl exec -it <pod> -n <namespace> -- /bin/sh

   Utile pour vérifier :

   • La connectivité réseau (wget, curl, nslookup)
   • La présence de fichiers de configuration
   • Les variables d’environnement (env)
   • Les processus en cours (ps aux)

   Si le conteneur n’a pas de shell (image distroless), utilisez kubectl debug (voir ci-dessous).

Utiliser kubectl debug (conteneurs éphémères)

Depuis Kubernetes v1.25, les conteneurs éphémères sont stables. Ils permettent d’inspecter un pod sans modifier son manifeste, même si l’image est minimaliste (distroless, scratch).

kubectl debug -it <pod> -n <namespace> --image=busybox:1.37 --target=<conteneur>

Cette commande lance un conteneur busybox attaché au pod existant. Le conteneur de debug rejoint le pod et partage au minimum son contexte réseau ; l’accès au namespace de processus dépend du mode utilisé, de --target et du support effectif du runtime.

Profils disponibles avec --profile :

Profil	Ce qu’il permet	Cas d’usage
legacy	Comportement historique (défaut si --profile absent)	Compatibilité, amené à disparaître
general	Conteneur isolé dans le pod	Diagnostic réseau basique
baseline	Comme general, plus contraint	Environnements restrictifs
restricted	Très limité	Clusters avec politique stricte
netadmin	Accès réseau complet (NET_ADMIN)	Diagnostic réseau avancé (tcpdump)
sysadmin	Accès complet (root, hostPID)	Diagnostic système poussé

Glissez pour voir

# Diagnostic réseau avancé avec tcpdump
kubectl debug -it <pod> -n <namespace> \
  --image=nicolaka/netshoot --profile=netadmin --target=<conteneur>

# Diagnostic d'un nœud directement
kubectl debug node/<nom-du-noeud> -it --image=busybox:1.37

Profils netadmin et sysadmin = privilégiés

Les profils netadmin et sysadmin accordent des capabilities élevées. Utilisez-les uniquement en cas de besoin et dans des clusters où votre rôle RBAC l’autorise. Préférez --profile=general explicitement plutôt que de laisser le profil legacy par défaut.

Niveau 4 : diagnostiquer le réseau (Services et DNS)

Si le pod tourne (Running) mais que l’application n’est pas joignable, le problème est souvent au niveau du Service, du DNS ou des Network Policies.

Vérifier le Service

kubectl get svc <service> -n <namespace>

Vérifiez que le TYPE, le CLUSTER-IP et le PORT correspondent à ce que vous attendez.

Vérifier les EndpointSlices

kubectl get endpointslices -n <namespace> -l kubernetes.io/service-name=<service>

Si la liste des endpoints est vide, le Service ne trouve aucun pod correspondant. Causes possibles :

• Le sélecteur (spec.selector) du Service ne correspond pas aux labels des pods
• Les pods ne sont pas Ready (probe échouée)
• Les pods sont dans un autre namespace

Vérifier la résolution DNS

Depuis un pod de test :

kubectl run dnstest --image=busybox:1.37 --rm -it --restart=Never -- \
  nslookup <service>.<namespace>.svc.cluster.local

Résultat attendu : le nom est résolu vers l’IP du Service (CLUSTER-IP).

Si la résolution échoue :

# Vérifier que CoreDNS fonctionne
kubectl get pods -n kube-system -l k8s-app=kube-dns

# Vérifier les logs de CoreDNS
kubectl logs -n kube-system -l k8s-app=kube-dns --tail=20

Tester la connectivité de bout en bout

kubectl run curltest --image=curlimages/curl:8.14.1 --rm -it --restart=Never -- \
  curl -v http://<service>.<namespace>.svc.cluster.local:<port>/

Si le DNS fonctionne mais la connexion échoue, vérifiez :

• Le port cible (targetPort) dans la définition du Service
• Les Network Policies qui pourraient bloquer le trafic
• Le kube-proxy (mode iptables/IPVS) sur les nœuds

Network Policies = pare-feu invisible

Si vous avez des Network Policies dans le namespace, elles peuvent bloquer le trafic entre pods sans message d’erreur explicite. Vérifiez avec kubectl get networkpolicies -n <namespace> et inspectez les règles ingress/egress.

Arbre de décision rapide

Utilisez ce tableau quand vous êtes face à un symptôme et que vous ne savez pas par quel niveau commencer :

Symptôme	Niveau probable	Première commande
kubectl ne répond pas	1 — Cluster	Vérifier kubeconfig, réseau, VPN
Nœud NotReady	2 — Nœud	kubectl describe node <noeud>
Pod Pending	3 — Pod	kubectl describe pod <pod> (Events)
Pod CrashLoopBackOff	3 — Pod	kubectl logs <pod> --previous
Pod ImagePullBackOff	3 — Pod	kubectl describe pod <pod> (Events)
Pod Running mais application inaccessible	4 — Réseau	kubectl get svc, kubectl get endpointslices
Timeout intermittent	4 — Réseau	DNS check + Network Policies
Pods évincés sans raison apparente	2 — Nœud	kubectl describe node (conditions, pression)

Glissez pour voir

Dépannage rapide

Symptôme	Cause probable	Solution
kubectl timeout	API server inaccessible	Vérifier kubeconfig et connectivité réseau
Nœud NotReady persistant	Kubelet arrêté ou disque plein	SSH sur le nœud, systemctl status kubelet
Pod Pending longue durée	Pas de nœud avec assez de ressources	kubectl describe pod → Events → ajuster requests ou ajouter un nœud
Logs vides + exit code 137	OOMKill (visible dans Last State de describe)	kubectl describe pod → augmenter limits.memory
Logs vides + exit code 127	Binaire introuvable dans l’image	Vérifier command: et le tag de l’image
Pod Running mais connexion refusée	Service mal configuré ou pod pas Ready	Vérifier le sélecteur du Service et les probes
DNS ne résout pas	CoreDNS en panne	kubectl get pods -n kube-system -l k8s-app=kube-dns
Trafic bloqué sans erreur	Network Policy restrictive	kubectl get networkpolicies -n <namespace>

Glissez pour voir

À retenir

• Toujours commencer par le haut : cluster → nœud → pod → réseau. Cela évite de perdre du temps à lire des logs quand le problème est un nœud en panne
• Les 4 commandes de base sont kubectl get, describe, logs et events. kubectl exec et kubectl debug complètent ensuite pour l’inspection interactive
• kubectl logs --previous est la commande la plus sous-utilisée : elle affiche les logs de l’exécution qui a planté, pas celle en cours
• kubectl debug avec les conteneurs éphémères permet d’inspecter un pod sans le redémarrer, même sur une image distroless
• Les problèmes réseau sont souvent des problèmes de configuration : sélecteur de Service incorrect, probe qui échoue, Network Policy qui bloque
• Documentez votre diagnostic : notez les commandes exécutées et leurs résultats, cela aide à communiquer avec l’équipe et à créer des runbooks

Prochaines étapes

Observer la santé du cluster Les 5 commandes essentielles pour vérifier l'état de votre cluster avant tout diagnostic.

Diagnostiquer un CrashLoopBackOff Appliquez la méthode sur le cas le plus fréquent : conteneur qui plante en boucle.

Préparer une maintenance de cluster Cordon, drain, PDB — le workflow pour intervenir sans provoquer d'incident.

Troubleshooting CKA Exercices de diagnostic orientés certification CKA.

×

📖 Voir la documentation →