kubectl debug : le guide complet pour dépanner pods et nœuds

kubectl debug, kubectl logs et kubectl describe : quelles différences ?

kubectl debug, kubectl logs et kubectl describe sont toutes trois des commandes de dépannage, mais elles répondent à des besoins différents. kubectl logs récupère la sortie de l'application, kubectl describe affiche les détails et les événements des ressources Kubernetes, et kubectl debug fournit un accès interactif pour une investigation en direct.

kubectl logs

La commande kubectl logs affiche la sortie stdout et stderr des conteneurs. Elle est couramment utilisée pour identifier les crashs applicatifs, les échecs au démarrage ou les erreurs d'exécution.

kubectl logs my-pod

Pour les pods multi-conteneurs, spécifiez le nom du conteneur :

kubectl logs my-pod -c app-container

Cette commande est légère et sûre, car elle ne modifie pas le pod et ne crée pas de nouveaux conteneurs.

kubectl describe

La commande kubectl describe fournit des informations détaillées sur les ressources Kubernetes, notamment les labels, les conditions, les volumes montés et les événements récents.

kubectl describe pod my-pod

Cette commande est utile pour diagnostiquer des problèmes tels que :

• Échecs de scheduling
• Erreurs de pull d'image
• Échecs de probes
• Contraintes de ressources
• Événements CrashLoopBackOff

Contrairement à kubectl logs, elle se concentre sur l'état des objets Kubernetes plutôt que sur la sortie de l'application.

kubectl debug

La commande kubectl debug permet un dépannage interactif en attachant des conteneurs éphémères ou en créant des pods de debug temporaires.

kubectl debug my-pod -it --image=busybox

Cette approche est utile lorsque les logs et les descriptions de ressources ne suffisent pas. Vous pouvez par exemple :

• Inspecter la connectivité réseau
• Examiner le contenu du système de fichiers
• Exécuter des outils d'inspection des processus
• Déboguer des conteneurs minimalistes sans shell
• Analyser des problèmes au niveau des nœuds

Comme elle crée des environnements de débogage temporaires, kubectl debug offre un accès plus profond que les autres commandes tout en minimisant les modifications apportées aux workloads en production.

Exemples pratiques de kubectl debug

Déboguer la connectivité réseau

Utilisez un conteneur de debug pour tester le DNS, la découverte de services et l'accès réseau sortant depuis le namespace réseau du pod.

kubectl debug my-pod -it --image=busybox --target=my-container

Dans le conteneur de debug, exécutez des commandes telles que :

nslookup kubernetes.default
wget -qO- http://my-service.default.svc.cluster.local
ping 10.0.0.10

C'est utile lorsque l'image de l'application n'inclut pas d'outils comme nslookup, curl ou ping.

Déboguer un pod en CrashLoopBackOff

Pour un pod qui redémarre en boucle, créez une copie destinée à l'inspection. Vous évitez ainsi de modifier le workload d'origine.

kubectl debug my-pod --copy-to=my-pod-debug -it --image=ubuntu

Vous pouvez inspecter les variables d'environnement, les fichiers montés, la configuration et l'accès réseau depuis le pod copié :

env
ls -la /etc/config
cat /etc/config/app.conf

Cela aide à identifier des fichiers manquants, des valeurs d'environnement erronées ou des dépendances d'exécution.

Déboguer avec le partage de namespace de processus

Utilisez le partage de namespace de processus lorsque vous devez inspecter les processus d'un autre conteneur du pod.

kubectl debug my-pod \
  --copy-to=my-pod-debug \
  --share-processes \
  -it \
  --image=ubuntu

Dans le conteneur de debug, examinez les processus en cours :

ps aux
top

C'est utile pour inspecter des processus bloqués, des processus zombies ou des processus enfants inattendus.

Déboguer avec une image personnalisée

Utilisez une image de debug personnalisée lorsque les images standard n'incluent pas les outils dont vous avez besoin.

kubectl debug my-pod -it \
  --image=my-registry.example.com/debug-tools:latest \
  --target=my-container

Une image personnalisée peut inclure des outils comme curl, dig, tcpdump, strace ou des clients de base de données. Vos images de production restent légères tout en permettant un dépannage plus approfondi lorsque c'est nécessaire.

Bonnes pratiques pour utiliser kubectl debug

Voici quelques pratiques utiles à garder en tête lorsque vous utilisez cette commande.

1. Commencer par l'observabilité avant d'entrer dans le pod

Utilisez kubectl logs, kubectl describe, les événements, les métriques et les traces avant de démarrer une session de debug interactive. Ces outils sont plus rapides, plus sûrs et suffisent souvent à identifier le problème.

kubectl logs my-pod
kubectl describe pod my-pod
kubectl get events --sort-by=.metadata.creationTimestamp

