Pods — The Atomic Unit¶

Overview¶

A Pod is the smallest deployable unit in Kubernetes — not a container, but a wrapper around one or more containers that share network and storage. Every Deployment, StatefulSet, Job, and DaemonSet ultimately creates Pods. Understanding Pod anatomy, lifecycle, and multi-container patterns is essential before managing replicas, Services, or storage.

This tutorial explains what Pods are, how they differ from Docker containers, when to use multi-container Pods, and how to author Pod manifests for labs — while emphasizing that Deployments manage Pods in production.

This is Tutorial 5 in Module 2: Workloads of the REBASH Academy Kubernetes series. Complete kubectl Essentials and Workflows and have a running cluster from Installing Kubernetes and kubectl. Review From Docker to Kubernetes for the Docker-to-Pod mapping. This tutorial follows our documentation standards.

Prerequisites¶

• kubectl Essentials and Workflows
• Installing Kubernetes and kubectl
• From Docker to Kubernetes
• Running Your First Container — container basics
• Running local cluster (minikube or kind) with kubectl configured

Learning Objectives¶

By the end of this tutorial, you will be able to:

• Explain what a Pod is and why Kubernetes wraps containers in Pods
• Author a Pod manifest with containers, ports, env vars, and resource requests
• Describe Pod lifecycle phases and container restart policies
• Implement sidecar and init container patterns at a basic level
• Debug Pod failures using kubectl describe, logs, and events
• Articulate why bare Pods are for labs — Deployments for production
• Map Docker run flags to Pod spec fields

Architecture Diagram¶

A Pod creates a shared execution environment: one IP address, one set of network namespaces, optional shared volumes.

flowchart TB
    subgraph POD["Pod — shared context"]
        NET["Network namespace<br/>IP: 10.244.1.15"]
        VOL["Shared volumes<br/>emptyDir / config"]

        subgraph MAIN["Primary container"]
            APP["app :8080"]
        end

        subgraph SIDE["Sidecar container"]
            LOG["log-shipper"]
        end

        subgraph INIT["Init containers<br/>run sequentially first"]
            INITC["fetch-config"]
        end
    end

    NODE["Worker Node<br/>kubelet + containerd"]
    SVC["Service selector<br/>app=web"]

    NODE --> POD
    INITC --> APP
    APP --> VOL
    LOG --> VOL
    SVC --> NET

Theory¶

What Is a Pod?¶

A Pod is a group of one or more containers with:

• Shared network namespace — one Pod IP; containers communicate via localhost
• Shared storage volumes — mount the same files (logs, config, sockets)
• Co-scheduled placement — always on the same node

The Pod is ephemeral. When it dies, it is replaced with a new Pod (new UID, often new IP). Stable identity requires higher-level controllers (Deployment, StatefulSet).

Pod vs Docker Container¶

Docker equivalent from From Docker to Kubernetes:

docker run -d --name api -e DB_HOST=db -p 3000:3000 myapi:1.2.0

Maps to a Pod spec with containers, env, and ports — but without -p on the Pod; use a Service for exposure.

Pod Manifest Structure¶

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  labels:
    app: my-app
spec:
  containers:
    - name: app
      image: myapp:1.0.0
      ports:
        - containerPort: 8080
      env:
        - name: LOG_LEVEL
          value: info
      resources:
        requests:
          memory: "64Mi"
          cpu: "100m"
        limits:
          memory: "128Mi"
          cpu: "200m"
  restartPolicy: Always

Pod Lifecycle Phases¶

Container states: Waiting (reason: ContainerCreating, ImagePullBackOff), Running, Terminated.

flowchart LR
    PEND["Pending"]
    RUN["Running"]
    SUCC["Succeeded"]
    FAIL["Failed"]

    PEND --> RUN
    RUN --> SUCC
    RUN --> FAIL
    PEND --> FAIL

Restart Policies¶

Bare Pod with restartPolicy: Always restarts on the same node — but if the node fails, the Pod is gone unless a Deployment recreates it.

Multi-Container Patterns¶

Sidecar¶

Helper container alongside main app — log shipping, proxy, config sync:

containers:
  - name: app
    image: myapp:1.0
    volumeMounts:
      - name: logs
        mountPath: /var/log/app
  - name: log-shipper
    image: fluent/fluent-bit:2.2
    volumeMounts:
      - name: logs
        mountPath: /var/log/app
