
Quatre commandes suffisent pour diagnostiquer 90 % des problèmes Kubernetes : kubectl get repère les ressources en erreur, kubectl describe explique pourquoi, kubectl logs montre ce que l’application a écrit, et kubectl top détecte les goulets de ressources. Ce guide vous apprend à les combiner efficacement.
Ce que vous allez apprendre
Section intitulée « Ce que vous allez apprendre »À la fin de ce guide, vous saurez :
- Lister et filtrer des ressources avec
kubectl get(labels, colonnes personnalisées, formats de sortie) - Inspecter l’état complet d’un pod avec
kubectl describeet interpréter chaque section de sa sortie - Extraire les logs d’un conteneur (en temps réel, multi-conteneurs, après un crash)
- Surveiller CPU et mémoire avec
kubectl topet repérer les fuites de ressources - Diagnostiquer les 6 incidents les plus courants grâce aux runbooks en fin de guide
kubectl get — Lister les ressources
Section intitulée « kubectl get — Lister les ressources »kubectl get est votre point d’entrée. Il affiche l’état de n’importe quelle ressource Kubernetes : pods, services, deployments, nodes, etc.
Syntaxe de base
Section intitulée « Syntaxe de base »kubectl get <ressource> [nom] [-n namespace] [options]Exemples courants :
# Tous les pods du namespace courantkubectl get pods
# Tous les pods de tous les namespaceskubectl get pods -A
# Un pod préciskubectl get pod mon-pod
# Plusieurs types de ressources en une commandekubectl get pods,services,deploymentsFiltrer avec les labels
Section intitulée « Filtrer avec les labels »Les labels permettent de cibler précisément les ressources qui vous intéressent :
# Pods avec un label préciskubectl get pods -l app=nginx
# Combiner plusieurs labels (ET logique)kubectl get pods -l app=nginx,env=production
# Exclure un labelkubectl get pods -l 'app!=nginx'
# Label présent (quelle que soit la valeur)kubectl get pods -l 'app'Formats de sortie
Section intitulée « Formats de sortie »Par défaut, kubectl get affiche un tableau lisible. Vous pouvez changer le format selon vos besoins :
| Option | Usage | Exemple |
|---|---|---|
-o wide | Colonnes supplémentaires (IP, node) | kubectl get pods -o wide |
-o yaml | Manifeste YAML complet | kubectl get pod mon-pod -o yaml |
-o json | Format JSON (pour scripts) | kubectl get pods -o json |
-o name | Noms uniquement | kubectl get pods -o name |
-o jsonpath | Extraction ciblée | kubectl get pod mon-pod -o jsonpath='{.status.phase}' |
-o custom-columns | Tableau personnalisé | Voir ci-dessous |
Colonnes personnalisées
Section intitulée « Colonnes personnalisées »Pour construire un affichage sur mesure :
kubectl get pods -o custom-columns=\NOM:.metadata.name,\STATUS:.status.phase,\IP:.status.podIP,\NODE:.spec.nodeNameRésultat :
NOM STATUS IP NODEnginx-abc123 Running 10.244.1.5 worker-1redis-def456 Pending <none> <none>JSONPath — Extraire une valeur précise
Section intitulée « JSONPath — Extraire une valeur précise »JSONPath permet d’extraire exactement l’information dont vous avez besoin :
# IP d'un podkubectl get pod mon-pod -o jsonpath='{.status.podIP}'
# Image utilisée par le premier conteneurkubectl get pod mon-pod -o jsonpath='{.spec.containers[0].image}'
# Toutes les images de tous les podskubectl get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}'Surveiller les changements en temps réel
Section intitulée « Surveiller les changements en temps réel »L’option --watch (-w) actualise l’affichage à chaque changement d’état :
kubectl get pods -wC’est particulièrement utile après un déploiement ou pendant un incident pour voir les transitions d’état (Pending → ContainerCreating → Running ou → Error).
Résumé kubectl get
Section intitulée « Résumé kubectl get »| Besoin | Commande |
|---|---|
| Vue rapide | kubectl get pods |
| Tous les namespaces | kubectl get pods -A |
| Avec IP et node | kubectl get pods -o wide |
| Filtrer par label | kubectl get pods -l app=nginx |
| Format script | kubectl get pods -o json |
| Valeur précise | kubectl get pod X -o jsonpath='{.status.phase}' |
| Temps réel | kubectl get pods -w |
kubectl describe — Inspecter une ressource
Section intitulée « kubectl describe — Inspecter une ressource »Quand kubectl get montre un pod en erreur, kubectl describe vous dit pourquoi. Il affiche la configuration complète et les événements récents.
kubectl describe <ressource> <nom> [-n namespace]# Décrire un podkubectl describe pod mon-pod
# Décrire un nodekubectl describe node worker-1
# Décrire un servicekubectl describe service mon-serviceLire la sortie de describe pod
Section intitulée « Lire la sortie de describe pod »La sortie est longue. Voici comment la lire efficacement, section par section :
Name: mon-pod ← IdentitéNamespace: defaultNode: worker-1/192.168.1.10 ← Sur quel node il tourneStatus: Running ← État globalIP: 10.244.1.5 ← IP du pod
Containers: ← Configuration des conteneurs nginx: Image: nginx:1.25 ← Image utilisée Port: 80/TCP State: Running ← État du conteneur Started: Mon, 01 Jan 2026 10:00:00 Ready: True Restart Count: 0 ← 0 = stable, >0 = problème potentiel Limits: ← Ressources maximales autorisées cpu: 500m memory: 128Mi Requests: ← Ressources demandées au scheduler cpu: 250m memory: 64Mi
Conditions: ← Check-list de santé Type Status Initialized True ← Init containers OK Ready True ← Prêt à recevoir du trafic ContainersReady True ← Tous les conteneurs sont prêts PodScheduled True ← Planifié sur un node
Events: ← SECTION LA PLUS IMPORTANTE Type Reason Age Message ---- ------ --- ------- Normal Scheduled 2m Successfully assigned default/mon-pod to worker-1 Normal Pulled 2m Container image "nginx:1.25" already present Normal Created 2m Created container nginx Normal Started 2m Started container nginxdescribe sur d’autres ressources
Section intitulée « describe sur d’autres ressources »describe fonctionne sur toutes les ressources Kubernetes. En particulier :
| Ressource | Ce que describe révèle |
|---|---|
node | Capacité, allocations, conditions (MemoryPressure, DiskPressure), pods hébergés |
service | Endpoints (pods ciblés), sélecteur de labels, ports |
deployment | Stratégie de rollout, replicas, conditions, événements de scaling |
pvc | StorageClass, taille, status (Bound/Pending), volume associé |
# Un node manque de ressources ?kubectl describe node worker-1 | grep -A5 "Allocated resources"
# Un service ne route pas le trafic ?kubectl describe service mon-service | grep -A5 "Endpoints"kubectl logs — Lire les journaux
Section intitulée « kubectl logs — Lire les journaux »Une fois le pod identifié et son état compris, kubectl logs vous montre ce que l’application a écrit sur stdout/stderr.
Syntaxe et options essentielles
Section intitulée « Syntaxe et options essentielles »kubectl logs <pod> [-n namespace] [options]| Option | Effet | Exemple |
|---|---|---|
-f | Flux continu (comme tail -f) | kubectl logs -f mon-pod |
--tail=N | N dernières lignes | kubectl logs --tail=50 mon-pod |
--since=T | Logs depuis une durée | kubectl logs --since=5m mon-pod |
--timestamps | Ajouter l’horodatage | kubectl logs --timestamps mon-pod |
-c conteneur | Conteneur spécifique (multi-conteneur) | kubectl logs mon-pod -c sidecar |
-p | Conteneur précédent (après crash) | kubectl logs -p mon-pod |
--all-containers | Tous les conteneurs du pod | kubectl logs --all-containers mon-pod |
6 recettes de logs pour le diagnostic
Section intitulée « 6 recettes de logs pour le diagnostic »1. Dernières erreurs d’un pod
Section intitulée « 1. Dernières erreurs d’un pod »kubectl logs --tail=100 mon-pod | grep -i "error\|fatal\|panic\|exception"2. Logs depuis le dernier redémarrage
Section intitulée « 2. Logs depuis le dernier redémarrage »kubectl logs --since=10m mon-pod --timestamps3. Logs du conteneur qui a crashé
Section intitulée « 3. Logs du conteneur qui a crashé »kubectl logs -p mon-pod4. Logs d’un conteneur spécifique (sidecar/init)
Section intitulée « 4. Logs d’un conteneur spécifique (sidecar/init) »# Lister les conteneurs d'un podkubectl get pod mon-pod -o jsonpath='{.spec.containers[*].name}'
# Voir les logs du sidecarkubectl logs mon-pod -c istio-proxy5. Logs de tous les pods d’un Deployment
Section intitulée « 5. Logs de tous les pods d’un Deployment »kubectl logs -l app=nginx --all-containers --tail=506. Flux temps réel multi-pods
Section intitulée « 6. Flux temps réel multi-pods »Pour suivre les logs de plusieurs pods simultanément, stern est l’outil idéal :
# Installer sternbrew install stern # macOS# ougo install github.com/stern/stern@latest
# Suivre tous les pods nginxstern nginx
# Avec filtre sur le contenustern nginx --include "error"Interpréter les logs courants
Section intitulée « Interpréter les logs courants »| Message dans les logs | Signification probable | Action |
|---|---|---|
connection refused | Service cible inactif ou mauvais port | Vérifier le service cible avec describe svc |
permission denied | RBAC ou filesystem | Vérifier le ServiceAccount et les montages |
OOMKilled | Dépassement de limite mémoire | Augmenter resources.limits.memory |
no such host | DNS ne résout pas | Vérifier le nom de service et CoreDNS |
dial tcp: i/o timeout | Réseau bloqué | Vérifier NetworkPolicies et connectivité |
certificate signed by unknown authority | TLS mal configuré | Vérifier les secrets TLS et la CA |
kubectl top — Surveiller les ressources
Section intitulée « kubectl top — Surveiller les ressources »kubectl top affiche la consommation CPU et mémoire en temps réel des nodes et des pods.
Surveiller les nodes
Section intitulée « Surveiller les nodes »kubectl top nodesNAME CPU(cores) CPU% MEMORY(bytes) MEMORY%worker-1 350m 17% 2048Mi 52%worker-2 820m 41% 3200Mi 82%control 150m 7% 1024Mi 26%Surveillez les nodes avec un usage CPU > 80 % ou mémoire > 85 % — ils sont proches de la saturation et peuvent causer des évictions de pods.
Surveiller les pods
Section intitulée « Surveiller les pods »# Tous les pods du namespacekubectl top pods
# Un pod préciskubectl top pod mon-pod
# Tous les namespaces, triés par CPUkubectl top pods -A --sort-by=cpu
# Avec détail par conteneurkubectl top pod mon-pod --containersNAME CPU(cores) MEMORY(bytes)nginx-abc123 5m 32Miredis-def456 120m 256Miapi-server-xyz 450m 512MiDétecter une fuite mémoire
Section intitulée « Détecter une fuite mémoire »Pour repérer un conteneur dont la consommation mémoire croît sans cesse :
# Surveiller toutes les 10 secondeswatch -n 10 kubectl top pod mon-pod --containersSi la colonne MEMORY augmente régulièrement sans retomber, c’est probablement une fuite mémoire. Comparez avec la limite définie :
kubectl get pod mon-pod -o jsonpath='{.spec.containers[0].resources.limits.memory}'Quand la consommation atteint la limite, Kubernetes tue le conteneur avec le status OOMKilled.
Combiner les commandes — Workflow de diagnostic
Section intitulée « Combiner les commandes — Workflow de diagnostic »Voici l’enchaînement complet pour diagnostiquer un pod en erreur :
-
Repérer le pod en erreur
Fenêtre de terminal kubectl get pods -A | grep -v Running | grep -v CompletedCette commande affiche uniquement les pods dont l’état n’est pas normal.
-
Comprendre la cause
Fenêtre de terminal kubectl describe pod <nom-du-pod> -n <namespace>Scrollez directement jusqu’à la section Events. Cherchez les lignes
Warning. -
Lire les logs applicatifs
Fenêtre de terminal # Si le pod tourne encorekubectl logs <nom-du-pod> --tail=100# Si le pod a crashékubectl logs -p <nom-du-pod> -
Vérifier les ressources
Fenêtre de terminal kubectl top pod <nom-du-pod>kubectl top nodeComparez la consommation avec les limits définies dans le manifeste.
-
Investiguer plus en profondeur si nécessaire
Si le problème persiste, passez à l’investigation avancée avec kubectl exec et debug.
Runbooks de diagnostic
Section intitulée « Runbooks de diagnostic »Ces runbooks couvrent les 6 incidents les plus fréquents en production. Pour chaque incident : symptôme, diagnostic pas à pas, et résolution.
Runbook 1 — Pod bloqué en Pending
Section intitulée « Runbook 1 — Pod bloqué en Pending »Symptôme : kubectl get pods affiche Status = Pending depuis plus de 30 secondes.
Causes fréquentes : ressources insuffisantes sur les nodes, affinité/anti-affinité non satisfaite, PVC non lié.
-
Lire les événements du pod
Fenêtre de terminal kubectl describe pod <nom> -n <namespace> | grep -A20 "Events:"Cherchez
FailedSchedulingdans les événements. -
Identifier la cause dans le message
Message Events Cause Solution Insufficient cpuPas assez de CPU disponible Ajoutez un node ou réduisez les requests Insufficient memoryPas assez de mémoire disponible Ajoutez un node ou réduisez les requests node(s) had taintTaint sans toleration Ajoutez la toleration au pod ou retirez le taint node(s) didn't match Pod's node affinityAffinité non satisfaite Vérifiez nodeSelectorounodeAffinitypersistentvolumeclaim not foundPVC inexistant Créez le PVC ou corrigez le nom -
Vérifier la capacité des nodes
Fenêtre de terminal kubectl describe nodes | grep -A5 "Allocated resources"Comparez
RequestsetLimitsavec la capacité totale. -
Vérifier les PVC si applicable
Fenêtre de terminal kubectl get pvc -n <namespace>Un PVC en
Pendingsignifie qu’aucun PV ne correspond (taille, storageClass, mode d’accès). -
Résoudre
Fenêtre de terminal # Option A : libérer des ressourceskubectl top pods -A --sort-by=cpu | head -10# Option B : vérifier les taintskubectl get nodes -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints# Option C : forcer le scheduling (si drain actif)kubectl uncordon <node>
Runbook 2 — CrashLoopBackOff
Section intitulée « Runbook 2 — CrashLoopBackOff »Symptôme : kubectl get pods affiche Status = CrashLoopBackOff, le RESTARTS augmente.
Causes fréquentes : erreur applicative au démarrage, variable d’environnement manquante, point de montage incorrect, commande de démarrage invalide.
-
Voir les logs de l’exécution qui a crashé
Fenêtre de terminal kubectl logs -p <nom> -n <namespace>C’est la commande la plus importante. Elle montre les logs du conteneur avant qu’il ne soit tué.
-
Examiner la configuration du pod
Fenêtre de terminal kubectl describe pod <nom> -n <namespace>Vérifiez dans la sortie :
- Last State :
Terminatedavec leReason(Error, OOMKilled) - Exit Code :
1= erreur applicative,137= OOMKilled,139= segfault - Restart Count : combien de fois le conteneur a redémarré
- Last State :
-
Vérifier les variables d’environnement et volumes
Fenêtre de terminal # Variables d'environnement injectéeskubectl get pod <nom> -o jsonpath='{.spec.containers[0].env[*].name}'# ConfigMaps référencéskubectl get pod <nom> -o jsonpath='{.spec.containers[0].envFrom[*].configMapRef.name}'# Secrets référencéskubectl get pod <nom> -o jsonpath='{.spec.containers[0].envFrom[*].secretRef.name}'Si un ConfigMap ou Secret n’existe pas, le pod crashe au démarrage.
-
Tester l’image manuellement
Fenêtre de terminal kubectl run debug-test --image=<image> --rm -it -- shSi l’image ne démarre pas non plus en mode interactif, le problème est dans l’image elle-même.
-
Résoudre selon l’exit code
Exit Code Signification Action 0Succès (le process se termine normalement) Vérifiez que la commande est un process long, pas un script one-shot 1Erreur applicative Lisez les logs -p, corrigez le code ou la config126Permission denied Vérifiez les permissions de l’entrypoint 127Commande introuvable Vérifiez command:dans le manifeste137OOMKilled (SIGKILL) Augmentez limits.memory139Segfault (SIGSEGV) Bug dans l’application, problème d’architecture (arm64/amd64)
Runbook 3 — ImagePullBackOff / ErrImagePull
Section intitulée « Runbook 3 — ImagePullBackOff / ErrImagePull »Symptôme : kubectl get pods affiche Status = ImagePullBackOff ou ErrImagePull.
Causes fréquentes : image inexistante, tag incorrect, registre privé sans credentials, limite de rate Docker Hub.
-
Identifier l’image en cause
Fenêtre de terminal kubectl describe pod <nom> -n <namespace> | grep -i "image\|pull\|back" -
Vérifier que l’image existe
Fenêtre de terminal # Tester le pull depuis votre machinedocker pull <image:tag># Ou avec crane (sans Docker)crane manifest <image:tag> -
Vérifier les credentials du registre
Fenêtre de terminal # ImagePullSecrets configurés sur le pod ?kubectl get pod <nom> -o jsonpath='{.spec.imagePullSecrets[*].name}'# Le secret existe ?kubectl get secret <nom-secret> -n <namespace># Contenu du secret (base64)kubectl get secret <nom-secret> -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d -
Vérifier le ServiceAccount par défaut
Fenêtre de terminal kubectl get serviceaccount default -n <namespace> -o yaml | grep -A5 imagePullSecrets -
Résoudre
Fenêtre de terminal # Créer un secret pour un registre privékubectl create secret docker-registry regcred \--docker-server=registry.example.com \--docker-username=user \--docker-password=pass \-n <namespace># Attacher au ServiceAccount par défautkubectl patch serviceaccount default -n <namespace> \-p '{"imagePullSecrets": [{"name": "regcred"}]}'
Runbook 4 — Service inaccessible (pas de réponse)
Section intitulée « Runbook 4 — Service inaccessible (pas de réponse) »Symptôme : un curl ou une requête HTTP vers un Service Kubernetes ne répond pas ou retourne connection refused.
-
Vérifier que le Service a des endpoints
Fenêtre de terminal kubectl get endpoints <service> -n <namespace>Si la colonne
ENDPOINTSest vide (<none>), aucun pod ne correspond au sélecteur du Service. -
Comparer le sélecteur du Service avec les labels des pods
Fenêtre de terminal # Sélecteur du Servicekubectl get svc <service> -n <namespace> -o jsonpath='{.spec.selector}'# Pods avec ces labelskubectl get pods -n <namespace> -l <key>=<value>Si aucun pod ne matche, il y a une incohérence entre les labels.
-
Vérifier que les pods ciblés sont Ready
Fenêtre de terminal kubectl get pods -n <namespace> -l <key>=<value> -o wideUn pod qui n’est pas
Readyest retiré des endpoints du Service. -
Tester la connectivité depuis le cluster
Fenêtre de terminal kubectl run test-net --image=busybox --rm -it -- wget -qO- http://<service>.<namespace>.svc.cluster.local:<port> -
Vérifier les NetworkPolicies
Fenêtre de terminal kubectl get networkpolicies -n <namespace>Une NetworkPolicy peut bloquer le trafic entrant vers les pods.
-
Résoudre
- Labels incohérents → corriger les labels du Deployment ou le sélecteur du Service
- Pod pas Ready → vérifier les readinessProbes (
kubectl describe pod) - NetworkPolicy → ajuster les règles d’ingress
Pour plus de détails sur les Services et le port-forward : kubectl expose, port-forward et proxy.
Runbook 5 — OOMKilled (mémoire dépassée)
Section intitulée « Runbook 5 — OOMKilled (mémoire dépassée) »Symptôme : le pod redémarre avec Reason: OOMKilled (visible dans kubectl describe pod) ou Exit Code 137.
-
Confirmer l’OOMKilled
Fenêtre de terminal kubectl describe pod <nom> -n <namespace> | grep -A3 "Last State"Vous devez voir
Reason: OOMKilled. -
Mesurer la consommation réelle
Fenêtre de terminal kubectl top pod <nom> --containersComparez avec la limite définie :
Fenêtre de terminal kubectl get pod <nom> -o jsonpath='{range .spec.containers[*]}{.name}: {.resources.limits.memory}{"\n"}{end}' -
Analyser l’historique de consommation
Si vous avez Prometheus/Grafana, consultez la métrique
container_memory_working_set_bytes. Sinon, surveillez avecwatch:Fenêtre de terminal watch -n 5 kubectl top pod <nom> --containersUne croissance linéaire sans palier indique une fuite mémoire.
-
Résoudre
Situation Action Pic ponctuel au démarrage Augmentez limits.memoryde 20-30 %Croissance continue (fuite) Corrigez l’application (profiling mémoire) Limite trop basse par rapport au besoin réel Ajustez requests et limits Fenêtre de terminal # Modifier la limite mémoire (via le Deployment)kubectl set resources deployment <nom> \--limits=memory=512Mi \--requests=memory=256Mi
Runbook 6 — Pod Evicted
Section intitulée « Runbook 6 — Pod Evicted »Symptôme : kubectl get pods affiche Status = Evicted. Les pods évincés restent visibles mais ne tournent plus.
-
Identifier la raison de l’éviction
Fenêtre de terminal kubectl describe pod <nom-evicted> -n <namespace> | grep -i "message\|reason\|status"Les raisons courantes :
The node was low on resource: ephemeral-storageoumemory. -
Vérifier la pression sur le node
Fenêtre de terminal kubectl describe node <node> | grep -A5 "Conditions"Cherchez
MemoryPressure,DiskPressureouPIDPressureàTrue. -
Identifier les consommateurs principaux
Fenêtre de terminal # CPU et mémoire par pod sur ce nodekubectl top pods -A --field-selector spec.nodeName=<node> --sort-by=memory# Espace disque éphémère (si applicable)kubectl get pods -A --field-selector spec.nodeName=<node> \-o jsonpath='{range .items[*]}{.metadata.namespace}/{.metadata.name}{"\n"}{end}' -
Nettoyer les pods évincés
Les pods évincés ne servent plus à rien, supprimez-les :
Fenêtre de terminal kubectl get pods -A --field-selector status.phase=Failed | grep Evictedkubectl delete pods -A --field-selector status.phase=Failed -
Prévenir les futures évictions
- Ajoutez des
requestsetlimitssur tous les pods - Configurez des
PodDisruptionBudgetspour les workloads critiques - Surveillez l’espace disque avec kubectl top et des alertes Prometheus
- Envisagez le drain contrôlé pour la maintenance
- Ajoutez des
Tableau récapitulatif des erreurs
Section intitulée « Tableau récapitulatif des erreurs »| Status / Erreur | Commande de diagnostic | Cause la plus fréquente |
|---|---|---|
Pending | kubectl describe pod → Events | Ressources insuffisantes ou taint |
CrashLoopBackOff | kubectl logs -p | Erreur applicative au démarrage |
ImagePullBackOff | kubectl describe pod → Events | Image inexistante ou credentials manquants |
OOMKilled | kubectl describe pod → Last State | Limite mémoire trop basse |
Evicted | kubectl describe pod + describe node | Node en pression (disque/mémoire) |
CreateContainerError | kubectl describe pod → Events | ConfigMap/Secret manquant |
RunContainerError | kubectl describe pod → Events | Commande de démarrage invalide |
| Service sans réponse | kubectl get endpoints | Pas de pods matchant le sélecteur |
À retenir
Section intitulée « À retenir »kubectl getliste et filtre les ressources — commencez toujours par là pour repérer les anomalies.kubectl describeinspecte une ressource en détail — allez directement à la section Events.kubectl logsaffiche les journaux applicatifs — utilisez-ppour voir les logs d’un conteneur crashé.kubectl topmontre la consommation CPU/mémoire en temps réel — nécessite metrics-server.- Le pipeline get → describe → logs → top couvre 90 % des diagnostics Kubernetes.
- Les 6 runbooks en fin de guide traitent les incidents les plus courants avec des commandes copier-coller.