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

Analogie simple

Les Events fonctionnent comme le journal de bord d’un avion. Chaque manœuvre, chaque alerte, chaque anomalie moteur y est consignée avec un horodatage et un code. En cas de problème, c’est le premier document qu’on consulte pour retracer la séquence des faits.

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 aujourd’hui un affichage plus lisible et des filtres dédiés que kubectl get events. C’est la commande recommandée 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

Le format YAML révèle les champs reportingController, series (nombre de répétitions), regarding (référence complète à l’objet) et eventTime (horodatage précis au microseconde).

kubectl events vs kubectl get events

kubectl events est aujourd’hui la commande la plus pratique pour explorer les événements récents : elle sait filtrer par type (--types), par ressource (--for) et suivre les nouveaux événements (--watch). kubectl get events reste utile, mais beaucoup d’exemples historiques s’appuient sur des champs désormais dépréciés dans l’API events.k8s.io/v1.

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

Champs historiques dans kubectl get events

Beaucoup d’exemples en ligne utilisent --sort-by=.metadata.creationTimestamp ou des colonnes comme .lastTimestamp. Ces champs proviennent de l’ancien modèle core/v1 et sont dépréciés dans events.k8s.io/v1. Ils fonctionnent encore, mais préférez kubectl events pour l’usage quotidien — ses options de tri et de filtrage s’appuient 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 Events liée à la ressource, sans exposer tous les champs du modèle events.k8s.io/v1 (comme reportingController ou series). Pour le détail complet, utilisez kubectl events -o yaml.

describe montre les Events récents seulement

kubectl describe n’affiche que les Events encore présents dans le cluster. Si l’événement a dépassé sa durée de rétention (voir section suivante), il n’apparaîtra plus. Pour un historique persistant, centralisez les Events dans un système de logs.

Patterns d’événements courants

Événements Normal (opérations attendues)

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

Events et etcd

Comme les Events sont stockés dans l’API Kubernetes (et donc dans etcd) et supprimés rapidement, il vaut mieux les exporter vers un système de logs si vous voulez conserver l’historique des incidents. Sur un cluster très actif, les Events peuvent représenter une part significative des écritures etcd — c’est pourquoi le TTL par défaut est court.

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 4 commandes, les Events ont permis de remonter la chaîne causale : éviction du pod base de données → erreur de connexion dans l’API → crash en boucle.

Dépannage

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é

Prochaines étapes

Observer la santé du cluster Les 5 commandes essentielles pour vérifier l'état de votre cluster.

Méthode de diagnostic d'un incident Approche systématique en 4 niveaux pour localiser la cause d'un problème.

Diagnostiquer un CrashLoopBackOff Appliquez les Events au cas le plus fréquent : conteneur qui plante en boucle.

Préparer une maintenance de cluster Cordon, drain, PDB — surveillez les Events pendant vos interventions.

×

📖 Voir la documentation →