Skip to content
Français
Account: not signed in, sync available My learning
Select theme
Français

Read the cluster state: kubectl get, describe, logs and top

By updated

Improve this page

Logo Kubernetes

Four commands are enough to understand what is going on in a cluster: kubectl get says what is wrong, kubectl describe says why, kubectl logs shows what the application wrote, and kubectl top measures what it consumes. In the first deployment, you already used get, describe and logs on a working application. This lesson takes these commands again on failing Pods, created on purpose in your kind cluster: a badly named image and a program that exits with an error. You will learn to filter what you list, to interpret a describe output, to find the useful logs and to measure the consumption of your Pods. It is the last lesson of the module before the knowledge check.

What you will learn

  • Spot a failing Pod with kubectl get, and filter by namespace or by label
  • Choose the right output format: table, -o wide, -o yaml, -o jsonpath
  • Read the container states and the events in kubectl describe
  • Extract the useful logs with kubectl logs, including after a restart
  • Measure CPU and memory consumption with kubectl top

Prerequisites

You need the kind cluster from the lesson Create your first cluster, running, and the notions of Deployment, Pod and label seen in the first deployment. You also know how to change the default namespace of a context, a gesture from the lesson Kubeconfig and contexts. All the outputs on this page come from kubectl 1.37, on a two-node test kind cluster, kubectl-rattach-control-plane and kubectl-rattach-worker. Your monapp cluster probably has only one node, monapp-control-plane: wherever the page shows one of these names, you will see yours. The IP addresses and the random suffixes of the Pods will differ too, and kubectl top nodes will show only one line.

Prepare a namespace with two failures

You are going to learn to read a diagnosis on a real failure, not on a table of statuses. Create a dedicated namespace, make it the default namespace, then launch three Deployments: web works, api has a typo in its image tag, and batch runs a program that exits with an error as soon as it starts.

Terminal window
kubectl create namespace diagnostic
kubectl config set-context --current --namespace=diagnostic
kubectl create deployment web --replicas=2 \
--image=nginx:1.30@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb
# ❌ deliberate typo: the tag 1.280 does not exist
kubectl create deployment api --image=nginx:1.280
kubectl create deployment batch \
--image=busybox:1.37@sha256:bdf57e528e45e4433820e045b29b4597825a1c9e38353532d90a01445013f82e \
-- sh -c 'echo "batch: démarrage"; echo "erreur: variable DB_HOST absente" >&2; exit 1'

The api Deployment is a counter-example: its image is deliberately neither pinned nor valid. batch simulates an application that refuses to start for lack of configuration, a common case: it writes an error message, then stops with exit code 1. Wait a minute before continuing, so the images have time to download.

kubectl get: what is wrong?

kubectl get lists resources and their state, one line each: it is the first command to run. It does not say why a resource is unhealthy, but it says which one, and it decides the next command. Without a namespace argument, it looks at the default namespace of the context, here diagnostic.

Terminal window
kubectl get pods
Output
NAME READY STATUS RESTARTS AGE
api-5694859b95-pbxqt 0/1 ErrImagePull 0 50s
batch-5f74bc5db8-rbg2z 0/1 Error 2 (27s ago) 50s
web-75b69c7f78-27d55 1/1 Running 0 50s
web-75b69c7f78-9smrs 1/1 Running 0 50s

Three columns carry the diagnosis. READY counts the ready containers out of the containers of the Pod: 0/1 signals a problem. STATUS summarizes the state: ErrImagePull for api, Error for batch. RESTARTS counts the restarts of the container and says how long ago the last one was: a rising counter signals a program that starts then stops in a loop. Depending on when you look, you will also see ImagePullBackOff and CrashLoopBackOff: Kubernetes retries with growing delays, and the displayed status alternates.

Choose where to look: -n and -A

kubectl get looks at one namespace at a time, unless you ask it for all namespaces. The -n <name> option targets another namespace for this command, and -A (--all-namespaces) goes through all of them, adding a NAMESPACE column. Many "my Pod disappeared" cases come from a default namespace that is not the one you think.

Terminal window
kubectl get pods -n kube-system # another namespace
kubectl get pods -A # all namespaces
kubectl get deployments,pods # several types at once

The resource type can be written in the singular, in the plural or abbreviated: pod, pods and po designate the same thing, as do deployment and deploy, or service and svc. The kubectl api-resources command gives the full list of abbreviations.

Filter by label with -l

The -l option (--selector) keeps only the resources whose labels match an expression. It is the same selector mechanism a Service uses to find its Pods, seen in the first deployment. kubectl create deployment put on each Pod an app label that carries the name of the Deployment, and that is the one you use to filter.

