Diagnostiquer un cluster Kubernetes avec kubectl

Lorsque vous gérez un cluster Kubernetes, des problèmes peuvent survenir : pods en erreur, conteneurs qui plantent ou services inaccessibles. Pour les diagnostiquer efficacement, kubectl propose plusieurs commandes essentielles comme get, describe, logs et top. Ce guide vous montre comment les utiliser pour identifier rapidement les causes des dysfonctionnements et appliquer les correctifs nécessaires.

• kubectl describe vous permet d’obtenir des informations détaillées sur une ressource Kubernetes (pods, nœuds, services…) et d’identifier les événements récents qui peuvent expliquer un dysfonctionnement.
• kubectl logs vous aide à analyser les journaux d’un conteneur, ce qui est important pour comprendre pourquoi une application plante ou ne fonctionne pas comme prévu.

Utilisation de la commande kubectl get

La commande kubectl get est l’une des commandes les plus fréquemment utilisées pour interagir avec Kubernetes. Elle permet de récupérer et d’afficher des informations sur les ressources d’un cluster Kubernetes. Que vous soyez en train de gérer des Pods, des Services, des Déploiements ou d’autres objets Kubernetes, kubectl get vous offre une vue d’ensemble de l’état de ces ressources.

Syntaxe de base

La syntaxe de base de la commande kubectl get est la suivante :

kubectl get [RESOURCE_TYPE] [NAME] [flags]

• RESOURCE_TYPE : Le type de ressource que vous souhaitez afficher (par exemple, pods, services, deployments).
• NAME (optionnel) : Le nom spécifique de la ressource. Si omis, toutes les ressources du type spécifié seront listées.
• flags (optionnel) : Options supplémentaires pour filtrer ou formater la sortie.

Affichage des ressources

Afficher tous les Pods :

Pour afficher tous les Pods dans le namespace par défaut, utilisez :

kubectl get pods

Pour afficher les Pods dans un namespace spécifique :

kubectl get pods -n my-namespace

Afficher un Pod spécifique :

Pour afficher un Pod spécifique nommé nginx-pod :

kubectl get pod nginx-pod

(Afficher d’autres types de ressources):

De la même manière, vous pouvez afficher d’autres types de ressources :

• Tous les Services :

  kubectl get services

• Tous les Déploiements :

  kubectl get deployments

Options de formatage

La commande kubectl get offre plusieurs options pour formater la sortie, ce qui peut être très utile pour obtenir des informations spécifiques dans un format facile à lire ou à traiter par des scripts.

(Option -o wide):

Pour obtenir une sortie plus détaillée, vous pouvez utiliser l’option -o wide :

kubectl get pods -o wide

Cette option ajoute des colonnes supplémentaires à la sortie, telles que l’adresse IP du Pod et le Node sur lequel il s’exécute.

(Option -o yaml ou -o json):

Pour afficher les ressources au format YAML ou JSON, utilisez respectivement les options -o yaml ou -o json :

kubectl get pod nginx-pod -o yaml

kubectl get pod nginx-pod -o json

(Option --selector (ou -l)):

Pour filtrer les ressources en fonction de labels, utilisez l’option --selector ou -l :

kubectl get pods -l app=nginx

(Surveiller les ressources en temps réel):

Pour surveiller les ressources en temps réel, utilisez l’option -w (watch) :

kubectl get pods -w

Utilisation de la commande kubectl describe

La commande kubectl describe est un outil essentiel pour obtenir des informations détaillées sur une ressource Kubernetes (pods, nœuds, services…). Elle permet d’identifier les événements récents qui peuvent expliquer un dysfonctionnement ou un comportement inattendu d’une ressource.

Tout est documenté dans un guide dédié.

kubectl logs : Analyser les journaux d’un conteneur

La commande kubectl logs est essentielle pour analyser les journaux d’un conteneur Kubernetes et comprendre pourquoi une application ne fonctionne pas correctement. Elle vous permet de voir les messages de sortie de l’application et de détecter d’éventuelles erreurs.

Cependant, il est important de noter que kubectl logs ne fonctionne pas sur un conteneur qui est en erreur et ne tourne plus. Dans ce cas, on peut utiliser --previous pour récupérer les logs de l’exécution précédente.

Syntaxe générale de la commande

kubectl logs <nom-du-pod>

Exemples d’utilisation :

• Lire les logs d’un pod en cours d’exécution :

  kubectl logs mon-pod

• Lire les logs d’un conteneur spécifique dans un pod multi-conteneur :

  kubectl logs mon-pod -c mon-conteneur

• Afficher les logs en continu (mode live) :

  kubectl logs -f mon-pod

  Regardez du coté de stern pour une meilleure expérience de suivi des logs.

• Récupérer les logs d’un conteneur qui a planté (previous) :

  kubectl logs --previous mon-pod

  Si un pod est en CrashLoopBackOff, cette option vous permet d’accéder aux logs de son exécution précédente.

