Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 78 ยท Pods

Pods

Learn what a Kubernetes Pod is, how its spec describes containers, why containers in one Pod share a network and volumes, and when to use more than one.

Every workload in Kubernetes ends up as a Pod. A Pod is the smallest thing you can deploy: a wrapper around one or more containers that always run together on the same node. Kubernetes never schedules a bare container. It schedules Pods, gives each Pod an IP address, restarts the containers inside it and cleans it up when it is done.

If you know Docker, think of a Pod as "a docker run that can start a few tightly related containers at once, with a shared network and shared folders". Most Pods hold exactly one container. The multi-container form is the exception, used when two processes must live and die together. This lesson shows the shape of a Pod manifest, what the containers in a Pod share, and how that sharing works.

There is no cluster on this site, so every manifest and kubectl command below is read-only. The runnable examples are Python stand-ins that model the rules Kubernetes applies. They are real code, but they are not Kubernetes.

What a Pod is

One or more containers Usually just one.
One node All containers land on the same machine.
One IP A single address for the whole Pod.
1 / 2

A minimal Pod manifest

Every Kubernetes object has the same four top-level parts: apiVersion, kind, metadata and spec (see YAML and the Shape of a Manifest). For a Pod, apiVersion is v1 and kind is Pod.

YAML
apiVersion: v1
kind: Pod
metadata:
  name: hello
  labels:
    app: hello
spec:
  containers:
    - name: web
      image: nginx:1.27
      ports:
        - containerPort: 80

The only required field in spec is containers, a list. Each container needs a name (unique inside the Pod) and an image. The ports entry is documentation: it does not open or publish anything, and a container listening on a port works whether or not you list it. It is still worth writing, because tools and humans read it.

You create the Pod with kubectl apply -f hello.yaml and look at it with kubectl get pod hello. A typical result looks like this (read-only example):

TEXT
NAME    READY   STATUS    RESTARTS   AGE
hello   1/1     Running   0          12s

READY 1/1 means one of one containers is ready. STATUS is a summary of the Pod state, which the next lesson explains.

Useful fields in the container spec

A container entry has many optional fields. These are the ones you will meet in almost every manifest:

Field Purpose
image The image to run, ideally with a fixed tag or a digest.
command, args Override the image's ENTRYPOINT and CMD (see Environment Variables and the Downward API).
env, envFrom Environment variables, literal or from ConfigMaps and Secrets.
ports Ports the container listens on (informational).
volumeMounts Where to mount volumes declared in the Pod's volumes.
resources CPU and memory requests and limits (Resource Requests and Limits).
livenessProbe, readinessProbe Health checks (Probes).
imagePullPolicy IfNotPresent, Always or Never.

Fields that belong to the Pod as a whole, not to one container, sit directly under spec: volumes, restartPolicy, serviceAccountName, nodeSelector, securityContext and more.

What containers in one Pod share

When the container runtime starts a Pod, it first creates a small "sandbox" that owns the network namespace. Every container in the Pod then joins that namespace. The consequences are the heart of the Pod idea:

  • One IP address. The Pod has a single address, not one per container. Other Pods reach it by that address (or, better, through a Service).
  • Shared ports. Two containers in the same Pod cannot both listen on port 8080. The second one fails to bind, exactly as if two programs ran on one machine.
  • localhost works. A sidecar can call the app at 127.0.0.1:8080 without any Service or DNS.
  • Shared volumes. A volume listed under the Pod's volumes can be mounted into several containers, so they can exchange files.

What they do not share by default is the filesystem of their images, their environment variables, and their process list (each container has its own PID namespace unless you set shareProcessNamespace: true). Resource limits are also per container.

This is a two-container Pod where a helper writes a file that the web server serves. It is read-only, because there is no cluster here:

YAML
apiVersion: v1
kind: Pod
metadata:
  name: web-with-writer
spec:
  volumes:
    - name: content
      emptyDir: {}
  containers:
    - name: web
      image: nginx:1.27
      ports:
        - containerPort: 80
      volumeMounts:
        - name: content
          mountPath: /usr/share/nginx/html
          readOnly: true
    - name: writer
      image: busybox:1.37
      command: ["sh", "-c", "while true; do date > /out/index.html; sleep 5; done"]
      volumeMounts:
        - name: content
          mountPath: /out

