Introduction

Pod events are one of the fastest ways to diagnose Kubernetes startup and scheduling issues. Instead of scanning all namespace events, you can filter by the specific pod name and object kind. With a few targeted commands, you can quickly identify image pull failures, probe errors, or scheduling constraints.

Basic Command to Filter Events by Pod Name

The most common command uses a field selector on involvedObject.name.

kubectl get events -n app-dev --field-selector involvedObject.name=my-pod-7d5d9f7d8b-2kq4x

This filters events to objects named that pod. Add involvedObject.kind=Pod to avoid matches from other object types with similar names.

kubectl get events -n app-dev \
  --field-selector involvedObject.kind=Pod,involvedObject.name=my-pod-7d5d9f7d8b-2kq4x

For clusters with heavy event volume, this is much faster than fetching all events and grepping locally.

Get Pod Name First

If you only know deployment or labels, resolve pod names first.

kubectl get pods -n app-dev -l app=my-app

Then choose the failing pod and run event query with that exact name.

For single-pod lookup in scripts:

POD=$(kubectl get pods -n app-dev -l app=my-app -o jsonpath='{.items[0].metadata.name}')
kubectl get events -n app-dev --field-selector involvedObject.kind=Pod,involvedObject.name="$POD"

This pattern is useful in CI diagnostics.

Sort Events by Time for Easier Reading

Default event ordering can be hard to follow. Sort by creation timestamp to reconstruct sequence.

kubectl get events -n app-dev \
  --field-selector involvedObject.kind=Pod,involvedObject.name=my-pod-7d5d9f7d8b-2kq4x \
  --sort-by=.metadata.creationTimestamp

Seeing chronological order helps identify whether failures are due to scheduling, image pull, then probe checks, or another chain.

Use kubectl describe pod as a Companion View

describe includes related event snippets and often surfaces the same root cause with less filtering.

kubectl describe pod my-pod-7d5d9f7d8b-2kq4x -n app-dev

Use describe for quick checks, and get events when you need scriptable output or broader event history.

Structured Output for Automation

For automated troubleshooting, request JSON and parse relevant fields.

kubectl get events -n app-dev \
  --field-selector involvedObject.kind=Pod,involvedObject.name=my-pod-7d5d9f7d8b-2kq4x \
  -o json

You can extract reasons and messages with jq.

kubectl get events -n app-dev \
  --field-selector involvedObject.kind=Pod,involvedObject.name=my-pod-7d5d9f7d8b-2kq4x \
  -o json | jq -r '.items[] | [.lastTimestamp, .type, .reason, .message] | @tsv'

This is helpful for alert pipelines and incident summaries.

Newer kubectl events Command

Some Kubernetes versions provide kubectl events, which presents event-focused output directly.

kubectl events -n app-dev --for pod/my-pod-7d5d9f7d8b-2kq4x

If available in your client version, this can be cleaner than get events field selectors. Keep get events knowledge anyway because many environments still rely on it.

Typical Pod Event Reasons and What They Mean

Common event reasons include:

• FailedScheduling: insufficient CPU, memory, node selector mismatch, or taint constraints.
• Failed: container runtime failures.
• ErrImagePull or ImagePullBackOff: image name, registry auth, or network issues.
• Unhealthy: readiness or liveness probe failures.
• BackOff: repeated restart failures.

Map event reason to next diagnostic command. For example, ImagePullBackOff should lead to checking image tag and pull secret in deployment spec.

Namespace and Retention Considerations

Events are namespace-scoped, so always pass -n for non-default namespaces. Missing namespace is a common reason for empty results.

Also remember events are ephemeral. Retention can be short depending on cluster settings, so recent failures may disappear from history. For long-term auditing, forward events to logging or observability systems.

Common Pitfalls

One pitfall is filtering only by pod name without involvedObject.kind. This can produce noisy results in edge cases.

Another issue is querying the wrong namespace and assuming no events exist. Always verify namespace and pod name spelling first.

Users also rely only on one command. In practice, combine get events, describe pod, and container logs for complete diagnosis.

Finally, do not assume old events reflect current pod state. Restarted replicas with new names generate new event streams.

Summary

• Use field selectors to retrieve events for one pod quickly.
• Include involvedObject.kind=Pod and correct namespace for precise filtering.
• Sort events by timestamp to reconstruct failure sequence.
• Use JSON output for scripting and incident automation.
• Combine pod events with describe and logs for full troubleshooting coverage.