Before learning the tool, it helps to feel the problem that the tool removes.

When a summary is not enough

Kubernetes runs your programs inside small units called Pods. When everything is healthy, you rarely look at them closely. But one day you list your Pods and see one with a worrying status: it says Pending, or ImagePullBackOff, or CrashLoopBackOff. These words tell you that something is wrong, but not what, not why, and not what to do next.

Now the questions pile up. Was the Pod ever placed on a machine? If so, which one? Did it manage to download its container image? Did the program start and then crash, and with what exit code? Did a health check fail? Is a storage disk missing? Is it waiting for a resource that does not exist? A one-line summary cannot answer any of these.

Why guessing is expensive

Without a proper inspection, people guess. They restart Pods, delete objects, change settings at random and hope. Each guess costs time and may hide the original cause. The cluster, however, already knows exactly what went wrong. It records the decisions made by its parts, and it writes short messages, called events, whenever something notable happens. The only skill you need is knowing where to read them, and describe puts them in front of you.

It is a read-only command that prints a detailed, human-friendly report about a Kubernetes resource.

The plain definition

The kubectl tool is the command-line tool used to talk to a Kubernetes cluster. Its describe action asks the cluster for a chosen object, such as a Pod, a node, a Deployment or a Service, and prints a neatly organised report. The report contains the main settings of the object, its current status, the conditions it is in, and, very importantly, the recent events connected with it.

The word “describe” is exactly right. Where a listing gives you one line per object, describe gives you a page of description for one object, written for a human to read from top to bottom.

Why it exists

Kubernetes objects are stored as structured data, and this raw data is long, repetitive and hard to read. Important facts, such as which events happened, live in separate objects and would need several different commands to gather. Describe exists to save you that work by collecting the scattered pieces, arranging them logically, and printing them in a readable layout with labelled sections.

Where it is used

Engineers use describe every day, first when a new application fails to start, then when it slows down or restarts, and finally when they want to understand how an object is configured. Platform teams use it to check node health and available capacity. Support engineers ask users to paste its output when reporting problems, because it contains most of the context in one place.

Kubernetes offers several ways to look at things. Knowing which one to reach for saves a great deal of time.

Beginners often mix up the different viewing commands, because they all seem to “show information”. In fact, each one answers a different kind of question, and a good troubleshooter uses them in a sensible order.

A sensible order of use

To trust the output, it helps to know where the information comes from.

The main players

Describe does not have a private source of truth. It simply asks the cluster’s normal front door, the API Server, several questions and assembles the answers into one report. The cards below introduce the parts involved.

flowchart LR
  U["You run describe"] --> K["kubectl"]
  K -->|"request the object"| A["API Server"]
  K -->|"request related items and events"| A
  A --> E[("etcd database")]
  E --> A
  A --> K
  K --> R["Readable report on your screen"]
        

Step by step

sequenceDiagram
  participant You as Engineer
  participant K as kubectl
  participant API as API Server
  participant ET as etcd
  You->>K: Describe this Pod
  K->>API: Get the Pod object
  API->>ET: Read stored data
  ET-->>API: Pod data
  API-->>K: Pod object
  K->>API: Get events about this Pod
  API-->>K: List of events
  K->>API: Get related items such as owner
  API-->>K: Related data
  K-->>You: One organised report
        

Because describe only reads, it never changes anything. You can run it as often as you like, on production or on a test cluster, without any risk of altering the object. The only cost is a few small requests to the API Server.

A Pod report has many sections. Once you know what each one is for, the page stops looking like a wall of text.

The report for a Pod is the one you will read most often. It follows a consistent layout. Here are its main sections, described in the order they usually appear.

Now let us learn how to read each part with a detective’s eye.

Status: the big picture

The status shows the phase of the Pod. Pending means the Pod is accepted by the cluster but its containers are not yet running, often because it has no machine yet or is still downloading images. Running means at least one container is running. Succeeded means all containers finished successfully and will not restart, which is typical for one-off tasks. Failed means all containers ended and at least one ended with an error. Unknown means the cluster lost contact with the machine.

Containers: the heart of the matter

Each container has a state, and that state has a reason. Waiting means the container is not running yet, and the reason tells why, such as an image that cannot be downloaded. Running means it is up, with the time it started. Terminated means it stopped, and you see its exit code, the reason and the start and finish times.

