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

Kubernetes Pods: create, observe and diagnose

By updated

Improve this page

Logo Kubernetes

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 run and with a YAML manifest
  • Observe a Pod: its state, its logs, and how to enter its container with kubectl exec
  • Predict the effect of restartPolicy and read a CrashLoopBackOff
  • 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, a Pending and 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:

Terminal window
kubectl config use-context kind-demo
kubectl run web --image=nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb
kubectl wait --for=condition=Ready pod/web --timeout=90s
kubectl get pods
Output
Switched to context "kind-demo".
pod/web created
pod/web condition met
NAME READY STATUS RESTARTS AGE
web 1/1 Running 0 7s

The 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:

Terminal window
kubectl run web-yaml \
--image=nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb \
--dry-run=client -o yaml
Output
apiVersion: v1
kind: Pod
metadata:
labels:
run: web-yaml
name: web-yaml
spec:
containers:
- image: nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb
name: web-yaml
resources: {}
dnsPolicy: ClusterFirst
restartPolicy: Always
status: {}

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:

Terminal window
kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
name: web-yaml
labels:
app: web-yaml
spec:
restartPolicy: Always
containers:
- name: nginx
image: nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb
ports:
- containerPort: 80
EOF
kubectl wait --for=condition=Ready pod/web-yaml --timeout=90s
kubectl get pods
Output
pod/web-yaml created
pod/web-yaml condition met
NAME READY STATUS RESTARTS AGE
web 1/1 Running 0 16s
web-yaml 1/1 Running 0 9s

Observe 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).

Terminal window
kubectl get pod web -o wide
Output
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
web 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:

Terminal window
kubectl describe pod web
Output
Name: web
Namespace: default
Priority: 0
Service Account: default
Node: demo-worker2/172.18.0.4
Start Time: Tue, 10 Nov 2026 23:07:29 +0000
Labels: run=web
topology.kubernetes.io/zone=zone-b
Annotations: <none>
Status: Running
IP: 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 started

The 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.

Terminal window
kubectl logs web --tail=5
kubectl exec web -- hostname
kubectl exec web -- cat /etc/nginx/nginx.conf | head -n 5
Output
2026/11/10 23:07:36 [notice] 1#1: OS: Linux 6.12.115+deb13.1-amd64
2026/11/10 23:07:36 [notice] 1#1: getrlimit(RLIMIT_NOFILE): 1073741816:1073741816
2026/11/10 23:07:36 [notice] 1#1: start worker processes
2026/11/10 23:07:36 [notice] 1#1: start worker process 35
2026/11/10 23:07:36 [notice] 1#1: start worker process 36
web
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.

FieldRole
metadata.nameName of the Pod, unique in its namespace
metadata.labelsLabels to organize and select objects
spec.containers[]List of containers, at least one
spec.containers[].imageImage to run
spec.containers[].ports[]Ports the container listens on (informational)
spec.restartPolicyWhat 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).

Phases of a Pod: Pending, then Running, which ends in Succeeded or in Failed.PendingRunningSucceededFailed
Source · SVG
Esc to close, + and − to zoom, scroll to move around. 100 %

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.

PhaseMeaning
PendingThe 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.
RunningThe Pod is placed on a node and at least one container is running, or starting, or restarting.
SucceededAll containers ended successfully (exit code 0) and will not be restarted.
FailedAll containers have ended, and at least one ended in failure (non-zero code, or stopped by the system), with no restart planned.
UnknownThe state of the Pod could not be obtained, usually because of a communication problem with the node.
Terminal window
kubectl get pod web -o jsonpath='{.status.phase}{"\n"}'
Output
Running

The 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):

Terminal window
kubectl run image-fausse --image=nginx:1.30.999 # ❌ nonexistent tag, on purpose
sleep 20
kubectl get pod image-fausse
Output
pod/image-fausse created
NAME READY STATUS RESTARTS AGE
image-fausse 0/1 ImagePullBackOff 0 20s

Kubernetes 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:

