Analyser les événements Kubernetes avec kubectl events

Les Events sont le journal d'alerte immédiat de votre cluster Kubernetes, pas son historique complet. Chaque création de pod, erreur de scheduling, échec de probe ou éviction génère un événement. Ce guide vous montre comment lire, filtrer et exploiter ces événements avec kubectl events et kubectl get events pour détecter les anomalies avant qu'elles ne deviennent des incidents. Vous apprendrez à reconnaître les patterns d'événements courants et à utiliser les bons filtres pour trouver rapidement l'information pertinente.

Ce que vous allez apprendre

• Comprendre ce qu'est un Event Kubernetes et ses champs essentiels
• Utiliser kubectl events pour filtrer par type, ressource et namespace
• Reconnaître les patterns d'événements courants (Normal et Warning)
• Exploiter les Events dans kubectl describe pour le diagnostic
• Comprendre la rétention des événements et ses implications

Prérequis

• Un cluster Kubernetes fonctionnel (v1.28+)
• kubectl configuré et connecté au cluster
• Des droits de lecture sur les événements du cluster
• Avoir suivi le guide Observer la santé du cluster

Qu'est-ce qu'un Event Kubernetes ?

Un Event est un objet API qui décrit quelque chose qui s'est passé dans le cluster. Les composants Kubernetes (kubelet, scheduler, controller-manager) créent des Events pour signaler les opérations normales et les anomalies.

Chaque Event contient :

Champ	Ce qu'il indique
type	Normal (opération attendue) ou Warning (anomalie détectée)
reason	Code court identifiant l'événement (Scheduled, BackOff, FailedMount...)
message	Description lisible de ce qui s'est passé
regarding	La ressource concernée (pod, nœud, deployment...)
reportingController	Le composant qui a créé l'événement (kubelet, scheduler...)
eventTime	Horodatage principal de l'événement
series.count	Nombre de répétitions si l'événement est agrégé
series.lastObservedTime	Dernière occurrence observée de cette série

Glissez pour voir

Normal vs Warning

Kubernetes ne définit que deux types d'événements :

• Normal : opérations attendues, un pod a été planifié, une image a été téléchargée, un conteneur a démarré. Ces événements confirment que le cluster fonctionne.
• Warning : anomalies détectées, un scheduling a échoué, un volume ne peut pas être monté, une probe a échoué. Ces événements signalent un problème à investiguer.

En exploitation, ce sont les Warning qui méritent votre attention. Les Normal vous aident à reconstituer la chronologie quand vous diagnostiquez un incident.

Lire les événements avec kubectl events

La sous-commande kubectl events offre un affichage plus lisible et des filtres dédiés, que kubectl get events n'a pas. C'est la commande à prendre pour explorer les événements.

Voir tous les événements Warning du cluster

kubectl events -A --types=Warning

L'option -A (ou --all-namespaces) couvre tout le cluster. --types=Warning filtre uniquement les anomalies.

Filtrer par ressource

L'option --for permet de cibler une ressource précise :

# Événements d'un pod
kubectl events -n default --for=pod/mon-pod

# Événements d'un nœud
kubectl events --for=node/ks-worker1

# Événements d'un deployment
kubectl events -n default --for=deployment/mon-deployment

Suivre les événements en temps réel

Le flag --watch affiche les nouveaux événements au fur et à mesure :

kubectl events -A --types=Warning --watch

Très utile pendant une maintenance ou un déploiement pour voir les anomalies apparaître en direct.

Sortie YAML pour le détail complet

Pour voir tous les champs d'un événement :

kubectl events -A -o yaml | head -60

Une surprise vous attend ici, et elle explique bien des recherches infructueuses : un même événement existe sous deux représentations, avec des noms de champs différents. La commande ci-dessus rend la forme historique, apiVersion: v1 :

apiVersion: v1
involvedObject:   count:         firstTimestamp:
source:           message:       lastTimestamp:

La forme moderne, events.k8s.io/v1, se demande explicitement et renomme tout :

kubectl get events.events.k8s.io -A -o yaml | head -60

apiVersion: events.k8s.io/v1
regarding:            note:                    eventTime:
reportingController:  deprecatedCount:         deprecatedLastTimestamp:

La correspondance est directe : involvedObject devient regarding, message devient note, source devient reportingController. Les anciens noms survivent dans la nouvelle API, préfixés de deprecated, ce qui est la façon la plus claire de savoir lesquels sont hérités. Un champ series apparaît en plus, mais seulement sur un événement qui se répète : sur un cluster calme, ne le cherchez pas.

Retenez surtout la conséquence pratique : un jsonpath écrit pour une forme ne fonctionne pas sur l'autre. involvedObject.name ne donne rien en events.k8s.io/v1, où il faut écrire regarding.name.

Lire les événements avec kubectl get events

La commande classique kubectl get events reste utile pour les filtrages par champ via --field-selector :

# Événements Warning uniquement
kubectl get events -A --field-selector type=Warning

