Débugger une application Kubernetes

Kubernetes offre plusieurs outils de diagnostic intégrés. Vous utiliserez principalement kubectl logs pour les erreurs applicatives, kubectl describe et kubectl get events pour les problèmes d’orchestration, et kubectl exec ou kubectl debug pour l’investigation interactive. Ce guide vous montre comment combiner ces outils efficacement.

Périmètre de ce guide

Ce guide cible surtout le debug d’une application dans un Pod. Si le problème vient du Service, du réseau du cluster, d’un nœud ou de kubectl lui-même, il faut compléter avec d’autres méthodes d’investigation (voir les sections dédiées plus bas).

Ce que vous allez apprendre

• Diagnostiquer avec kubectl get, kubectl describe et kubectl get events
• Analyser les logs avec kubectl logs
• Exécuter des commandes avec kubectl exec
• Utiliser les conteneurs éphémères (kubectl debug)
• Investiguer les problèmes réseau et de service
• Résoudre les erreurs courantes (CrashLoopBackOff, ImagePullBackOff, OOMKilled, Pending)

Philosophie du debug Kubernetes

Le debugging suit une progression logique :

1. Observer — Quel est l’état actuel du Pod, des événements ?
2. Comprendre — Pourquoi cet état ? Logs, conditions, exit codes
3. Investiguer — Plonger dans le conteneur si nécessaire
4. Corriger — Appliquer la solution et vérifier

Tableau de décision rapide

Symptôme	Première commande	Deuxième commande
Pod en CrashLoopBackOff	kubectl logs --previous	kubectl describe pod
Pod en Pending	kubectl describe pod	kubectl get events
Pod Running mais application KO	kubectl logs	kubectl port-forward / debug réseau
Image minimale sans shell	kubectl debug --image=busybox	ps, ss, nslookup, curl
Suspicion OOM	kubectl describe pod	kubectl top pod
Problème de Service	kubectl get endpoints	kubectl port-forward pod

Glissez pour voir

Commandes essentielles

kubectl get — Vue globale

Première commande pour voir l’état de vos ressources :

# État des Pods dans un namespace
kubectl get pods -n mon-namespace

# État de TOUS les Pods du cluster
kubectl get pods -A

# Plus de détails (node, IP)
kubectl get pods -o wide

# Rafraîchissement continu
kubectl get pods -w

Exemple de sortie :

NAME             READY   STATUS             RESTARTS      AGE
app-healthy      1/1     Running            0             2h
app-crashloop    0/1     CrashLoopBackOff   5 (30s ago)   3m
app-pending      0/1     Pending            0             5m

La colonne RESTARTS

Un nombre élevé de redémarrages indique une instabilité à investiguer. La cause peut être applicative (bug, crash), liée aux probes (trop agressives), aux ressources (OOM), ou à la configuration du Pod. Ne concluez pas trop vite “problème applicatif” sans examiner les logs et le statut détaillé.

kubectl get events — Vue chronologique

Commande sous-estimée mais extrêmement utile. Les événements donnent une vue chronologique de ce qui s’est passé :

# Événements du namespace courant, triés par date
kubectl get events --sort-by=.lastTimestamp

# Événements de tous les namespaces
kubectl get events -A --sort-by=.lastTimestamp

# Événements d'un namespace spécifique
kubectl get events -n mon-namespace --sort-by=.lastTimestamp

Exemple de sortie :

LAST SEEN   TYPE      REASON              OBJECT              MESSAGE
2m          Warning   FailedScheduling    pod/app-pending     0/3 nodes are available: 3 Insufficient memory
3m          Normal    Pulling             pod/app-new         Pulling image "nginx:1.25"
5m          Warning   BackOff             pod/app-crashloop   Back-off restarting failed container

Événements vs describe

kubectl describe pod montre les événements d’un seul Pod. kubectl get events montre tous les événements du namespace, ce qui est plus efficace quand vous ne savez pas encore quel Pod pose problème.

kubectl describe — Analyse détaillée

Pour comprendre pourquoi un Pod est dans un état donné :

kubectl describe pod mon-pod

Sections clés à examiner :

Section	Information
Status	État actuel du Pod
Conditions	Ready, Initialized, ContainersReady, PodScheduled
Containers	État de chaque conteneur, codes de sortie, raison
Events	Historique chronologique des actions sur ce Pod

