Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 37 ยท Pods and Volumes

Pods: Containers That Share a Network

Group containers into Podman pods that share one network namespace and localhost: create a pod, add containers, publish ports, inspect the infra container, stop and remove it.

A pod is a group of containers that run together and share some parts of their environment, most importantly the network. If you know Kubernetes, the idea is exactly the same: the smallest thing you deploy is not a single container, but a pod with one or more containers inside. Podman is named after this concept ("pod manager"), and it lets you use it on a single machine without a cluster.

Pods are useful when two programs are tightly coupled: a web application and a sidecar that collects its logs, an app and a local cache that must be reachable on localhost, or a database and an admin tool that should share one published port set. This lesson shows how to create and manage them, and what is really shared.

Create a pod and put containers in it

Terminal
podman pod create --name shop -p 8080:80

podman run -d --pod shop --name shop-web docker.io/library/nginx:alpine
podman run -d --pod shop --name shop-cache docker.io/library/redis:7-alpine

podman pod ps
podman ps --pod

Study what happened:

  1. podman pod create made an empty pod called shop, and a hidden infra container. The -p 8080:80 mapping belongs to the pod, because the network belongs to the pod.
  2. Each podman run --pod shop created a container inside the pod. Both join the pod's network, so nginx listens on port 80 of the pod and Redis on 6379 of the same address.
  3. podman pod ps lists pods with their status and number of containers. podman ps --pod adds the pod name to container listings.

Because the containers share a network namespace, they can talk to each other on localhost:

Terminal
podman exec shop-cache redis-cli -h 127.0.0.1 ping

The cache container reaches its own server on 127.0.0.1, and so would the web container with any client it had, because both live in the same network namespace. Inside an nginx configuration you could proxy to an application on 127.0.0.1:3000 without any network setup.

Published ports belong to the pod

Port publishing happens when the pod is created, and not on podman run --pod:

Terminal
podman pod create --name wrong
podman run -d --pod wrong -p 8080:80 docker.io/library/nginx:alpine   # rejected: ports cannot be set on an existing pod

If you forgot a port, you need a new pod (or you can add the mapping when you recreate the pod, for example through a Kubernetes YAML file or a Quadlet file later in the course). It follows from the sharing: all containers in a pod use the same address and port space, so two containers in one pod cannot listen on the same port. If both want port 80, put them in different pods.

What is shared

Resource Shared in a pod by default
Network namespace (IP, ports, localhost) yes
IPC namespace (shared memory, semaphores) yes
UTS namespace (hostname) yes
PID namespace no (can be shared)
File systems no: each container has its own image and layers
cgroup limits per container, plus optional pod-level parent

Choose with --share:

Terminal
podman pod create --name debug --share net,ipc,uts,pid
podman pod create --name isolated --share ""           # share nothing (rare)

Sharing the PID namespace lets a sidecar see the other containers' processes, for debugging tools such as strace or a log reader.

Here is a stand-in that mimics a pod's port space and the "same port twice" rule. It is JavaScript logic, not Podman.

JS Stand-in: a pod's shared port space

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

No output.

The infra container

Containers come and go, but the pod's network namespace must exist the whole time the pod does. Podman keeps it alive with a tiny infra container, also called the pause container, running a minimal program (catatonit in current versions, which does nothing but wait and reap zombies). It owns the namespaces; the other containers join them. You see it in podman ps -a as a container named like <podid>-infra.

Terminal
podman ps -a --pod
podman pod inspect shop
podman pod inspect --format '{{.InfraContainerID}}' shop

You rarely touch it, but it explains a few details: a pod with only the infra container is "Running" but idle; stopping a pod stops every container including the infra one; and the pod's ports are held by the infra container, which is why they must be set at creation. You can customize it with --infra-image, --infra-name, or turn it off with --infra=false (then there is no shared network and the pod is only a grouping label).

Managing the pod as a unit

Terminal
podman pod stop shop
podman pod start shop
podman pod restart shop
podman pod pause shop ; podman pod unpause shop
podman pod kill shop
podman pod top shop
podman pod stats --no-stream shop
podman pod logs shop
podman pod rm shop              # fails if containers are running
podman pod rm --force shop      # stops containers and removes everything

One command acts on all containers in the pod, and the state of the pod is derived from them: Running when at least one container is running, Exited when all have stopped, Degraded when some are running and others have exited.

An important setting is the pod's exit policy. With --exit-policy=continue (the default), a container that exits does not stop its siblings. With stop, when the last container exits, the pod stops; Kubernetes-style YAML sets this for you. Use --restart per container in the usual way, or let systemd start the whole pod.

When to use a pod, and when not to

Use a pod when containers:

  • must talk to each other over localhost;
  • should start, stop and move together;
  • need to share IPC or the PID namespace.

Use separate containers on a network (Networking chapter) when services are independent, need their own published ports, or should scale separately: for example a database and several applications. In the Kubernetes world the rule of thumb is the same: one pod per instance of an application, with sidecars only for supporting processes.

JS Stand-in: pod status from container states

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

No output.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Two containers are in the same pod. How can the web container reach the cache container?

    A pod shares one network namespace, so containers see each other on localhost.
  2. 2. Where do you declare -p 8080:80 for a pod?

    Ports belong to the pod's network namespace, so they are set when the pod is created.
  3. 3. What is the infra container for?

    A tiny pause-like process owns the shared namespaces so the pod's network persists.
  4. 4. Why can't two containers in one pod both listen on port 80?

    One namespace means one set of ports. Use separate pods for services that need the same port.
  5. 5. What status shows when some containers in a pod run and others have exited?

    Podman reports Degraded when the pod is partly running.

Summary

  • A pod is a group of containers sharing network, IPC and UTS namespaces, like a Kubernetes pod.
  • Create it with podman pod create (and publish ports there), then add containers with podman run --pod.
  • Containers in a pod talk over localhost and cannot reuse each other's ports.
  • A hidden infra container owns the namespaces; manage the whole group with podman pod start/stop/rm.
  • Use pods for tightly coupled containers; use networks for independent services.

Next: Kubernetes YAML: kube generate and kube play