kubernetes

Kubernetes Pods

Learn how Kubernetes Pods work, including Pod architecture, lifecycle phases, container states, restart policies, CrashLoopBackOff, probes, init containers, sidecars and troubleshooting.

By Shubhankar Tripathi • • 5 min read

BitCodeMatrix

Kubernetes Pod Explained

Architecture, Lifecycle, States and Restart Behavior

Practical Kubernetes Guide for Developers, DevOps Engineers and Cloud Engineers


Article objective
Understand what a Kubernetes Pod actually represents, how it is created and placed on a node, how its lifecycle is reported, how container states differ from Pod phases, and why containers restart without the Pod necessarily being recreated.

Introduction

A Kubernetes Pod is the smallest deployable unit that Kubernetes can create and manage. It is not simply another name for a container. A Pod provides the execution context in which one or more containers are co-located, co-scheduled and given shared networking and storage resources.

Understanding Pods is essential because higher-level Kubernetes workload resources—such as Deployments, StatefulSets, DaemonSets and Jobs—ultimately create and manage Pods. When an application fails in production, engineers often need to answer questions such as: Was the Pod scheduled? Did the container start? Why is the container restarting? Is the application ready to receive traffic? Was the Pod replaced, or did only the container restart?

This article builds that mental model from the inside out: Pod architecture, creation flow, lifecycle phases, container states, restart policies, probes, init containers, sidecars and a practical troubleshooting workflow.

1. What Is a Kubernetes Pod?

A Pod is a group of one or more containers with shared storage and network resources, plus a specification describing how those containers should run. The containers in a Pod are always co-located and co-scheduled on the same node.

Key mental model
Think of a Pod as an application-specific logical host. A single-container Pod is the most common model. Multiple containers should generally be placed in the same Pod only when they are tightly coupled and need to share resources or lifecycle context.

A Pod can provide:

  • A shared network namespace and Pod IP. Containers in the same Pod can communicate with one another through localhost.

  • Shared volumes that multiple containers can mount.

  • A common scheduling boundary: all containers in a Pod are scheduled onto the same node.

  • A common lifecycle boundary for the Pod as a unit, while individual containers still have their own states and restart behavior.

  • An execution context for application containers, init containers and, where appropriate, sidecar containers.

2. Pod Architecture: What Exists Inside a Pod?

A useful way to understand a Pod is to separate the Kubernetes API object from the processes that actually execute on a node.

Layer

Role

Pod object

Stores desired configuration and observed status in the Kubernetes API.

Scheduler

Selects a suitable node for an unscheduled Pod.

Kubelet

Runs on the selected node and works to make the Pod's desired state match actual state.

Container runtime

Creates and manages the containers through the Kubernetes container-runtime interface.

Pod sandbox / networking

Provides the Pod execution/network context; the runtime and networking components establish the Pod sandbox and networking.

Application containers

Run the application processes defined in the Pod specification.

Volumes

Provide storage that can be mounted into one or more containers in the Pod.

3. Shared Networking Inside a Pod

All containers in a Pod share the Pod's network namespace. The Pod receives a network identity, including a Pod IP, and containers in that Pod share the network interfaces and port space.

# Example concept
Container A  ---- localhost:8080 ---->  Container B
        \________ shared Pod network namespace ________/

Because the containers share the same network namespace, two containers cannot both bind the same network port on the same address. This is one reason multi-container Pods should be used for tightly coupled processes rather than unrelated applications.

4. Shared Storage Inside a Pod

A Pod can define volumes that are mounted by multiple containers. This is commonly useful when containers need to exchange files or when a supporting container processes files produced by an application container.

volumes:
  - name: shared-data
    emptyDir: {}

containers:
  - name: app
    image: nginx:stable
    volumeMounts:
      - name: shared-data
        mountPath: /usr/share/nginx/html

  - name: helper
    image: busybox:1.36
    volumeMounts:
      - name: shared-data
        mountPath: /data

