A Pod is the object that Kubernetes creates, places on a node and watches in order to run one or more containers. In this lesson, you start a Pod with kubectl run, you describe it in YAML, you read its state with get, describe, logs and exec, then you break it in two ways (an image that cannot be found, a container that crashes) to see what the cluster says about it.
Prerequisites: the four-node demo cluster from the lesson First cluster (section "Create a multi-node cluster"), kubectl configured, and the architecture covered in Kubernetes architecture.
What you will learn
- Create a Pod with
kubectl runand with a YAML manifest - Observe a Pod: its state, its logs, and how to enter its container with
kubectl exec - Predict the effect of
restartPolicyand read aCrashLoopBackOff - Tell a single-container Pod from a multi-container Pod, and say what an init container is for
- Explain why a bare Pod does not replace itself
- Diagnose an
ImagePullBackOff, aPendingand a container that crashes
What is a Pod?
A Pod runs your containers, and Kubernetes manages the Pod: it places it on a node, starts it and watches it. Most of the time, a Pod contains a single container.
Kubernetes does not handle containers directly because some applications need several processes that share the same IP address (they talk to each other through localhost), the same volumes, the same node and the same start and stop cycle. The Pod is that grouping unit, and it is the Pod that the scheduler (the component that chooses the node of each Pod) places on a node.
Create your first Pod
Two paths lead to the same object. The imperative method fits in one command and is used to try things out or to troubleshoot. The declarative method goes through a YAML file that you keep under version control, and it is the one your team uses.
Imperative method: kubectl run
First check that kubectl talks to the demo cluster, then start a Pod named web with an Nginx image pinned by its digest:
kubectl config use-context kind-demokubectl run web --image=nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edbkubectl wait --for=condition=Ready pod/web --timeout=90skubectl get podsSwitched to context "kind-demo".pod/web createdpod/web condition metNAME READY STATUS RESTARTS AGEweb 1/1 Running 0 7sThe READY column shows how many containers of the Pod are ready out of the total, STATUS gives the displayed state, and RESTARTS counts the restarts of the container. 1/1 Running with zero restarts is the healthy state.
Declarative method: a YAML manifest
kubectl can produce the YAML for you, without creating anything on the cluster. It is the fastest way to get a manifest skeleton:
kubectl run web-yaml \ --image=nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb \ --dry-run=client -o yamlapiVersion: v1kind: Podmetadata: labels: run: web-yaml name: web-yamlspec: containers: - image: nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb name: web-yaml resources: {} dnsPolicy: ClusterFirst restartPolicy: Alwaysstatus: {}Now write your own manifest and apply it. kubectl apply -f - reads the file on its standard input, which saves you from creating a file:
kubectl apply -f - <<'EOF'apiVersion: v1kind: Podmetadata: name: web-yaml labels: app: web-yamlspec: restartPolicy: Always containers: - name: nginx image: nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb ports: - containerPort: 80EOFkubectl wait --for=condition=Ready pod/web-yaml --timeout=90skubectl get podspod/web-yaml createdpod/web-yaml condition metNAME READY STATUS RESTARTS AGEweb 1/1 Running 0 16sweb-yaml 1/1 Running 0 9sObserve a Pod: get, describe, logs, exec
When a Pod has a problem, four commands are always run in this order, from the least intrusive to the most intrusive: where is it (get), what did Kubernetes try (describe), what did the application say (logs), what does the container hold (exec).
kubectl get pod web -o wideNAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATESweb 1/1 Running 0 16s 10.244.1.2 demo-worker2 <none> <none>The -o wide option adds the IP address of the Pod and the node that hosts it. The describe command details the object:
kubectl describe pod webName: webNamespace: defaultPriority: 0Service Account: defaultNode: demo-worker2/172.18.0.4Start Time: Tue, 10 Nov 2026 23:07:29 +0000Labels: run=web topology.kubernetes.io/zone=zone-bAnnotations: <none>Status: RunningIP: 10.244.1.2[...]Containers: web: Image: nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb Port: <none> State: Running Started: Tue, 10 Nov 2026 23:07:36 +0000 Ready: True Restart Count: 0[...]Conditions: Type Status PodReadyToStartContainers True Initialized True Ready True ContainersReady True PodScheduled True[...]Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal Scheduled 16s default-scheduler Successfully assigned default/web to demo-worker2 Normal Pulling 16s kubelet spec.containers{web}: Pulling image "nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb" Normal Pulled 9s kubelet spec.containers{web}: Successfully pulled image "nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb" in 7.07s (7.071s including waiting). Image size: 63638242 bytes. Normal Created 9s kubelet spec.containers{web}: Container created Normal Started 9s kubelet spec.containers{web}: Container startedThe topology.kubernetes.io/zone label is not in your manifest: the API server copies it from the chosen node at placement time (through the PodTopologyLabels admission plugin, a module of the API server that completes or checks each object before saving it, enabled by default since Kubernetes 1.35). The lesson Labels and annotations comes back to labels.
Look at the Events section at the bottom of the output: it tells what Kubernetes did, in order (placement, image pull, creation, start). It is the section that gives the cause when a Pod does not start.
kubectl logs web --tail=5kubectl exec web -- hostnamekubectl exec web -- cat /etc/nginx/nginx.conf | head -n 52026/11/10 23:07:36 [notice] 1#1: OS: Linux 6.12.115+deb13.1-amd642026/11/10 23:07:36 [notice] 1#1: getrlimit(RLIMIT_NOFILE): 1073741816:10737418162026/11/10 23:07:36 [notice] 1#1: start worker processes2026/11/10 23:07:36 [notice] 1#1: start worker process 352026/11/10 23:07:36 [notice] 1#1: start worker process 36web
user nginx;worker_processes auto;
error_log /var/log/nginx/error.log notice;kubectl logs prints the standard output of the container. kubectl exec web -- <command> runs a command in the container and returns control to you. For an interactive shell, add -it (kubectl exec -it web -- sh), type your commands, then exit to leave: without -it, you cannot type anything in the container.
To follow the logs continuously, add --follow to kubectl logs; Ctrl+C stops the following and leaves the Pod alive.
What does a Pod manifest contain?
Now that you have seen a Pod live, reread the manifest written above field by field.
| Field | Role |
|---|---|
metadata.name | Name of the Pod, unique in its namespace |
metadata.labels | Labels to organize and select objects |
spec.containers[] | List of containers, at least one |
spec.containers[].image | Image to run |
spec.containers[].ports[] | Ports the container listens on (informational) |
spec.restartPolicy | What Kubernetes does when a container stops |
This structure is almost frozen once the Pod is created: the API only lets you change a few fields in place, including the image of a container. Changing an environment variable, a port or restartPolicy requires you to delete and recreate the Pod, which is a first reason not to manage Pods by hand.
What are the phases of a Pod?
The phase sums up in one word where the Pod stands. It is read in the status.phase field, and the STATUS column of kubectl get pods is a finer display that can show something else (for example CrashLoopBackOff).
On the diagram, the thick arrow is the normal path: Pending, then Running. A Pod that runs a finite task then leaves Running for Succeeded or Failed.
| Phase | Meaning |
|---|---|
Pending | The Pod is accepted by the API, but its containers are not running yet: it is waiting to be placed on a node, or for its images to be pulled. |
Running | The Pod is placed on a node and at least one container is running, or starting, or restarting. |
Succeeded | All containers ended successfully (exit code 0) and will not be restarted. |
Failed | All containers have ended, and at least one ended in failure (non-zero code, or stopped by the system), with no restart planned. |
Unknown | The state of the Pod could not be obtained, usually because of a communication problem with the node. |
kubectl get pod web -o jsonpath='{.status.phase}{"\n"}'RunningThe phase is deliberately coarse. Each container has its own state (Waiting, Running or Terminated), which kubectl describe details. CrashLoopBackOff is not a phase: it is the waiting reason of a container that has crashed several times, shown in the STATUS column.
Break a Pod in two ways
Reading a healthy Pod teaches little. Break two of them in the simplest way, and read what the cluster says about it.
First failure: an image that cannot be found
The following Pod asks for a version of Nginx that does not exist. The image is wrong on purpose (# ❌, do not reproduce it outside the exercise):
kubectl run image-fausse --image=nginx:1.30.999 # ❌ nonexistent tag, on purposesleep 20kubectl get pod image-faussepod/image-fausse createdNAME READY STATUS RESTARTS AGEimage-fausse 0/1 ImagePullBackOff 0 20sKubernetes tries to pull the image, fails (ErrImagePull), then spaces out its attempts (ImagePullBackOff). The two labels alternate: it is a single failure seen at two moments. The Pod stays in the Pending phase, since no container has started. The exact cause is in the events:
kubectl describe pod image-fausse | tail -n 8kubectl get pod image-fausse -o jsonpath='{.status.phase}{"\n"}' Type Reason Age From Message ---- ------ ---- ---- ------- Normal Scheduled 20s default-scheduler Successfully assigned default/image-fausse to demo-worker3 Normal BackOff 18s kubelet spec.containers{image-fausse}: Back-off pulling image "nginx:1.30.999" Warning Failed 18s kubelet spec.containers{image-fausse}: Error: ImagePullBackOff Normal Pulling 5s (x2 over 19s) kubelet spec.containers{image-fausse}: Pulling image "nginx:1.30.999" Warning Failed 4s (x2 over 19s) kubelet spec.containers{image-fausse}: Failed to pull image "nginx:1.30.999": rpc error: code = NotFound desc = failed to pull and unpack image "docker.io/library/nginx:1.30.999": failed to resolve reference "docker.io/library/nginx:1.30.999": docker.io/library/nginx:1.30.999: not found Warning Failed 4s (x2 over 19s) kubelet spec.containers{image-fausse}: Error: ErrImagePullPendingA typo in the image, a private image without credentials or an unreachable registry give this same symptom, and it is the message of the Failed event that tells them apart. The page ImagePullBackOff (in French) details each cause.
Second failure: a container that crashes
Here the image exists, but the program of the container ends immediately with code 1. Since restartPolicy is Always by default, Kubernetes restarts it, then waits longer and longer between two attempts:
kubectl run plante \ --image=busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4 \ -- sh -c 'echo "je démarre puis je plante"; exit 1'sleep 45kubectl get pod plantepod/plante createdNAME READY STATUS RESTARTS AGEplante 0/1 Error 3 (30s ago) 45sThe STATUS column alternates between Error, CrashLoopBackOff and Running depending on the moment you look: it is a photograph, not a history. The capture above lands on Error, with 3 restarts. The RESTARTS counter climbs, and the Pod stays 0/1 most of the time.
The first restart is immediate, then the kubelet waits 10 s, 20 s, 40 s, and so on up to 5 min at most. The delay counter resets to zero after 10 minutes without a crash. The page CrashLoopBackOff explains this mechanism and its causes.
To know why the container stopped, kubectl logs --previous rereads the log of the previous container, when it is still available. It is not always: here, the command answered unable to retrieve container logs. The exit code is then read in the status of the Pod, and it is indeed 1:
kubectl logs plante --previouskubectl get pod plante -o jsonpath='{.status.containerStatuses[0].lastState.terminated.exitCode}{"\n"}'kubectl get pod plante -o jsonpath='{.status.phase}{"\n"}'unable to retrieve container logs for containerd://5ae6f9a1bddbe91da7598eb43f85c18a0a40be8ff0ac1468dc619e5b18a36df01RunningNote that the phase stays Running while the container crashes in a loop: the phase alone is not enough to judge the health of a Pod, look at STATUS and RESTARTS.
What does restartPolicy do?
The restartPolicy field decides what Kubernetes does when a container stops.
| Value | Behavior | Typical use |
|---|---|---|
Always (default) | Restarts the container whatever its exit code | Web servers, APIs |
OnFailure | Restarts only if the exit code is not 0 | Batch processing |
Never | Never restarts | One-off tasks |
With classic applications, you will mostly see Always. The two other values serve one-off Pods or Pods created by a Job. With Never, the Pod ends in Succeeded or in Failed depending on the exit code of the container:
kubectl run une-fois --restart=Never \ --image=busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4 \ -- sh -c 'echo ok; exit 0'kubectl run echec --restart=Never \ --image=busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4 \ -- sh -c 'echo ko; exit 1'sleep 15kubectl get pods une-fois echeckubectl get pod une-fois -o jsonpath='{.status.phase}{"\n"}'kubectl get pod echec -o jsonpath='{.status.phase}{"\n"}'pod/une-fois createdpod/echec createdNAME READY STATUS RESTARTS AGEune-fois 0/1 Completed 0 15sechec 0/1 Error 0 15sSucceededFailedThe Pod une-fois is Completed (phase Succeeded) and the Pod echec is Error (phase Failed). Neither is restarted.
Why does a Pod stay Pending?
A Pod in Pending has been accepted by the API but no node has taken it yet. A frequent cause is a scheduler that finds no acceptable node. Trigger it with a Pod that requires a node carrying a label that no node has:
kubectl apply -f - <<'EOF'apiVersion: v1kind: Podmetadata: name: bloquespec: nodeSelector: disktype: ssd containers: - name: nginx image: nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edbEOFsleep 5kubectl get pod bloquekubectl describe pod bloque | tail -n 5pod/bloque createdNAME READY STATUS RESTARTS AGEbloque 0/1 Pending 0 5s node.kubernetes.io/unreachable:NoExecute op=Exists for 300sEvents: Type Reason Age From Message ---- ------ ---- ---- ------- Warning FailedScheduling 5s default-scheduler 0/4 nodes are available: 1 node(s) had untolerated taint(s), 3 node(s) didn't match Pod's node affinity/selector. preemption: 0/4 nodes are available: 4 Preemption is not helpful for scheduling.The first line of the describe extract, node.kubernetes.io/unreachable:NoExecute op=Exists for 300s, is a toleration that Kubernetes adds by default to every Pod: it sets to 300 s the delay before the Pod is evicted from an unreachable node. It has nothing to do with the failure.
The reason for the blockage is in the FailedScheduling event: three nodes do not match the nodeSelector, and the fourth, the control plane, carries a taint (a mark that repels ordinary Pods). A resource request that the nodes cannot satisfy, or a volume that is not available yet, also keep a Pod in Pending: the page Pods Pending goes over them.
Should you put several containers in a Pod?
By default, no: a Pod with a single container is simpler and scales independently. Several containers are only justified when they absolutely must share the network and the volumes. Two cases come up.
A sidecar is an auxiliary container that stays next to the application (log agent, proxy). An init container runs before the main containers, one after the other, and all of them must succeed before the application starts: it prepares the ground (wait for a database, fetch a file). A Pod that stays in Init:0/1 is waiting for an init container that has not finished. The containers of a same Pod communicate through localhost without a Service. The manifests and the native sidecar are in Init containers and sidecars.
Why avoid bare Pods?
A Pod created directly by kubectl run or by a manifest of kind Pod, like web, is watched by no controller. Delete it and see what happens:
kubectl delete pod webkubectl get podspod "web" deleted from default namespaceNAME READY STATUS RESTARTS AGEbloque 0/1 Pending 0 5sechec 0/1 Error 0 21simage-fausse 0/1 ImagePullBackOff 0 86splante 0/1 Error 3 (51s ago) 66sune-fois 0/1 Completed 0 21sweb-yaml 1/1 Running 0 95sNo web Pod comes back: nobody was tasked with keeping one. A bare Pod does not survive the failure of its node, is not replicated and cannot be updated without interruption. In practice, you go through a controller: a Deployment for a stateless application, a StatefulSet for a stateful application, a DaemonSet for one Pod per node, a Job or a CronJob for a finite task.
Changing the image of an existing Pod with kubectl set image pod/... is possible, but a Deployment does it cleanly: the lesson on Deployments shows how.
In what order should you diagnose a Pod?
Diagnosis goes from the least intrusive to the most intrusive: kubectl get pod <name> -o wide (where is it), kubectl describe pod <name> (events), kubectl logs <name> --tail=50 (what the application said, with --previous after a crash), then kubectl exec (enter the container). These four commands are enough for the failures of this lesson. Metrics (kubectl top) and ephemeral containers (kubectl debug) need extra tools: they are covered in Debug a Kubernetes application.
When the Pod does not start, the following table links the displayed symptom to the place to look.
What get pods shows | Where to look | Frequent cause |
|---|---|---|
ErrImagePull, ImagePullBackOff | describe, Failed events | Image or tag does not exist, private registry |
CrashLoopBackOff | exit code, logs --previous | The application ends at startup |
Pending | describe, FailedScheduling event | No acceptable node, insufficient resources |
Init:0/1 | logs <pod> -c <init-container> | An init container has not finished |
Clean up the cluster
Delete the Pods of this lesson to start again from a clean cluster:
kubectl delete pod web-yaml image-fausse plante une-fois echec bloque --wait=falsekubectl get podspod "web-yaml" deleted from default namespacepod "image-fausse" deleted from default namespacepod "plante" deleted from default namespacepod "une-fois" deleted from default namespacepod "echec" deleted from default namespacepod "bloque" deleted from default namespaceNAME READY STATUS RESTARTS AGEimage-fausse 0/1 Terminating 0 86splante 0/1 Error 3 (51s ago) 66sweb-yaml 1/1 Terminating 0 95sPut it into practice
The guided lab replays the two failures of the lesson on a kind cluster, in the pods-en-panne namespace: the Pod image-fausse asks for an image that does not exist, and the container of the Pod plante stops with an error. You record in ~/pods-en-panne/releve.txt the waiting reason of the first and the exit code of the second, then you repair them. The image of image-fausse is fixed in place, on the same Pod. The command of an existing Pod cannot be changed: plante is therefore recreated under the same name, with the same image and a corrected command, and must run without restarting. The validation reads the state of the Pods, their identifier and their restart counter: a Pod repaired under another name is refused.
Key takeaways
- A Pod runs one or more containers, and Kubernetes places it, starts it and watches it.
- The containers of a same Pod share the network (
localhost) and the volumes. - To observe a Pod:
get,describe(the events at the bottom),logs, thenexec. - The phase of a Pod is
Pending,Running,Succeeded,FailedorUnknown;CrashLoopBackOffis not a phase but the waiting reason of a container that crashes. restartPolicyisAlwaysby default;OnFailureandNeverserve finite tasks.ImagePullBackOffis read in the events ofdescribe,CrashLoopBackOffin the exit code and inlogs --previous,Pendingin theFailedSchedulingevent.- An init container prepares the environment before the main containers.
- A bare Pod does not replace itself: you go through a Deployment or another controller.
Test your knowledge
Seven questions to check the life cycle, restartPolicy, init containers and the diagnosis of the three failures of the lesson.
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: Kubernetes Deployments: deploy, update, roll back
A new full quiz with random questions
Work again only on the questions you missed
FAQ: frequently asked questions about Pods
These questions come up often when you discover Kubernetes Pods: difference with a container, multi-container Pods, CrashLoopBackOff, init containers and life cycle.
localhost) and the volumes, which allows the sidecar pattern: a secondary container that assists the main one (log collection, proxy). But it is not the common case: by default, keep a single container per Pod and add a sidecar only if the need is real.CrashLoopBackOff signals that a container starts, crashes, then restarts in a loop. Between two attempts, Kubernetes waits longer and longer (exponential backoff). Beware: it is not a Pod phase, but a container state visible in kubectl get pods. To find the cause, read the logs: kubectl logs my-pod --previous prints the output of the previous attempt.kubectl logs my-pod. A few useful options:-f: follow the logs live (liketail -f).--previous: print the logs of the previous instance, essential after a crash.-c container-name: target a specific container in a multi-container Pod.
kubectl describe pod my-pod completes the diagnosis by showing the events.Waiting, Running, Terminated) with kubectl describe pod.