Kubernetes Events Explained: A Powerful Troubleshooting Tool
Learn what Kubernetes events are, how to read them with kubectl, common reasons and messages, their 1 hour limit, and how to export them for alerting.
Kubernetes Events Explained: A Powerful Troubleshooting Tool
bitcodematrix.com | Kubernetes Series
1. Introduction
When something goes wrong in Kubernetes, the first question is usually: what did the cluster just try to do to this object? The answer is often found in events. An event is a small record that a component creates when something happens to an object: a Pod is scheduled, an image is pulled, a probe fails, a volume cannot be mounted or a Deployment scales up. Events are the cluster's running commentary, and they are the fastest way to understand why a Pod is Pending, restarting or not ready.
This article explains what events are, what their fields mean, how to read and filter them, which components produce which events, how to use them to diagnose common problems, their limits (most importantly their short lifetime), how to keep them longer and alert on them, and how to troubleshoot missing events. It complements the articles on Pod Pending troubleshooting, logging and monitoring architecture.
After reading it you should be able to:
Explain what a Kubernetes event is and how it differs from a log line or a metric.
Read, sort and filter events with kubectl.
Recognize the most common event reasons and what to do about them.
Understand the limits of events and how to export them for history and alerts.
Use events as the first step in a repeatable troubleshooting routine.
2. What Events Are
Events are Kubernetes API objects. A control plane component or the kubelet creates an Event that refers to another object, such as a Pod or a Node, and describes something that happened to it. Events are stored by the API server like other objects, which is why kubectl can list them, and they are deleted automatically after a fixed time.
Figure 1: Events are created by cluster components and expire quickly
Events do not replace the other signals. They are best for explaining state changes and failures of Kubernetes operations, such as scheduling, image pulls and volume mounts, while application behavior belongs in logs and trends belong in metrics.
3. Anatomy of an Event
kubectl get events -n default -o yaml
apiVersion: v1
kind: Event
metadata:
name: web-6d8f9-abc.17a1b2c3d4e5f678
namespace: default
involvedObject:
kind: Pod
name: web-6d8f9-abc
namespace: default
type: Warning
reason: FailedScheduling
message: "0/3 nodes are available: 3 Insufficient cpu."
source:
component: default-scheduler
count: 4
firstTimestamp: "2026-10-13T05:30:01Z"
lastTimestamp: "2026-10-13T05:34:12Z"
Kubernetes also has a newer Event API in the events.k8s.io group, with field names such as regarding, note and series. The core v1 events are still widely used and both are served, so you normally interact with them in the same way through kubectl.
Events are namespaced and live in the namespace of the object they refer to. Events about cluster-scoped objects, such as Nodes, are normally created in the default namespace, which is why a node event can seem to be missing if you look in the wrong namespace.
4. Reading Events with kubectl
4.1 kubectl describe
The simplest way is kubectl describe, which prints the events for that object at the end of its output.
kubectl describe pod <pod-name>
kubectl describe node <node-name>
kubectl describe pvc <pvc-name>
kubectl describe deployment <name>
4.2 kubectl get events
# Events in the current namespace (order is not guaranteed)
kubectl get events
# Sorted by time, newest last
kubectl get events --sort-by=.lastTimestamp
# All namespaces
kubectl get events -A --sort-by=.lastTimestamp
# Only warnings
kubectl get events --field-selector type=Warning
# Events about one object
kubectl get events --field-selector involvedObject.name=<pod-name>
kubectl get events --field-selector involvedObject.kind=Node
# A specific reason
kubectl get events -A --field-selector reason=FailedScheduling
# Watch new events as they happen
kubectl get events -w
4.3 kubectl events
Recent kubectl versions include a dedicated kubectl events command that sorts events by time and can filter by object. Check that your kubectl version has it.
kubectl events
kubectl events --for pod/<pod-name>
kubectl events --types=Warning
kubectl events -A --watch
5. Common Events by Component
Reasons are not a fixed public contract, and new ones appear in new versions, but the common ones have been stable for years.
5.1 Scheduler
5.2 Kubelet: starting and running containers
5.3 Controllers and autoscalers
5.4 Nodes and storage
6. Troubleshooting with Events
Events are the first step in most Pod problems. The pattern is always the same: find the object that is wrong, read its events from the oldest to the newest, and follow the chain.
# A good first routine for a misbehaving workload
kubectl get pods -o wide
kubectl describe pod <pod>
kubectl get events --sort-by=.lastTimestamp | tail -20
kubectl logs <pod> --previous
7. Limitations of Events
Short lifetime. The API server deletes events after a time to live, one hour by default (the event-ttl setting, which managed services usually do not let you change). An incident from last night usually has no events left.
Aggregation. Repeated events are merged and counted. You see the first and last time, not every occurrence.
Rate limiting and best effort. Components limit how fast they emit events and may drop them under load, so events are not an audit trail.
Namespaced and scattered. You must look in the right namespace, and node events often sit in the default namespace.
Load on etcd. Events are objects in etcd, and a flood of events in a large or unstable cluster adds load. This is another reason for the short lifetime.
Free text. The message format is not stable and should not be parsed in scripts. Use the reason field.
Not logs. They explain Kubernetes actions, not what your application did.
8. Keeping Events Longer
To investigate incidents after the fact, copy events to a place that keeps them. Several approaches are common, and the tools evolve, so check which are maintained when you choose.
Note that kube-state-metrics and Prometheus do not store events. To alert on events you need an exporter or a logging pipeline that supports alerts on the stored records.
9. Alerting on Events
Events can drive useful alerts, provided you filter them carefully, because many Warning events are harmless and short-lived.
Alert on the reason and the namespace, not on the message text.
Use counts or time windows so that one transient event does not page anyone.
Prefer metrics-based alerts for steady conditions, and use events as extra context in the notification.
10. Hands-On Walkthrough
Watch events in one terminal.
kubectl get events -w
In another terminal, create a Pod with a wrong image tag.
kubectl run bad-image --image=nginx:does-not-exist
Observe the sequence in the first terminal: Scheduled, Pulling, Failed, then BackOff. Read the same sequence with describe.
kubectl describe pod bad-image | grep -A12 Events
Create a Pod that cannot be scheduled because of a huge request.
apiVersion: v1
kind: Pod
metadata:
name: too-big
spec:
containers:
- name: app
image: nginx:1.27
resources:
requests:
memory: 500Gi
kubectl apply -f too-big.yaml
kubectl get events --field-selector involvedObject.name=too-big
Create a Pod with a failing liveness probe and watch Unhealthy and Killing events.
apiVersion: v1
kind: Pod
metadata:
name: bad-probe
spec:
containers:
- name: app
image: nginx:1.27
livenessProbe:
httpGet:
path: /does-not-exist
port: 80
initialDelaySeconds: 3
periodSeconds: 5
failureThreshold: 2
kubectl apply -f bad-probe.yaml
kubectl get events --field-selector involvedObject.name=bad-probe -w
Filter only warnings across the namespace, then clean up.
kubectl get events --field-selector type=Warning --sort-by=.lastTimestamp
kubectl delete pod bad-image too-big bad-probe
After the Pods are deleted, their events remain until the time to live ends, then disappear. This shows why you should read events early.
11. When Events Are Missing
12. Best Practices
Make events the first step of every Pod investigation: describe the object, then read recent events sorted by time.
Check events soon after a problem starts, because they expire quickly.
Use field selectors on type and reason to cut noise.
Export events to your logging or monitoring backend so that history survives the time to live.
Alert on a small set of meaningful reasons, with time windows, and include the event message in the notification.
Do not parse message text in automation. Use reason and involvedObject.
Combine events with logs and metrics for the full picture.
Write your own operators and controllers so that they emit events for important actions, which helps their users troubleshoot.
13. Conclusion
Kubernetes events are a small but powerful feature: they record what the cluster tried to do to your objects and why it failed. A few commands, kubectl describe, kubectl get events with sorting and field selectors, and kubectl events, solve a large share of everyday problems, from unschedulable Pods to failing probes and volume errors. Their short lifetime and aggregation are the main limits, and an event exporter or logging integration closes that gap. Use events first, then move to logs and metrics, and most mysteries get shorter.