Use Podman Pods on Oracle Linux

Introduction

The inspiration behind Podman Pods originated from Kubernetes, providing a way to group containers that need to share the same network, storage, and other resources. This feature is unique to Podman.

Using a Pod allows you to manage and run multiple containers that need to work together, such as a web server and a database, in a single namespace. This means the containers inside the Pod share resources, including networking, allowing them to work together as a complete application. So let's get started.

Objectives

In this tutorial, you'll learn to:

Use Podman to create and run Pods.
Use Podman to manage Pods.
Use Podman to remove Pods.

Prerequisites

Minimum of a single Oracle Linux system
Each system should have Oracle Linux installed and configured with:
- A non-root user account with sudo access
- Access to the Internet

Deploy Oracle Linux

Note: If running in your own tenancy, read the linux-virt-labs GitHub project README.md and complete the prerequisites before deploying the lab environment.

Open a terminal on the Luna Desktop.

Clone the linux-virt-labs GitHub project.

git clone https://github.com/oracle-devrel/linux-virt-labs.git

Change into the working directory.
```
cd linux-virt-labs/ol
```

Install the required collections.

ansible-galaxy collection install -r requirements.yml

Deploy the lab environment.
```
ansible-playbook create_instance.yml -e localhost_python_interpreter="/usr/bin/python3.6" -e use_podman=true -e update_all=true -e os_version="9"
```
The free lab environment requires the extra variable local_python_interpreter, which sets ansible_python_interpreter for plays running on localhost. This variable is needed because the environment installs the RPM package for the Oracle Cloud Infrastructure SDK for Python, located under the python3.6 modules.
The default deployment shape uses the AMD CPU and Oracle Linux 8. To use an Intel CPU or Oracle Linux 9, add -e instance_shape="VM.Standard3.Flex" or -e os_version="9" to the deployment command.
Important: Wait for the playbook to run successfully and reach the pause task. At this stage of the playbook, the installation of Oracle Linux is complete, and the instances are ready. Take note of the previous play, which prints the public and private IP addresses of the nodes it deploys and any other deployment information needed while running the lab.

Confirm Podman Works

The container-tools package in Oracle Linux provides the latest versions of Podman, Buildah, Skopeo, and associated dependencies.

Open a terminal and connect via SSH to the ol-node-01 instance.
```
ssh oracle@<ip_address_of_instance>
```
Check the version of Podman.
```
podman -v
```

Confirm the Podman CLI is working.

podman run quay.io/podman/hello

Example Output:

[oracle@ol-server ~]$ podman run quay.io/podman/hello
Trying to pull quay.io/podman/hello:latest...
Getting image source signatures
Copying blob f82b04e85914 done
Copying config dbd85e09a1 done
Writing manifest to image destination
Storing signatures
!... Hello Podman World ...!

         .--"--.
       / -     - \
      / (O)   (O) \
   ~~~| -=(,Y,)=- |
    .---. /`  \   |~~
 ~/  o  o \~~~~.----. ~~
  | =(X)= |~  / (O (O) \
   ~~~~~~~  ~| =(Y_)=-  |
  ~~~~    ~~~|   U      |~~

Project:   https://github.com/containers/podman
Website:   https://podman.io
Documents: https://docs.podman.io
Twitter:   @Podman_io

Creating Pods

Create a Pod Definition

Create a Pod.
```
podman pod create --name my-pod
```
Verify the pod has been created.
```
podman pod ps
```
Example Output:
```
POD ID        NAME        STATUS      CREATED         INFRA ID      # OF CONTAINERS
0a136adcd989  my-pod      Created     36 minutes ago  81737a7384f7  1
```
Notice that it shows that a container is running. How is that possible when you have not deployed a container into the Pod?

Inspect the pod and the container.

podman pod inspect my-pod

Example Output:

[oracle@ol-node-01 ~]$ podman pod inspect my-pod
[
     {
          "Id": "0a136adcd98932097960b4bdc50323064c1b4dc27685a131f714440e46843a3c",
          "Name": "my-pod",
          "Created": "2025-08-01T13:24:03.771530284Z",
          "CreateCommand": [
               "podman",
               "pod",
               "create",
               "--name",
               "my-pod"
          ],
          "ExitPolicy": "continue",
...
...
          ],
          "NumContainers": 1,
          "Containers": [
               {
                    "Id": "81737a7384f70d9353a2e52aa30599e1469ff1853e652f3ed8fb83ccaaa7b6a5",
                    "Name": "0a136adcd989-infra",
                    "State": "running"
               },
          ],
          "LockNumber": 0
     }
]

This shows that the Pod you just created is running a container called 0a136adcd989-infra. Where did that come from? Well, every pod creates an 'infra' container. The infra container coordinates the shared kernel namespace of the pod. For more information about configuring this and other aspects of the Pod, check out the upstream documentation .

Add a Container to the Pod

Next, create and attach a container to the pod you just created.

Add a web server to the Pod.

podman run -dt  --pod my-pod --name web-server1 --expose 8080 ghcr.io/oracle/oraclelinux9-nginx:1.20

Confirm the Container started.

podman pod inspect my-pod

Example Output:

[oracle@ol-node-01 ~]$ podman pod inspect my-pod
[
     {
          "Id": "0a136adcd98932097960b4bdc50323064c1b4dc27685a131f714440e46843a3c",
          "Name": "my-pod",
          "Created": "2025-08-01T13:24:03.771530284Z",
          "CreateCommand": [
               "podman",
               "pod",
               "create",
               "--name",
               "my-pod"
          ],
          "ExitPolicy": "continue",
...
...
          ],
          "NumContainers": 2,
          "Containers": [
               {
                    "Id": "81737a7384f70d9353a2e52aa30599e1469ff1853e652f3ed8fb83ccaaa7b6a5",
                    "Name": "0a136adcd989-infra",
                    "State": "running"
               },
               {
                    "Id": "e6bcbf65bfc202ef928cc7a85616941e694888b09fec4ae65c0c39b36806e955",
                    "Name": "web-server1",
                    "State": "running"
               }
          ],
          "LockNumber": 0
     }
]

The output confirms that the container is attached to the pod.

Create a Pod and Container Together.

It is also possible to create a pod and add containers with a single command.

Create a pod with an associated contaner.
```
podman run -dt --pod new:my-nginx -p 8081:80 ghcr.io/oracle/oraclelinux9-nginx:1.20
```
This creates a new pod called 'my-nginx', deploys an Nginx container inside the pod and maps the container to port 8081 on the host.

Verify the pod has been created.

podman pod ps

Example Output:

[oracle@ol-node-01 ~]$ podman pod ps
POD ID        NAME        STATUS      CREATED             INFRA ID      # OF CONTAINERS
0161fd536cb0  my-nginx    Running     4 seconds ago       204e8250dd2f  2
3a858c0e2827  my-pod      Running     About a minute ago  97864c5a0fc5  2

List the containers currently deployed.

The output shows a list of all containers and pods on the system.

podman ps -ap

Example Output:

[oracle@ol-node-01 ~]$ podman ps -ap
CONTAINER ID  IMAGE                                    COMMAND               CREATED        STATUS                    PORTS                          NAMES                POD ID        PODNAME
38b38b25994e  quay.io/podman/hello:latest              /usr/local/bin/po...  4 minutes ago  Exited (0) 4 minutes ago                                 infallible_raman                   
97864c5a0fc5  localhost/podman-pause:5.4.0-1754069649                        4 minutes ago  Up 3 minutes                                             3a858c0e2827-infra   3a858c0e2827  my-pod
377b60ae3f0d  ghcr.io/oracle/oraclelinux9-nginx:1.20   nginx -g daemon o...  3 minutes ago  Up 3 minutes              80/tcp, 443/tcp, 8080/tcp      web-server1          3a858c0e2827  my-pod
204e8250dd2f  localhost/podman-pause:5.4.0-1754069649                        2 minutes ago  Up 2 minutes              0.0.0.0:8081->80/tcp           0161fd536cb0-infra   0161fd536cb0  my-nginx
9d231e7900a7  ghcr.io/oracle/oraclelinux9-nginx:1.20   nginx -g daemon o...  2 minutes ago  Up 2 minutes              0.0.0.0:8081->80/tcp, 443/tcp  romantic_archimedes  0161fd536cb0  my-nginx

The output confirms both pods are running a single container.

List the port mappings for the pod and associated containers.
```
podman port --all
```
Note: You can use either --all or the -a flag to list all known port mappings. This tutorial used --all for clarity.
Example Output:
```
[oracle@ol-node-01 ~]$ podman port --all
204e8250dd2f	80/tcp -> 0.0.0.0:8081
9d231e7900a7	80/tcp -> 0.0.0.0:8081
```
Confirm you can access the my-nginx pod and its Nginx container from the host.
```
curl http://localhost:8081
```
This confirms you have created a pod and deployed an Nginx container into it.

Pausing and Restarting Pods

You can temporarily suspend and restart a pod without destroying it. This suspends all the processes inside the pod, along with any containers it contains, until you restart it later.

Suspend the my-pod pod.
```
podman pod pause my-pod
```

Confirm that my-pod pod is not active.

podman pod ps

Example Output:

[oracle@ol-node-01 ~]$ podman pod ps
POD ID        NAME        STATUS      CREATED         INFRA ID      # OF CONTAINERS
0161fd536cb0  my-nginx    Running     22 minutes ago  204e8250dd2f  2
3a858c0e2827  my-pod      Paused      23 minutes ago  97864c5a0fc5  2

Notice that the pod called 'my-pod' has a 'Paused' status.

Restart the my-pod pod.
```
podman pod unpause my-pod
```

Confirm the my-pod pod is active again.

podman pod ps

Example Output:

[oracle@ol-node-01 ~]$ podman pod ps
POD ID        NAME        STATUS      CREATED         INFRA ID      # OF CONTAINERS
0161fd536cb0  my-nginx    Running     24 minutes ago  204e8250dd2f  2
3a858c0e2827  my-pod      Running     25 minutes ago  97864c5a0fc5  2

The 'my-pod' pod has a 'Running' status.

Note: Both the podman pause and the podman unpause commands provide the --all flag so you can perform the operations on all deployed pods.

Starting and Stopping Pods

You can manage (e.g., start and stop) individual containers inside the pod using the container ID or name, in the usual manner. Or you can manage all the containers within a pod collectively using these commands:

Stop the pod.
```
podman pod stop my-nginx
```

Confirm the pod stopped.

podman pod ps

Example Output:

[oracle@ol-node-01 ~]$ podman pod ps
POD ID        NAME        STATUS      CREATED         INFRA ID      # OF CONTAINERS
9ed4dc9101f9  my-nginx    Exited      2 minutes ago   85c4b9a533fe  2
2e7d4c5a2d82  my-pod      Created     10 minutes ago  7a6bc9871222  1

Notice that my-nginx pod's status shows as Exited, confirming it has stopped running.

Restart the my-nginx pod.
```
podman pod start my-nginx
```
Verify that my-nginx pod has restarted.
```
podman pod ps
```
The my-nginx pod's status shows as Running, confirming it is running again.
If you have more than one pod, the podman pod start command may help you manage them more efficiently. It can restart either all of the pods by using the --all flag, or use multiple IDs to restart multiple, specific pods. More detail is provided in the upstream documentation .
Note: You can also use the podman pod restart, which stops and then restarts any currently running pods, as well as starts any pods that are currently stopped.

Removing Pods

Finally, you will stop and remove the pod along with its contents.

Stop the pods.
```
podman pod stop my-pod my-nginx
```
Remove the pods and any containers they hold.
```
podman pod rm my-pod my-nginx
```
Confirm the pod is gone, along with any containers.
```
podman pod ps
podman ps
```
No pods or containers are currently running, confirming that the two pods and their associated containers, which you created, have been deleted.
Information: Alternatively, you can forcefully remove the pod, along with all its container, forcefully using the -f flag with this command: podman pod rm -f <pod-name>.

Next Steps

This tutorial demonstrated how to set up and use Pods with Podman. Check out the Oracle Linux Training Station for additional tutorials and content.