Glissez pour voir

Regardez les Events et Last State

La section Events en bas de describe contient souvent la réponse : échec de pull d’image, volume non trouvé, ressources insuffisantes. La section Last State du conteneur indique pourquoi il s’est arrêté.

kubectl logs — Logs applicatifs

kubectl logs lit les logs via le kubelet sur le nœud, à partir des fichiers de logs du conteneur. C’est pourquoi votre application doit écrire vers stdout et stderr.

# Logs d'un Pod (conteneur unique)
kubectl logs mon-pod

# Logs d'un conteneur spécifique (Pod multi-conteneurs)
kubectl logs mon-pod -c mon-conteneur

# Dernières 100 lignes
kubectl logs mon-pod --tail=100

# Logs en temps réel
kubectl logs mon-pod -f

# Logs de l'instance précédente du conteneur (après crash)
kubectl logs mon-pod --previous

--previous après un crash

Après un CrashLoopBackOff, kubectl logs --previous permet de récupérer les logs de l’instance précédente du conteneur, si elle existe. Si le conteneur n’a pas encore redémarré ou s’il n’y a pas d’instance précédente, la commande retourne une erreur.

Pods multi-conteneurs

Sur un Pod avec plusieurs conteneurs, vous devez spécifier lequel avec -c nom-conteneur. Sinon, kubectl logs échoue ou choisit le premier conteneur.

kubectl exec — Accès interactif

Pour exécuter des commandes dans un conteneur en cours d’exécution :

# Commande unique
kubectl exec mon-pod -- ls -la /app

# Shell interactif
kubectl exec -it mon-pod -- /bin/sh

# Avec conteneur spécifique (Pod multi-conteneurs)
kubectl exec -it mon-pod -c sidecar -- /bin/bash

Images minimales

Beaucoup d’images de production n’ont pas de shell (distroless, scratch, alpine sans bash). Si exec échoue, utilisez kubectl debug avec une image de debug.

kubectl debug — Conteneurs éphémères

Les conteneurs éphémères sont stables depuis Kubernetes v1.25. Ils permettent d’injecter un conteneur de debug temporaire dans un Pod existant :

# Ajouter un conteneur éphémère basique
kubectl debug mon-pod -it --image=busybox:1.36 --target=app

# Avec des outils réseau complets
kubectl debug mon-pod -it --image=nicolaka/netshoot --target=app

Option --target

L’option --target permet de partager le namespace de processus avec le conteneur cible. Vous pourrez voir ses processus avec ps aux, lire /proc/1/environ, etc.

Exemple pratique dans le conteneur de debug :

# Voir les processus du conteneur cible
ps aux

# Variables d'environnement du processus principal
cat /proc/1/environ | tr '\0' '\n'

# Ports en écoute
ss -tlnp

# Test de connectivité réseau
curl -v http://mon-service:8080/health

Conteneur éphémère ≠ conteneur applicatif

Un conteneur éphémère sert au diagnostic ponctuel. Ce n’est pas un vrai conteneur applicatif : il ne supporte pas les probes, les lifecycle hooks, et ne remplace ni un sidecar ni un conteneur défini dans le Pod d’origine.

kubectl cp — Copier des fichiers

# Pod → Local
kubectl cp mon-pod:/app/logs/error.log ./error.log

# Local → Pod
kubectl cp ./config.yaml mon-pod:/app/config.yaml

# Avec conteneur spécifique
kubectl cp mon-pod:/app/dump.txt ./dump.txt -c app

Nécessite tar dans le conteneur

kubectl cp nécessite la présence de tar dans le conteneur distant. Sur des images minimales (distroless, scratch), la commande échoue. Dans ce cas, utilisez kubectl exec avec un pipe ou kubectl debug pour accéder aux fichiers.

kubectl top — Métriques instantanées

Voir la consommation CPU/mémoire (nécessite metrics-server installé) :

# Pods du namespace courant
kubectl top pods

# Tous les Pods
kubectl top pods -A

# Nœuds
kubectl top nodes

# Tri par mémoire
kubectl top pods --sort-by=memory

# Un Pod spécifique avec ses conteneurs
kubectl top pod mon-pod --containers

Diagnostic rapide, pas monitoring

