Kubernetes
Beginner 15 min read Kubernetes

Pods & Containers

A Pod is the smallest deployable unit in Kubernetes: one or more containers sharing a network namespace, an IP and optional volumes. Master pod manifests, init containers, sidecars, probes and the classic pod failure states.

podcontainerinit containersidecarprobesrestartPolicyCrashLoopBackOff
Prerequisites: Kubernetes Architecture
Introduction

What is this?

A Pod is the smallest deployable unit in Kubernetes: a group of one or more containers that share a network namespace (one IP), loopback, IPC and optionally storage volumes. Containers in a pod are always co-located on the same node and can talk to each other over localhost. The pod is the unit of scheduling, scaling and lifecycle management.

Motivation

Why do you need it?

  • A Pod gives a stable identity and a shared IP to a microservice even as individual containers restart underneath it.
  • Multi-container pods enable the sidecar pattern: logging agents, proxies and watchers that extend a main container.
  • Init containers run setup tasks to completion before application containers start.
  • Probes (liveness, readiness, startup) let the platform keep restarts and traffic honest.
Think about it

Mental model

Imagine

A building with rooms sharing one street address

Think of

A Pod

Every room (container) has its own interior, but all rooms share the front door (IP), the plumbing (volumes) and the address, and they must be built on the same lot (node).

Mechanics

How it works

  • You declare a Pod manifest: containers, image, ports, probes, resource requests and limits, and volumes.
  • The scheduler binds the pod to a node; the kubelet pulls the images and starts the containers in order.
  • Containers in a pod share the network namespace, so they see localhost and share a single cluster IP.
  • The kubelet restarts containers according to restartPolicy; the default of Always is what Deployments rely on.
  • When a pod finishes or fails it is deleted and, if owned by a controller such as a Deployment, recreated by that controller.

From manifest to running pod with health checks.

kubectl apply -f pod.yaml
Scheduling
kubelet
Containers
Probes
Pod status
Reference

Key commands

kubectl run web --image=nginx:1.25 --restart=Never

Create a single Pod imperatively (the --restart=Never flag is what makes it a Pod, not a Deployment).

kubectl get pods -o wide

List pods with the node and pod IP columns.

NAME   READY   STATUS    RESTARTS   AGE   IP            NODE      NOMINATED NODE   READINESS GATES
web    1/1     Running   0          3m    10.244.0.5    minikube  <none>           <none>
kubectl describe pod web

Show detailed status, conditions and recent events for a pod.

kubectl logs web --previous

Read the logs of a crashed container instance (before the restart).

kubectl exec -it web -- /bin/sh

Open a shell inside a running container.

kubectl port-forward pod/web 8080:80

Tunnel a local port to a pod port for debugging without exposing a Service.

Hands-on

Examples

A pod with an init container, shared volume and probes

A pod with an init container, shared volume and probes
apiVersion: v1
kind: Pod
metadata:
  name: web
  labels:
    app: web
spec:
  restartPolicy: Always
  initContainers:
  - name: init
    image: busybox:1.36
    command: ["sh", "-c", "echo ready > /workdir/ready.txt"]
    volumeMounts:
    - name: workdir
      mountPath: /workdir
  containers:
  - name: nginx
    image: nginx:1.25
    ports:
    - containerPort: 80
    volumeMounts:
    - name: workdir
      mountPath: /usr/share/nginx/html
    resources:
      requests:
        cpu: 100m
        memory: 64Mi
      limits:
        memory: 128Mi
    livenessProbe:
      httpGet:
        path: /
        port: 80
  volumes:
  - name: workdir
    emptyDir: {}

The init container runs first and writes a file into the shared emptyDir volume. Only after it exits successfully does the kubelet start the nginx container, which mounts the same directory. The liveness probe restarts nginx if the HTTP endpoint stops responding, and the resource requests reserve capacity on the node.

Real world

In production

  • One microservice per pod, with sidecars for logging, metrics or mTLS proxies that share the pod lifecycle.
  • Init containers prepare data directories, run schema migrations or wait for dependencies before the app starts.
  • Readiness probes remove unhealthy pods from Service endpoints; liveness probes restart wedged containers.
  • Resource requests reserve capacity and limits protect the node from noisy neighbors.
Guidelines

Best practices

  • Run one main container per pod; add sidecars only when they must share the pod lifecycle.
  • Always set liveness and readiness probes plus resource requests and limits on production containers.
  • Treat pods as ephemeral: write durable data to volumes, never to the container filesystem.
  • Label every pod so Services and controllers can select them reliably.
Watch out

Common mistakes

  • Bundling several independent apps in one pod, forcing them to scale and restart together.
  • Running the app as root inside the container instead of a non-root user.
  • Forgetting imagePullSecrets for private registries, which causes ImagePullBackOff.
  • Misconfiguring probes so readiness failures silently remove healthy traffic.
Root cause analysis

Common issues

Error
ImagePullBackOff
Root cause

Kubernetes cannot pull the container image: wrong tag, private registry without credentials, or rate limiting.

Fix

Verify the image and tag, test the pull locally, and add imagePullSecrets for private registries.

Error
CrashLoopBackOff
Root cause

The container starts and exits repeatedly, often a missing dependency, bad config or immediate error.

Fix

Run kubectl logs <pod> --previous and kubectl describe pod <pod> to read the crash output and events.

Error
CreateContainerConfigError
Root cause

The container spec references a missing ConfigMap or Secret key, or an invalid volume name.

Fix

Inspect the pod events with kubectl describe, then create the missing object or fix the key reference.

When things break

Debugging tips

  • kubectl describe pod <name> shows events for scheduling, image pull, container start and failures.
  • kubectl logs <pod> --previous reads output from the crashed container instance.
  • kubectl exec -it <pod> -- /bin/sh lets you inspect the live container.
  • kubectl get pods --show-labels verifies that Service selectors match pod labels.
Interviews

Interview checkpoint

Practice

Hands-on lab

Run and Debug Your First Pod
25 min · beginner
In progress
Objectives
  • Create a Pod from a manifest and with kubectl run
  • Inspect pod status, IP and events
  • Exec into a running container and port-forward
  • Reproduce and diagnose a CrashLoopBackOff

Run and Debug Your First Pod

25 min · beginner

0/6 steps
0%
sandbox · Linux sandbox
$
Try these commands
Test yourself

Quick quiz

0/3
1

What is the smallest deployable unit in Kubernetes?

2

Containers inside the same Pod share an IP address and network namespace.

3

Which restartPolicy do Deployments require for their pods?

Quick reference

Cheat sheet

Pod operations
kubectl run web --image=nginx --restart=NeverCreate a single pod
kubectl get pods -o wideList pods with IP and node
kubectl describe pod NAMEStatus, conditions, events
kubectl logs NAME --previousLogs of crashed instance
kubectl exec -it NAME -- /bin/shShell into a container
kubectl port-forward pod/NAME 8080:80Local tunnel to the pod
Go deeper

Official documentation

Pods
docs
Pod Lifecycle
docs
Init Containers
docs
kubectl cheatsheet
docs