The exact storage behavior depends on the volume type. In particular, shared volume access should not be confused with durable storage: an ephemeral volume such as emptyDir has a different lifecycle from a PersistentVolume-backed volume.

5. A Minimal Pod Manifest

The following example defines a single-container Pod:

apiVersion: v1
kind: Pod
metadata:
  name: nginx-pod
spec:
  containers:
    - name: nginx
      image: nginx:stable

The manifest declares the desired state. Kubernetes stores the Pod object through the API server. Once the Pod is scheduled, the kubelet on the selected node works with the container runtime and node networking components to make the requested workload run.

6. Pod Creation Flow: From YAML to a Running Container

A simplified flow is:

  • You submit the Pod manifest to the Kubernetes API.
  • The API server validates and persists the Pod object in the cluster state.
  • If the Pod is not already assigned to a node, the scheduler evaluates it and selects a suitable node.
  • The Pod becomes bound to the selected node.
  • The kubelet on that node observes the Pod specification and begins reconciliation.
  • The node's container runtime and networking components establish the Pod execution context and create the required containers.
  • Init containers, if present, run in the required order and must complete successfully before regular application containers can start.
  • Application containers start and their individual states are reported through Pod status.
  • Readiness and other health signals influence whether the Pod is considered ready to serve traffic.
  • If a container terminates, the kubelet may restart it according to the applicable restart policy.

Important distinction
A container restart is not the same thing as creating a new Pod. The kubelet can replace a terminated container within the same Pod on the same node. A higher-level controller such as a Deployment can instead create a replacement Pod when the Pod itself is deleted or otherwise needs replacement.

7. Pod Lifecycle vs Container Lifecycle

Kubernetes exposes lifecycle information at more than one level. This is a common source of confusion.

Level

What it describes

Examples

Pod phase

High-level lifecycle phase of the Pod object.

Pending, Running, Succeeded, Failed, Unknown

Pod conditions

More specific conditions describing scheduling, initialization, container readiness and overall readiness.

PodScheduled, Initialized, ContainersReady, Ready

Container state

Current state of an individual container.

Waiting, Running, Terminated

Container termination details

Details about a terminated container.

Exit code, reason, start/finish time

kubectl display

Human-friendly output that may summarize state/reason.

CrashLoopBackOff, ImagePullBackOff


Do not equate STATUS with phase
For example, CrashLoopBackOff is commonly shown by kubectl while a container is repeatedly failing and being restarted with backoff. It is not one of the five Pod phase values.


8. The Five Pod Phases

The Kubernetes API defines five Pod phase values:

Phase

Meaning

Typical interpretation

Pending

The Pod has been accepted but one or more containers are not yet running. This can include scheduling and image-pull/setup time.

Investigate scheduling, resources, volumes, image access and initialization.

Running

The Pod has been bound to a node and all containers have been created; at least one container is still running or starting/restarting.

The Pod exists and has running container activity, but it does not automatically mean the application is ready.

Succeeded

All containers terminated successfully and will not be restarted.

Common for completed Jobs.

Failed

All containers terminated and at least one terminated with failure, according to the Pod phase rules.

Common for failed batch workloads or terminal Pod failure.

Unknown

The state of the Pod could not be obtained, typically because communication with the node could not be established.

Investigate node and kubelet/control-plane communication.


A phase is deliberately coarse-grained. For troubleshooting, you normally need Pod conditions and individual container status in addition to the phase.

9. Pod Conditions

Pod conditions provide more detail than the phase field. Current Kubernetes documentation describes lifecycle conditions such as PodScheduled, PodReadyToStartContainers, Initialized, ContainersReady and Ready.

Condition

What it tells you

PodScheduled

The Pod has been scheduled to a node.

PodReadyToStartContainers

The Pod sandbox has been created successfully and networking has been configured.

Initialized

All regular init containers have completed successfully; Pods without init containers can satisfy this condition without running init containers.

ContainersReady

All containers in the Pod are ready according to their readiness state.