Terminal window
kubectl describe pod image-fausse | tail -n 8
kubectl get pod image-fausse -o jsonpath='{.status.phase}{"\n"}'
Output
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: ErrImagePull
Pending

A 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:

Terminal window
kubectl run plante \
--image=busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4 \
-- sh -c 'echo "je démarre puis je plante"; exit 1'
sleep 45
kubectl get pod plante
Output
pod/plante created
NAME READY STATUS RESTARTS AGE
plante 0/1 Error 3 (30s ago) 45s

The 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:

Terminal window
kubectl logs plante --previous
kubectl get pod plante -o jsonpath='{.status.containerStatuses[0].lastState.terminated.exitCode}{"\n"}'
kubectl get pod plante -o jsonpath='{.status.phase}{"\n"}'
Output
unable to retrieve container logs for containerd://5ae6f9a1bddbe91da7598eb43f85c18a0a40be8ff0ac1468dc619e5b18a36df0
1
Running

Note 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.

ValueBehaviorTypical use
Always (default)Restarts the container whatever its exit codeWeb servers, APIs
OnFailureRestarts only if the exit code is not 0Batch processing
NeverNever restartsOne-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:

Terminal window
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 15
kubectl get pods une-fois echec
kubectl get pod une-fois -o jsonpath='{.status.phase}{"\n"}'
kubectl get pod echec -o jsonpath='{.status.phase}{"\n"}'
Output
pod/une-fois created
pod/echec created
NAME READY STATUS RESTARTS AGE
une-fois 0/1 Completed 0 15s
echec 0/1 Error 0 15s
Succeeded
Failed

The 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:

Terminal window
kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
name: bloque
spec:
nodeSelector:
disktype: ssd
containers:
- name: nginx
image: nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb
EOF
sleep 5
kubectl get pod bloque
kubectl describe pod bloque | tail -n 5
Output
pod/bloque created
NAME READY STATUS RESTARTS AGE
bloque 0/1 Pending 0 5s
node.kubernetes.io/unreachable:NoExecute op=Exists for 300s
Events:
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:

Terminal window
kubectl delete pod web
kubectl get pods
Output
pod "web" deleted from default namespace
NAME READY STATUS RESTARTS AGE
bloque 0/1 Pending 0 5s
echec 0/1 Error 0 21s
image-fausse 0/1 ImagePullBackOff 0 86s
plante 0/1 Error 3 (51s ago) 66s
une-fois 0/1 Completed 0 21s
web-yaml 1/1 Running 0 95s

No 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 showsWhere to lookFrequent cause
ErrImagePull, ImagePullBackOffdescribe, Failed eventsImage or tag does not exist, private registry
CrashLoopBackOffexit code, logs --previousThe application ends at startup
Pendingdescribe, FailedScheduling eventNo acceptable node, insufficient resources
Init:0/1logs <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:

Terminal window
kubectl delete pod web-yaml image-fausse plante une-fois echec bloque --wait=false
kubectl get pods
Output
pod "web-yaml" deleted from default namespace
pod "image-fausse" deleted from default namespace
pod "plante" deleted from default namespace
pod "une-fois" deleted from default namespace
pod "echec" deleted from default namespace
pod "bloque" deleted from default namespace
NAME READY STATUS RESTARTS AGE
image-fausse 0/1 Terminating 0 86s
plante 0/1 Error 3 (51s ago) 66s
web-yaml 1/1 Terminating 0 95s

Put 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

  1. A Pod runs one or more containers, and Kubernetes places it, starts it and watches it.
  2. The containers of a same Pod share the network (localhost) and the volumes.
  3. To observe a Pod: get, describe (the events at the bottom), logs, then exec.
  4. The phase of a Pod is Pending, Running, Succeeded, Failed or Unknown; CrashLoopBackOff is not a phase but the waiting reason of a container that crashes.
  5. restartPolicy is Always by default; OnFailure and Never serve finite tasks.
  6. ImagePullBackOff is read in the events of describe, CrashLoopBackOff in the exit code and in logs --previous, Pending in the FailedScheduling event.
  7. An init container prepares the environment before the main containers.
  8. 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

7 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

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.