Kubernetes : Déboguer un pod en cours d'exécution – Concepts avancés et exemples pratiques

Introduction

Déboguer un pod en cours d'exécution dans Kubernetes exige plus que consulter les journaux. Lorsqu'un pod se comporte anormalement mais ne plante pas, vous devez inspecter son état interne sans perturber la charge de travail. Cet article couvre des techniques avancées pour déboguer des pods en direct, notamment les conteneurs éphémères, l'inspection des processus, l'analyse réseau et les flux de récupération sécurisés. Il s'adresse aux développeurs, ingénieurs DevOps et SRE qui doivent diagnostiquer des problèmes dans des environnements de type production.

Le principe fondamental est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés pour les secrets, vérifier les résultats et documenter les étapes de récupération. Nous explorerons des commandes, des sorties attendues et des signaux d'échec pour vous aider à passer du symptôme à la solution.

Prérequis et inventaire de l'environnement

Avant de déboguer, confirmez que votre cluster et vos outils sont prêts.

Kubernetes version 1.23 ou ultérieure pour kubectl debug avec conteneurs éphémères.
Client kubectl dont la version se situe à une version mineure près du serveur.
Accès au cluster avec la permission de créer des pods et d'exécuter des commandes dans les conteneurs.
Activer la fonctionnalité EphemeralContainers si vous utilisez des versions plus anciennes (disponible de manière générale en 1.25).

Vérifiez votre environnement avec :

kubectl version --short
# Exemple de sortie :
# Client Version: v1.27.2
# Server Version: v1.27.3

Vérifiez que les conteneurs éphémères sont autorisés en listant les ressources API :

kubectl api-resources | grep -i ephemeral
# Exemple de sortie :
# ephemeralcontainers   pods   true   EphemeralContainer

Si la ressource est absente, vous devrez peut-être mettre à jour votre cluster ou utiliser des méthodes de débogage plus anciennes comme la modification de la spécification du déploiement.

Comprendre les états d'un pod et les points d'entrée du débogage

Le champ STATUS retourné par kubectl get pods donne le premier indice. Les états courants incluent Running, Pending, CrashLoopBackOff, Error et Completed. Chaque état suggère des approches de débogage différentes.

Running : Le pod est planifié et au moins un conteneur est en cours d'exécution. Des problèmes internes peuvent toujours exister.
Pending : Le pod ne peut pas être planifié, souvent en raison de contraintes de ressources ou de sélecteurs de nœuds.
CrashLoopBackOff : Un conteneur démarre puis se termine avec une erreur de manière répétée. Les journaux de l'instance précédente sont cruciaux.
Error : Un conteneur s'est terminé avec une erreur.
Completed : Le conteneur s'est terminé avec succès ; pour le débogage, vous devrez peut-être le maintenir en cours d'exécution.

Pour voir les événements détaillés et les conditions :

kubectl describe pod <pod-name> -n <namespace>

Examinez la section Events pour les échecs de planification, les erreurs de récupération d'image ou les échecs de sondes.

Débogage avancé avec des conteneurs éphémères

Les conteneurs éphémères sont la méthode moderne pour déboguer un pod en cours d'exécution sans le redémarrer. Ils partagent le réseau du pod, l'espace de noms des processus et éventuellement d'autres espaces de noms, vous permettant d'inspecter de l'intérieur.

Quand utiliser des conteneurs éphémères

Le pod n'a pas de shell dans ses conteneurs existants (images distroless).
Vous devez attacher des outils de débogage sans modifier le conteneur d'origine.
Vous voulez observer l'activité au niveau des processus sans arrêter le conteneur.

Créer un conteneur éphémère avec kubectl debug

La commande de base :

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

Exemple :

kubectl debug -it my-app-pod --image=busybox --target=my-app -n production

Vous serez placé dans un shell à l'intérieur du conteneur éphémère. Vous pouvez maintenant inspecter les fichiers, exécuter des commandes réseau ou utiliser des outils de débogage.

Partager l'espace de noms des processus

Par défaut, le conteneur éphémère ne partage pas l'espace de noms des processus, donc vous ne verrez pas les processus du conteneur cible. Pour le partager, vous devez créer le conteneur éphémère en utilisant un correctif JSON ou un fichier YAML car kubectl debug n'a pas de drapeau pour cela.

Exemple de fichier correctif debug-pod.yaml :

apiVersion: v1
kind: Pod
metadata:
  name: my-app-pod
  namespace: production