kubectl top donne des métriques instantanées utiles pour le triage. Il ne remplace pas une stack d’observabilité avec historique, alertes et corrélation (Prometheus, Grafana, Loki). Pour diagnostiquer un OOM, kubectl describe pod reste la référence.

kubectl port-forward — Accès direct

Accédez à un Pod ou Service sans exposition externe :

# Vers un Pod
kubectl port-forward mon-pod 8080:80

# Vers un Service
kubectl port-forward svc/mon-service 8080:80

# En arrière-plan
kubectl port-forward mon-pod 8080:80 &

Utile pour tester si le Pod répond indépendamment du Service.

Erreurs courantes et solutions

CrashLoopBackOff

Symptôme : Le conteneur démarre, crash, redémarre en boucle.

1. Vérifiez les logs du crash précédent

   kubectl logs mon-pod --previous

2. Examinez le code de sortie et la raison

   kubectl describe pod mon-pod | grep -A10 "Last State"

3. Interprétez le code de sortie

   Code	Signification
   0	Sortie normale (mais Pod censé tourner → vérifiez la commande)
   1	Erreur applicative générique
   137	Processus tué par SIGKILL (souvent OOM — confirmez avec describe)
   143	SIGTERM reçu (arrêt propre demandé)

   Glissez pour voir

4. Appliquez la solution

   • Code 1 : Corrigez le bug applicatif (voir logs)
   • Code 137 + OOMKilled : Augmentez resources.limits.memory
   • Sortie immédiate (code 0) : Vérifiez la commande/entrypoint

ImagePullBackOff

Symptôme : Kubernetes ne peut pas télécharger l’image.

kubectl describe pod mon-pod | grep -A10 Events
kubectl get events --field-selector involvedObject.name=mon-pod

Cause	Solution
Image inexistante	Vérifiez le nom et le tag exact
Registry privé	Créez un imagePullSecret et référencez-le
Quota Docker Hub	Authentifiez-vous ou utilisez un registry privé
Erreur réseau	Vérifiez la connectivité du nœud vers le registry

Glissez pour voir

Pending

Symptôme : Le Pod reste en Pending indéfiniment.

kubectl describe pod mon-pod | grep -A20 Events
kubectl get events -A --sort-by=.lastTimestamp | grep -i scheduling

Cause	Solution
Insufficient cpu/memory	Réduisez les requests ou ajoutez des nœuds
No nodes match nodeSelector	Vérifiez les labels des nœuds
Taints not tolerated	Ajoutez les tolerations nécessaires
PVC pending	Vérifiez le PVC et le StorageClass

Glissez pour voir

OOMKilled

Symptôme : Conteneur tué pour surconsommation mémoire.

# Vérifier l'état du conteneur
kubectl describe pod mon-pod | grep -A5 "Last State"

# Chercher OOMKilled explicitement
kubectl describe pod mon-pod | grep -i oom

# Voir la consommation actuelle
kubectl top pod mon-pod --containers

Solutions :

1. Augmentez resources.limits.memory
2. Analysez les fuites mémoire de l’application
3. Ajoutez du monitoring pour détecter la tendance avant le crash

Pod Running mais application inaccessible

C’est un cas très fréquent : le Pod est Running, mais l’application ne répond pas.

Étape 1 : Vérifiez que le Pod répond directement

# Accès direct au Pod, contournant le Service
kubectl port-forward mon-pod 8080:80
# Dans un autre terminal
curl http://localhost:8080/health

Si le Pod répond : le problème vient du Service ou du réseau. Si le Pod ne répond pas : le problème est applicatif.

Étape 2 : Vérifiez le Service et les Endpoints

# Voir le Service
kubectl get svc mon-service -o wide

# Vérifier que le Service a des endpoints
kubectl get endpoints mon-service

# Ou avec EndpointSlices (Kubernetes moderne)
kubectl get endpointslices -l kubernetes.io/service-name=mon-service

Endpoints vides ? Le selector du Service ne matche aucun Pod. Vérifiez les labels :

# Labels du Service (selector)
kubectl get svc mon-service -o jsonpath='{.spec.selector}'

# Labels des Pods
kubectl get pods --show-labels

Étape 3 : Testez la connectivité depuis un autre Pod

# Lancer un Pod de debug avec des outils réseau
kubectl run debug-net --rm -it --image=nicolaka/netshoot -- /bin/bash