Ready

The Pod is ready to serve requests and can be included in the load-balancing pool of matching Services.

10. Container States

Each container inside a Pod can be in one of three primary states: Waiting, Running or Terminated.

Container state

Meaning

Examples

Waiting

The container is not running and has not terminated; Kubernetes is performing or waiting for startup-related work.

Image pull, setup, waiting for dependencies or retrying startup.

Running

The container has started and its process is running.

Application server is executing.

Terminated

The container has finished execution or was stopped.

Exit code 0, application error, SIGTERM, OOM-related termination.


11. Waiting State: What to Investigate

The Waiting state is accompanied by a reason in container status. Useful reasons can point directly to the failure domain, but the exact reason should be inspected rather than guessed.

  • kubectl get pod nginx-pod
  • kubectl describe pod nginx-pod
  • kubectl get pod nginx-pod -o wide
  • kubectl get pod nginx-pod -o yaml

12. Running State Does Not Mean Ready

A container can be running while its application is not ready to receive traffic. This is why Kubernetes separates liveness and readiness concepts.

Mechanism

Purpose

Typical consequence

Startup probe

Determines whether a slow-starting application has completed startup.

While startup probe is active, liveness and readiness probes are not executed.

Liveness probe

Determines whether the container should be restarted because the application is unhealthy.

A failed liveness probe can cause kubelet to kill and restart the container according to restart policy.

Readiness probe

Determines whether the application is ready to receive traffic.

A Pod that is not ready is removed from matching Service endpoints.


Production rule
Use readiness to answer 'Should traffic be sent here?' and liveness to answer 'Is this container so unhealthy that restarting it is appropriate?' Do not use liveness as a substitute for readiness.


13. Terminated State and Exit Codes

When a container terminates, Kubernetes records information such as the termination reason, exit code and timestamps. This information is often the fastest path to the root cause.

kubectl get pod nginx-pod -o jsonpath='{.status.containerStatuses[*].state}'
kubectl get pod nginx-pod -o jsonpath='{.status.containerStatuses[*].lastState}'
kubectl describe pod nginx-pod

An exit code of 0 generally indicates successful process termination, while a non-zero exit code indicates an error from the process. However, the exit code alone is not enough to diagnose every failure; inspect the container logs, events and termination reason as well.

14. Restart Policy

The Pod specification has a restartPolicy that controls how kubelet handles terminated containers for the Pod's application containers and regular init containers. The supported Pod-level values are Always, OnFailure and Never. The default is Always.

restartPolicy

Behavior

Typical use

Always

Restart the container after termination.

Long-running application workloads; default for Pods.

OnFailure

Restart the container only when it terminates with a failure.

Batch-style behavior where successful completion should remain completed.

Never

Do not automatically restart the terminated container.

Workloads where a single execution attempt is desired.


Restart policy is about restarting containers within a Pod. It should not be confused with workload-controller behavior. Deployments, Jobs and other controllers have their own logic for managing Pods.

15. Container Restart vs Pod Replacement

Situation

What may happen

Application process exits inside a running Pod

Kubelet may restart the container according to restart policy.

Container repeatedly crashes

The container may be restarted with exponential backoff; kubectl may show CrashLoopBackOff.

Pod is deleted and managed by a Deployment

The Deployment controller can create a replacement Pod to maintain desired replicas.

Node fails

Pods on that node can become unavailable and are handled according to workload/controller and node-failure behavior.

Pod IP changes after replacement

A newly created Pod gets a new Pod identity and typically a new Pod IP; Services provide stable discovery instead of relying on Pod IPs.


Operational insight
If you see a restart count increasing but the Pod name and UID remain the same, you are usually looking at container restarts inside that Pod. If a controller creates a replacement Pod, the replacement has a different Pod identity.

16. Why CrashLoopBackOff Happens

CrashLoopBackOff means Kubernetes is repeatedly attempting to start a container that keeps failing, while applying an increasing delay between restart attempts. It is a symptom of repeated container failure, not a root cause.

