SUSE Linux Enterprise Micro 5.1

Podman Guide #

Publication Date: November 14, 2024

This guide describes Podman and containers.

Revision History: SUSE Linux Enterprise Micro Documentation

1 Introduction to containers #

Containers offer a lightweight virtualization method to run multiple virtual environments (containers) simultaneously on a single host. Unlike technologies such as Xen or KVM, where the processor simulates a complete hardware environment and a hypervisor controls virtual machines, containers provide virtualization on the operating system level, where the kernel controls the isolated containers.

Advantages of using containers #

Containers make it possible to isolate applications in self-contained units.
Containers provide near-native performance. Depending on the runtime, a container can use the host kernel directly, thus minimizing overhead.
It is possible to control network interfaces and apply resources inside containers through kernel control groups.

Limitations of containers #

Containers run on the host system's kernel, so they cannot use different kernels or different kernel versions.
Containers security depends on the host system. Containerized applications can be secured through AppArmor or SELinux profiles. Securing containers is harder than securing virtual machines, due to the larger attack surface.

2 Podman overview #

Podman is a short name for Pod Manager Tool. It is a daemonless container engine that enables you to run and deploy applications using containers and container images. Podman provides a command line interface to manage containers.

As Podman does not have a daemon, it provides integration with systemd. This makes it possible to control containers via systemd units. You can create these units for existing containers as well as generate units that can start containers if they do not exist in the system. Moreover, Podman can run systemd inside containers.

Podman enables you to organize your containers into pods. Pods share the same network interface and resources. A typical use case for organizing a group of containers into a pod is a container that runs a database and a container with a client that accesses the database. For further information about pods, refer to Section 2.1, “Pods architecture”.

2.1 Pods architecture #

A pod is a group of containers that share the same name space, ports, and network connection. Usually, containers within one pod can communicate directly with each other. Each pod contains an infrastructure container (INFRA), whose purpose is to hold the name space. INFRA also enables Podman to add other containers to the pod. Port bindings, cgroup-parent values, and kernel name spaces are all assigned to the infrastructure container. Therefore, later changes of these values are not possible.

Figure 1: Pods architecture #

Each container in a pod has its own instance of a monitoring program. The monitoring program watches the container's process and if the container dies, the monitoring program saves its exit code. The program also holds open the tty interface for the particular container. The monitoring program enables you to run containers in the detached mode when Podman exits, because this program continues to run and enables you to attach tty later.

3 Getting Podman #

In case of SLE Micro, Podman is delivered in all raw images or is installed by default if you installed your system manually from ISO. To verify that Podman is installed in your system, run the following command:

# zypper se -i podman

If Podman is not listed in the output, install it by running:

# transactional-update pkg install podman

In the Cockpit web interface, you need to start Podman as a service by clicking Start podman to access container management.

By default, Podman requires root privileges. To enable rootless mode for the current user, run the following command:

> sudo usermod --add-subuids 100000-165535 \
  --add-subgids 100000-165535 USER

Reboot the machine to enable the change. The command above defines a range of local UIDs to which the UIDs allocated to users inside the container are mapped on the host. Note that the ranges defined for different users must not overlap. It is also important that the ranges do not reuse the UID of an existing local user or group. By default, adding a user with the useradd command automatically allocates subUID and subGID ranges.

Note: Limitations of rootless containers

Running a container with Podman in rootless mode on SLE Micro may fail, because the container might need access to directories or files that require root privileges.

4 Getting container images #

To run a container, you need an image. An image includes all the dependencies needed to run an application. You can obtain images from an image registry. Available registries are defined in the /etc/containers/registries.conf configuration file. If you have a local image registry or want to use other registries, add the registries into the configuration file.

Important: No tools for building images in SLE Micro

SLE Micro does not provide tools for building custom images. Therefore, the only way to get an image is to pull it from an image registry.

The podman pull command pulls an image from an image registry. The syntax is as follows:

# podman pull [OPTIONS] SOURCE

The source can be an image without the registry name. In that case, Podman tries to pull the image from all registries configured in the /etc/containers/registries.conf file. The default image tag is latest. The default location of pulled images is /var/lib/containers/storage/overlay-images/.

To view all possible options of the podman pull command, run:

# podman pull --help

Note: Getting images using Cockpit

If you are using Cockpit, you can also pull images from an image registry in the Podman containers menu by clicking + Get new image.

Podman enables you to search for images in an image registry or a list of registries using the command:

# podman search IMAGE_NAME

5 Working with containers #

The following section covers common container management tasks. This includes creating, starting, and modifying containers.

5.1 Running containers #

After you have pulled your container image, you can create containers based on it. You can run an instance of the image using the podman run command. The command syntax is as follows:

# podman run [OPTIONS] IMAGE [CONTAINER_NAME]

IMAGE is specified in format transport:path. If transport is omitted, the default docker is used. The path can reference to a specific image registry. If omitted, Podman searches for the image in registries defined in the /etc/containers/registries.conf file. An example that runs a container called sles15 based on the sle15 image follows:

# podman run registry.opensuse.org/suse/templates/images/sle-15-sp3/base/images/suse/sle15 sles15

Below is a list of frequently used options. For a complete list of available options, run the command: podman run --help.

--detach, -d: The container will run in the background.
--env, -e=env: This option allows arbitrary environment variables that are available for the process to be launched inside of the container. If an environment variable is specified without a value, Podman will check the host environment for a value and set the variable only if it is set on the host.
--help: Prints help for the podman run command.
--hostname=name, -h: Sets the container host name that is available inside the container.
--pod=name: Runs container in an existing pod. To create a pod, prefix the pod name with new:.
--read-only: Mounts the container’s root file system as read only.
--systemd=true|false|always: Runs container in systemd mode. The default is true.