Terminal window
kubectl get pods -l app=web
Output
NAME READY STATUS RESTARTS AGE
web-75b69c7f78-27d55 1/1 Running 0 50s
web-75b69c7f78-9smrs 1/1 Running 0 50s

Four forms of expression cover the essentials. Put single quotes around those that contain ! or parentheses, otherwise the shell interprets them before kubectl does.

ExpressionWhat it keeps
-l app=webthe resources whose app label equals web
-l 'app!=web'those whose app is something else, or that lack this label
-l 'app in (web, api)'those whose app is web or api
-l appthose that carry the app label, whatever its value

Several conditions separated by a comma combine as AND: -l app=web,env=prod keeps only the resources that carry both labels. To see the labels before filtering, add --show-labels to kubectl get.

Choose the output format with -o

The -o option changes what kubectl get displays, without changing what it queries. The default table is made for the eye; the other formats are for seeing more, seeing everything, or extracting a value for a script.

FormatWhat it displaysWhen to use it
-o widethe table, plus the Pod IP and its nodeknow where a Pod runs
-o yamlthe full object, as the API stores itread a field absent from the table
-o nametype/name, one line per resourcepass a list to another command
-o jsonpath='{...}'only the requested valuefeed a script variable
Terminal window
kubectl get pods -o wide
Output (NOMINATED NODE and READINESS GATES columns removed)
NAME READY STATUS RESTARTS AGE IP NODE
api-5694859b95-pbxqt 0/1 ErrImagePull 0 50s 10.244.1.39 kubectl-rattach-worker
batch-5f74bc5db8-rbg2z 0/1 Error 2 (27s ago) 50s 10.244.1.40 kubectl-rattach-worker
web-75b69c7f78-27d55 1/1 Running 0 50s 10.244.1.37 kubectl-rattach-worker
web-75b69c7f78-9smrs 1/1 Running 0 50s 10.244.1.38 kubectl-rattach-worker

The -o yaml format returns the whole object: its specification (spec, what you asked for) and its state (status, what Kubernetes observes). It is the longest output, and the most complete. -o jsonpath does the opposite and extracts only one field, designated by its path in the object:

Terminal window
kubectl get pod web-75b69c7f78-27d55 -o jsonpath='{.status.podIP}'; echo
Output
10.244.1.37

The jsonpath output has no final line break, hence the ; echo that keeps the shell prompt from sticking to the value. The path .status.podIP is read in the -o yaml output of the same Pod: it tells you which fields exist.

Follow changes with -w

The -w option (--watch) keeps the command open and adds a line at every state change. It does not refresh the table: it stacks the transitions, which leaves you the history on screen. Stop it with Ctrl+C.

Terminal window
kubectl get pods -w

It lets you see a Pod go from ContainerCreating to Running, or from Error to CrashLoopBackOff, during a deployment or right after a fix.

kubectl describe: why is it wrong?

kubectl describe gathers everything Kubernetes knows about a resource, and ends with its recent events. Where get summarizes the state in one word, describe gives the state of each container, its restarts, the conditions of the Pod and the events that explain the status. It is the command that answers "why".

Terminal window
kubectl describe pod api-5694859b95-pbxqt
Output (excerpt)
Name: api-5694859b95-pbxqt
Namespace: diagnostic
Node: kubectl-rattach-worker/172.26.0.2
Status: Pending
Controlled By: ReplicaSet/api-5694859b95
Containers:
nginx:
Image: nginx:1.280
State: Waiting
Reason: ErrImagePull
Ready: False
Restart Count: 0
Conditions:
Type Status
PodReadyToStartContainers True
Initialized True
Ready False
ContainersReady False
PodScheduled True
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Scheduled 76s default-scheduler Successfully assigned diagnostic/api-5694859b95-pbxqt to kubectl-rattach-worker
Normal Pulling 14s (x3 over 76s) kubelet spec.containers{nginx}: Pulling image "nginx:1.280"
Warning Failed 9s (x3 over 56s) kubelet spec.containers{nginx}: Failed to pull image "nginx:1.280": rpc error: code = NotFound desc = failed to pull and unpack image "docker.io/library/nginx:1.280": failed to resolve reference "docker.io/library/nginx:1.280": docker.io/library/nginx:1.280: not found
Warning Failed 9s (x3 over 56s) kubelet spec.containers{nginx}: Error: ErrImagePull

Read the output of describe pod

A describe pod output is read in a precise order: the container state, then the events. The top of the output says where the Pod runs (Node) and who manages it (Controlled By, the ReplicaSet of the Deployment). The Containers block gives, for each container, its image and its State: Waiting with a reason, Running, or Terminated with an exit code. Here, Waiting and ErrImagePull say that the container never started.