Common root-cause categories include:

  • Application exits immediately because of a configuration or code error.
  • Required environment variables, ConfigMaps or Secrets are missing or incorrect.
  • The process starts but fails its health checks.
  • The container is terminated because it exceeds available memory and is killed.
  • The command or arguments are incorrect.
  • A required dependency is unavailable or the application is not handling startup dependencies correctly.
  • A startup probe or liveness probe is configured too aggressively.

kubectl get pod <pod-name>
kubectl describe pod <pod-name>
kubectl logs <pod-name> --previous
kubectl logs <pod-name>
kubectl get events --sort-by=.lastTimestamp

The --previous option is especially useful when the current container has already restarted and you need the logs from the previous terminated container instance.

17. Restart Backoff

When kubelet restarts a failing container, Kubernetes uses exponential backoff between restart attempts. Current Kubernetes documentation describes a sequence beginning at 10 seconds, doubling to 20 and 40 seconds, and continuing up to a 300-second (5-minute) cap. The backoff timer is reset after the container has run successfully for 10 minutes.

Why backoff exists
Without backoff, a broken process could be restarted continuously at high frequency, wasting CPU, generating logs and increasing pressure on the node and dependent systems.

18. Init Containers and Pod Startup

Init containers are specialized containers that run before the application containers. They run to completion, and each init container must complete successfully before the next init container starts.

apiVersion: v1
kind: Pod
metadata:
  name: init-demo
spec:
  initContainers:
    - name: init-config
      image: busybox:1.36
      command: ["sh", "-c", "echo preparing; sleep 2"]
  containers:
    - name: app
      image: nginx:stable

Typical uses include initialization tasks, generating files, waiting for a prerequisite, or preparing data in a shared volume. Regular init containers are not long-running application containers and do not support the same probe fields as application containers.

19. Native Sidecar Containers

Kubernetes has a stable native sidecar mechanism. A sidecar is a secondary container that runs alongside the main application container and provides supporting functionality such as logging, monitoring, security or data synchronization.

In the Kubernetes model, native sidecars are implemented as restartable entries in initContainers, using a container-level restartPolicy of Always. This lets Kubernetes control startup ordering and keep the sidecar running during the Pod lifetime.

When to use a sidecar
Use a sidecar when the supporting process is tightly coupled to the application and benefits from sharing the Pod's network namespace or volumes. Avoid placing unrelated applications in the same Pod merely because they are deployed together.

20. Pod Lifecycle: A Practical Mental Model

Kubernetes API
                        |
                        v
                  Pod specification
                        |
                        v
                    Scheduling
                        |
                        v
                    Node selected
                        |
                        v
                      Kubelet
                        |
              +----------+----------+
              |                     |
              v                     v
        Pod sandbox/network     Containers
              |                     |
              |              +------+------+
              |              |             |
              |           Init(s)       App/Sidecar
              |              |             |
              |              +------+------+
              |                     |
              +----------+----------+
                        |
                        v
                Status / Conditions
                        |
                +-------+-------+
                |               |
              Ready           Not Ready
                |
              Service traffic

This diagram is intentionally conceptual. Kubernetes contains more components and asynchronous reconciliation loops, but this model is sufficient to reason about most Pod startup and troubleshooting problems.

21. Hands-On Lab: Create and Observe a Pod

Create a Pod:

cat <<'EOF' > pod-demo.yaml
apiVersion: v1
kind: Pod
metadata:
  name: pod-demo
spec:
  containers:
    - name: web
      image: nginx:stable
      ports:
        - containerPort: 80
EOF

kubectl apply -f pod-demo.yaml

Observe the Pod:

kubectl get pod pod-demo
kubectl get pod pod-demo -o wide
kubectl describe pod pod-demo
kubectl get pod pod-demo -o yaml

Inspect container logs:

kubectl logs pod-demo
kubectl logs pod-demo --previous

Clean up:

kubectl delete pod pod-demo

