Podman Pod Architecture: Requirements, Minimal Design, and Operational Checks

Requirements

Before using Podman pods, identify what you need to share between containers. The primary motivation is to give a group of containers a common network, IPC, and UTS namespace while keeping storage and PID namespaces isolated. This mirrors the Kubernetes pod model and enables tight‑coupled workloads such as a sidecar logger or a proxy that must reach the application container via localhost.

Smallest Suitable Design

The minimal implementation relies on libpod to create a special "pause" container that holds the shared namespaces. All workload containers are then attached to that pause container through the CNI plugin. No extra daemon or sidecar is required; the pause container is a regular OCI container that runs a minimal program (often pause) and remains alive for the lifetime of the pod.

To create a pod and attach workloads:

# Create the pod (run as a regular user for rootless, or with sudo for rootful)
podman pod create --name mypod

# Start the pause container implicitly; then run workloads attached to the pod
podman run --pod mypod -d nginx
podman run --pod mypod -d busybox sleep 3600

The pause container gets an ID that you can see with podman ps -a. Workload containers share its network namespace.

Trust/Data Boundaries

The pod is treated as a single security context. In rootless mode, the pause container and all workloads run under the invoking user's UID, confined by user namespaces. This limits host exposure to the user's ID range. Storage remains per‑container, so each workload gets its own writable layer. IPC and UTS are shared, meaning signals and hostname changes affect all members of the pod.

Operational Checks

After starting a pod, verify that the sharing works as expected:

1. List the pod and confirm it reports a single IP address:

   podman pod ps
   

2. Enter each workload and check the interface:

   podman exec -it $(podman ps --filter name=mypod --format "{{.ID}}" | head -n1) ip a show eth0
   podman exec -it $(podman ps --filter name=mypod --format "{{.ID}}" | tail -n1) ip a show eth0
   

   Both commands should display the same IPv4/IPv6 address.
3. Test connectivity between containers using the pod's IP:

   podman exec -it  ping -c 3 
   

   Success indicates shared network namespace.
4. Confirm that pausing the pod affects all members:

   podman pod pause mypod
   podman exec -it  ping -c 2 8.8.8.8  # should fail
   podman pod unpause mypod
   

Run these steps as the same user that created the pod; no extra privileges are needed for rootless pods.

Failure Modes

If the pause container stops or crashes, the shared network namespace disappears. All workload containers instantly lose network connectivity, though they continue to run in their isolated PID and storage namespaces. The pod remains in a "stopped" state until a new pause container is created or the pod is removed.

If a workload container exits, the pod stays alive as long as the pause container is running. You can define a restart policy with --restart on the podman run command to automatically replace failed workloads.

Conditions That Would Change the Design

The current pause‑container approach would be revisited if any of the following occurs:

• Podman adopts a first‑class sidecar model where namespace sharing is handled by the runtime without an extra container.
• The OCI runtime specification adds native pod concepts, eliminating the need for a pause container.
• A new CNI plugin provides built‑in pod‑wide namespace management that does not rely on a pause container.

In such cases, the trust boundary might shift (e.g., finer‑grained per‑container security contexts) and the operational checks would need to adapt to the new primitive.

Limitations and Practical Verification

Rootless pods require a recent kernel that supports user namespace cloning and proper ID mapping. On older distributions you may see errors like "failed to allocate uid/gid range". Check your kernel version (uname -r) and ensure /proc/sys/user/max_user_namespaces is non‑zero.

SELinux labels must be homogeneous across containers in a pod; mixing types can cause AVC denials. Use podman run --security-opt label=type:container_t to enforce a uniform label or adjust local SEPolicy.

To verify that a rootless pod works without sudo, run the entire sequence as a regular user and confirm that no password prompt appears. If you are forced to use sudo, the pod is operating in rootful mode and the trust boundary shifts to the host UID 0.