5 Podman Pods

Podman introduces the concept of the "pod" within the context of a container runtime. This concept is borrowed from Kubernetes and isn't available in Docker.

A pod is a collection of containers that are grouped together into a single namespace so that they can share resources, such as local networking, to communicate with each other and interact. A pod can be used to group a set of services that you need to deploy a complete application.

In many ways a pod behaves in a similar way to a virtual host on which the services within each container are run. This means that each container can access the services on each other container as if they were running on the same host. Running containers in this way can remove a lot of complexity around networking and can make it easier to limit public exposure of ports that are only intended for use by services within the application itself.

Podman pods are the smallest compute units that can be created and deployed in a Kubernetes environment. These pods include an infra container so that Podman can connect with all the containers within the pod. Podman can manage the containers in the pod, such as stopping containers, without interfering with the operation of the pod itself.

By running containers within pods, it's more straightforward to set up and tear down entire application environments using atomic operations. By using pods, you can create service wrappers to automatically start a set of containers for an application at boot. See Podman Service Wrappers for more information.

Creating Pods

To create Podman pods, use the podman pod create command, or the podman run command with the --pod flag.

Create a pod with the podman pod create command. Include the --name flag to give the pod a human-readable identifier. You can also set the --hostname option if services within the pod need to use a particular hostname when connecting to each other.

Pods can be created automatically when a container is run for the first time. To do this, use the podman run command with the --pod option, and prepend the new: option to the name for the pod.

Attach containers to a pod using the podman run command with the --pod flag.

For more information on the podman pod create command, see the podman-pod-create(1) manual page.

Example 5-1 Create a pod with a name

Create a pod named mypod: 

podman pod create --name mypod

Example 5-2 Create a container and an associated pod automatically

Create a pod named mypod that includes a container that runs an NGINX web server: 

podman run --pod new:mypod --detach quay.io/libpod/alpine_nginx:latest

Example 5-3 Create and attach containers to a pod

  1. Create a pod named mypod: 

    podman pod create --name mypod

  2. Create a container using an nginx image and connect it to the pod named mypod: 

    podman run --pod mypod --detach quay.io/libpod/alpine_nginx:latest

  3. Create a second container, using an oraclelinux image and connect it to the pod named mypod: 

    podman run --pod mypod -it --rm oraclelinux:9-slim curl http://localhost:80

    The curl command is run in the second container to access the NGINX web service running on localhost on port 80 (running on the first container). The output from the curl command shows the HTML output of the NGINX server, and looks similar to: 

    podman rulez

    The containers are both running as a standard user (not root), but can use a reserved port within the pod without any port mapping required. Furthermore, the containers can both use the localhost network namespace and can access each other as if they were running on the same host. This example provides an illustration of how pods can make it easier for services running within different containers to access each other and work together without any requirement for complex networking.

Listing and Monitoring Pods

Podman contains various commands to list and monitor pods. The examples here show you a few options.

Example 5-4 List pods

List all the available and running pods using the podman pod ps or podman pod list command. For example: 

podman pod ps

Or:

podman pod list

Both commands show similar output to the following:

POD ID        NAME        STATUS      CREATED         INFRA ID      # OF CONTAINERS
d2789902abe4  oraclepod   Created     9 seconds ago   4e203a8a2f6d  1
d8e8626a058c  mypod       Running     21 seconds ago  c31228fb0310  2

Example 5-5 List the containers in a pod

Review all the containers on the system using the podman ps command. Use the --all flag to show the containers, and the --pod flag to show the pods they're associated with. 

podman ps --all --pod

You can also combine these flags using:

podman ps -ap

The output might look similar to:

CONTAINER ID  IMAGE                                             COMMAND               CREATED         STATUS         PORTS            NAMES               POD ID        PODNAME
7fefb402a3b8  localhost/podman-pause:5.4.0-1750143108                                 45 seconds ago  Up 33 seconds                   9e746bbc3f6b-infra  9e746bbc3f6b  mypod
22061372871d  container-registry.oracle.com/olcne/nginx:1.20.1  nginx -g daemon o...  32 seconds ago  Up 33 seconds  80/tcp, 443/tcp  awesome_driscoll    9e746bbc3f6b  mypod

In this example, the mypod pod is listed under PODNAME for each of the two containers, so these two containers are running in the same pod.

Example 5-6 List the containers in a named pod

Show the containers in pod named mypod: 

podman pod ps --ctr-names --filter name=mypod

The output lists the containers in the pod, and might look similar to:

POD ID        NAME        STATUS      CREATED         INFRA ID      NAMES
8f7088f859da  mypod       Running     13 minutes ago  d2bb22029ec9  8f7088f859da-infra,nginxcontainer

Example 5-7 Inspect a pod

To show the configuration information about a pod, use the podman pod inspect command. For example: 

podman pod inspect mypod

The JSON output looks similar to:

[
     {
          "Id": "d8e8626a058c4bc538f95542728e6bdc8c44fb34b960ad9b81b06e4a804c4f3e",
          "Name": "mypod",
          "Created": "2025-07-11T03:26:07.8625531Z",
          "CreateCommand": [
               "podman",
               "run",
               "-d",
               "--pod",
               "new:mypod",
               "container-registry.oracle.com/olcne/nginx:1.20.1"
          ],
          "ExitPolicy": "continue",
          "State": "Running",
          "Hostname": "",
          "CreateCgroup": true,
          "CgroupParent": "user.slice",
          "CgroupPath": "user.slice/user-1000.slice/user@1000.service/user.slice/user-libpod_pod_d8e8626a058c4bc538f95542728e6bdc8c44fb34b960ad9b81b06e4a804c4f3e.slice",
          "CreateInfra": true,
          "InfraContainerID": "c31228fb03102c049f195f07da6415eee14267b55135ce480ef5a8f4d6660bbb",
          "InfraConfig": {
               "PortBindings": {},
               "HostNetwork": false,
               "StaticIP": "",
               "StaticMAC": "",
               "NoManageResolvConf": false,
               "DNSServer": null,
               "DNSSearch": null,
               "DNSOption": null,
               "NoManageHostname": false,
               "NoManageHosts": false,
               "HostAdd": null,
               "HostsFile": "",
               "Networks": null,
               "NetworkOptions": null,
               "pid_ns": "private",
               "userns": "host",
               "uts_ns": "private"
          },
          "SharedNamespaces": [
               "ipc",
               "net",
               "uts"
          ],
          "NumContainers": 2,
          "Containers": [
               {
                    "Id": "c31228fb03102c049f195f07da6415eee14267b55135ce480ef5a8f4d6660bbb",
                    "Name": "d8e8626a058c-infra",
                    "State": "running"
               },
               {
                    "Id": "971bc0b8146584f65f0cb71d93eade808540d9a956d2a2d6c6445d33adf0abea",
                    "Name": "eager_pascal",
                    "State": "running"
               }
          ],
          "LockNumber": 0
     }
]

Example 5-8 List processes running in a pod

To list the processes running in a pod, use the podman pod top command. For example: 

podman pod top mypod

The output might look similar to:

USER        PID         PPID        %CPU        ELAPSED           TTY         TIME        COMMAND
0           1           0           0.000       15m43.454064014s  ?           0s          /catatonit -P 
root        1           0           0.000       15m42.454997215s  ?           0s          nginx: master process nginx -g daemon off; 
nginx       2           1           0.000       15m42.455054885s  ?           0s          nginx: worker process 
nginx       3           1           0.000       15m42.455123415s  ?           0s          nginx: worker process

Example 5-9 Show hardware resource usage for pods

To show resource usage for containers in pods, use the podman pod stats command. 

podman pod stats -a --no-stream

The output might look similar to:

POD           CID           NAME                CPU %       MEM USAGE/ LIMIT   MEM %       NET IO        BLOCK IO    PIDS
d8e8626a058c  c31228fb0310  d8e8626a058c-infra  0.00%       53.25kB / 16.29GB  0.00%       0B / 1.076kB  -- / --     1
d8e8626a058c  971bc0b81465  eager_pascal        0.00%       2.642MB / 16.29GB  0.02%       0B / 1.076kB  -- / --     3
d2789902abe4  4e203a8a2f6d  d2789902abe4-infra  0.00%       -- / --            0.00%       -- / --       -- / --     --

To show real time resource usage, don't include the --no-stream flag. 

podman pod stats -a

To exit the real time resource reporting, use Ctrl+C.

Pausing and Resuming Pods

Pause and resume Podman pods using the podman pod pause and podman pod unpause commands.

To temporarily halt the operation of a pod without destroying its workload, use the podman pod pause command and specify the pod name or ID.

Running the previous command freezes all the running processes inside a pod, in their current state. When you're ready for the pod to resume where it was halted, you can instruct the pod to continue with its previous operation from that point by using the podman pod unpause command with the pod name or ID.

For more information on the podman pod pause command, see the podman-pod-pause(1) manual page. For information on the podman pod unpause command, see the podman-pod-unpause(1) manual page.

Example 5-10 Pause a pod

podman pod pause mypod

Example 5-11 Unpause a pod

podman pod unpause mypod

Stopping and Starting Pods

Stop and start Podman pods using the podman pod stop and podman pod start commands.

Starting and stopping containers in a pod might affect the entire pod. However, you can use the podman pod start and podman pod stop commands to start and stop every container in a pod at the same time.

To stop a pod, use the podman pod stop command with the name or pod ID. If you need to temporarily take the server down for maintenance, you can stop every running pod by appending the --all flag to the podman pod stop command.

To start a pod, use the use the podman pod start command with the name or pod ID.

For more information on the podman pod stop command, see the podman-pod-stop(1) manual page. For information on the podman pod start command, see the podman-pod-start(1) manual page.

Example 5-12 Stop a pod

podman pod stop mypod

Example 5-13 Stop all running pods

podman pod stop --all

Example 5-14 Start a pod

podman pod start mypod

Removing Pods

Remove Podman pods using the podman pod rm command.

To delete a pod use the podman pod rm command with the pod name or ID. You can remove every running pod by appending the --all flag to the podman pod rm command.

Before you remove a pod it must be stopped. Use the podman pod stop command to stop pods.

Pods can only be removed when all the containers in the pod have been removed, except for the infra container. By default, an infra container is created for each pod, so a pod normally contains at least one container which can only be removed by removing the pod itself.

Example 5-15 Remove a pod

podman pod rm mypod

Example 5-16 Remove all running pods

podman pod rm --all