• Récupérer les logs d’un pod dans un namespace spécifique :

  kubectl logs -n mon-namespace mon-pod

Interprétation des logs et analyse des erreurs

(Vérifier les logs d’un conteneur en cours d’exécution):

Si votre pod tourne normalement, mais que mon application ne fonctionne pas comme prévu, commencez par lire ses logs avec :

kubectl logs mon-pod

Dans un pod multi-conteneur, on doit préciser le conteneur concerné :

kubectl logs mon-pod -c mon-conteneur

À analyser dans les logs :

• Messages d’erreur ou d’exception (Error, Exception, Failed).
• Logs de démarrage pour vérifier si l’application charge bien sa configuration.
• Requêtes HTTP pour identifier des erreurs (500 Internal Server Error, 403 Forbidden…).

Diagnostiquer un pod en CrashLoopBackOff

Si un pod redémarre en boucle, vous ne pourrez pas voir ses logs en direct, mais vous pouvez récupérer les logs de l’exécution précédente avec :

kubectl logs --previous mon-pod

On peut ainsi identifier la dernière erreur avant que le conteneur ne plante.

Cas d’erreurs courants dans les logs :

• Problème d’environnement (Missing environment variable).
• Échec de connexion à une base de données (Connection refused).
• Fichier de configuration introuvable (FileNotFoundError).

Lorsque kubectl logs ne suffit pas à identifier un problème, j’utilise kubectl exec et kubectl debug pour aller plus loin dans l’analyse et la résolution des erreurs.

kubectl describe : Explorer les ressources Kubernetes**

La commande kubectl describe est essentielle pour obtenir des informations détaillées sur une ressource Kubernetes et comprendre pourquoi un pod, un nœud ou un service ne fonctionne pas correctement. Elle vous permet d’analyser l’état de la ressource, de voir les événements récents et de détecter d’éventuelles erreurs.

Syntaxe générale de la commande

kubectl describe <ressource> <nom>

Exemples d’utilisation :

• Décrire un pod :

  kubectl describe pod mon-pod

• Décrire un nœud :

  kubectl describe node mon-nœud

• Décrire un service :

  kubectl describe svc mon-service

• Décrire un déploiement :

  kubectl describe deployment mon-deploiement

Informations retournées par kubectl describe pod

Lorsque vous exécutez kubectl describe pod mon-pod, la commande retourne plusieurs sections importantes que vous devez analyser en fonction du problème rencontré.

Informations générales

Affiche des détails sur le pod et ses métadonnées :

Name:         mon-pod
Namespace:    default
Node:         worker-node-1
Start Time:   Thu, 20 Feb 2025 10:30:00 +0000
Labels:       app=web
Status:       Running

À vérifier :

• Le nom du nœud où tourne le pod.
• L’heure de démarrage du pod.
• Les labels pour voir s’il correspond bien aux sélections des services ou des déploiements.

Informations sur les conteneurs

Détaille les conteneurs du pod, leurs images et leurs configurations :

Containers:
  my-container:
    Container ID:   docker://abcdef12345
    Image:          nginx:latest
    Ports:          80/TCP
    State:          Running
      Started:      Thu, 20 Feb 2025 10:30:10 +0000
    Ready:          True
    Restart Count:  0

À vérifier :

• Image utilisée (nginx:latest dans cet exemple) → Vérifier que l’image est correcte.
• État du conteneur (Running, Waiting, Terminated).
• Nombre de redémarrages (Restart Count).
  • Si ce nombre est élevé, c’est un signe que le pod plante et redémarre en boucle (CrashLoopBackOff).
• Ports exposés pour vérifier s’ils correspondent au service associé.

Événements récents et erreurs

Affiche la liste des événements récents affectant le pod :

Events:
  Type     Reason     Age               From               Message
  ----     ------     ----              ----               -------
  Normal   Scheduled  5m                default-scheduler  Successfully assigned default/mon-pod to worker-node-1
  Normal   Pulled     4m                kubelet            Container image "nginx:latest" already present on machine
  Normal   Created    4m                kubelet            Created container my-container
  Normal   Started    4m                kubelet            Started container my-container
  Warning  Unhealthy  2m                kubelet            Liveness probe failed: HTTP probe failed with status code 500

À vérifier :

• Échecs des probes de santé (Liveness probe failed) indiquant un problème d’application.
• Événements en Warning (erreurs de scheduling, image non trouvée, etc.).
• Délais de lancement des conteneurs (Pulling, Created, Started).

Analyse détaillée des erreurs possibles avec kubectl describe

Pod bloqué en Pending

Symptômes : kubectl get pods affiche Pending.

Diagnostic avec :

kubectl describe pod mon-pod

Solutions possibles :

• Vérifier si un volume ne peut pas être monté.
• Voir les événements pour détecter une erreur de scheduling.