Cela permet de confirmer si le problème vient de l'application, du scheduling, des probes, des limites de ressources, du réseau ou de la configuration Kubernetes. Par exemple, kubectl describe peut révéler des échecs de pull d'image, des readiness probes en échec ou des erreurs de montage de volumes avant que vous ne passiez du temps à inspecter le conteneur directement.

Utilisez kubectl debug lorsque les signaux disponibles n'expliquent pas le problème, ou lorsque vous devez inspecter l'état d'exécution depuis l'intérieur de l'environnement du pod.

2. Utiliser les conteneurs éphémères pour inspecter, pas pour modifier l'application

Les conteneurs éphémères sont destinés au dépannage. Ne les utilisez pas pour corriger des fichiers, redémarrer des services, installer des dépendances ou modifier le comportement d'une application dans un workload en cours d'exécution.

Utilisez-les pour inspecter l'état, exécuter des commandes de diagnostic et collecter des éléments de preuve :

kubectl debug my-pod -it --image=busybox --target=my-container

Par exemple, vous pouvez vérifier la résolution DNS, inspecter les fichiers montés, tester la connectivité des services ou visualiser les processus en cours. Ces actions aident à comprendre ce qui se passe sans modifier le workload.

Toute correction doit être apportée dans le code source, l'image de conteneur, les manifestes ou le pipeline de déploiement. Le comportement en production reste ainsi reproductible et vous évitez les modifications manuelles ponctuelles qui disparaissent au redémarrage du pod.

3. Privilégier les conteneurs de debug plutôt que d'ajouter des outils aux images de production

Évitez d'installer des shells, des gestionnaires de paquets et des outils réseau dans les images de production juste pour le dépannage. Ces outils augmentent la taille de l'image et peuvent élargir la surface d'attaque du conteneur.

Gardez plutôt des images applicatives légères et utilisez une image de debug distincte en cas de besoin :

kubectl debug my-pod -it --image=nicolaka/netshoot --target=my-container

C'est particulièrement utile pour les images minimalistes, comme les conteneurs distroless ou basés sur scratch, qui n'incluent souvent pas de shell. Un conteneur de debug peut fournir des outils comme curl, dig, tcpdump, ss et ip sans modifier l'image de production.

Cette approche maintient aussi une frontière claire : l'image applicative exécute le workload, tandis que l'image de debug ne sert que pendant des sessions de dépannage contrôlées.

4. Utiliser des images de débogage approuvées et sécurisées

Les images de debug incluent souvent des outils puissants tels que tcpdump, strace, curl, dig, des gestionnaires de paquets et des utilitaires shell. Utilisez uniquement des images approuvées provenant de registres de confiance.

Figez les versions des images plutôt que d'utiliser des tags flottants :

kubectl debug my-pod -it --image=registry.example.com/debug-tools:1.4.2

Les images approuvées doivent être analysées pour détecter les vulnérabilités et maintenues à jour. Elles doivent contenir les outils dont vos équipes ont réellement besoin, sans paquets superflus.

L'accès doit également être contrôlé via RBAC. Tous les utilisateurs ne devraient pas être autorisés à créer des conteneurs éphémères, à s'attacher à des workloads sensibles ou à démarrer des sessions de debug au niveau des nœuds. Le débogage de nœud peut exposer les systèmes de fichiers de l'hôte et des informations système : il doit être réservé à des opérateurs de confiance — combinez-le lorsque c'est possible avec le flag --profile (restricted ou baseline) pour éviter d'accorder plus d'accès que nécessaire à la session.

5. Nettoyer les pods de debug et documenter la session

Supprimez les pods de debug copiés après le dépannage pour éviter l'encombrement et la consommation inutile de ressources.

kubectl delete pod my-pod-debug

Les conteneurs éphémères ajoutés à des pods existants ne peuvent pas être retirés de la spécification du pod, mais ils cessent de s'exécuter à la fin de la session de débogage. Les pods copiés, en revanche, restent dans le cluster jusqu'à leur suppression.

Consignez ce qui a été vérifié, les commandes exécutées et les résultats obtenus. L'incident sera plus facile à analyser et vos runbooks s'amélioreront pour les prochains problèmes.

De bonnes notes doivent inclure le pod ou le nœud affecté, l'image de debug utilisée, les sorties de commandes importantes et la cause finale. D'autres ingénieurs éviteront ainsi de refaire la même investigation plus tard.

Réduisez le débogage manuel en corrigeant proactivement les risques de résilience avec PerfectScale