# Dans le Pod de debug
nslookup mon-service
curl -v http://mon-service:80/health
nc -zv mon-service 80

Debug avec images minimales

Quand kubectl exec échoue faute de shell (distroless, scratch), voici le workflow :

1. Lancez un conteneur éphémère avec une image de debug

   kubectl debug mon-pod -it --image=nicolaka/netshoot --target=app

2. Explorez le conteneur cible

   # Processus
   ps aux
   
   # Variables d'environnement
   cat /proc/1/environ | tr '\0' '\n'
   
   # Fichiers ouverts
   ls -la /proc/1/fd/

3. Testez le réseau

   # Résolution DNS
   nslookup kubernetes.default
   nslookup mon-service.mon-namespace.svc.cluster.local
   
   # Connectivité TCP
   nc -zv mon-service 80
   
   # Test HTTP
   curl -v http://mon-service:80/health
   
   # Ports en écoute dans le conteneur cible
   ss -tlnp
   
   # Routes réseau
   ip route

4. Vérifiez les volumes montés

   mount | grep -v "cgroup\|proc\|sys"
   cat /etc/resolv.conf

Workflow de debug complet

1. Vue globale

   kubectl get pods -A | grep -v Running
   kubectl get events -A --sort-by=.lastTimestamp | head -20

2. Cibler le Pod problématique

   kubectl describe pod mon-pod

3. Logs applicatifs

   kubectl logs mon-pod --tail=100
   # Si crash récent
   kubectl logs mon-pod --previous

4. Investigation interactive

   # Si shell disponible
   kubectl exec -it mon-pod -- /bin/sh
   
   # Sinon
   kubectl debug mon-pod -it --image=nicolaka/netshoot --target=app

5. Vérification réseau/service

   kubectl port-forward mon-pod 8080:80
   kubectl get endpoints mon-service

6. Métriques

   kubectl top pod mon-pod --containers

Bonnes pratiques

Pour vos applications

1. Loguez vers stdout/stderr — Kubernetes capture automatiquement via le kubelet
2. Implémentez des health endpoints — /health, /ready pour les probes
3. Définissez des ressources — Évite les OOMKilled silencieux et les Pending
4. Utilisez des labels cohérents — Facilite le filtrage (kubectl get pods -l app=api)
5. Gérez SIGTERM proprement — Arrêt gracieux pour les rolling updates

Pour le debug

1. Commencez par get events — Vue chronologique de ce qui s’est passé
2. Utilisez -A / --all-namespaces — Quand vous ne savez pas où est le problème
3. Gardez une image de debug — nicolaka/netshoot ou busybox pour les cas difficiles
4. Centralisez les logs — Loki, Elasticsearch, CloudWatch pour l’historique

Réflexes CKAD

1. Vue globale rapide

   kubectl get pods -A
   kubectl get events -A --sort-by=.lastTimestamp

2. Diagnostic d’un Pod

   kubectl describe pod <pod>
   kubectl logs <pod> --previous

3. Investigation interactive

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

4. Test de connectivité

   kubectl port-forward <pod> 8080:80

5. Debug avancé (images minimales)

   kubectl debug <pod> -it --image=busybox --target=<container>

6. Vérifier les endpoints d’un Service

   kubectl get endpoints <service>

À retenir

Situation	Commande
Vue globale tous namespaces	kubectl get pods -A
Événements chronologiques	kubectl get events --sort-by=.lastTimestamp
Détails d’un Pod	kubectl describe pod
Logs applicatifs	kubectl logs [--previous]
Shell interactif	kubectl exec -it -- /bin/sh
Images minimales	kubectl debug --image=busybox --target=app
Test direct Pod	kubectl port-forward pod 8080:80
Vérifier Service	kubectl get endpoints
Métriques instantanées	kubectl top pods
Copier des fichiers	kubectl cp (nécessite tar dans le conteneur)

Glissez pour voir

Le debugging Kubernetes suit toujours le même pattern : observer l’état global, lire les événements, analyser les logs, vérifier le réseau/service, investiguer interactivement si nécessaire.

Prochaines étapes

Requests et Limits Évitez les OOMKilled en configurant correctement les ressources

Probes de santé Détectez automatiquement les applications défaillantes

Observabilité Monitoring et tracing pour un debug avancé

Rolling Updates Déployez avec interruption minimale et rollback si nécessaire

×

📖 Voir la documentation →