The line Status: Pending is the phase of the Pod, not to be confused with the STATUS column of kubectl get. A Pod stays in the Pending phase as long as at least one of its containers has not started, even if it is already placed on a node: waiting for a node and downloading the image are part of it. The STATUS column displays the most precise reason available, here ErrImagePull.

The Events section, at the very bottom, tells what Kubernetes tried, from oldest to most recent. The Warning lines carry the explanation: nginx:1.280: not found points at the typo without ambiguity. The mention (x3 over 56s) means the same event repeated three times in 56 seconds. The Conditions block confirms the table: the Pod is indeed scheduled (PodScheduled), but not ready (Ready at False).

The batch Pod tells another story. Its container started, then stopped:

kubectl describe pod batch-5f74bc5db8-rbg2z (excerpt)
State: Terminated
Reason: Error
Exit Code: 1
Last State: Terminated
Reason: Error
Exit Code: 1
Ready: False
Restart Count: 2
Events:
Warning BackOff 29s (x3 over 42s) kubelet spec.containers{busybox}: Back-off restarting failed container busybox in pod batch-5f74bc5db8-rbg2z_diagnostic(9a4bdd0d-0554-481b-b114-f22444dab8de)

Exit Code: 1 is the exit code of the program: any code other than 0 signals a failure, and the reason is found in the application's logs. Last State describes the previous run, and BackOff says Kubernetes is waiting before relaunching. Kubernetes did its job: the problem is in the application.

Events across a whole namespace

kubectl get events lists the events of the whole namespace, where describe shows only those of one resource. The first deployment showed you sorting by date. The --field-selector type=Warning filter is very useful in diagnosis, since it keeps only the warnings:

Terminal window
kubectl get events --field-selector type=Warning
Output
LAST SEEN TYPE REASON OBJECT MESSAGE
24s Warning Failed pod/api-5694859b95-pbxqt Failed to pull image "nginx:1.280": rpc error: code = NotFound desc = failed to pull and unpack image "docker.io/library/nginx:1.280": failed to resolve reference "docker.io/library/nginx:1.280": docker.io/library/nginx:1.280: not found
24s Warning Failed pod/api-5694859b95-pbxqt Error: ErrImagePull
10s Warning Failed pod/api-5694859b95-pbxqt Error: ImagePullBackOff
20s Warning BackOff pod/batch-5f74bc5db8-rbg2z Back-off restarting failed container busybox in pod batch-5f74bc5db8-rbg2z_diagnostic(9a4bdd0d-0554-481b-b114-f22444dab8de)

In one command, the two failures of the namespace appear with their cause. Events expire after one hour by default: for an older incident, they will say nothing. The lesson Analyze Kubernetes events (in French) in the Operate module goes deeper into reading them.

describe on other resources

describe works on every resource type, and each type highlights what concerns it. You used it on a Service and a Deployment in the first deployment. The table says what to look for first.

ResourceWhat describe reveals first
podstate of each container, restarts, events
deploymentnumber of desired and available replicas, current ReplicaSet
serviceselector and Endpoints, hence the Pods actually reached
nodecapacity, resources already reserved (Allocated resources), health conditions

kubectl logs: what did the application say?

kubectl logs displays what the container wrote on its standard output and its error output. Anything the program writes elsewhere, in a file inside the container for example, does not appear: it is the first thing to check when the command returns nothing. The logs of batch give the cause that describe could not know:

Terminal window
kubectl logs batch-5f74bc5db8-rbg2z
Output
erreur: variable DB_HOST absente
batch: démarrage

The two lines come from two distinct streams, the standard output and the error output: kubectl logs merges them without guaranteeing their writing order, and you may see them in the other order.

The logs of api, for their part, do not exist: a container that never started wrote nothing. kubectl says so plainly and sends you to describe, the only command able to explain a missing image:

Terminal window
kubectl logs api-5694859b95-pbxqt
Output
Error from server (BadRequest): container "nginx" in pod "api-5694859b95-pbxqt" is waiting to start: image can't be pulled

Logs of the previous run

The --previous option (-p) reads the logs of the previous run of the container, the one that crashed. You came across it in the first deployment. Two error answers are often met, and they say different things.

On a container that never restarted
Error from server (BadRequest): previous terminated container "nginx" in pod "web-75b69c7f78-27d55" not found
On batch, when the previous run is no longer kept
unable to retrieve container logs for containerd://a53b532730ae6ce819221cf4b209091f6845c257efd625fdf47b75a7cf919f1b

