Image
![IT Automation ebook](/sysadmin/sites/default/files/styles/image_cta/public/2021-07/automation-expert-e-book-medium.jpg?itok=X_OfbjdH)
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. ]
Podman's REST API consists of two components:
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.
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.
To manage a pod using the REST API, begin by downloading the images required. After that, create the pods.
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. ]
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
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
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
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. ]
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.
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.
Jakub is a software engineer with a passion for Linux and system administration. He previously worked in the field of embedded systems and multi-arch solutions. He recently switched his interest to containers and orchestration. More about me