# Événements d'un objet précis
kubectl get events -n default --field-selector involvedObject.name=mon-pod

# Combiner les filtres
kubectl get events -A --field-selector type=Warning,reason=FailedScheduling

Beaucoup d'exemples en ligne trient avec --sort-by=.lastTimestamp ou --sort-by=.metadata.creationTimestamp. Ces champs appartiennent au modèle historique, celui que events.k8s.io/v1 range sous le préfixe deprecated. Ils fonctionnent toujours, et il n'y a aucune urgence à les remplacer dans un script qui tourne ; mais kubectl events vous évitera d'avoir à choisir, ses filtres s'appuyant sur le modèle moderne.

Les événements dans kubectl describe

La commande kubectl describe affiche les événements liés à une ressource dans sa section Events en bas de la sortie. C'est souvent la première chose à lire quand on diagnostique un pod :

kubectl describe pod mon-pod -n default

La section Events en bas ressemble à :

Events:
  Type     Reason     Age   From               Message
  ----     ------     ----  ----               -------
  Normal   Scheduled  2m    default-scheduler  Successfully assigned default/mon-pod to ks-worker1
  Normal   Pulling    2m    kubelet            Pulling image "nginx:1.27"
  Normal   Pulled     118s  kubelet            Successfully pulled image "nginx:1.27"
  Normal   Created    118s  kubelet            Created container nginx
  Normal   Started    118s  kubelet            Started container nginx

Cette séquence montre le cycle de vie normal d'un pod : planification → téléchargement de l'image → création du conteneur → démarrage.

kubectl describe node affiche de la même façon les événements liés à un nœud (évictions, problèmes kubelet, pression sur les ressources).

kubectl describe présente une vue condensée des événements liés à la ressource, sans exposer tous les champs du modèle events.k8s.io/v1, comme reportingController ou series. Pour le détail complet, passez par kubectl events -o yaml.

describe montre les Events récents seulement

kubectl describe n'affiche que les événements encore présents dans le cluster. Passé leur durée de rétention, ils disparaissent purement et simplement. Pour un historique durable, il faut les centraliser dans un système de journalisation.

Patterns d'événements courants

Quelques dizaines de reason couvrent la quasi-totalité de ce que vous lirez au quotidien. Les connaître de vue fait gagner du temps pour une raison simple : vous cessez de lire les lignes normales, et votre œil s'arrête sur celles qui ne le sont pas.

Événements Normal (opérations attendues)

Ces événements racontent le cycle de vie nominal d'un pod, du placement au démarrage. Les voir dans cet ordre est le signe que tout va bien ; c'est l'endroit où la séquence s'arrête qui désigne l'étape en échec.

Reason	Source	Ce que cela signifie
Scheduled	scheduler	Le pod a été affecté à un nœud
Pulling	kubelet	Le téléchargement de l'image a commencé
Pulled	kubelet	L'image a été téléchargée (ou était déjà en cache)
Created	kubelet	Le conteneur a été créé
Started	kubelet	Le conteneur a démarré
ScalingReplicaSet	deployment-controller	Un Deployment a ajusté le nombre de réplicas
SuccessfulCreate	replicaset-controller	Un ReplicaSet a créé un pod
Killing	kubelet	Le conteneur est en cours d'arrêt (rolling update, suppression)

Glissez pour voir

Événements Warning (anomalies à investiguer)

Reason	Source	Ce que cela signifie	Action
FailedScheduling	scheduler	Aucun nœud ne peut accueillir le pod	Vérifier requests, taints, affinité, capacité des nœuds
BackOff	kubelet	Le conteneur a crashé et Kubernetes attend avant de le relancer	Vérifier les logs : kubectl logs --previous
FailedMount	kubelet	Un volume n'a pu être monté	Vérifier le PVC, le StorageClass, les droits
FailedAttachVolume	attachdetach-controller	Le volume n'a pu être attaché au nœud	Vérifier le provider de stockage et l'état du volume
Unhealthy	kubelet	Une liveness ou readiness probe a échoué	Vérifier la config des probes et l'état de l'application
Evicted	kubelet	Le pod a été évincé (pression mémoire/disque du nœud)	Vérifier les conditions du nœud, ajuster les ressources
NodeNotReady	node-controller	Un nœud a perdu le contact avec le plan de contrôle	Vérifier le kubelet et le réseau du nœud
FailedCreate	replicaset-controller	Le ReplicaSet n'a pas pu créer un pod	Vérifier les quotas, RBAC, ou les erreurs d'admission

Glissez pour voir

Un Warning isolé ≠ un incident

Un seul événement Warning (par exemple un Unhealthy ponctuel) n'est pas forcément un problème. C'est la répétition qui compte. Si le champ count augmente ou que l'événement réapparaît toutes les minutes, il faut investiguer. Un Unhealthy suivi d'un retour à Ready est normal, c'est le comportement attendu des probes.

Rétention des événements