22. Hands-On Lab: Reproduce CrashLoopBackOff

apiVersion: v1
kind: Pod
metadata:
  name: crash-demo
spec:
  restartPolicy: Always
  containers:
    - name: crash
      image: busybox:1.36
      command: ["sh", "-c", "echo failing; exit 1"]

Apply it and observe:

  • kubectl apply -f crash-demo.yaml
  • kubectl get pod crash-demo -w
  • kubectl describe pod crash-demo
  • kubectl logs crash-demo --previous

The container exits with a non-zero status. Because the Pod uses the default Always policy, kubelet repeatedly restarts the container. The increasing restart delay is why the workload can appear as CrashLoopBackOff in kubectl output.

23. Troubleshooting Decision Tree

Observation

First checks

Likely investigation area

Pod is Pending

kubectl describe pod; events; scheduler-related messages

Scheduling, resources, affinity/taints, volumes, image/setup dependencies

Pod is Running but not Ready

describe; readiness probe; Pod conditions

Application readiness, readiness probe, dependencies

Pod is CrashLoopBackOff

logs --previous; describe; exit code; events

Application startup, configuration, probes, memory/resource issues

Pod shows ImagePullBackOff

describe; image name; registry credentials/events

Image reference, registry access, authentication

Container is OOMKilled

describe; container termination state; resource settings

Memory consumption, limits, workload behavior

Pod is Ready but requests fail

Service endpoints, DNS, application port, network policy

Service/networking/application routing

Pod is Unknown

node status; kubelet/node connectivity

Node availability and control-plane-to-node communication

24. Commands Every Kubernetes Engineer Should Know

Command

Purpose

kubectl get pods

List Pods and their high-level status.

kubectl get pod <name> -o wide

Show Pod placement and networking-related details.

kubectl describe pod <name>

Inspect conditions, container states, events and configuration.

kubectl logs <pod>

Read current container logs.

kubectl logs <pod> --previous

Read logs from the previous terminated container instance.

kubectl get pod <name> -o yaml

Inspect the full API representation including spec and status.

kubectl get events --sort-by=.lastTimestamp

Review recent cluster events relevant to failures.

kubectl exec -it <pod> -- <command>

Run a command in a running container when appropriate.

kubectl delete pod <name>

Delete a Pod; a controller may create a replacement if it manages the Pod.

25. Common Mistakes

  • Treating a Pod as if it were permanently equivalent to a virtual machine.
  • Assuming Running means Ready.
  • Assuming CrashLoopBackOff is the actual root cause.
  • Trying to diagnose a repeated crash without checking --previous logs.
  • Putting unrelated applications into one Pod.
  • Using liveness probes to control traffic readiness.
  • Relying directly on Pod IP addresses for stable application discovery.
  • Assuming a container restart means the Pod itself was recreated.
  • Expecting a Pod to provide durable storage without choosing an appropriate storage mechanism.
  • Creating production applications as unmanaged standalone Pods when a suitable workload controller should manage them.

26. Best Practices

  • Use Deployments, StatefulSets, Jobs, DaemonSets or another appropriate workload resource for most production workloads rather than manually managing individual Pods.
  • Keep one primary application container per Pod unless multiple containers are tightly coupled and need shared resources or lifecycle context.
  • Define readiness probes for applications that should not receive traffic until they are actually ready.
  • Use liveness probes carefully; an incorrect liveness probe can cause unnecessary restarts or cascading failures.
  • Use startup probes for applications that have legitimately long startup times.
  • Set realistic CPU and memory requests and limits based on measured workload behavior.
  • Use init containers for explicit initialization tasks rather than embedding unrelated startup logic into the application container.
  • Use native sidecars when a supporting process truly belongs in the same Pod.
  • Treat Pods as replaceable and design applications to tolerate restarts.
  • Use Services for stable application discovery rather than hard-coding Pod IPs.

27. Interview Questions

