Podman Tutorial - Basics for Beginners

Introduction

Podman is a container engine for running and managing OCI containers on Linux. RedHat develops it as a direct alternative to Docker, the famous container management platform that started it all.

This tutorial will help you understand how Podman works by explaining its command syntax, and providing real-life examples of how to use Podman commands.

Prerequisites

• Access to a command line/terminal window.
• Podman installed and configured (see How to Install Podman on macOS or How to Install Podman on Ubuntu).

Podman Commands

Podman has a very similar command syntax to Docker. The main podman command is followed by Podman management commands and options:

podman [command] [options]

Below is a table containing all Podman commands:

Command	Description
attach	Attach to a running container using its name or ID.
auto-update	Use the container auto-update policy to update containers.
build	Use Containerfiles instructions to build an image.
commit	Create a new image reflecting changes made to a container.
container	Manage Podman containers.
cp	Copy files/directories from a container to the local filesystem and vice versa.
create	Create a container without starting it.
diff	Display changes made to a container or an image.
events	Display podman events.
exec	Execute a process inside a running container.
export	Create a tar archive containing container’s filesystem contents.
generate	Create structured output based on a container, volume, or pod.
healthcheck	Manage container healthchecks.
history	Show image history.
image	Manage images.
images	List images available in local storage.
import	Import a filesystem image tarball.
info	Show podman system info.
init	Initialize containers.
inspect	Show container or image configuration.
kill	Kill containers.
load	Load an image available in the container archive.
login	Container registry login.
logout	Log out of a container registry.
logs	View container logs.
machine	Manage the Podman VM.
manifest	Create and manage manifest lists and image indexes.
mount	Mount the root filesystem of a container or list currently mounted containers.
network	Manage Podman networks.
pause	Pause container processes.
play	Play a container, volume, or pod.
pod	Manage Podman pods.
port	List port mappings or list a container-specific mapping for the container.
ps	List running containers.
pull	Copy an image from a registry to local storage.
push	Push an image from a local machine to a specified destination.
rename	Rename a container.
restart	Restart a container.
rm	Remove a container.
rmi	Remove an image from local storage.
run	Run a command in a container.
save	Save image to a local file.
search	Look for an image in a registry.
secret	Manipulate secrets.
start	Start a container.
stats	Display resource usage statistics.
stop	Stop a container.
system	Manage the Podman systems.
tag	Assign a name to a local image.
top	Show the processes running in a container.
unmount	Unmount root filesystem of a container.
unpause	Unpause container processes.
unshare	Launch a process in a new user namespace.
untag	Remove tags from a local image.
version	View the version information.
volume	Manage container volumes.
wait	Wait for a container to stop.

Podman Tutorial

Although Podman is primarily a container engine - it is designed to create and run OCI containers, users can also use podman commands to manage container images.

The following sections explain how to use Podman to create and manipulate images, containers, and pods.

Viewing Podman Help Manual

You can reference Podman documentation quickly using the command line. To view available podman commands in your terminal, type:

podman help

To see the full Podman manual, use the man command:

Podman Images

Image building and management in Podman is performed with Buildah, an image-building tool that uses a lower-level coreutils interface. When a user executes a podman command related to images, Podman calls Buildah to perform the action.

The following sections demonstrate some important image management commands.

Searching Images

Search registries for available images using the search command.

podman search [search-term]

Limit the number of results with the --limit option. For example, to produce three results for the "centos" search term, type:

podman search --limit 3 centos

Inspect Image

Prior to pulling a Podman image, it is good practice to inspect it. Use the podman inspect command and the system outputs image metadata, such as file size, architecture, OS, etc.

podman inspect [repository or image ID]

Use the --format option with the podman inspect command to get specific metadata. In the example below, the command returns just the image's description:

podman inspect --format=’{{.Labels.description}}’ [image ID]

Downloading Images

Pulling images from online repositories is performed using the podman pull command. The syntax is:

podman pull [registry/image]

The example illustrates pulling an image from the fedoraproject.org registry:

Running Images

Run Podman images with podman run:

podman run [image]

If the image is not locally available, Podman pulls it from an online registry and then runs it as a container.

Viewing Images

The podman images sub-command is used to list locally available images:

podman images

Use options to narrow the search results. The --filter option filters the output based on the conditions you provide. For example, the following command looks for all images containing "redhat" in the name:

podman images --filter reference=redhat

Building Custom Images

To build custom images with Podman, you need a dockerfile or containerfile. These files contain instructions the Buildah tool uses to create an image.

Building files is performed with the podman build command. For example, to create an image from a directory containing the instruction script, run the following command:

podman build .

Buildah gathers the necessary file context and builds an image.

Removing Images

The podman rmi command is used to remove images from the local storage. Before removing a Podman image, make sure that all related containers have been stopped and removed.

Remove an image by using the podman rmi command followed by the image name or ID:

podman rmi [image-name-or-id]

The output confirms the image was removed.

Podman Containers

Creating and managing containers is Podman's main function. Find some of the most common container management commands in the section below.

