Chapter 4: Pods
Introduces pods as groups of cooperating containers and previews managing containers and volumes within them.
After this chapter you will be able to
- Pod membership and shared resources. Explain that a pod is one or more containers working toward a common purpose, sharing namespaces and cgroups, which constrain resources.
- Infra container and shared resources. Explain that every Podman pod has an infra, or pause, container that holds its namespaces and cgroups open so other containers can join them and come and go.
- Init container startup sequence. Trace how init containers run before the primary application containers and must complete before those containers launch. Distinguish Once init containers, which run only when the pod is first created, from Always init containers, which run each time the pod starts.
- Pod-wide lifecycle management. Explain that a pod can be managed as one unit: starting it starts all its containers, and stopping it stops all its containers.
- Pod creation and inherited options. Describe creating mypod with podman pod create and explain that containers added to the pod inherit its creation options as defaults. Identify the planned roles of the myimage application container and the sidecar that updates its web content.
- Shared pod network port. Explain that -p 8080:8080 binds a port for the pod and that its containers share a network namespace and therefore the binding. State that the kernel permits only one process to listen on port 8080.
- Shared volume and SELinux relabeling. Explain that --volume ./html:/var/www/html:z mounts the html directory into the pod and automatically into every container that joins it. Describe how :z relabels the directory content so containers sharing the pod's SELinux label can share the volume.
- First container pod membership. Explain how to create the myapp container in mypod with `podman create --pod mypod` and what Podman takes from the pod’s infra container.
- Time updating sidecar setup. Describe how the time sidecar uses an executable `html/time.sh` script to update the shared `index.html` every second, and how the pod volume and `--workdir` let it run the script inside the container.
- Pod startup and inspection. Describe starting the pod with `podman pod start` and using `podman ps` to confirm that its infra, application, and update containers are running.
- Shared volume update verification. Explain that the ubi8 sidecar runs `time.sh` to change `index.html` in the shared `/var/www/html` mount, so refreshing the application at `http://localhost:8080` shows a changed date.
- Pod shutdown and verification. Explain that `podman pod stop` stops a pod and that `podman ps` can be used afterward to check that its containers have stopped.
- Pod listing command and options. Describe how to list pods with `podman pod list`, use `--ctr*` to show container information within pods, and use `--format` to change the output.
- Pod removal and verification. Describe how to remove a pod with `podman pod rm` and confirm that both the pod and its containers are gone. Explain that listing all containers with their IDs, images, and pod IDs before removal shows which containers belong to the pod.
What it builds on
- Pods (chapter 1) · The earlier introduction of pods as a Podman feature.
- Volume mount options (chapter 3) · Volume mount options.
- Using volumes with containers (chapter 3) · A host directory can be mounted into a container.
- Working with container images (chapter 2) · Container images and their names were introduced.
Section by section
Introduction
Introduces pods as groups of cooperating containers and previews managing containers and volumes within them.
- Pod membership and shared resources: Explain that a pod is one or more containers working toward a common purpose, sharing namespaces and cgroups, which constrain resources.
Why it matters: This shared setup is the basis for understanding how containers work together in a pod. - Shared pod SELinux labels: Describe how Podman gives all container processes in a pod the same SELinux labels on SELinux machines so they can work together from an SELinux point of view.
Why it matters: Shared labels are another part of how Podman enables pod members to cooperate on SELinux machines.
Key terms: pod, namespaces, cgroups, resource constraints, SELinux labels
4.1 Running pods
This section explains how Podman runs a pod through an infra container, per-container monitors, optional init and sidecar containers, and pod-wide start and stop operations.
- Infra container and shared resources: Explain that every Podman pod has an infra, or pause, container that holds its namespaces and cgroups open so other containers can join them and come and go.
Why it matters: The infra container explains how a pod remains a shared environment as its other containers change. - Per-container conmon monitoring: Describe how each container in a pod has its own conmon process, which launches the OCI runtime and monitors the container after Podman exits. Explain that conmon reports exit status and provides output for attachment and logs.
Why it matters: Conmon explains how Podman can exit yet still reconnect to and report on running containers. - Init container startup sequence: Trace how init containers run before the primary application containers and must complete before those containers launch. Distinguish Once init containers, which run only when the pod is first created, from Always init containers, which run each time the pod starts.
Why it matters: Init containers let a pod prepare something, such as a database on a volume, before its application runs. - Primary and sidecar roles: Distinguish the primary container, which runs the application, from optional sidecar containers that support it, such as by monitoring it or updating files in a shared volume.
Why it matters: These roles show how tightly coupled containers can work together as one service. - Pod-wide lifecycle management: Explain that a pod can be managed as one unit: starting it starts all its containers, and stopping it stops all its containers.
Why it matters: Pod-wide operations simplify managing containers that form one service.
Key terms: infra container, pause container, namespaces, cgroups, conmon, OCI runtime, OCI spec file, rootfs, STDOUT, STDERR
4.2 Creating a pod
This section creates a pod for an application and a planned sidecar, explaining how pod-level settings are shared by containers that join it.
- Pod creation and inherited options: Describe creating mypod with podman pod create and explain that containers added to the pod inherit its creation options as defaults. Identify the planned roles of the myimage application container and the sidecar that updates its web content.
Why it matters: Pod-level options set defaults for the containers you add next. - Shared pod network port: Explain that -p 8080:8080 binds a port for the pod and that its containers share a network namespace and therefore the binding. State that the kernel permits only one process to listen on port 8080.
Why it matters: Shared networking determines how the containers can use the pod's published port. - Shared volume and SELinux relabeling: Explain that --volume ./html:/var/www/html:z mounts the html directory into the pod and automatically into every container that joins it. Describe how :z relabels the directory content so containers sharing the pod's SELinux label can share the volume.
Why it matters: The shared mount lets the sidecar update content used by the application.
Key terms: podman pod create, mypod, myimage, sidecar container, -p 8080:8080, network namespace, port binding, --volume ./html:/var/www/html:z, :z, SELinux label
4.3 Adding a container to a pod
This section adds an application container and a time-updating sidecar to a Podman pod, showing how they share the pod’s volume and namespaces.
- First container pod membership: Explain how to create the myapp container in mypod with `podman create --pod mypod` and what Podman takes from the pod’s infra container.
Why it matters: Pod membership determines which volume mounts and namespaces the container uses. - Time updating sidecar setup: Describe how the time sidecar uses an executable `html/time.sh` script to update the shared `index.html` every second, and how the pod volume and `--workdir` let it run the script inside the container.
Why it matters: The sidecar demonstrates how two containers in a pod can work with the same files. - Different images within pods: Explain that the time sidecar can use the `ubi8` image even though myapp uses a different image, and state how Podman resolves the `ubi8` short name.
Why it matters: Containers can collaborate in one pod without being built from the same image or distribution.
Key terms: podman create, --pod mypod, infra container, volume mount, namespaces, sidecar container, html/time.sh, chmod, index.html, --workdir
4.4 Starting a pod
This section starts a pod, checks its containers, and verifies that a sidecar updates content served by the application.
- Pod startup and inspection: Describe starting the pod with `podman pod start` and using `podman ps` to confirm that its infra, application, and update containers are running.
Why it matters: Checking the running containers confirms that the whole pod—not just the web application—started. - Shared volume update verification: Explain that the ubi8 sidecar runs `time.sh` to change `index.html` in the shared `/var/www/html` mount, so refreshing the application at `http://localhost:8080` shows a changed date.
Why it matters: The changing page demonstrates how one container can update data served by another container in the pod. - Pod start selection options: Distinguish `podman pod start --all`, which starts all pods, from `--latest` or `-l`, which starts the last pod created and is unavailable on Mac and Windows.
Why it matters: These options let you choose whether to start every pod or just the most recently created one.
Key terms: podman pod start, podman ps, infra container, myapp container, update container, ubi8 sidecar container, time.sh, index.html, /var/www/html, myapp
4.5 Stopping a pod
This section shows how to stop a running pod, verify that its containers stopped, and choose options that change which pods are stopped or how long Podman waits.
- Pod shutdown and verification: Explain that `podman pod stop` stops a pod and that `podman ps` can be used afterward to check that its containers have stopped.
Why it matters: Stopping the pod is not the whole check; you also want to confirm its containers stopped. - Pod stop option meanings: Distinguish the `--all`, `--latest` (`-l`), and `--timeout` (`-t`) options: they stop all pods, stop the most recently started pod, and set the timeout for stopping containers within a pod, respectively.
Why it matters: These options let you choose the scope and timeout of a pod stop operation.
Key terms: podman pod stop, podman ps, --all, --latest, -l, --timeout, -t
4.6 Listing pods
This section shows how to list pods and adjust the information displayed.
- Pod listing command and options: Describe how to list pods with `podman pod list`, use `--ctr*` to show container information within pods, and use `--format` to change the output.
Why it matters: Listing pods lets you see what is present before cleaning up the demonstration.
Key terms: podman pod list, --ctr*, --format
4.7 Removing pods
This section shows how to remove a Podman pod, verify that its containers are gone, and choose options for removing multiple or running pods.
- Pod removal and verification: Describe how to remove a pod with `podman pod rm` and confirm that both the pod and its containers are gone. Explain that listing all containers with their IDs, images, and pod IDs before removal shows which containers belong to the pod.
Why it matters: Checking the containers as well as the pod confirms that cleanup is complete. - Pod removal options: Distinguish the `--all` and `--force` options for `podman pod rm`: `--all` removes all pods, while `--force` first stops running containers so their pods can be removed. State that without `--force`, Podman removes only non-running pods.
Why it matters: These options determine which pods can be removed and whether running containers are stopped first.
Key terms: podman pod rm, --all, --format, pod ID, --force
4.8 Summary
This summary recaps how pods group containers into applications and let those containers share namespaces, resource constraints, and pod-level options.
Where this is used later
- Filesystem isolation: SELinux (chapter 10) · The later discussion of SELinux isolation provides context for the labels mentioned here.
- Starting the container monitor: conmon (chapter 6) · The earlier description of conmon.
- (chapter intro) (chapter 8) · Running pods with Podman.
- Generating Kubernetes YAML files with Podman (chapter 8) · Creating a Podman pod.
Concepts explained in this chapter
- sidecar processA sidecar container is an additional co-located container that supports or monitors a primary container or its execution environment.
- podA pod is a group of one or more containers that share storage and network resources and a runtime specification.
- infra containerAn infra container is a pod container that keeps the pod's namespaces and cgroups open while other containers start and stop.
- conmonconmon is a lightweight C program that monitors a container, manages attached I/O streams, and reports the container's exit status.
- PodmanPodman is a daemonless container engine that runs containers and builds images, including under an unprivileged user account.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.