spec:
  ephemeralContainers:
  - name: debugger
    image: busybox
    command:
    - sleep
    - "3600"
    targetContainerName: my-app
    securityContext:
      runAsUser: 0
    stdin: true
    tty: true

Appliquez avec :

kubectl replace --raw /api/v1/namespaces/production/pods/my-app-pod/ephemeralcontainers -f debug-pod.yaml

Puis attachez-vous :

kubectl attach -it -n production my-app-pod -c debugger

À l'intérieur, exécutez ps aux pour voir les processus du conteneur cible.

Copier des fichiers

Les conteneurs éphémères peuvent être utilisés pour copier des fichiers vers et depuis le pod avec kubectl cp. Cela est utile pour extraire des coredumps ou ajouter des outils de débogage.

Du pod vers le local :

kubectl cp production/my-app-pod:/app/data -c debugger ./local-data

Du local vers le pod :

kubectl cp ./my-tool production/my-app-pod:/tmp/my-tool -c debugger

Considérations de sécurité

Les conteneurs éphémères s'exécutent avec les mêmes privilèges que l'utilisateur spécifié dans le contexte de sécurité. Évitez de les exécuter en tant que root sauf nécessité, et nettoyez après le débogage. Le conteneur éphémère reste jusqu'à la suppression du pod ; vous pouvez le supprimer en modifiant le pod.

Inspecter les processus et l'état d'exécution

Lorsque vous ne pouvez pas utiliser de conteneurs éphémères, vous pouvez toujours recueillir des informations avec kubectl exec si le conteneur cible possède un shell.

Exécuter des commandes dans le conteneur cible

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

Si le conteneur s'exécute en tant qu'utilisateur non root, vous devrez peut-être utiliser les drapeaux --user ou --privileged, mais utilisez-les avec prudence.

Vérifier la liste des processus

kubectl exec <pod-name> -n <namespace> -- ps aux
# Exemple de sortie :
# USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
# root 1 0.1 0.3 123456 7890 ? Ssl 10:00 0:01 python app.py
# root 250 0.0 0.1 65432 1234 ? Ss 10:05 0:00 /bin/sh

Cela montre si le processus attendu est en cours d'exécution et son utilisation des ressources.

Inspection du système de fichiers

kubectl exec <pod-name> -n <namespace> -- df -h
kubectl exec <pod-name> -n <namespace> -- du -sh /app

Vérifiez les problèmes d'espace disque ou les fichiers inattendus.

Informations d'exécution via /proc

Vous pouvez accéder à /proc à l'intérieur du conteneur pour obtenir des détails d'exécution :

kubectl exec <pod-name> -n <namespace> -- cat /proc/1/status

Cela donne des détails sur la mémoire, le CPU et d'autres informations sur le PID 1.

Débogage réseau à l'intérieur du pod

Les problèmes réseau sont courants. Utilisez des outils depuis l'intérieur du pod pour tester la connectivité et le DNS.

Tester la résolution DNS

kubectl exec <pod-name> -n <namespace> -- nslookup kubernetes.default
# Sortie attendue :
# Server: 10.96.0.10
# Address: 10.96.0.10:53
# Name: kubernetes.default.svc.cluster.local
# Address: 10.96.0.1

Si le DNS échoue, vérifiez resolv.conf et le service DNS du cluster.

Vérifier la connectivité avec curl

kubectl exec <pod-name> -n <namespace> -- curl -v http://service-name.namespace.svc.cluster.local

Si curl n'est pas disponible, utilisez wget ou nc.

Inspecter les sockets et le routage

kubectl exec <pod-name> -n <namespace> -- netstat -tulpn
kubectl exec <pod-name> -n <namespace> -- ip route

Ces commandes aident à identifier les ports en écoute et les problèmes de routage.

Utiliser un conteneur de débogage pour les outils réseau

Si le conteneur cible manque d'outils réseau, créez un conteneur éphémère avec une image d'outils réseau, comme nicolaka/netshoot :

kubectl debug -it <pod-name> --image=nicolaka/netshoot --target=<container-name> -n <namespace>

Ensuite, exécutez tcpdump, nmap, etc.

Question rapide 2 sur 2

Quand peut-on utiliser kubectl debug pour créer une copie d'un Pod ?

Le passage indique : « Parfois, les options de configuration du Pod rendent le dépannage difficile dans certaines situations. Par exemple, vous ne pouvez pas exécuter kubectl exec pour dépanner votre conteneur si votre image de conteneur ne comprend pas de shell ou si votre application plante au démarrage. Dans ces situations, vous pouvez utiliser kubectl debug pour créer une copie du Pod avec des valeurs de configuration modifiées afin de faciliter le débogage. »

