Maîtriser kubectl logs et describe pour un débogage efficace des Pods
Le débogage des applications dans un environnement distribué comme Kubernetes peut être difficile. Lorsqu'un Pod ne parvient pas à démarrer, entre dans une boucle de redémarrage ou présente un comportement inattendu, les deux outils les plus critiques dans la boîte à outils d'un opérateur Kubernetes sont kubectl describe et kubectl logs.
Ces commandes fournissent des vues différentes, mais complémentaires, sur l'état et l'historique d'un Pod Kubernetes. kubectl describe vous donne les métadonnées, le statut, les variables d'environnement du Pod et, de manière cruciale, un historique des événements système. kubectl logs fournit les flux de sortie standard (stdout) et d'erreur standard (stderr) générés par l'application conteneurisée elle-même.
La maîtrise des options (flags) et des techniques associées à ces commandes est essentielle pour diagnostiquer et résoudre rapidement les problèmes, améliorant ainsi considérablement votre efficacité globale en matière de dépannage de cluster.
Le flux de travail de débogage des Pods en trois étapes
Avant de plonger dans les commandes, il est utile de comprendre le flux de travail de débogage typique :
- Vérifier l'état : Utilisez
kubectl get podspour identifier l'état d'échec (Pending,CrashLoopBackOff,ImagePullBackOff, etc.). - Obtenir le contexte et les événements : Utilisez
kubectl describe podpour comprendre pourquoi la transition d'état s'est produite (par exemple, échec du planificateur, échec de la sonde de vivacité (liveness probe), échec du montage du volume). - Inspecter la sortie de l'application : Utilisez
kubectl logspour examiner le comportement d'exécution de l'application (par exemple, erreurs de configuration, échecs de connexion à la base de données, traces de pile).
1. kubectl describe : L'outil de triage système
kubectl describe est la première commande que vous devriez exécuter lorsqu'un Pod se comporte mal. Elle n'affiche pas la sortie de l'application, mais elle fournit les métadonnées et l'historique critiques que Kubernetes lui-même a enregistrés sur le Pod.
Utilisation de base
L'utilisation fondamentale ne nécessite que le nom du Pod :
kubectl describe pod my-failing-app-xyz789
Sections clés de la sortie
Lors de l'examen de la sortie de describe, concentrez-vous sur ces sections critiques :
A. Statut et État
Regardez le champ Status en haut, puis examinez les états des conteneurs individuels dans le Pod. Cela vous indique si le conteneur est Running (En cours d'exécution), Waiting (En attente) ou Terminated (Terminé), et fournit la raison de cet état.
| Champ | Statut/Raison Courant | Signification |
|---|---|---|
Status |
Pending |
Le Pod attend d'être planifié ou manque de ressources. |
Reason |
ContainerCreating |
Le runtime du conteneur tire l'image ou exécute la configuration. |
State |
Waiting / Reason: CrashLoopBackOff |
Le conteneur a démarré et s'est arrêté de manière répétée. |
State |
Terminated / Exit Code |
Le conteneur a terminé son exécution. Les codes de sortie non nuls indiquent généralement des erreurs. |
B. Configuration du Conteneur
Cette section vérifie que vos variables d'environnement, les demandes/limites de ressources, les montages de volumes et les sondes de vivacité/prêt (liveness/readiness probes) sont correctement définis, correspondant au manifeste que vous avez appliqué.
C. La section Events (Cruciale)
La section Events, située au bas de la sortie, est sans doute la partie la plus précieuse. Elle fournit un journal chronologique de ce que le plan de contrôle Kubernetes a fait pour et au Pod, y compris les avertissements et les erreurs.
Erreurs courantes révélées par les Events :
- Problèmes de planification :
Warning FailedScheduling: Indique que le planificateur n'a pas pu trouver de nœud approprié (par exemple, en raison de contraintes de ressources, de taints de nœuds ou de règles d'affinité). - Échecs de tirage d'image :
Warning Failed: ImagePullBackOff: Indique que le nom de l'image est incorrect, que l'étiquette n'existe pas, ou que Kubernetes n'a pas les informations d'identification nécessaires pour tirer depuis un registre privé. - Erreurs de volume :
Warning FailedAttachVolume: Indique des problèmes de connexion au stockage externe.
Astuce : Si la section
Eventsest propre, le problème est généralement lié à l'application (crash d'exécution, échec d'initialisation, erreur de configuration), vous dirigeant vers l'utilisation dekubectl logsensuite.
2. kubectl logs : Inspection de la sortie de l'application
Si describe montre que le Pod a été planifié avec succès et que les conteneurs ont tenté de s'exécuter, l'étape suivante consiste à vérifier les flux de sortie standard à l'aide de kubectl logs.
Récupération de base des journaux et flux en temps réel
Pour visualiser les journaux actuels du conteneur principal d'un Pod :
# Récupérer tous les journaux jusqu'au moment actuel
kubectl logs my-failing-app-xyz789
# Diffuser les journaux en temps réel (utile pour surveiller le démarrage)
kubectl logs -f my-failing-app-xyz789
Gestion des Pods multi-conteneurs
Pour les Pods utilisant le modèle Sidecar ou d'autres conceptions multi-conteneurs, vous devez spécifier les journaux de quel conteneur vous souhaitez voir en utilisant l'option -c ou --container.
# Voir les journaux du conteneur 'sidecar-proxy' dans le Pod
kubectl logs my-multi-container-pod -c sidecar-proxy
# Diffuser les journaux pour le conteneur de l'application principale
kubectl logs -f my-multi-container-pod -c main-app
Débogage des conteneurs redémarrant (--previous)
L'un des scénarios de débogage les plus courants est l'état CrashLoopBackOff. Lorsqu'un conteneur redémarre, kubectl logs n'affiche que la sortie de la tentative actuelle (échouée), qui ne contient souvent que le message de démarrage avant le crash.
Pour visualiser les journaux de l'instance précédente et terminée — qui contient l'erreur réelle ayant provoqué la sortie — utilisez l'option --previous (-p) :
# Voir les journaux de l'instance de conteneur précédente et plantée
kubectl logs my-crashloop-pod --previous
# Combiner avec la spécification du conteneur si nécessaire
kubectl logs my-crashloop-pod -c worker --previous
Limitation de la sortie
Pour les journaux à volume élevé, la récupération de l'historique complet peut être lente ou accablante. Utilisez --tail pour limiter la sortie aux N dernières lignes.
# Afficher uniquement les 50 dernières lignes des journaux du conteneur
kubectl logs my-high-traffic-app --tail=50
3. Combinaison des techniques pour un diagnostic avancé
Un débogage efficace implique souvent de passer rapidement entre les commandes describe et les commandes logs spécifiques.
Étude de cas : Diagnostic de l'échec de la sonde de vivacité (Liveness Probe)
Imaginez qu'un Pod soit bloqué en état Running mais redémarre occasionnellement, provoquant des perturbations.
Étape 1 : Vérifiez describe pour la vue système.
kubectl describe pod web-server-dpl-abc
La sortie montre dans la section Événements :
Type Reason Age From Message
---- ------ ---- ---- -------
Warning Unhealthy 2s kubelet, node-a01 Liveness probe failed: HTTP GET http://10.42.0.5:8080/health failed: 503 Service Unavailable
Conclusion de l'étape 1 : Le conteneur est en cours d'exécution, mais la sonde de vivacité échoue avec une erreur 503, ce qui incite Kubernetes à redémarrer le conteneur.
Étape 2 : Vérifiez les logs pour le contexte de l'application.
Maintenant, enquêtez sur la raison pour laquelle l'application renvoie un statut 503, ce qui est une erreur au niveau de l'application.
kubectl logs web-server-dpl-abc --tail=200
La sortie des journaux révèle :
2023-10-26 14:01:15 ERROR Database connection failure: Timeout connecting to DB instance 192.168.1.10
Conclusion finale : Le Pod redémarre en raison d'une sonde de vivacité défaillante, et la sonde échoue parce que l'application ne peut pas se connecter à la base de données. Le problème est externe (réseau ou configuration de la base de données), et non lié au conteneur lui-même.
Bonnes pratiques et avertissements
| Pratique | Commande | Justification |
|---|---|---|
| Vérifiez toujours les journaux précédents | kubectl logs --previous |
Nécessaire pour diagnostiquer CrashLoopBackOff. L'erreur critique se trouve presque toujours dans l'exécution précédente. |
| Spécifiez les conteneurs | kubectl logs -c <name> |
Évite l'ambiguïté dans les Pods multi-conteneurs et empêche la récupération des journaux des sidecars non intentionnels. |
| Utilisez des étiquettes pour les opérations groupées | kubectl logs -l app=frontend -f |
Permet de diffuser simultanément les journaux de plusieurs Pods correspondant à un sélecteur (utile pour les mises à jour progressives). |
| Avertissement : Rotation des journaux | N/A | Les nœuds Kubernetes effectuent une rotation des journaux. Les journaux plus anciens que la politique de rétention configurée du nœud (souvent quelques jours ou basés sur la taille) seront purgés et inaccessibles via kubectl logs. Utilisez une solution de journalisation centralisée externe (par exemple, Fluentd, Loki, Elastic Stack) pour une rétention à long terme. |
Conclusion
kubectl describe et kubectl logs sont les commandes de base indispensables pour le débogage dans Kubernetes. En traitant describe comme le rapport d'état du système (en se concentrant sur la configuration, les événements et les erreurs de planification) et logs comme le flux d'exécution de l'application (en se concentrant sur les erreurs de code et le comportement d'exécution), vous pouvez systématiquement cerner la cause de presque toutes les défaillances de Pod, réduisant ainsi considérablement le Temps Moyen de Résolution (MTTR) au sein de votre cluster.