volumes:
  - name: logs
    emptyDir: {}

Both containers share emptyDir volume at /var/log/app.

Init Containers¶

Run sequentially before app containers start — wait for dependencies, download assets, migrate DB schema:

initContainers:
  - name: wait-for-db
    image: busybox:1.36
    command: ['sh', '-c', 'until nc -z db 5432; do sleep 2; done']
containers:
  - name: app
    image: myapp:1.0

Init failure blocks Pod startup — kubelet retries per restart policy.

Resource Requests and Limits¶

Without requests, scheduler may overcommit nodes — worse than missing Docker --memory limits (see From Docker to Kubernetes).

CPU units: 100m = 0.1 core. Memory: 128Mi, 1Gi.

Why Not Bare Pods in Production?¶

Use bare Pods for learning, one-off debug, and Job patterns — not for stateless web apps.

Pod Networking Recap¶

• Each Pod gets a cluster-routable IP from the CNI plugin
• Containers in Pod share IP — bind to different ports on localhost
• Other Pods reach this Pod via Service ClusterIP or direct Pod IP (discouraged)
• hostNetwork: true uses node network — rare, security-sensitive

Hands-on Lab¶

Step 1 – Create a single-container Pod¶

Command:

mkdir -p ~/k8s-lab/module2/pods
cat <<'EOF' > ~/k8s-lab/module2/pods/nginx-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: nginx-pod
  labels:
    app: nginx
    tier: frontend
spec:
  containers:
    - name: nginx
      image: nginx:1.27-alpine
      ports:
        - containerPort: 80
      resources:
        requests:
          memory: "32Mi"
          cpu: "50m"
        limits:
          memory: "64Mi"
          cpu: "100m"
  restartPolicy: Never
EOF
kubectl apply -f ~/k8s-lab/module2/pods/nginx-pod.yaml
kubectl get pod nginx-pod -w
# Ctrl+C when Running

Explanation: restartPolicy: Never suits lab Pods you manage manually. Observe phase transition Pending → Running.

Expected output:

NAME        READY   STATUS    RESTARTS   AGE
nginx-pod   1/1     Running   0          15s

Step 2 – Inspect Pod details and IP¶

Command:

kubectl describe pod nginx-pod
kubectl get pod nginx-pod -o jsonpath='{.status.podIP}{"\n"}{.status.phase}{"\n"}'
kubectl exec nginx-pod -- curl -s -o /dev/null -w "%{http_code}\n" http://localhost:80

Explanation: Pod IP is reachable from other Pods in the cluster. localhost works inside the container because it shares the Pod network namespace.

Expected output:

10.244.x.x
Running
200

Step 3 – Environment variables and commands¶

Command:

cat <<'EOF' > ~/k8s-lab/module2/pods/env-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: env-demo
spec:
  containers:
    - name: shell
      image: busybox:1.36
      command: ["sh", "-c", "echo HOST=$HOST VERSION=$VERSION && sleep 3600"]
      env:
        - name: HOST
          value: rebash-lab
        - name: VERSION
          value: "1.0"
  restartPolicy: Never
EOF
kubectl apply -f ~/k8s-lab/module2/pods/env-pod.yaml
kubectl logs env-demo

Explanation: Maps Docker -e flags to env list. command overrides image entrypoint — same as Docker CMD.

Expected output:

HOST=rebash-lab VERSION=1.0

Step 4 – Init container pattern¶

Command:

cat <<'EOF' > ~/k8s-lab/module2/pods/init-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: init-demo
spec:
  initContainers:
    - name: init-myservice
      image: busybox:1.36
      command: ['sh', '-c', 'echo prepared > /work/data.txt']
      volumeMounts:
        - name: workdir
          mountPath: /work
  containers:
    - name: app
      image: busybox:1.36
      command: ['sh', '-c', 'cat /work/data.txt && sleep 3600']
      volumeMounts:
        - name: workdir
          mountPath: /work
  volumes:
    - name: workdir
      emptyDir: {}
  restartPolicy: Never
EOF
kubectl apply -f ~/k8s-lab/module2/pods/init-pod.yaml
kubectl get pod init-demo -w
kubectl logs init-demo