Par défaut, l'API server conserve les Events pendant 1 heure via le paramètre --event-ttl=1h0m0s. Au-delà, ils sont supprimés automatiquement. Les Events sont donc utiles pour le diagnostic immédiat, mais pas comme système d'historisation.

Ce que cela implique :

• Les Events ne sont pas un système de monitoring : ils disparaissent. Pour conserver un historique, exportez-les vers un système de logs (Elasticsearch, Loki, etc.)
• Si un incident a eu lieu il y a plus d'une heure, les Events ont probablement disparu. Il faudra s'appuyer sur les logs des composants ou sur un outil de centralisation
• Sur un cluster très actif, le volume d'Events peut être important. Le TTL de 1 heure limite la charge sur etcd

La raison de ce TTL court tient au stockage : les Events vivent dans l'API Kubernetes, donc dans etcd, au même titre que vos Deployments. Sur un cluster très actif, ils peuvent représenter une part significative des écritures d'etcd, ce qui explique qu'on ne les garde pas. Si l'historique des incidents vous importe, ce n'est donc pas le TTL qu'il faut rallonger, c'est un export vers un système de logs qu'il faut mettre en place.

Exemple pratique : diagnostiquer avec les Events

Voici un scénario typique. Un collègue signale qu'une application ne répond plus. Vous commencez par les Events :

1. Vérifier les Warning récents du namespace :

   kubectl events -n mon-app --types=Warning

   Résultat : plusieurs événements BackOff sur le pod api-server-xyz.

2. Cibler les événements du pod :

   kubectl events -n mon-app --for=pod/api-server-xyz

   La séquence montre : Started → BackOff → Started → BackOff en boucle. Le conteneur crash en boucle.

3. Compléter avec les logs :

   kubectl logs api-server-xyz -n mon-app --previous --tail=30

   Les logs révèlent une erreur de connexion à la base de données.

4. Vérifier les Events du Service de base de données :

   kubectl events -n mon-app --for=pod/postgres-0

   Un événement Evicted apparaît : le pod PostgreSQL a été évincé pour pression mémoire sur le nœud.

En quatre commandes, les événements ont permis de remonter la chaîne causale : éviction du Pod de base de données, puis erreur de connexion dans l'API, puis redémarrage en boucle.

Dépannage

Les trois situations ci-dessous ne portent pas sur ce que disent les événements, mais sur le fait de ne pas en trouver. C'est un cas déroutant, parce que l'absence de message ressemble à une absence de problème alors qu'elle signifie le plus souvent que vous regardez au mauvais endroit, ou trop tard.

Symptôme	Cause probable	Solution
kubectl events retourne error: unknown command	Version kubectl < 1.26	Mettre à jour kubectl, ou utiliser kubectl get events
Aucun événement affiché	Événements expirés (TTL dépassé)	Relancer l'observation, les Events ne persistent que ~1h
Trop d'événements, difficile de trouver l'info	Cluster actif sans filtrage	Utiliser --types=Warning, --for=<ressource> ou --field-selector
Events visibles dans describe mais pas dans kubectl events	Différence de namespace ou de temporalité	Vérifier le namespace avec -n, les deux commandes lisent les mêmes objets
Warning FailedScheduling en boucle sans résolution	Ressources insuffisantes sur tous les nœuds	kubectl describe pod pour voir les détails, ajouter un nœud ou ajuster les requests
Events répétés avec count croissant	Problème persistant non résolu	Traiter la cause racine (le count ne fait qu'indiquer la répétition)

Glissez pour voir

À retenir

• Les Events sont le premier réflexe de diagnostic : avant de lire les logs, vérifiez les Events pour comprendre ce que Kubernetes a fait (ou tenté de faire). Ce sont des signaux immédiats, pas un historique complet
• kubectl events -A --types=Warning est la commande la plus utile au quotidien, elle affiche toutes les anomalies du cluster en un coup d'œil
• Normal = opération attendue, Warning = anomalie, seuls deux types existent, la classification est simple
• La répétition compte plus que l'occurrence : un Warning isolé est souvent bénin, un Warning qui se répète signale un problème réel
• Les Events disparaissent après ~1 heure : ils ne remplacent pas un système de monitoring. Pour un historique, centralisez-les dans un outil de logs
• kubectl describe affiche les Events d'une ressource en bas de sa sortie, c'est le raccourci le plus rapide pour un diagnostic ciblé

Contrôle de connaissances

Sept questions sur ce qui trompe le plus : les deux jeux de noms de champs d'un même événement, la lecture d'un compteur de répétitions, et ce qu'une section Events vide veut vraiment dire.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

7 questions

5 min.

80% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

Pour aller plus loin

• Diagnostiquer un CrashLoopBackOff : L'exploitation des Events sur le cas le plus courant en production.
• Diagnostiquer un Pod Pending : La lecture des Events FailedScheduling jusqu'à la cause réelle.
• Préparer une maintenance de cluster : La surveillance des Events pendant un cordon et un drain.

×

📖 Voir la documentation →