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.
kubectl create namespace diagnostickubectl 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 existkubectl 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.
kubectl get podsNAME READY STATUS RESTARTS AGEapi-5694859b95-pbxqt 0/1 ErrImagePull 0 50sbatch-5f74bc5db8-rbg2z 0/1 Error 2 (27s ago) 50sweb-75b69c7f78-27d55 1/1 Running 0 50sweb-75b69c7f78-9smrs 1/1 Running 0 50sThree 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.
kubectl get pods -n kube-system # another namespacekubectl get pods -A # all namespaceskubectl get deployments,pods # several types at onceThe 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.
kubectl get pods -l app=webNAME READY STATUS RESTARTS AGEweb-75b69c7f78-27d55 1/1 Running 0 50sweb-75b69c7f78-9smrs 1/1 Running 0 50sFour forms of expression cover the essentials. Put single quotes around those that contain ! or parentheses, otherwise the shell interprets them before kubectl does.
| Expression | What it keeps |
|---|---|
-l app=web | the 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 app | those 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.
| Format | What it displays | When to use it |
|---|---|---|
-o wide | the table, plus the Pod IP and its node | know where a Pod runs |
-o yaml | the full object, as the API stores it | read a field absent from the table |
-o name | type/name, one line per resource | pass a list to another command |
-o jsonpath='{...}' | only the requested value | feed a script variable |
kubectl get pods -o wideNAME READY STATUS RESTARTS AGE IP NODEapi-5694859b95-pbxqt 0/1 ErrImagePull 0 50s 10.244.1.39 kubectl-rattach-workerbatch-5f74bc5db8-rbg2z 0/1 Error 2 (27s ago) 50s 10.244.1.40 kubectl-rattach-workerweb-75b69c7f78-27d55 1/1 Running 0 50s 10.244.1.37 kubectl-rattach-workerweb-75b69c7f78-9smrs 1/1 Running 0 50s 10.244.1.38 kubectl-rattach-workerThe -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:
kubectl get pod web-75b69c7f78-27d55 -o jsonpath='{.status.podIP}'; echo10.244.1.37The 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.
kubectl get pods -wIt 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".
kubectl describe pod api-5694859b95-pbxqtName: api-5694859b95-pbxqtNamespace: diagnosticNode: kubectl-rattach-worker/172.26.0.2Status: PendingControlled By: ReplicaSet/api-5694859b95Containers: nginx: Image: nginx:1.280 State: Waiting Reason: ErrImagePull Ready: False Restart Count: 0Conditions: Type Status PodReadyToStartContainers True Initialized True Ready False ContainersReady False PodScheduled TrueEvents: 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: ErrImagePullRead 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:
State: Terminated Reason: Error Exit Code: 1 Last State: Terminated Reason: Error Exit Code: 1 Ready: False Restart Count: 2Events: 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:
kubectl get events --field-selector type=WarningLAST SEEN TYPE REASON OBJECT MESSAGE24s 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 found24s Warning Failed pod/api-5694859b95-pbxqt Error: ErrImagePull10s Warning Failed pod/api-5694859b95-pbxqt Error: ImagePullBackOff20s 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.
| Resource | What describe reveals first |
|---|---|
pod | state of each container, restarts, events |
deployment | number of desired and available replicas, current ReplicaSet |
service | selector and Endpoints, hence the Pods actually reached |
node | capacity, 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:
kubectl logs batch-5f74bc5db8-rbg2zerreur: variable DB_HOST absentebatch: démarrageThe 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:
kubectl logs api-5694859b95-pbxqtError from server (BadRequest): container "nginx" in pod "api-5694859b95-pbxqt" is waiting to start: image can't be pulledLogs 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.
Error from server (BadRequest): previous terminated container "nginx" in pod "web-75b69c7f78-27d55" not foundunable to retrieve container logs for containerd://a53b532730ae6ce819221cf4b209091f6845c257efd625fdf47b75a7cf919f1bThe 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.
| Option | Effect | Example |
|---|---|---|
--tail=N | the last N lines | kubectl logs web-75b69c7f78-27d55 --tail=20 |
-f | follow the log continuously, until Ctrl+C | kubectl logs -f web-75b69c7f78-27d55 |
--since=10m | only the lines from the last 10 minutes | kubectl logs web-75b69c7f78-27d55 --since=10m |
--timestamps | prefix each line with its timestamp | kubectl logs web-75b69c7f78-27d55 --timestamps |
-l app=web | the logs of all the Pods that carry this label | kubectl logs -l app=web --prefix |
--prefix | prefix each line with the originating Pod and container | same |
-c <name> | a specific container, when the Pod contains several | kubectl logs my-pod -c journal |
--all-containers | all the containers of the Pod | kubectl 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:
kubectl logs -l app=web --tail=2 --prefix[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 51A 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:
kubectl top nodeserror: Metrics API not availableInstall 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.
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-systemThe 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.
kubectl top nodesNAME CPU(cores) CPU(%) MEMORY(bytes) MEMORY(%)kubectl-rattach-control-plane 317m 1% 689Mi 1%kubectl-rattach-worker 512m 3% 829Mi 1%kubectl top podsNAME CPU(cores) MEMORY(bytes)web-75b69c7f78-27d55 0m 13Miweb-75b69c7f78-9smrs 0m 13Miapi 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.
-
What? List and spot the abnormal line.
Terminal window kubectl get podsLook at
READY,STATUSandRESTARTS. A Pod at0/1or a rising restart counter points to the suspect. -
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
Warninglines of the events give the cause, or say that the container started then failed. -
What did the application say? If the container started, read its logs.
Terminal window kubectl logs <full-pod-name> --tail=50Add
--previousif the container is running again after a crash and you are looking for the trace of the previous run. -
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 get | What it means | Next command |
|---|---|---|
Pending | at least one container has not started, most often for lack of a node that accepts the Pod | kubectl describe pod, Events section |
ErrImagePull, ImagePullBackOff | the image does not download | kubectl describe pod, Events section |
Error, CrashLoopBackOff | the container starts then stops | kubectl logs, then describe for the exit code |
Running with a rising RESTARTS | the container restarts regularly | kubectl logs --previous and kubectl describe pod |
Running and 1/1, but the application answers badly | the Pod is fine, the problem is elsewhere | kubectl 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.
kubectl delete namespace diagnostickubectl config set-context --current --namespace=defaultKeep 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
kubectl getsays what is wrong: readREADY,STATUSandRESTARTS, filter with-n,-Aand-l.-o wide,-o yamland-o jsonpathshow more, everything, or a single value, without changing what is queried.kubectl describesays why: state of each container, exit code, and theEventssection at the bottom, which you must never skip.- Give
describethe full name: with the beginning of a name, or a selector that designates several Pods, theEventssection disappears. kubectl logshas nothing to show until the container has started;--previousreads the previous run, and-lwith--prefixreads several Pods.kubectl toprequires metrics-server, which kind does not install; it measures the present moment, without history, and ignores stopped Pods.- 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
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
Review
(0/0)Score by domain
A domain groups several guides and gets several questions, so its score is more reliable than a per-topic score, which often rests on a single question.
Summary
Strengths
No topic passed at 80% on at least two questions yet.
Weak areas
No topic below the pass mark.
Recommended next
Hints before you try again?
Continue the course: Quiz: check your Kubernetes basics
A new full quiz with random questions
Work again only on the questions you missed