Skip to main content

Pods: The Atomic Unit

Key Takeaways for AI & Readers
  • Definition: The smallest deployable unit in Kubernetes.
  • Isolation: Containers in a Pod share the same Network (IP/Port space) and Storage.
  • Ephemeral: Pods are disposable; Kubernetes manages their lifecycle automatically.
📦

Pending

Restarts: 0

The Pod has been accepted by the cluster, but one or more container images has not been created.

0. Anatomy of a Pod​

A Pod is a logical wrap around one or more containers.

Single-Container Pod​

The most common case. "One Pod = One Container".

Multi-Container Pod (The "Sidecar" Pattern)​

A Pod can hold multiple containers that work together.

  • Shared Networking: All containers in a Pod share the same IP and localhost.
    • The Port Constraint: Since they share an IP, two containers in the same Pod cannot listen on the same port (e.g. you can't have two Nginx containers both on port 80).
    • Inter-container Talk: Container A can hit Container B at 127.0.0.1:8080.
  • Shared Storage: They can mount the same Volume to share files.

Example:

  • Main Container: A web server serving HTML files.
  • Sidecar Container: A git-sync agent that pulls the latest HTML from GitHub every minute and saves it to the shared volume.

1. The Startup Phase​

When a Pod is created, it goes through several initialization steps before your app actually runs:

  1. Pending: The Scheduler is looking for a Node with enough CPU/RAM.
  2. InitContainers: If defined, these run sequentially to completion. Use them to wait for DBs or generate config files.
  3. ContainerCreating: Docker/containerd is pulling the image and setting up the network.
  4. PostStart Hook: (Optional) Executes immediately after the container starts. Warning: There is no guarantee it runs before the container ENTRYPOINT.

2. The Termination Phase (Graceful Shutdown)​

This is the most misunderstood part of Kubernetes. When you delete a Pod (or scale down), it doesn't just "die" instantly.

The Sequence of Events:​

  1. Endpoint Removal: The API Server marks the Pod as "Terminating". It is immediately removed from all Service Endpoints. No new traffic will be sent to it.
  2. PreStop Hook: If defined, this command runs inside the container. Useful for triggering a "soft shutdown" in apps that don't handle signals well.
  3. SIGTERM: Kubernetes sends the UNIX SIGTERM signal to PID 1 in the container.
    • Your App's Job: Catch this signal! Stop accepting new requests, finish processing current ones, and exit.
  4. Grace Period: Kubernetes waits for terminationGracePeriodSeconds (default: 30s).
  5. SIGKILL: If the container is still running after the grace period, K8s sends SIGKILL (Force Kill). The process stops immediately.

Common Pitfall: Nginx/Apache might drop active connections if they receive SIGTERM and exit immediately. You often need a PreStop hook like sleep 5 to allow in-flight requests to drain while the Service update propagates.

3. Restart Policies​

Defined by spec.restartPolicy:

  • Always (Default): If the container exits (even with code 0), restart it. Good for servers.
  • OnFailure: Only restart if exit code != 0. Good for Jobs.
  • Never: Never restart. Good for one-shot pods where you want to debug the logs after failure.

5. Advanced Concepts​

Static Pods​

Most Pods are managed by the API Server. Static Pods are managed directly by the Kubelet on a specific node.

  • How: You drop a YAML file into /etc/kubernetes/manifests on the Node.
  • Use Case: The Control Plane components (etcd, apiserver, scheduler) often run as Static Pods on the Master Node. This is how the cluster "bootstraps" itself!

6. Troubleshooting: "My Pod is Stuck!"​

Stuck in Pending?​

  • Check Scheduling: kubectl describe pod <name>. Look for "Insufficient cpu" or "No node(s) matched taint".
  • Check Image: Is the image tag correct? Is it private (missing imagePullSecrets)?

Stuck in Terminating?​

  • Finalizers: Does the Pod have a finalizer (like from a PVC or storage driver) that is waiting for cleanup?
  • Node Failure: If the Kubelet on the Node is dead, the Control Plane might not know the Pod is gone, so it stays "Terminating" forever until you force delete it.

CrashLoopBackOff?​

  • Logs: kubectl logs <pod> --previous.
  • Exit Code 137: OOMKilled (Out of Memory). Increase limits!
  • Exit Code 1/255: Application error. Check config or args.

💬 Feedback & Comments

Have a question or found a bug? Leave a comment below using your GitHub account.