5.2 Stopping containers #

If the podman run command finished successfully, a new container has been started. You can stop the container by running:

# podman stop [OPTIONS] CONTAINER

You can specify a single container name or ID or a space-separated list of containers. The command takes the following options:

--all, -a: Stops all running containers.
--latest, -l: Instead of providing a container name, the last created container will be stopped.
--time, -t=seconds: Seconds to wait before forcibly stopping the container.

To view all possible options of the podman stop command, run the following:

# podman stop --help

5.3 Starting containers #

To start already created but stopped containers, use the podman start command. The command syntax is as follows:

# podman start [OPTIONS] CONTAINER

CONTAINER can be a container name or a container ID.

For a complete list of possible options of podman start, run the command:

# podman start --help

5.4 Committing modified containers #

You can run a new container with specific attributes that are not part of the original image. To save the container with these attributes as a new image, you can use the podman commit command:

# podman commit [OPTIONS] CONTAINER IMAGE

CONTAINER is a container name or a container ID. IMAGE is the new image name. If the image name does not start with a registry name, the value localhost is used.

5.5 Listing containers #

Podman enables you to list all running containers using the podman ps command. The generic syntax of the command is as follows:

# podman  ps [OPTIONS]

Command options can change the displayed information. For example, using the --all option will output all containers created by Podman (not only the running containers).

For a complete list of podman ps options, run:

# podman ps --help

5.6 Removing containers #

To remove one or more unused container from the host, use the podman rm command as follows:

# podman rm [OPTIONS] CONTAINER

CONTAINER can be a container name or a container ID.

The command does not remove the specified container if the container is running. To remove a running container, use the -f option.

For a complete list of podman rm options, run:

# podman rm --help

Note: Deleting all stopped containers

You can delete all stopped containers from your host with a single command:

# podman container prune

Make sure that each stopped container is intended to be removed before you run the command, otherwise you might remove containers that are still in use and were stopped only temporarily.

6 Working with pods #

Containers can be grouped into a pod. The containers in the pod then share network, pid, and IPC namespace. Pods can be managed by podman pod commands. This section provides an overview of the commands for managing pods.

6.1 Creating pods #

The command podman pod create is used to create a pod. The syntax of the command is as follows:

# podman pod create [OPTIONS]

The command outputs the pod ID. By default, the pods are created without being started. You can start a pod by running a container in the pod, or by starting the pod as described in Section 6.3, “Starting/stopping/restarting pods”.

Note: Default pod names

If you do not specify a pod name with the --name option, Podman will assign a default name for the pod.

For a complete list of possible options, run the following command:

# podman pod create --help

6.2 Listing pods #

You can list all pods by running the command:

# podman pod list

The output looks as follows:

POD ID        NAME               STATUS   CREATED       # OF CONTAINERS  INFRA ID
30fba506fecb  upbeat_mcclintock  Created  19 hours ago  1                4324f40c9651
976a83b4d88b  nervous_feynman    Running  19 hours ago  2                daa5732ecd02

As each pod includes the INFRA container, the number of containers in a pod is always larger than zero.

6.3 Starting/stopping/restarting pods #

After a pod is created, you must start it, as it is not in the state running by default. In the commands below, POD can be a pod name or a pod ID.

To start a pod, run the command:

# podman pod start [OPTIONS] POD

For a complete list of possible options, run:

# podman pod start --help

To stop a pod, use the podman pod stop as follows:

# podman pod stop POD

To restart a pod, use the podman pod restart command as follows:

# podman pod restart POD

6.4 Managing containers in a pod #

To add a new container to a pod, use the podman run command with the option --pod. A general syntax of the command follows:

# podman run [OPTIONS] --pod POD_NAME IMAGE

For details about the podman run command, refer to Section 5.1, “Running containers”.

Note: Only new containers can be added to a pod

The podman start command does not allow for starting a container in a pod if the container was not added to the pod during the container's initial running.

You cannot remove a container from a pod and keep the container running, because the container itself is removed from the host.

Other actions like start, restart, and stop can be performed on specific containers without affecting the status of the pod.

6.5 Removing pods #

There are two ways to remove pods. You can use the podman pod rm command to remove one or more pods. Alternatively, you can remove all stopped pods using the podman pod prune command.

To remove a pod or several pods, run the podman pod rm command as follows:

# podman pod rm POD

POD can be a pod name or a pod ID.

To remove all currently stopped pods, use the podman pod prune command. Make sure that all stopped pods are intended to be removed before you run the podman pod prune command, otherwise you might remove pods that are still in use.

6.6 Monitoring processes in pods #

To view all containers in all pods, use the following command:

# podman ps -a --pod

The output of the command will be similar to the following one:

CONTAINER ID  IMAGE                       COMMAND    CREATED       STATUS                 [...]
4324f40c9651  k8s.gcr.io/pause:3.2                   21 hours ago  Created
daa5732ecd02  k8s.gcr.io/pause:3.2                   22 hours ago  Up 3 hours ago
e5c8e360c54b  localhost/test:latest       /bin/bash  3 days ago    Exited (137) 3 days ago
82dad15828f7  localhost/opensuse/toolbox  /bin/bash  3 days ago    Exited (137) 3 days ago
1a23da456b6f  docker.io/i386/ubuntu       /bin/bash  4 days ago    Exited (0) 6 hours ago
df890193f651  localhost/opensuse/toolbox  /bin/bash  4 days ago    Created

The first two records are the INFRA containers of each pod, based on the k8s.gcr.io/pause:3.2 image. Other containers in the output are stand-alone containers that do not belong to any pod.