Explanation: Init container writes to shared emptyDir; main container reads it. Init runs to completion before app starts.

Expected output:

prepared

Step 5 – Sidecar pattern (shared volume)¶

Command:

cat <<'EOF' > ~/k8s-lab/module2/pods/sidecar-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: sidecar-demo
spec:
  containers:
    - name: writer
      image: busybox:1.36
      command: ['sh', '-c', 'while true; do date >> /var/log/app.log; sleep 5; done']
      volumeMounts:
        - name: logs
          mountPath: /var/log
    - name: reader
      image: busybox:1.36
      command: ['sh', '-c', 'tail -f /var/log/app.log']
      volumeMounts:
        - name: logs
          mountPath: /var/log
  volumes:
    - name: logs
      emptyDir: {}
  restartPolicy: Never
EOF
kubectl apply -f ~/k8s-lab/module2/pods/sidecar-pod.yaml
sleep 8
kubectl logs sidecar-demo -c reader --tail=3

Explanation: Classic sidecar: writer appends logs; reader tails the same file via shared volume — mimics log shipping without a separate daemonset.

Expected output:

Tue Jul 28 ... UTC 2026
Tue Jul 28 ... UTC 2026

Step 6 – Simulate failure and observe restart policy¶

Command:

cat <<'EOF' > ~/k8s-lab/module2/pods/crash-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: crash-demo
spec:
  containers:
    - name: flaky
      image: busybox:1.36
      command: ['sh', '-c', 'echo starting; exit 1']
  restartPolicy: OnFailure
EOF
kubectl apply -f ~/k8s-lab/module2/pods/crash-pod.yaml
sleep 5
kubectl get pod crash-demo
kubectl describe pod crash-demo | grep -A6 "Containers:" | head -10

Explanation: Container exits with code 1; OnFailure triggers kubelet restart. Compare with restartPolicy: Never where Pod stays Failed.

Expected output:

NAME         READY   STATUS   RESTARTS      AGE
crash-demo   0/1     Error    3 (30s ago)   45s

Step 7 – Clean up lab Pods¶

Command:

kubectl delete -f ~/k8s-lab/module2/pods/ --ignore-not-found
kubectl get pods

Commands & Code¶

Pod quick-debug alias¶

# Usage: kdebug my-pod
kdebug() {
  kubectl describe pod "$1"
  echo "--- logs ---"
  kubectl logs "$1" --all-containers=true --tail=30
}

Common Mistakes¶

Best Practices¶

Troubleshooting¶

Summary¶

• A Pod wraps one or more containers sharing network and volumes — the atomic unit of scheduling in Kubernetes
• Pod lifecycle phases: Pending → Running → Succeeded/Failed; container states include Waiting, Running, Terminated
• Init containers run sequentially before app containers; sidecars run alongside the main container sharing volumes
• restartPolicy controls kubelet restarts; Deployments provide replica management and self-healing across node failures
• resource requests/limits affect scheduling and cgroup enforcement — always set requests in production
• Bare Pods are for learning and Jobs; next in the track: Deployments for replicated workloads
• Continue to Deployments — Managing Replicated Pods when published in this module

Interview Questions¶

1. What is a Pod, and why does Kubernetes use Pods instead of scheduling containers directly?
2. How do containers within a Pod communicate with each other?
3. Explain the difference between init containers and sidecar containers.
4. What are Pod phases, and what does Pending indicate?
5. Compare restartPolicy values: Always, OnFailure, Never.
6. What is the purpose of resource requests vs limits?
7. Why should production apps avoid bare Pods?
8. How does a Pod get its IP address?
9. Map Docker -e, -p, and --restart to Pod spec fields.
10. What happens to Pod data when a Pod is deleted?

Related Tutorials¶

• kubectl Essentials and Workflows (previous)
• Deployments — Managing Replicated Pods (next in Module 2)
• From Docker to Kubernetes
• Installing Kubernetes and kubectl
• Kubernetes – Category Overview
• Learning Paths – DevOps Engineer

References¶

• Kubernetes – Pods
• Kubernetes – Pod Lifecycle
• Kubernetes – Init Containers
• Kubernetes – Sidecar Containers
• Kubernetes – Resource Management
• Kubernetes – Pod Networking