Look for the section called Last State. When a container has crashed and been restarted, the current state may look healthy, but the last state preserves the reason for the previous crash. This is the clue many beginners miss.

The restart count is also crucial. A count that keeps rising tells you the program keeps dying, even if it looks fine at the moment you look.

Conditions: a quick checklist

Resources: requests and limits

Each container states how much processor power and memory it asks for, called requests, and the maximum it may use, called limits. Requests decide where the Pod can be placed. Limits decide when the cluster steps in: a container that exceeds its memory limit is stopped, and one that exceeds its processor limit is slowed down. Reading these values often explains both scheduling failures and sudden stops.

Environment and volumes

The report lists environment settings, including where each value comes from, such as a settings bundle or a secret bundle. For secrets, the report shows the name of the source but not the value itself. The volumes section shows what storage is attached, which helps when a Pod is stuck waiting for a disk.

Describe is not only for Pods. Almost every Kubernetes object has its own useful report.

Node reports deserve a special mention

A node report is like a health certificate for a machine. It has a conditions checklist, including whether the memory or disk is under pressure and whether the machine is ready. It shows capacity, which is the total of the machine, and allocatable, which is what remains for Pods after the system takes its own share. It also lists every Pod on the machine along with the total of their requests. When Pods refuse to schedule, this is the fastest place to see how full your machines are.

Deployment reports tell the update story

A Deployment report shows how many copies were wanted, how many exist, how many are updated and how many are available. It lists the old and new ReplicaSets side by side, which reveals whether a rolling update is in progress or stuck. Its conditions tell you whether the Deployment is available and whether its progress has stalled.

Service reports expose broken links

The single most useful line in a Service report is the one named Endpoints. It lists the addresses of Pods currently receiving traffic. If it says none, then no Pod matches the Service’s selector or none is ready. That one line explains countless “my application is unreachable” problems.

You can point the command at one object or at many. Choosing well saves time.

Namespaces matter

Most objects live inside a namespace, and the command looks in your current namespace unless told otherwise. A very frequent moment of confusion is describing something that seems to be missing, when in fact it exists in another namespace. If you see a “not found” message, check the namespace before doubting the object.

Controlling the events

By default the report includes events. A switch can turn them off if you want a shorter output, but for troubleshooting you almost always want them on. There is also a setting for how many items are fetched at a time when describing very large lists, which matters only on big clusters.

If you learn to read only one section of a report, make it this one.

What an event is

An event is a short message that a part of Kubernetes writes when something notable happens to an object. The scheduler writes one when it places a Pod. The kubelet writes one when it downloads an image, starts a container or fails a health check. Controllers write one when they create or delete Pods. Describe gathers the events connected to the object and prints them in time order.

The columns of the events table

Common reasons and what they mean

Events have a short memory

This is the most important limit of describe. Events are not kept forever. By default the cluster keeps them for about one hour and then removes them. If you look at a problem the next morning, the events that explained it may already be gone, leaving the section empty. This is why a report showing “no events” does not mean nothing happened.

Pending means the Pod exists on paper but has not started. The events will say why.

When a Pod is Pending, the first thing to check in the report is whether a machine name appears in the identity block. If it does not, the Pod has not been scheduled. The events then normally show a FailedScheduling message, and the message contains a helpful tally of how many machines were rejected and for which reasons.

flowchart TD
  P["Pod is Pending"] --> M{"Machine name shown in report?"}
  M -->|"No"| S["Read FailedScheduling event"]
  M -->|"Yes"| C["Read container states"]
  S --> R1["Insufficient resources"]
  S --> R2["Untolerated taints"]
  S --> R3["Label or affinity mismatch"]
  S --> R4["Unbound storage claim"]
  C --> R5["Waiting for image download"]
  C --> R6["Waiting for volume to attach"]
        

These are the most famous status words in Kubernetes, and describe explains each of them.

ImagePullBackOff and ErrImagePull

The machine could not download the container image. The events name the image and the reason. Typical causes are a misspelled image name, a version tag that does not exist, a private registry that requires credentials which are missing or wrong, or a registry that cannot be reached from the machine. The word BackOff simply means Kubernetes is waiting longer between each new attempt.

CrashLoopBackOff

The container starts, stops quickly, and Kubernetes keeps restarting it with growing delays. The report holds the answer in the container’s last state: the reason and the exit code. The logs of the previous run then explain what the program itself complained about.