Débogage avec coredumps et analyse mémoire

Pour les plantages ou les problèmes de mémoire, vous devrez peut-être capturer un coredump.

Activer les coredumps

Définissez ulimit -c unlimited dans le conteneur et assurez-vous que /proc/sys/kernel/core_pattern est accessible en écriture ou redirigez vers un volume monté.

Exemple de spécification de pod :

apiVersion: v1
kind: Pod
metadata:
  name: core-dump-pod
spec:
  containers:
  - name: app
    image: myapp:latest
    volumeMounts:
    - name: core-dumps
      mountPath: /cores
    securityContext:
      capabilities:
        add: ["SYS_PTRACE"]
  volumes:
  - name: core-dumps
    emptyDir: {}

Ensuite, à l'intérieur du conteneur, définissez ulimit -c unlimited && cd /cores && ./app.

Après le plantage, récupérez le fichier core :

kubectl cp core-dump-pod:/cores/core ./core

Analysez avec gdb :

gdb ./app ./core

Modes de défaillance et stratégies de récupération

Modes de défaillance courants

OOMKilled (mémoire insuffisante)

Symptôme : Le pod redémarre avec la raison OOMKilled dans kubectl describe pod.
Vérification : Consultez kubectl get pod -o yaml pour lastState.terminated.reason: OOMKilled.
Récupération : Augmentez les limites de mémoire ou optimisez l'application.

CrashLoopBackOff

Symptôme : Le statut du pod montre CrashLoopBackOff.
Vérification : kubectl logs <pod> --previous montre l'erreur du dernier plantage.
Récupération : Corrigez l'erreur de l'application.

ImagePullBackOff

Symptôme : Le pod ne peut pas récupérer l'image, statut ImagePullBackOff.
Vérification : kubectl describe pod montre une erreur d'authentification auprès du registre ou une image introuvable.
Récupération : Corrigez le nom de l'image ou ajoutez imagePullSecrets.

Plantage dû à une mauvaise configuration

Symptôme : L'application se termine immédiatement.
Débogage : Utilisez kubectl exec pour exécuter la commande manuellement si possible.

Flux de récupération

Ayez toujours un plan de retour en arrière. Utilisez kubectl rollout undo pour les déploiements :

kubectl rollout undo deployment/my-app -n production

Vérifiez l'état du déploiement :

kubectl rollout status deployment/my-app -n production

Si un pod est bloqué, vous pouvez le supprimer de force :

kubectl delete pod <pod-name> -n <namespace> --grace-period=0 --force

Mais soyez prudent : cela peut entraîner une perte de données.

Liste de contrôle des opérations

Suivez cette liste de contrôle pour un débogage systématique :

Identifier le pod et l'espace de noms : kubectl get pods -n production
Vérifier l'état du pod et les événements : kubectl describe pod my-app-pod -n production
Consulter les journaux : kubectl logs my-app-pod -c my-app -n production --tail=100
En cas de boucle de plantage, consulter les journaux précédents : kubectl logs my-app-pod -c my-app -n production --previous
Vérifier l'utilisation des ressources : kubectl top pod my-app-pod -n production
Attacher un conteneur éphémère si nécessaire : kubectl debug -it my-app-pod --image=busybox --target=my-app -n production
Tester le réseau : Depuis l'intérieur, exécutez curl http://service ou nslookup.
Inspecter les processus : ps aux, df -h, du -sh /app.
Faire un changement à la fois et observer.
Documenter les constatations et les étapes de récupération.

Conclusion

Déboguer un pod en cours d'exécution dans Kubernetes exige une approche systématique qui équilibre observation et intervention. Des techniques avancées comme les conteneurs éphémères offrent des moyens puissants d'inspecter les charges de travail en direct sans perturbation. En suivant les principes du débogage sécurisé, vous pouvez isoler rapidement les problèmes et récupérer avec un impact minimal. Vérifiez toujours votre environnement, comprenez l'état du pod et utilisez les bons outils pour le diagnostic. Avec de la pratique, vous gérerez même les problèmes de pods les plus complexes avec confiance.

Comme prochaine étape, choisissez une technique de cet article, comme les conteneurs éphémères ou l'inspection des processus, et appliquez-la à un pod non critique de votre cluster. Notez les commandes et les sorties, et construisez votre propre manuel de débogage.