CrashLoopBackOff (Redémarrage en boucle)

Symptômes : kubectl get pods montre CrashLoopBackOff.

Diagnostic avec :

kubectl describe pod mon-pod

Solutions possibles :

• Vérifier les logs (kubectl logs mon-pod).
• Vérifier l’environnement (kubectl exec mon-pod -- env).

Erreur ErrImagePull ou ImagePullBackOff

Symptômes : L’image ne se télécharge pas.

Diagnostic avec :

kubectl describe pod mon-pod

Solutions possibles :

• Vérifier que l’image existe (docker pull <image>).
• Vérifier les credentials pour un registre privé.
• Vérfier que les tags d’image sont corrects.

Pod supprimé immédiatement (Evicted)

Symptômes : kubectl get pods montre Evicted.

Diagnostic avec :

kubectl describe pod mon-pod

Solutions possibles :

• Vérifier les événements (kubectl get events).
• Vérifier si le pod manque de ressources (kubectl describe pod).

Autres ressources que vous pouvez analyser avec kubectl describe**

Ressource	Commande
Pods	kubectl describe pod mon-pod
Nœuds	kubectl describe node mon-nœud
Services	kubectl describe svc mon-service
Deployments	kubectl describe deployment mon-deploiement
ConfigMaps	kubectl describe configmap mon-configmap

Grâce à kubectl describe, vous pouvez comprendre pourquoi un pod ne fonctionne pas, voir les événements récents et identifier les erreurs de scheduling ou d’exécution. C’est une première étape essentielle dans le diagnostic Kubernetes.

kubectl top : Surveiller l’utilisation des ressources

La commande kubectl top est un outil essentiel pour surveiller l’utilisation des ressources dans un cluster Kubernetes. Elle permet d’afficher les consommations CPU et mémoire des nœuds et des pods en temps réel, facilitant ainsi la gestion des performances et l’identification des goulets d’étranglement.

Prérequis

Pour utiliser kubectl top, le cluster doit avoir le Metrics Server installé. Ce composant collecte et expose les métriques d’utilisation des ressources des nœuds et des pods.

Si Metrics Server n’est pas encore installé, vous pouvez l’ajouter avec :

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

Après installation, vérifiez son bon fonctionnement :

kubectl get apiservices | grep metrics

Afficher l’utilisation des ressources des nœuds

Pour surveiller la consommation CPU et mémoire de chaque nœud du cluster :

kubectl top nodes

Cette commande affiche les nœuds avec leur consommation actuelle de ressources.

Afficher l’utilisation des ressources des

Pour voir les ressources utilisées par chaque pod :

kubectl top pods

Pour filtrer par namespace :

kubectl top pods -n mon-namespace

Afficher l’utilisation des ressources pour un pod spécifique

kubectl top pod mon-pod

Cette commande montre la consommation CPU et mémoire d’un pod donné.

Conclusion

kubectl describe et kubectl logs sont des outils indispensables pour diagnostiquer et résoudre les problèmes dans un cluster Kubernetes. Tandis que kubectl describe permet d’examiner l’état des ressources et d’identifier les événements récents, kubectl logs offre un accès direct aux journaux des conteneurs pour comprendre les erreurs applicatives.

En complément, kubectl exec permet d’exécuter des commandes dans un conteneur en cours d’exécution, et kubectl debug facilite le dépannage des pods qui ne démarrent pas. En combinant ces commandes, on peut identifier rapidement les causes des dysfonctionnements et appliquer des correctifs adaptés.

Notes importantes

Ce guide fait partie d’une série complète dédiée à l’utilisation de kubectl, l’outil en ligne de commande incontournable pour administrer un cluster Kubernetes. Chaque commande de kubectl est abordée en détail dans des guides spécifiques, organisés par thématique pour faciliter l’apprentissage et la référence rapide.

Pour naviguer efficacement entre les différents chapitres, vous trouverez un tableau récapitulatif listant les commandes et leurs guides associés. N’hésitez pas à explorer ces ressources pour approfondir vos connaissances et optimiser votre gestion des clusters Kubernetes.

Commandes	Documentation
kubectl api-resources, kubectl explain	Exploration de l’API
kubectl create, kubectl apply	Création et mise à jour des ressources
kubectl edit, kubectl patch, kubectl replace	Modification des ressources
kubectl get, kubectl describe, kubectl logs, kubectl top	Récupération d’informations sur les ressources
kubectl exec, kubectl attach, kubectl debug, kubectl cp	Gestion et Debug des Pods
kubectl delete, kubectl annotate, kubectl label	Suppression et annotation
kubectl expose, kubectl port-forward, kubectl proxy	Exposition et accès aux applications
kubectl scale, kubectl autoscale, kubectl rollout, kubectl set	Mise à l’échelle et gestion des déploiements
kubectl wait, kubectl diff	Attente et validation des ressources