The emptyDir volume starts empty when the Pod starts on a node and disappears when the Pod is removed. Both containers mount it, at different paths. See Volumes for the other kinds.

A Pod as a Python object

The real implementation lives in the kubelet and the container runtime, but the rules are simple enough to model. This stand-in builds a Pod from a manifest-like dictionary and applies the sharing rules: one IP, one port table and a shared volume table. Watch what happens when a second container wants a port that is already taken.

Python A Pod with a shared network namespace

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The first Pod is healthy: both containers share the IP 10.244.1.7, only web listens on port 80, and a call to 127.0.0.1:80 from either container reaches it. The second Pod shows two classic mistakes. Both containers claim port 8080, and one mounts a volume that the Pod never declared. In a real cluster the API server catches the volume mistake when you apply the manifest, and the port clash shows up at runtime as a container that crashes with "address already in use".

Checking a Pod before you apply it

Kubernetes validates manifests when they arrive at the API server, but you can check the same rules earlier, in CI or in a pre-commit hook. The stand-in below runs several of those checks over a list of Pod manifests. It is far smaller than the real validation (which uses the full OpenAPI schema), but the habit is the same: catch cheap mistakes before a human has to read kubectl describe.

Python A tiny Pod manifest linter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Pods are disposable

A Pod is not a durable thing. If its node dies, the Pod is gone, and nothing brings back the same Pod. If you delete it, it stays deleted. Its IP address is assigned when it starts and is not kept when a replacement is created. Because of this:

  • You rarely create bare Pods in production. A Deployment (or StatefulSet, Job, DaemonSet) creates Pods for you and replaces them when they fail. See Deployments.
  • You never hard-code a Pod IP. A Service gives clients a stable name and address in front of changing Pods (Services).
  • You keep important data outside the Pod, in a PersistentVolume or a database (PersistentVolumes and Claims).

Bare Pods are still handy for learning, one-off debugging (kubectl run) and quick experiments. The handy imperative form creates a Pod without a file:

Terminal
kubectl run hello --image=nginx:1.27 --port=80
kubectl get pod hello -o wide
kubectl logs hello
kubectl exec -it hello -- sh
kubectl delete pod hello

When to put several containers in one Pod

Put containers together in a Pod only when they are a single unit: they must be scheduled on the same node, they need to talk over localhost or share files, and they scale together. Good examples are a web server and a log shipper, an app and a proxy that handles TLS, or a main container and a helper that refreshes a config file. Init Containers and Sidecars covers these patterns in detail.

A bad example is "the web app and its database in one Pod". They scale differently, fail differently and need different storage. Put them in separate workloads and connect them with a Service.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the smallest deployable unit in Kubernetes?

    Kubernetes schedules Pods, not bare containers. A Pod wraps one or more containers that run together on a single node.
  2. 2. Two containers in the same Pod both try to listen on port 8080. What happens?

    Containers in a Pod share one network namespace and one IP, so ports behave as on a single machine. The clash appears at runtime, not when you apply the manifest.
  3. 3. How can a sidecar container reach the main container's web server in the same Pod?

    Because the network namespace is shared, localhost works between containers of the same Pod. No Service or DNS entry is needed.
  4. 4. Why should you normally create a Deployment instead of a bare Pod?

    A Pod is disposable. Controllers such as Deployments keep the desired number of Pods running and replace failed ones.

Summary

  • A Pod is the smallest unit Kubernetes schedules: one or more containers on one node, with one IP.
  • The manifest has apiVersion: v1, kind: Pod, metadata and a spec whose only required field is containers.
  • Containers in a Pod share the network namespace (IP, ports, localhost) and can share volumes, but not image filesystems.
  • Pods are disposable: use Deployments and other controllers to manage them, and Services to reach them.
  • Use several containers in a Pod only for tightly coupled helpers, not for separate application tiers.

Next, see how a Pod moves through its states in Pod Lifecycle and Phases.