How to manage pods in Podman with the REST API

The REST API became available in Podman two years ago, and it is still actively maintained with new features added with every release. This article explores how Podman's REST API helps you manage pods. I'll use the classic use case for a pod: a WordPress container and a MariaDB database container using Podman's native REST API.

[ Get the Podman basics cheat sheet. ]

What is Podman's REST API?

Podman's REST API consists of two components:

• A Docker-compatible portion called Compat API
• A native portion called Libpod API that provides access to additional features not available in Docker, including pods

I highly encourage you to use Podman's native Libpod API if possible, as it contains all the current Podman features. Generally, you should not use a compatible version except when there is a strong attachment to Docker or your project is in maintenance mode with a high cost of reimplementation for API usage.

Set up the REST API service

Follow the latest Podman REST API documentation to create the REST API service as a regular user on any Linux machine with Podman installed:

$ podman system service -t 0 &

A service created with -t 0 runs until it's canceled. You can also specify the time frame that it runs. For example, -t 100 runs the service for 100 seconds.

Manage a pod using the REST API

To manage a pod using the REST API, begin by downloading the images required. After that, create the pods.

1. Download the container images

The first step toward managing a pod using the REST API is downloading all necessary images. I use two official images from the docker.io repository to set up a pod running an isolated blog service. The images are wordpress and mariadb.

First, download the mariadb image by executing the curl command on the images pull endpoint:

$ curl -XPOST --unix-socket /run/user/${UID}/podman/podman.sock \
  -H content-type:application/json \
  http://d/v4.0.0/libpod/images/pull?reference=docker.io%2Flibrary%2Fwordpress

Next, do the same for the wordpress image:

$ curl -XPOST --unix-socket /run/user/${UID}/podman/podman.sock \
  -H content-type:application/json \
  http://d/v4.0.0/libpod/images/pull?reference=docker.io%2Flibrary%2Fmariadb

[ Free download: Advanced Linux commands cheat sheet. ]

2. Create a pod

Next, create an empty pod. I suggest creating a config file first to enable an outgoing port for the service to expose and a port for internal communication. The contents of the create.conf file will include only a small portion of the attributes available to create a pod:

{
	"portmappings": [
		{
			"container_port": 80,
			"host_port": 8080
		}
	],
	"name": "my-pod"
}

Next, create an empty pod by sending a POST request with the content-type:application/json header to the libpod/pods/create endpoint with create.conf as a configuration file:

$ curl -XPOST --unix-socket /run/user/${UID}/podman/podman.sock \
	-H content-type:application/json \
	http://d/v4.0.0/libpod/pods/create -d @create.conf

3. Create the MariaDB container

It's time to begin connecting containers to the created pod. Starting from MariaDB, create a mariadb.conf file to use with the curl command, like in the previous section:

{
    "image" : "mariadb",
    "env": {
        "MYSQL_ROOT_PASSWORD": "w0rdpr3ss",
        "MYSQL_DATABASE": "wp",
        "MYSQL_USER" : "wordpress",
        "MYSQL_PASSWORD" : "w0rdpr3ss"
    },
    "restart_policy": "always",
    "pod": "my-pod",
    "name": "mariadb"
}

The most important sections are the env field, as it contains login credentials for the MariaDB instance, and the pod field, which points to a created pod.

[ Getting started with containers? Check out this free course. Deploying containerized applications: A technical overview. ]

Create a container named mariadb in the existing pod by sending a POST request to the libpod/containers/create endpoint, with mariadb.conf as a configuration file:

$ curl -XPOST --unix-socket /run/user/${UID}/podman/podman.sock \
    -H content-type:application/json \
    http://d/v4.0.0/libpod/containers/create -d @mariadb.conf

Create the WordPress container

Similarly, create a wordpress.conf config file, which will be attached to the my-pod pod and match passwords set in the configuration of the MariaDB container:

{
    "image" : "wordpress",
    "env": {
        "WORDPRESS_DB_NAME": "wp",
        "WORDPRESS_DB_USER": "wordpress",
        "WORDPRESS_DB_PASSWORD" : "w0rdpr3ss",
        "WORDPRESS_DB_HOST" : "127.0.0.1"
    },
    "pod": "my-pod",
    "name": "wordpress"
}

Finally, to conclude the configuration, create a container named wordpress in the existing pod by sending a POST request to the libpod/containers/create endpoint, with wordpress.conf as a configuration file:

$ curl -XPOST --unix-socket /run/user/${UID}/podman/podman.sock \
    -H content-type:application/json \
    http://d/v4.0.0/libpod/containers/create -d @wordpress.conf

Inspect a pod

A very useful endpoint is libpod/pods/{name}/json. It allows you to GET the current configuration of a pod. A simplified output of the inspecting command run against my-pod shows that containers are in the configured state and the pod is in the Created state:

$ curl  --unix-socket /run/user/${UID}/podman/podman.sock \
    http://d/v4.0.0/libpod/pods/my-pod/json | jq
...
...
{
     "Id": "ef494608cee76dcf2e03d79704c5984819fafefec93bbf86c08b165213ce80f2",
     "Name": "my-pod",
     "Created": "2022-04-11T22:50:58.066046201+02:00",
     "State": "Created",
     ...
     ...
     "NumContainers": 3,
     "Containers": [
         {
             "Id": "8a886dee57899e5eabd2f9c9e9b47c7ee0ba14b7aee12db4872a51f71fad166c",
             "Name": "mariadb",
             "State": "configured"
         },
         {
             "Id": "e5a8a346863953560daa53dcbb53db7523debac96cf88481f8bc88e84aaf8141",
             "Name": "wordpress",
             "State": "configured"
         },
         {
             "Id": "e84d75413878516a16df3b96cddefafbdf2f5905f77a33851b274e00a372d406",
             "Name": "ef494608cee7-infra",
             "State": "configured"
         }
     ]
}

The third container is the infra container, which holds the namespaces associated with the pod and allows Podman to connect other containers to the pod.

[ Check out this free guide to boosting hybrid cloud security and protecting your business. ]

Start a pod

You can start the my-pod by sending a POST request to the libpod/pods/my-pod/start endpoint:

$ curl -XPOST --unix-socket /run/user/${UID}/podman/podman.sock \
    -H content-type:application/json \
    http://d/v4.0.0/libpod/pods/my-pod/start

It's not necessary to manually start the Podman system service. Systemd will start the service automatically when talking to the socket by means of socket activation.

You can inspect the WordPress application running on http://localhost:8080/ in your web browser.

Wrap up

In this blog post, I presented only a small portion of the REST command that can help configure pods. This is only a starting point for exploring more about using REST to manage pods. Pods can also be pruned, deleted, or stopped. The full list of available commands and attributes is available on the REST API webpage.