Reading exit codes

OOMKilled: out of memory

When a container uses more memory than its limit, the machine’s kernel stops it. The report shows the reason OOMKilled and usually the exit code 137. The remedy is to raise the memory limit, fix a memory leak in the program, or reduce the work each copy does.

Some of the most confusing problems involve a Pod that is running but not doing its job.

Failing health checks

Kubernetes can test a container in two important ways. A readiness check decides whether the Pod may receive traffic. A liveness check decides whether the container is alive or should be restarted. When such a check fails, the events show an Unhealthy reason with a message describing the failure, such as a refused connection or a timeout. The container section shows the exact check configuration, including the path, the port, the delay before the first check and how many failures are tolerated.

Two typical patterns appear. If a readiness check fails, the Pod runs but is marked not ready, and the Service ignores it. If a liveness check fails repeatedly, the container is killed and restarted, which shows up as a rising restart count. A very common mistake is a check that starts too early, before the application has finished starting.

Volume problems

If a Pod refers to a settings bundle, a secret bundle or a storage claim that does not exist, the container cannot start, and the events show FailedMount with the missing item named. Fix the name, or create the missing object.

The Service with no endpoints

flowchart LR
  S["Service report shows selector"] --> Q{"Endpoints listed?"}
  Q -->|"None"| L["Compare selector with Pod labels"]
  L --> R["Check Pods are Ready"]
  Q -->|"Yes but no answer"| T["Compare target port with container port"]
  R --> D["Describe the Pods for failing checks"]
        

When something is broken and people are waiting, a fixed routine beats improvisation.

Describe only reads, but what it reads can still be sensitive.

What you need permission for

Kubernetes uses role-based access control to decide what each person may read. To describe an object, you need permission to read that object. To see events, you need permission to read events as well. Some reports also fetch related objects, such as the Pods on a node. If any of those permissions is missing, the report is either refused or shown without the missing parts, and an empty events section may simply mean you are not allowed to see them.

What the report can reveal

Sharing output safely

People often paste describe output into chat rooms, tickets and forums to ask for help. Before you do, read it through and remove anything confidential, such as tokens typed into environment values, internal host names or customer identifiers. Treat the report as an internal document.

Every tool has limits. Knowing them stops you from trusting the report too much.

These mistakes appear again and again in real teams. Learn to recognise them early.

A short checklist of good habits, in the order you are likely to need them.

See how ordinary teams use the report every day.

Every tool has strengths and limits. Knowing both keeps your expectations realistic.

Quick answers to the questions beginners ask most often.

It reads an object and related information from the cluster and prints a readable report with the object’s settings, status, conditions and recent events.

No. It is strictly read-only, so it is safe to run on any cluster, at any time.

Get gives a short list or the raw stored data, while describe gives a readable report that also includes related events and helpful context.

Events are kept for a short time, about an hour by default, so old ones may have expired. It can also mean you do not have permission to read events.

Read the events at the bottom first, especially the Warnings. Then check the conditions and the container states to confirm what they suggest.

It is probably crashing and being restarted. Check the restart count and the last state for the reason and exit code of the previous run.

The process was forcibly killed. It is most often caused by running out of memory, in which case the reason shows as OOMKilled.

Yes. You can use a name prefix, a label selector, a definition file or an all-namespaces switch. Keep the scope small so the output remains readable.

No. For secrets it shows key names and sizes, and for environment values that come from secrets it shows only the source, not the value.

No. Its layout is designed for people and may change. Use structured output formats when a script needs data.

Most often you are in the wrong namespace or connected to the wrong cluster, or the name is misspelled. Check those first.

No. It explains what the platform saw. For application errors you also need logs, and for real resource use and trends you need metrics tools.

You began this guide at a garage, where a good mechanic does a full inspection instead of glancing at the dashboard. The kubectl describe command is that inspection for Kubernetes. It asks the cluster for an object and its related information, arranges everything into a readable report, and adds the diary of recent events that so often names the cause of a problem. You learned how the report is put together, how to read a Pod report section by section, what the reports of nodes, Deployments and Services highlight, and how to solve the classic problems: Pods stuck in Pending, image failures, crash loops, memory kills, failing health checks and Services with no endpoints. You also learned its limits, since events expire and the report is only a snapshot, and how to use it safely and sensibly alongside logs and metrics.