Les commandes comme kubectl debug sont indispensables lorsque vous devez analyser en temps réel un pod qui crashe, un processus bloqué ou un problème au niveau d'un nœud, mais la plupart de ces incidents trouvent leur origine dans des erreurs de configuration des ressources qui auraient pu être détectées plus tôt. PerfectScale renforce de manière autonome la résilience et les performances de Kubernetes grâce au right-sizing des workloads, en prévenant les interruptions et en optimisant l'utilisation des ressources pour une disponibilité de 99,99 %, afin que votre équipe passe moins de temps à ouvrir des sessions de debug interactives et plus de temps à livrer. Au lieu d'attendre qu'un pod tombe en panne pour recourir aux conteneurs éphémères, PerfectScale identifie et corrige en amont les risques de résilience à l'origine de ces défaillances.

Fonctionnalités clés de PerfectScale :

• Remédiation automatique des problèmes : identifie et corrige instantanément les risques de résilience pour maximiser la disponibilité et éliminer la latence, en prévenant les erreurs de configuration (absence de CPU request, de memory request, de memory limits) et les problèmes de sous-provisionnement des ressources tels que l'OOM, le CPU throttling et les évictions.
• Renforcement de l'infrastructure : offre une visibilité globale sur vos nœuds pour faire remonter proactivement les erreurs de configuration, éviter la surallocation des nœuds grâce à des recommandations précises de memory limits, valider les node affinities et les taints, et choisir les types de nœuds les plus adaptés à vos pods.
• Priorisation par impact : concentre votre équipe sur les problèmes les plus critiques en temps réel grâce à une auto-priorisation avancée, et aligne les alertes sur vos SLA et SLO pour maintenir vos niveaux de service.
• Alertes en temps réel et intégrations de ticketing : envoie des notifications instantanées via Slack, MS Teams ou Datadog, et vous permet d'escalader n'importe quel problème vers un workflow établi en créant un ticket en un clic.
• Large couverture des risques : détecte en continu les évictions, les erreurs out of memory, les fuites mémoire suspectées, le CPU throttling, les redémarrages de pods, les HPA atteignant leur nombre maximal de réplicas, ainsi que les requests et limits CPU et mémoire sous-provisionnées ou non définies.

Découvrez comment PerfectScale peut maintenir la stabilité de vos clusters et réduire le besoin de dépannage manuel sur la plateforme d'optimisation des performances Kubernetes.

FAQ

À quoi sert la commande kubectl debug ?

kubectl debug sert à dépanner de manière interactive les workloads et les nœuds Kubernetes. Elle peut attacher un conteneur éphémère à un pod en cours d'exécution, créer une copie modifiée d'un pod en crash, ou lancer un pod de debug sur un nœud — le tout sans que les outils de débogage soient déjà intégrés à l'image cible.

Comment utiliser kubectl debug sur un pod ?

Exécutez kubectl debug <pod-name> -it --image=busybox pour attacher un conteneur de debug éphémère à un pod en cours d'exécution. Ajoutez --target=<container-name> pour partager le namespace de processus avec un conteneur spécifique, ou --copy-to=<new-pod-name> pour déboguer une copie plutôt que le pod en production (utile pour les pods qui crashent au démarrage).

Comment utiliser kubectl debug sur un nœud ?

Exécutez kubectl debug node/<node-name> -it --image=ubuntu pour créer un pod de debug qui s'exécute dans les namespaces de l'hôte du nœud, avec le système de fichiers racine du nœud monté sur /host. Le profil par défaut est general, qui n'accorde pas d'accès privilégié — utilisez --profile=sysadmin si vous avez besoin de capacités root complètes.

Quelle est la syntaxe de la commande kubectl debug ?

La forme générale est kubectl debug (POD | TYPE/NAME) [flags], le plus souvent utilisée avec --image pour définir l'image du conteneur de debug, -it pour un terminal interactif, --target pour cibler un conteneur spécifique et --copy-to pour déboguer une copie du pod.

Quelle est la différence entre kubectl debug et kubectl exec ?

kubectl exec exécute une commande à l'intérieur d'un conteneur existant, avec l'image même du pod : cela ne fonctionne donc que si cette image contient déjà les outils nécessaires. kubectl debug attache un conteneur (ou un pod) distinct avec l'image de votre choix, ce qui est indispensable pour les conteneurs minimalistes ou distroless qui n'ont pas de shell du tout.

kubectl debug modifie-t-il le pod d'origine ou ses conteneurs ?

L'ajout d'un conteneur éphémère avec kubectl debug ne redémarre pas et ne modifie pas les conteneurs existants du pod — il ajoute simplement un conteneur temporaire à leurs côtés. L'option --copy-to va plus loin et crée un pod distinct, en laissant l'original totalement intact.

Faut-il nettoyer les pods créés par kubectl debug ?

Oui, pour tout pod créé avec --copy-to. Ces pods persistent dans le cluster jusqu'à ce que vous les supprimiez avec kubectl delete pod <debug-pod-name>. Les conteneurs éphémères ajoutés directement à un pod existant ne nécessitent pas de nettoyage distinct — ils cessent de s'exécuter à la fin de la session, même s'ils restent listés dans la spécification du pod.