The first says there was no restart: the problem is not a crash. The second says the traces of that run are no longer available. Then run again without --previous: when the container is stopped between two attempts, like batch in Error or in CrashLoopBackOff, kubectl logs shows precisely the last run, the one that just failed.

Options that bound the output

Without options, kubectl logs pours out all the available log of a single container. On a chatty application, that means thousands of lines: the options below bound the output, and they combine.

OptionEffectExample
--tail=Nthe last N lineskubectl logs web-75b69c7f78-27d55 --tail=20
-ffollow the log continuously, until Ctrl+Ckubectl logs -f web-75b69c7f78-27d55
--since=10monly the lines from the last 10 minuteskubectl logs web-75b69c7f78-27d55 --since=10m
--timestampsprefix each line with its timestampkubectl logs web-75b69c7f78-27d55 --timestamps
-l app=webthe logs of all the Pods that carry this labelkubectl logs -l app=web --prefix
--prefixprefix each line with the originating Pod and containersame
-c <name>a specific container, when the Pod contains severalkubectl logs my-pod -c journal
--all-containersall the containers of the Podkubectl logs my-pod --all-containers

With an -l selector, kubectl logs reads all the matching Pods but by default keeps only their last 10 lines each. The --prefix option then says which Pod each line comes from:

Terminal window
kubectl logs -l app=web --tail=2 --prefix
Output
[pod/web-75b69c7f78-27d55/nginx] 2026/10/13 15:41:11 [notice] 1#1: start worker process 50
[pod/web-75b69c7f78-27d55/nginx] 2026/10/13 15:41:11 [notice] 1#1: start worker process 51
[pod/web-75b69c7f78-9smrs/nginx] 2026/10/13 15:41:12 [notice] 1#1: start worker process 50
[pod/web-75b69c7f78-9smrs/nginx] 2026/10/13 15:41:12 [notice] 1#1: start worker process 51

A Pod can contain several containers, for example an application and a container that ships its logs. Without -c, kubectl logs then picks the first and announces it with a line Defaulted container "app" out of: app, journal: read it, because the log displayed may not be the one you are looking for.

kubectl top: how much does it consume?

kubectl top displays the current CPU and memory consumption of nodes and Pods. These figures do not come from the usual API but from the metrics API, provided by a component you have to install: metrics-server. kind does not install it, and on a new cluster the command fails:

Terminal window
kubectl top nodes
Output on a new kind cluster
error: Metrics API not available

Install metrics-server on kind

metrics-server is installed from the manifest published with each release, here v0.9.1, compatible with Kubernetes 1.34 and later. On kind, it also needs the --kubelet-insecure-tls option: the certificate presented by the kind kubelets is not signed by the authority metrics-server expects, and without this option its Pod stays at 0/1 and never serves any measurement. This option disables a security check: it is justified on a learning cluster, never on a production cluster.

Terminal window
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/download/v0.9.1/components.yaml
kubectl patch deployment metrics-server -n kube-system --type=json -p '[
{"op":"add","path":"/spec/template/spec/containers/0/args/-","value":"--kubelet-insecure-tls"},
{"op":"replace","path":"/spec/template/spec/containers/0/image","value":"registry.k8s.io/metrics-server/metrics-server:v0.9.1@sha256:9b0ba1926e1d3089673f45461c3c1416109dea33b3ba3434048defd380df329b"}
]'
kubectl rollout status deployment metrics-server -n kube-system

The manifest address carries the version number: you install exactly v0.9.1, and not the latest version of the moment, which could change without warning. The manifest designates the image by its tag alone; the patch replaces it with the same version pinned by its digest, which designates a precise content even if the tag were republished. The last command waits for the fixed Pod to be ready and ends with deployment "metrics-server" successfully rolled out. Then allow about thirty seconds before the first measurement.

Read the nodes and the Pods

kubectl top nodes measures each node, kubectl top pods each Pod of the namespace. CPU is expressed in millicores (317m is 317 thousandths of a core) and memory in mebibytes (Mi). The node percentages are computed on the allocatable capacity, the one that remains once the system is served.

Terminal window
kubectl top nodes
Output
NAME CPU(cores) CPU(%) MEMORY(bytes) MEMORY(%)
kubectl-rattach-control-plane 317m 1% 689Mi 1%
kubectl-rattach-worker 512m 3% 829Mi 1%
Terminal window
kubectl top pods
Output
NAME CPU(cores) MEMORY(bytes)
web-75b69c7f78-27d55 0m 13Mi
web-75b69c7f78-9smrs 0m 13Mi

