Pods

This section explains everything you need to know about Pods, the most fundamental unit in Kubernetes.

What is a Pod?

A Pod is the smallest deployable and manageable unit in Kubernetes. It represents a single instance of a running process in your cluster.

Every container you run in Kubernetes runs inside a Pod. You can think of a Pod as a wrapper around one or more containers, providing them with:

• A shared network namespace (they share the same IP and port space).

• Shared storage volumes.

• A shared lifecycle, they start, run, and terminate together.

When you deploy something on Kubernetes even a simple web server, Kubernetes doesn’t run the container directly, it creates a Pod to host it. That’s because Kubernetes manages Pods, not individual containers.

Why Kubernetes Uses Pods

You might wonder, why not run containers directly? Because containers are meant to be lightweight, single-purpose processes but in the real world, applications often need multiple supporting containers (for example, one container serving an app, another collecting logs, another proxying traffic).

Pods make this possible by grouping related containers so they can:

• Share the same network interface (localhost).

• Mount and read/write the same volumes.

• Communicate easily via the file system or localhost.

• Be scheduled together on the same node.

In short, Pods exist to simplify multi-container management and to give Kubernetes a consistent unit of scheduling and scaling.

Pod Lifecycle

A Pod goes through different phases, reported by its status:

Phase	Meaning
Pending	Pod accepted by the cluster, but containers not yet running (scheduling, image pulling, etc.).
Running	At least one container is running, and all have been created successfully.
Succeeded	All containers completed successfully and won’t restart.
Failed	All containers terminated, and at least one failed.
Unknown	The control plane can’t determine the Pod’s state (usually communication issue).

If a Pod fails, Kubernetes won’t recreate it automatically unless it’s managed by a controller like a Deployment or ReplicaSet.

Pod Structure (Anatomy of a Pod Manifest)

Every Pod definition in Kubernetes follows the same structure:

apiVersion: v1       # Kubernetes API version (v1 is used for core objects like Pods)
kind: Pod            # Tells Kubernetes this object is a Pod
metadata:            # Metadata defines the identity of the Pod
  name: my-first-pod     # Unique name within a namespace
  namespace: default     # Namespace in which Pod will run (default if omitted)
  labels:                # Key/value pairs used for identification and grouping
    app: demo-app
  annotations:           # Optional - store arbitrary metadata (e.g., version info)
    purpose: learning

spec:                 # Spec defines the desired behavior of the Pod
  restartPolicy: Always     # Controls when containers are restarted (Always, OnFailure, Never)
  containers:               # List of containers in this Pod
  - name: web-container     # Name of the container
    image: nginx:1.24       # Container image from Docker Hub
    ports:
    - containerPort: 80     # Port exposed inside the container
    resources:              # Resource requests and limits
      requests:
        cpu: "100m"         # Minimum CPU guaranteed
        memory: "128Mi"     # Minimum memory guaranteed
      limits:
        cpu: "500m"         # Max CPU allowed
        memory: "256Mi"     # Max memory allowed
    livenessProbe:          # Check container health and restart if it fails
      httpGet:
        path: /
        port: 80
      initialDelaySeconds: 10
      periodSeconds: 10
    readinessProbe:         # Check if container is ready to serve traffic
      httpGet:
        path: /
        port: 80
      initialDelaySeconds: 5
      periodSeconds: 5
    env:                    # Environment variables inside container
    - name: ENVIRONMENT
      value: "dev"
    volumeMounts:           # Mount volumes to container filesystem
    - name: shared-data
      mountPath: /usr/share/nginx/html

  volumes:                  # Define volumes used by the containers
  - name: shared-data
    emptyDir: {}            # Temporary storage, erased when Pod dies

Breaking Down the YAML

Let’s understand what’s happening here:

apiVersion - Specifies which version of the Kubernetes API to use. Pods are part of the core API group, so they use v1.

kind - Tells Kubernetes what resource this YAML definesn here it’s a Pod.

metadata - Contains identifying information:

• name: unique name of the Pod within the namespace.

• namespace: logical grouping of resources.

• labels: help you organize and query resources (e.g., Services match Pods by labels).

• annotations: metadata for humans or automation, not used for filtering.

spec - Defines the desired state of the Pod the heart of the YAML.

• restartPolicy: determines how the container behaves on exit. Common values:

  • Always (default): restarts container whenever it exits.

  • OnFailure: restarts only if it exits with a non-zero status.

  • Never: no restarts.

• containers: list of containers to run inside the Pod. Each container requires at least a name and image. You can define multiple containers (main + sidecars).

• ports: informs Kubernetes which ports the container listens on (mostly informational).

• resources: defines compute guarantees:

  • requests: scheduler uses these values to find a suitable node.

  • limits: caps how much CPU/memory the container can use.

• livenessProbe and readinessProbe: tell Kubernetes how to check if the app is healthy and ready. If liveness fails → container restarts. If readiness fails → container stays alive but is removed from load balancing.

• env: inject environment variables.

• volumeMounts and volumes: allow containers to read/write shared data. Here, emptyDir gives a temporary shared directory.

Creating a Pod Manually

Note: Setup your own multi node cluster from scratch so that you can get your hands dirty!

1. Create a YAML file

Save the previous YAML as my-first-pod.yaml.

2. Apply it to the cluster

kubectl apply -f my-first-pod.yaml

3. Check Pod status

kubectl get pods

Example output:

NAME             READY   STATUS    RESTARTS   AGE
my-first-pod     1/1     Running   0          10s

4. Describe the Pod

kubectl describe pod my-first-pod

This gives detailed information: node assignment, IP address, container restarts, and recent events (e.g., image pulling, probe results).

5. Access the container shell

kubectl exec -it my-first-pod -- /bin/bash

You’ll get an interactive shell inside the nginx container.

6. View logs

kubectl logs my-first-pod

1. When you’re done testing:

kubectl delete pod my-first-pod

1. If you want to remove all Pods in the default namespace:

kubectl delete pods --all

Pod Volumes in Detail

Pods can define volumes that are accessible by any container inside that Pod. Common use-cases include:

• Sharing data between containers.

• Storing temporary files.

• Mounting ConfigMaps or Secrets.

Example (temporary shared volume):

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

When the Pod is deleted, the data in emptyDir is lost. For persistent data, you’d use a PersistentVolumeClaim (covered separately).

Multiple Containers Inside a Pod

Sometimes, you might want to run more than one container inside the same Pod for example, a main application container and a sidecar for logging.

apiVersion: v1
kind: Pod
metadata:
  name: app-with-sidecar
spec:
  containers:
  - name: main-app
    image: nginx:1.24
    volumeMounts:
    - name: logs
      mountPath: /var/log/nginx
  - name: log-agent
    image: busybox
    command: ["sh", "-c", "tail -f /var/log/nginx/access.log"]
    volumeMounts:
    - name: logs
      mountPath: /var/log/nginx
  volumes:
  - name: logs
    emptyDir: {}

Here:

• Both containers share /var/log/nginx.

• The log agent continuously tails the log file generated by nginx.

Key Things to Remember About Pods

1. Pods are ephemeral. They can be created, destroyed, and replaced at any time. Never store persistent data inside them unless you use external volumes.

2. Each Pod gets its own IP. Containers inside a Pod share that IP and communicate via localhost.

3. Containers in a Pod share resources. They share networking and storage but run as isolated processes.

4. Controllers manage Pods. In production, Pods are almost always created and managed by higher-level controllers (e.g., Deployments).

5. Lifecycle hooks & probes are critical for reliability. They allow you to detect and recover from application failures gracefully.

The more you play with Pods, the more Kubernetes will start to feel intuitive.