What is a Kubernetes Pod?
The smallest deployable unit in Kubernetes: one or more co-located containers with shared networking/storage context and a Pod specification.

Why doesn't Kubernetes usually run one application container independently of a Pod?
Kubernetes manages Pods as the deployable unit, allowing it to provide scheduling, networking, storage and lifecycle context around containers.

Can two containers in the same Pod use the same port?
They share the same network namespace and port space, so they cannot both bind the same address/port combination.

What are the five Pod phases?
Pending, Running, Succeeded, Failed and Unknown.

What are the three primary container states?
Waiting, Running and Terminated.

Is CrashLoopBackOff a Pod phase?
No. It is a kubectl-visible status/reason associated with repeated container startup failures and backoff.

What is the difference between a container restart and a Pod replacement?
A container restart can occur within the same Pod on the same node. A Pod replacement creates a new Pod object/identity, commonly through a workload controller.

What is restartPolicy?
A Pod-level setting controlling automatic restart behavior for app containers and regular init containers: Always, OnFailure or Never.

What is the difference between readiness and liveness?
Readiness determines whether the application should receive traffic; liveness determines whether the container should be restarted because it is unhealthy.

Why is --previous useful?
It retrieves logs from the previous terminated container instance, which is often essential when the current instance has already restarted.

28. Practical Exercise

Build a small multi-container Pod in a disposable development cluster. Use a shared emptyDir volume and two containers: one that writes a timestamped file and another that reads or serves that file. Then add a readiness probe to the application container. Observe the differences between container Running state, Pod Ready condition and Service traffic.

Expected learning outcomes:

  • Explain why the containers belong in the same Pod.
  • Demonstrate localhost communication within a Pod.
  • Demonstrate shared-volume behavior.
  • Observe Pod conditions and container states.
  • Explain why a running container can still be unready.
  • Use kubectl describe and logs to diagnose behavior.

29. Summary

The Pod is the fundamental execution unit of Kubernetes. It provides a shared context for one or more tightly coupled containers, including shared networking and optional shared storage. A Pod is scheduled as a unit, while kubelet on the selected node reconciles the desired Pod specification with the actual container state.

For troubleshooting, remember the hierarchy: Pod phase is high-level, Pod conditions provide additional lifecycle detail, and container states show what each individual container is doing. A container can be restarted without recreating the Pod, and repeated failures can produce CrashLoopBackOff with exponential restart backoff. Readiness, liveness and startup probes solve different problems and should be configured according to the application's actual behavior.

Core mental model to remember
Pod = scheduling + network + storage + lifecycle context for tightly coupled containers. Container state tells you what an individual container is doing; Pod phase tells you the high-level Pod lifecycle; controllers determine how Pods are created, replaced and maintained at the workload level.


30. Suggested Next Articles

  • Kubernetes ReplicaSet Explained: How Kubernetes Maintains Pod Availability

  • Kubernetes Deployment Explained: Rolling Updates, Rollbacks and Revision History

  • Kubernetes Service Explained: ClusterIP, NodePort and LoadBalancer

  • Kubernetes DNS Explained: CoreDNS and Service Discovery

  • Kubernetes ConfigMap vs Secret

  • Kubernetes CPU and Memory Requests vs Limits

  • Kubernetes PersistentVolume, PVC and StorageClass Explained

  • Kubernetes NetworkPolicy Explained

Official References

  • Kubernetes Pods: https://kubernetes.io/docs/concepts/workloads/pods/

  • Kubernetes Pod Lifecycle: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/

  • Pod Conditions: https://kubernetes.io/docs/concepts/workloads/pods/pod-condition/

  • Liveness, Readiness and Startup Probes: https://kubernetes.io/docs/concepts/workloads/pods/probes/

  • Init Containers: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/

  • Sidecar Containers: https://kubernetes.io/docs/concepts/workloads/pods/sidecar-containers/

  • Kubernetes Networking: https://kubernetes.io/docs/concepts/services-networking/


BitCodeMatrix.com | Kubernetes Learning Series