Kubernetes Pods
Learn how Kubernetes Pods work, including Pod architecture, lifecycle phases, container states, restart policies, CrashLoopBackOff, probes, init containers, sidecars and troubleshooting.
BitCodeMatrix
Kubernetes Pod Explained
Architecture, Lifecycle, States and Restart Behavior
Practical Kubernetes Guide for Developers, DevOps Engineers and Cloud Engineers
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.
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.
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.
7. Pod Lifecycle vs Container Lifecycle
Kubernetes exposes lifecycle information at more than one level. This is a common source of confusion.
8. The Five Pod Phases
The Kubernetes API defines five Pod phase values:
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.
10. Container States
Each container inside a Pod can be in one of three primary states: Waiting, Running or Terminated.
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.
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.
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
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.
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.
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
24. Commands Every Kubernetes Engineer Should Know
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.
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