Running Containers

The podman run command has the same functions as docker run. The options that follow the command depend on the type of container being run. The example below illustrates running an httpd instance, using an image available in the docker.io repository:

podman run -p 8080:80/tcp docker.io/library/httpd

The command runs the container and displays its command prompt.

Exit the container prompt by pressing Ctrl + C. This command will exit the container.

Running Containers in the Background

To skip the container prompt and run the container in the background, use the following syntax:

podman run -dt -p 8080:80/tcp docker.io/library/httpd

If the container starts successfully, the output of the command displays the container's long ID.

Attaching to Containers

Enter the container with the podman attach command:

podman attach [container-name-or-id]

The example shows attaching to a running Alpine Linux container using the container ID.

Viewing Running Containers

View currently running containers with the ps command:

podman ps

The command output shows a list containing basic information about running containers.

Automatically Deleting Containers After Closing

Use the --rm option with podman run to automatically delete a container:

podman run --rm -dt -p 8080:80/tcp alpine:latest

Starting and Stopping Containers

Use start and stop commands to start and stop existing containers.

podman start [container-id]

The output shows the container ID.

podman stop [container-id]

The ID of the stopped container is shown.

Assigning Names to Containers

You can name running containers using the option --name with the podman run command. For example, to name an Alpine Linux container, use the following command:

podman run --name AlpineTest -dt -p 8080:80/tcp alpine:latest

The image below shows that podman run was successful. The podman ps command lists running Podman containers, and the name is visible in the NAMES column.

Viewing Containers Logs

Display container logs at the time of execution with the podman logs command.

podman logs [container-name-or-id]

Use the -l flag to display the logs for the newest container.

Removing Containers

To delete a Podman container, first make sure that the container has been stopped. Then, use the podman rm command followed by the container's name or ID.

podman rm [container-name-or-id]

The example below shows the removal of the AlpineTest container.

To remove a running or unusable container, add the -f option.

podman rm -f [container-name-or-id]

To remove multiple containers in one go, list the containers' IDs separated with a space:

podman rm [container-1-id container-2-id container-3-id]

Podman Pods

Pods are groups of containers that share resources. Podman pods are the feature that distinguishes Podman from Docker. The next sections illustrate some of the common pod operations in Podman.

Listing Pods

Use the command below to list all pods available on the system:

podman pod ls

The list shows pod ID, name, status, time of creation, infra ID, and the number of containers it contains.

Creating Empty Pods

Create an empty pod in Podman using the following syntax:

podman pod create

The output shows the ID of the newly created pod.

Adding Containers to Pods

To add a container to a pod, use the --pod label with docker run:

podman run [options] --pod [pod-name-or-id] [image]

In the example below, an Alpine Linux container is assigned to the pod with the ID e06ed089b454:

Creating Pods With Containers

Podman can create a container and add it to a new pod in a single podman run command. The syntax includes the --pod label:

podman run [options] --pod new:[pod-name] [image]

The example below runs a container with the alpine:latest image and adds it to a new pod named AlpineTest:

The podman pod ls command output shows the new pod with two containers.

Starting, Stopping, and Deleting Pods

Start a pod using the following command:

podman pod start [pod-name-or-id]

To stop a pod, run:

podman pod stop [pod-name-or-id]

To remove a stopped pod and its container, use:

podman pod rm [pod-name-or-id]

To stop and remove running containers and then remove the pod, use the -f option:

podman pod rm -f [pod-name-or-id]

To remove multiple stopped pods with one command, list pod IDs separated with a space:

podman pod rm -f [pod1-id pod2-id pod3-id]

Potential Podman Issues and How to Troubleshoot Them

This section lists some common Podman issues and provides solutions.

Cannot Expose Privileged Port

Podman allows non-root users to run containers. However, they are limited to forwarding only to non-privileged ports. If you attempt to forward to a privileged port as a non-root user, you receive the following error:

The solution to this issue is to choose a non-privileged port or run the command using sudo.

podman search Issues

Another common problem is the podman search command returning an empty output.

This issue usually relates to the /etc/containers/registries.conf file. Open the file in a text editor:

sudo nano /etc/containers/registries.conf

Scroll to the bottom of the file and ensure that Podman has registries to search.

If you do not have any registries listed in the file, you can add the common ones, such as RedHat, Fedora, and Docker, by using the following syntax:

unqualified-search-registries=["registry.access.redhat.com", "registry.fedoraproject.org", "docker.io"]

Save the file. The podman search list should be populated with results from the registered online registries.

Error: invalid config provided

When adding containers to a pod, the following message may appear:

Error: invalid config provided: published or exposed ports must be defined when the pod is created: network cannot be configured when it is shared with a pod

This issue occurs when you attempt to add a container with ports that were not defined on pod creation. Currently, Podman does not allow this.

Conclusion

After reading this tutorial, you learned how to use Podman commands to create and manage images, containers, and pods. For a detailed comparison between Podman and Docker, read the Podman vs Docker article.