api and batch do not appear: a container that is not running consumes nothing and produces no measurement. kubectl top is therefore not for finding a failing Pod, it is for spotting a Pod that consumes too much. Two options complete the command: --sort-by=cpu or --sort-by=memory sorts the Pods, and --containers details the consumption container by container.

These figures are instantaneous measurements, refreshed at regular intervals, with no history at all: kubectl top says what is happening now, not what happened last night. Tracking consumption over time is a job for a monitoring tool, such as Prometheus, which keeps the measurements.

Chain the four commands

Faced with a Pod that is unhealthy, the order get, describe, logs, top keeps you from looking in the wrong place. Each command answers a question and picks the next one. Skipping describe to rush to the logs is a common mistake: a Pod whose image does not download, or which is waiting for a spot on a node, has no log to show.

  1. What? List and spot the abnormal line.

    Terminal window
    kubectl get pods

    Look at READY, STATUS and RESTARTS. A Pod at 0/1 or a rising restart counter points to the suspect.

  2. Why? Describe the Pod by its full name and read the end.

    Terminal window
    kubectl describe pod <full-pod-name>

    The container state and the Warning lines of the events give the cause, or say that the container started then failed.

  3. What did the application say? If the container started, read its logs.

    Terminal window
    kubectl logs <full-pod-name> --tail=50

    Add --previous if the container is running again after a crash and you are looking for the trace of the previous run.

  4. How much? If the Pod runs but answers badly, measure its consumption.

    Terminal window
    kubectl top pod <full-pod-name>

Applied to the two failures of this lesson, the sequence stops early: for api, describe is enough (typo in the tag); for batch, logs gives the cause (missing variable). The tougher failures each have their own lesson in the Operate module: a Pod stuck in Pending, a CrashLoopBackOff, an ImagePullBackOff (in French), and the method for diagnosing an incident (in French). Getting into a container with kubectl exec or kubectl debug belongs to the lesson Debug a Kubernetes application.

Reading a status: where to start?

The status displayed by kubectl get points to the command to run next. This table serves as a switchboard for the statuses you will meet at the beginning; when in doubt, the events of describe remain a good starting point.

Status in kubectl getWhat it meansNext command
Pendingat least one container has not started, most often for lack of a node that accepts the Podkubectl describe pod, Events section
ErrImagePull, ImagePullBackOffthe image does not downloadkubectl describe pod, Events section
Error, CrashLoopBackOffthe container starts then stopskubectl logs, then describe for the exit code
Running with a rising RESTARTSthe container restarts regularlykubectl logs --previous and kubectl describe pod
Running and 1/1, but the application answers badlythe Pod is fine, the problem is elsewherekubectl logs, kubectl top pod

Clean up

Deleting the namespace deletes everything it contains, Deployments and Pods included. Also set the default namespace of the context back to default, otherwise your next commands would target a namespace that no longer exists and answer No resources found.

Terminal window
kubectl delete namespace diagnostic
kubectl config set-context --current --namespace=default

Keep metrics-server: it takes only about twenty mebibytes of memory, and kubectl top will serve you again.

Put it into practice

In the diagnostic namespace, two Deployments do not start: api references an image that does not exist, and batch exits with an error. You write three files in ~/diagnostic: api.txt gives the waiting reason of the Pod and the faulty image, batch.txt the error of the previous run and its exit code, and top.txt the Pod that consumes the most memory. You repair nothing. The validation checks your files against what the cluster says at the time of the check (reason, actual exit code, measurement from the metrics API) and verifies that both Deployments were left intact.

Key takeaways

  1. kubectl get says what is wrong: read READY, STATUS and RESTARTS, filter with -n, -A and -l.
  2. -o wide, -o yaml and -o jsonpath show more, everything, or a single value, without changing what is queried.
  3. kubectl describe says why: state of each container, exit code, and the Events section at the bottom, which you must never skip.
  4. Give describe the full name: with the beginning of a name, or a selector that designates several Pods, the Events section disappears.
  5. kubectl logs has nothing to show until the container has started; --previous reads the previous run, and -l with --prefix reads several Pods.
  6. kubectl top requires metrics-server, which kind does not install; it measures the present moment, without history, and ignores stopped Pods.
  7. In the order get, describe, logs, top: the two failures of this lesson are solved before the fourth command.

Knowledge check

Six questions about what you read and where to read it: the status that points to the next command, the Events section that a partial name makes disappear, and the logs that do not exist until a container has started.

Knowledge check

Check what you have learned with this interactive quiz

6 questions
5 min
80% to pass

How it works

  • The timer starts when you click Start
  • Multiple choice, true/false and short answer questions
  • You can move between questions
  • Detailed results are shown at the end

Starts the quiz and the timer