lumikha

3 min de lecture

kubectl debug : inspecter un pod en production sans le modifier

kubectl debug -it --copy-to, ephemeral containers, et le cas des images distroless : comment déboguer un pod en production sans le modifier ni redémarrer.

Déboguer un pod en production est souvent frustrant : les images de prod sont minimalistes (pas de shell, pas d'outils réseau), et modifier un pod en cours d'exécution n'est pas possible. kubectl debug résout ça proprement.

Le problème avec kubectl exec#

kubectl exec fonctionne bien si l'image contient les outils dont vous avez besoin. Mais en production, les images sont souvent distroless (sans shell, sans curl, sans netstat) pour réduire la surface d'attaque. kubectl exec devient inutile dans ce contexte.

kubectl debug --copy-to : une copie avec des outils#

La première approche crée une copie du pod avec une image enrichie que vous choisissez, sans modifier le pod original :

kubectl debug mon-pod \
  --copy-to=mon-pod-debug \
  --image=busybox \
  --stdin --tty \
  -- /bin/sh

Vous obtenez un shell dans un nouveau pod mon-pod-debug : une copie de mon-pod à laquelle kubectl ajoute un container busybox, à côté des containers d'origine. Le pod original continue de tourner normalement. (Pour remplacer l'image d'un container dans la copie, c'est l'option --set-image, par exemple --set-image=*=busybox.)

Avec une image plus riche en outils et le partage du PID namespace :

# nicolaka/netshoot : image avec outils réseau complets
# --share-processes : partage le PID namespace (activé par défaut avec --copy-to)
kubectl debug mon-pod \
  --copy-to=mon-pod-debug \
  --image=nicolaka/netshoot \
  --stdin --tty \
  --share-processes \
  -- bash

--share-processes permet au container de debug d'accéder aux processus du container applicatif — utile pour inspecter /proc, les fichiers ouverts, ou attacher strace.

Ephemeral containers : debug sans copie#

L'approche la plus propre en production : les ephemeral containers. Ils sont injectés dans le pod existant, sans le redémarrer ni le copier. Parfait pour le debugging en live.

kubectl debug -it mon-pod \
  --image=busybox \
  --target=mon-container

Le flag --target permet de partager le PID namespace avec le container ciblé, ce qui donne accès à ses processus depuis le container éphémère.

Pour sortir de la session, exit suffit. Le pod original est inchangé.

Le cas des images distroless#

Les images distroless (gcr.io/distroless/*) n'ont pas de shell. kubectl exec retourne une erreur immédiatement. Avec les ephemeral containers, on injecte notre propre shell dans le pod :

kubectl debug -it mon-pod-distroless \
  --image=gcr.io/distroless/base:debug \
  --target=app

L'image distroless/base:debug inclut busybox en plus du contenu distroless standard — c'est l'image de debug officielle pour inspecter les containers distroless.

Déboguer directement un node#

kubectl debug permet aussi d'ouvrir un shell directement sur le node AKS :

kubectl debug node/aks-nodepool1-12345678-vmss000000 \
  --image=ubuntu \
  --stdin --tty

Cela crée un pod sur le node avec accès au filesystem de l'hôte monté sous /host. Utile pour inspecter les logs système, les fichiers de configuration kubelet, ou diagnostiquer des problèmes réseau au niveau du node.

Nettoyer après le debug#

Les pods créés avec --copy-to restent après la session. Penser à les supprimer :

kubectl delete pod mon-pod-debug

Les ephemeral containers, eux, s'arrêtent à la fin de la session mais restent visibles dans kubectl describe pod — c'est normal, ils ne consomment plus de ressources.

Résumé#

Schéma des trois façons de déboguer avec kubectl debug : 1. un container éphémère busybox est ajouté au pod existant, qui n'est pas modifié autrement, et partage le PID namespace du container app (--target=app) ; 2. --copy-to crée une copie mon-pod-debug avec le container app et un container debug (netshoot), le pod original restant intact ; 3. node/ lance un pod de debug dans les namespaces de l'hôte, avec le système de fichiers du node monté sous /host

MéthodePod modifiéPod redémarréCas d'usage
kubectl execNonNonImage avec shell et outils
kubectl debug --copy-toCopie crééeNonDebug approfondi avec outils custom
Ephemeral containersOui (in-place)NonDebug en production, images distroless
Debug nodePod sur le nodeNonProblèmes OS / kubelet / réseau

← Tous les articles