Container Guide

Although Docker Open Source Engine is a popular choice for working with images and containers, Podman provides a drop-in replacement for Docker that offers several advantages. While Section 14, “Podman overview” provides more information on Podman, this chapter offers a quick introduction to key concepts and a basic procedure for creating a container image and using Podman to run a container.

The basic Podman workflow is as follows:

Running a container, either on a local machine or in a cloud service, normally involves the following steps:

To run a container, you need an image. An image includes all dependencies needed to run the application. For example, the SLE BCI-Base image contains the SLE distribution with a minimal package selection.

While it is possible to create an image from scratch, few applications would work in such an empty environment. Thus, using an existing base image is more practical in most situations. A base image has no parent, meaning it is not based on another image.

Although you can use a base image for running containers, the main purpose of base images is to serve as foundations for creating custom images that can run containers with specific applications, servers, services, and so on.

Both base and custom images are available through a repository of images called a registry. Unless a registry is explicitly specified, Podman pulls images from the openSUSE and Docker Hub registry. While you can fetch a base image manually, Podman can do that automatically when building a custom image.

To build a custom image, you must create a special file called a Containerfile or Dockerfile containing building instructions. For example, a Dockerfile can contain instructions to update the system software, install the desired application, open specific network ports, run commands, etc.

You can build images not only from base images, but also on top of custom images. So you can have an image consisting of multiple layers. Please refer to Section 19, “Creating custom container images” for more information.

https://registry.suse.com is the official source of SLE Base Container Images. It contains tested, updated and certified SLE Base Container Images. All images in the SUSE Registry are regularly rebuilt to include updates and fixes. The SUSE Registry's Web user interface lists a subset of the available images: Base Container Images, Development Stack Container Images, Application Container Images, SUSE Linux Enterprise Server Images, and Releases Out of General Support. The Web UI also provides additional information for each image, including release date, support level, size, digest of the images and packages inside the image.

Docker is a system for creating and managing containers. Its core is the Docker Open Source Engine—a lightweight virtualization solution to run containers simultaneously on a single host. Docker containers can be built using Dockerfiles.

Podman stands for Pod Manager tool. It is a daemonless container engine for developing, managing and running Open Container Initiative (OCI) containers on a Linux system, and it offers a drop-in alternative for Docker. Podman is the recommended container runtime for SLES. For a general introduction to Podman, refer to Section 14, “Podman overview”.

Buildah is a utility for building OCI container images. It is a complementary tool to Podman. In fact, the podman build command uses Buildah to perform container image builds. Buildah makes it possible to build images from scratch, from existing images, and using Dockerfiles. OCI images built using the Buildah command-line tool and the underlying OCI-based technologies (for example, containers/image and containers/storage ) are portable and can therefore run in a Docker Open Source Engine environment. For information on installing and using Buildah, refer to Section 18, “Buildah overview”.

skopeo is a command-line utility for managing, inspecting and signing container images and image repositories. skopeo can be used to inspect containers and repositories on remote and local container registries. skopeo can copy container images between different storage back-ends. skopeo is part of the Basesystem Module of SUSE Linux Enterprise Server.

Helm is the Kubernetes package manager, and it is the de-facto standard for deploying containerized applications on Kubernetes clusters using charts. Helm can be used to install, update and remove containerized applications in Kubernetes environments. It can also handle the associated resources, such as configuration, storage volumes, etc. For instance, it is used for instance to deploy the RMT server (see RMT documentation for more information).

Distribution is an open-source registry implementation for storing and distributing container images using the OCI Distribution Specification. It provides a simple, secure and scalable base for building a large scale registry solution or running a simple private registry. Distribution can also mirror Docker Hub but not any other private registry.

The Open Build Service (OBS) provides free infrastructure for building and storing RPM packages including different container formats. The OBS Container Registry provides a detailed listing of all container images built by the OBS, complete with commands for pulling the images into your local environment. The OBS openSUSE container image templates can be modified to specific needs, which offers the easiest way to create your own container branch. Container images can be built with Docker tools from an existing image using a Dockerfile. Alternatively, images can be built from scratch using the KIWI NG image-building solution.

Instructions on how to build images on OBS can be found in the following blog post.

SUSE Container Images, called SLE Base Container Images (SLE BCIs) are the only official container images. They are not available at https://build.opensuse.org, and the RPMs available on the OBS are not identical to the RPMs distributed as part of SUSE Linux Enterprise Server. This means that it is not possible to build supported images at https://build.opensuse.org.

For more information about SLE BCIs, refer to Section 4, “General-purpose SLE Base Container Images”.

KIWI Next Generation (KIWI NG) is a multi-purpose tool for building images. In addition to container images, regular installation ISO images, and images for virtual machines, KIWI NG can build images that boot via PXE or Vagrant boxes. The main building block in KIWI NG is an image XML description, a directory that includes the config.xml or config.kiwi file along with scripts or configuration data. The process of creating images with KIWI NG is fully automated and does not require any user interaction. Any information required for the image creation process is provided by the primary configuration file config.xml. The image can be customized using the config.sh and images.sh scripts.

Note

It is important to distinguish between KIWI NG (currently version 9.20.9) and its unmaintained legacy versions (7.x.x or older), now called KIWI Legacy.

For information on how to install KIWI NG and use it to build images, see the KIWI NG documentation. A collection of example image descriptions can be found on the KIWI NG GitHub repository.

KIWI NG's man pages provide information on using the tool. To access the man pages, install the kiwi-man-pages package.

SLE BCIs offer a platform for creating SLES-based custom container images and containerized applications that can be distributed freely. SLE BCIs feature the same predictable enterprise lifecycle as SLES. The SLE_BCI 15 SP3 and SP4 repository (which is a subset of the SLE repository) gives SLE BCIs access to 4000 packages available for the AMD64/Intel 64, AArch64, POWER and IBM Z architectures. The packages in the repository have undergone quality assurance and security audits by SUSE. The container images are FIPS-compliant when running on a host in FIPS mode. In addition to that, SUSE can provide support for SLE BCIs through SUSE subscription plans.

SLE BCI-Base comes with the Zypper package manager and the free SLE_BCI repository. This allows you to install software available in the repository and customize the image during the build. The downside is the size of the image. It is the largest of the general-purpose SLE BCIs, so it is not always the best choice for a deployment image.

A variant of SLE BCI-Base called SLE BCI-Init comes with systemd preinstalled. The SLE BCI-Init container image can be useful in scenarios requiring systemd for managing services in a single container.

Important: Using SLE BCI-init with Docker

When using SLE BCI-init container with Docker, you must use the following arguments for systemd to work correctly in the container:

> docker run -ti --tmpfs /run -v /sys/fs/cgroup:/sys/fs/cgroup:rw --cgroupns=host registry.suse.com/bci/bci-init:latest

To correctly shut down the container, use the following command:

> docker kill -s SIGRTMIN+3 CONTAINER_ID

This is a stripped-down version of the SLE BCI-Base image. SLE BCI-Minimal comes without Zypper, but it does have the RPM package manager installed. This significantly reduces the size of the image. However, while RPM can install and remove packages, it lacks support for repositories and automated dependency resolution. The SLE BCI-Minimal image is therefore intended for creating deployment containers, and then installing the desired RPM packages inside the containers. Although you can install the required dependencies, you need to download and resolve them manually. However, this approach is not recommended as it is prone to errors.

This image is similar to SLE BCI-Minimal but without the RPM package manager. The primary use case for the image is deploying static binaries produced externally or during multi-stage builds. As there is no straightforward way to install additional dependencies inside the container image, we recommend deploying a project using the SLE BCI-Micro image only when the final build artifact bundles all dependencies and has no external runtime requirements (like Python or Ruby).

Similar to SLE BCI-Micro, the SLE BCI-BusyBox image comes with the most basic tools only. However, these tools are provided by the BusyBox project. This has the benefit of further size reduction. Furthermore, the image contains no GPLv3 licensed software. When using the image, keep in mind that there are certain differences between the BusyBox tools and the GNU Coreutils. So scripts written for a system that uses GNU Coreutils may require modification to work with BusyBox.

For your reference, the list below provides an approximate size of each SLE BCI. Keep in mind that the provided numbers are rough estimations.

All SLE Base Container Images include information such as a build time stamp and description. This information is provided in the form of labels attached to the base images, and is therefore available for derived images and containers.

Here is an example of the labels information shown by podman inspect:

podman inspect registry.suse.com/suse/sle15
    [...]
    "Labels": {
                "com.suse.bci.base.created": "2023-01-26T22:15:08.381030307Z",
                "com.suse.bci.base.description": "Image for containers based on SUSE Linux Enterprise Server 15 SP4.",
                "com.suse.bci.base.disturl": "obs://build.suse.de/SUSE:SLE-15-SP4:Update:CR/images/1477b070ae019f95b0f2c3c0dce13daf-sles15-image",
                "com.suse.bci.base.eula": "sle-bci",
                "com.suse.bci.base.image-type": "sle-bci",
                "com.suse.bci.base.lifecycle-url": "https://www.suse.com/lifecycle",
                "com.suse.bci.base.reference": "registry.suse.com/suse/sle15:15.4.27.14.31",
                "com.suse.bci.base.release-stage": "released",
                "com.suse.bci.base.source": "https://sources.suse.com/SUSE:SLE-15-SP4:Update:CR/sles15-image/1477b070ae019f95b0f2c3c0dce13daf/",
                "com.suse.bci.base.supportlevel": "l3",
                "com.suse.bci.base.title": "SLE 15 SP4 Base Container Image",
                "com.suse.bci.base.url": "https://www.suse.com/products/server/",
                "com.suse.bci.base.vendor": "SUSE LLC",
                "com.suse.bci.base.version": "15.4.27.14.31",
                "com.suse.eula": "sle-bci",
                "com.suse.image-type": "sle-bci",
                "com.suse.lifecycle-url": "https://www.suse.com/lifecycle",
                "com.suse.release-stage": "released",
                "com.suse.sle.base.created": "2023-01-26T22:15:08.381030307Z",
                "com.suse.sle.base.description": "Image for containers based on SUSE Linux Enterprise Server 15 SP4.",
                "com.suse.sle.base.disturl": "obs://build.suse.de/SUSE:SLE-15-SP4:Update:CR/images/1477b070ae019f95b0f2c3c0dce13daf-sles15-image",
                "com.suse.sle.base.eula": "sle-bci",
                "com.suse.sle.base.image-type": "sle-bci",
                "com.suse.sle.base.lifecycle-url": "https://www.suse.com/lifecycle",
                "com.suse.sle.base.reference": "registry.suse.com/suse/sle15:15.4.27.14.31",
                "com.suse.sle.base.release-stage": "released",
                "com.suse.sle.base.source": "https://sources.suse.com/SUSE:SLE-15-SP4:Update:CR/sles15-image/1477b070ae019f95b0f2c3c0dce13daf/",
                "com.suse.sle.base.supportlevel": "l3",
                "com.suse.sle.base.title": "SLE 15 SP4 Base Container Image",
                "com.suse.sle.base.url": "https://www.suse.com/products/server/",
                "com.suse.sle.base.vendor": "SUSE LLC",
                "com.suse.sle.base.version": "15.4.27.14.31",
                "com.suse.supportlevel": "l3",
                "org.openbuildservice.disturl": "obs://build.suse.de/SUSE:SLE-15-SP4:Update:CR/images/1477b070ae019f95b0f2c3c0dce13daf-sles15-image",
                "org.opencontainers.image.created": "2023-01-26T22:15:08.381030307Z",
                "org.opencontainers.image.description": "Image for containers based on SUSE Linux Enterprise Server 15 SP4.",
                "org.opencontainers.image.source": "https://sources.suse.com/SUSE:SLE-15-SP4:Update:CR/sles15-image/1477b070ae019f95b0f2c3c0dce13daf/",
                "org.opencontainers.image.title": "SLE 15 SP4 Base Container Image",
                "org.opencontainers.image.url": "https://www.suse.com/products/server/",
                "org.opencontainers.image.vendor": "SUSE LLC",
                "org.opencontainers.image.version": "15.4.27.14.31",
                "org.opensuse.reference": "registry.suse.com/suse/sle15:15.4.27.14.31"
            },
    [...]

All labels are shown twice to ensure that the information in derived images about the original base image is still visible and not overwritten.

Use Podman to retrieve labels of a local image. The following command lists all labels and only the labels information of the bci-base:15.5 image:

podman inspect -f {{.Labels | json}} registry.suse.com/bci/bci-base:15.5

It is also possible to retrieve the value of a specific label:

podman inspect -f {{ index .Labels \"com.suse.sle.base.supportlevel\" }} registry.suse.com/bci/bci-base:15.5

The preceding command retrieves the value of the com.suse.sle.base.supportlevel label.

The skopeo tool makes it possible to examine labels of an image without pulling it first. For example:

skopeo inspect -f {{.Labels | json}} docker://registry.suse.com/bci/bci-base:15.5
skopeo inspect -f {{ index .Labels \"com.suse.sle.base.supportlevel\" }} docker://registry.suse.com/bci/bci-base:15.5

The default package manager in SLES is Zypper. Similar to APT in Debian and APK in Alpine Linux, Zypper offers a command-line interface for all package management tasks. Below is a brief overview of commonly used container-related Zypper commands.

For more information on using Zypper, refer to https://documentation.suse.com/sles/html/SLES-all/cha-sw-cl.html#sec-zypper.

All the described commands use the --non-interactive flag to skip confirmations, since you cannot approve these manually during container builds. Keep in mind that you must use the flag with any command that modifies the system. Also note that --non-interactive is not a "yes to all" flag. Instead, --non-interactive confirms what is considered to be the intention of the user. For example, an installation command with the --non-interactive option fails if it needs to import new repository signing keys, as that is something that the user must verify themselves.

container-suseconnect is a plugin available in all SLE BCIs that ship with Zypper. When the plugin detects the host's SUSE Linux Enterprise Server registration credentials, it uses them to give the container access to the SUSE Linux Enterprise repositories. This includes additional modules and previous package versions that are not part of the free SLE_BCI repository. Refer to Section 13.3, “container-suseconnect” for more information on how to use the repository for SLES, openSUSE and non-SLES hosts.

The following examples demonstrate how to accomplish certain tasks in a SLE BCI compared to Debian.

SLE package naming conventions differ from Debian, Ubuntu and Alpine, and they are closer to those of Red Hat Enterprise Linux. The main difference is that development packages of libraries (that is, packages containing headers and build description files) are named PACKAGE-devel in SLE, as opposed to PACKAGE-dev in Debian and Ubuntu. When in doubt, search for the package using the following command: docker run --rm registry.suse.com/bci/bci-base:OS_VERSION zypper search PACKAGE_NAME (replace OS_VERSION with the appropriate service version number, for example: 15.3 or 15.4).

The SUSE keys are already in the RPM database of the SLE Base Container Image. This means that you do not have to import them.

However, adding external repositories to a container or container image normally requires importing the GPG key used for signing the packages. This can be done with the rpm --import KEY_URL command. This adds the key to the RPM database, and all packages from the repository can be installed afterwards.

The Containers Module can also be added with the following command:

> sudo SUSEConnect -p sle-module-containers/15.4/x86_64

container-suseconnect is a plugin available in all SLE Base Container Images that ship with Zypper. When the plugin detects the host's SUSE Linux Enterprise Server registration credentials, it uses them to give the container access the SUSE Linux Enterprise repositories. This includes additional modules providing access to all packages included in SLES.

13.3.2 Using container-suseconnect on non-SLES hosts or with Podman and Buildah #

  

You need a registered SLES system to use container-suseconnect on non-SLE hosts or with Podman and Buildah. This can be a physical machine, a virtual machine, or the SLE BCI-Base container with SUSEConnect installed and registered.

If you do not use RMT, copy /etc/zypp/credentials.d/SCCcredentials to the development machine. Otherwise, copy both the /etc/zypp/credentials.d/SCCcredentials and /etc/SUSEConnect files.

You can use the following command to obtain SCCcredentials (replace REGISTRATION_CODE with your SCC registration code)

podman run --rm registry.suse.com/suse/sle15:latest bash -c \
        "zypper -n in SUSEConnect; SUSEConnect --regcode REGISTRATION_CODE; \
         cat /etc/zypp/credentials.d/SCCcredentials"

If you are running a container based on a SLE BCI, mount SCCcredentials (and optionally /etc/SUSEConnect) in the correct destination. The following example shows how to mount SCCcredentials in the current working directory:

podman run -v /path/to/SCCcredentials:/etc/zypp/credentials.d/SCCcredentials \
        -it --pull=always registry.suse.com/bci/bci-base:latest

Do not copy the SCCcredentials and SUSEConnect files into the container image to avoid inadvertently adding them to the final image. Use secrets instead, as they are only available to a single layer and are not part of the built image. To do this, put a copy of SCCcredentials (and optionally SUSEConnect) somewhere on the file system and modify the RUN instructions that invoke Zypper as follows:

FROM registry.suse.com/bci/bci-base:latest
    
    RUN --mount=type=secret,id=SUSEConnect \
        --mount=type=secret,id=SCCcredentials \
        zypper -n in fluxbox

Buildah support mounting secrets via the --secret flag as follows:

buildah bud --layers --secret=id=SCCcredentials,src=/path/to/SCCcredentials \
        --secret=id=SUSEConnect,src=/path/to/SUSEConnect .

Note: known issue

container-suseconnect runs automatically every time you invoke Zypper. If you are not using a registered SLES host, you may see the following error message:

> zypper ref
    Refreshing service 'container-suseconnect-zypp'.
    Problem retrieving the repository index file for service 'container-suseconnect-zypp':
    [container-suseconnect-zypp|file:/usr/lib/zypp/plugins/services/container-suseconnect-zypp]
    Warning: Skipping service 'container-suseconnect-zypp' because of the above error.

Ignore the message, as it simply indicates that container-suseconnect was not able to retrieve your SUSE Customer Center credentials, and thus could not add the full SLE repositories. You still have full access to the SLE_BCI repository, and can continue using the container as intended.

FROM registry.suse.com/bci/bci-base:latest
    ENV ADDITIONAL_MODULES sle-module-desktop-applications,sle-module-development-tools
    
    RUN --mount=type=secret,id=SCCcredentials zypper -n in fluxbox && zypper -n clean

To install Podman, make sure you have the SLE Containers Module enabled (see Section 13, “Registration and online repositories”), run the command sudo zypper in podman. Then run podman info to check whether Podman has been installed successfully.

By default, Podman launches containers as the current user. For unprivileged users, this means launching containers in rootless mode. Support for rootless containers is enabled for all newly created users in SLE by default, and no additional steps are necessary.

In case Podman fails to launch containers in rootless mode, check whether an entry for the current user is present in /etc/subuid:

> grep $(id -nu) /etc/subuid
    user:10000:65536

When no entry is found, add the required sub-UID and sub-GID entries via the following command:

> sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $(id -nu)

To enable the change, reboot the machine or stop the session of the current user. To do the latter, run loginctl list-sessions | grep USER and note the session ID. Then run loginctl kill-session SESSION_ID to stop the session.

The usermod 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 on SUSE Linux Enterprise automatically allocates sub-UID and sub-GID ranges.

When using rootless containers with Podman, it is recommended to use cgroups v2. cgroups v1 are limited in terms of functionality compared to v2. For example, cgroups v1 do not allow proper hierarchical delegation to the user's subtrees. Additionally, Podman is unable to read container logs properly with cgroups v1 and the systemd log driver. To enable cgroups v2, add the following to the kernel cmdline: systemd.unified_cgroup_hierarchy=1

Running a container with Podman in rootless mode on SUSE Linux Enterprise Server may fail, because the container needs read access to the SUSE Customer Center credentials. For example, running a container with the command podman run -it --rm registry.suse.com/suse/sle15 bash and then executing zypper ref results in the following error message:

Refreshing service 'container-suseconnect-zypp'.
    Problem retrieving the repository index file for service 'container-suseconnect-zypp':
    [container-suseconnect-zypp|file:/usr/lib/zypp/plugins/services/container-suseconnect-zypp]
    Warning: Skipping service 'container-suseconnect-zypp' because of the above error.
    Warning: There are no enabled repositories defined.
    Use 'zypper addrepo' or 'zypper modifyrepo' commands to add or enable repositories

To solve the problem, grant the current user the required access rights by running the following command on the host:

> sudo setfacl -m u:$(id -nu):r /etc/zypp/credentials.d/*

Log out and log in again to apply the changes.

To give multiple users the required access, create a dedicated group using the groupadd GROUPNAME command. Then use the following command to change the group ownership and rights of files in the /etc/zypp/credentials.d/ directory.

> sudo chgrp GROUPNAME /etc/zypp/credentials.d/*
      > sudo chmod g+r /etc/zypp/credentials.d/*

You can then grant a specific user write access by adding them to the created group.

> podman run --rm -it registry.suse.com/bci/bci-base id
    uid=0(root) gid=0(root) groups=0(root)

> podman run --userns=keep-id --rm -it registry.suse.com/bci/bci-base id
    uid=1000(user) gid=1000(users) groups=1000(users)

> podman run --rm -it -v $(pwd):/share/ registry.suse.com/bci/bci-base stat /share/
      File: /share/
      Size: 318             Blocks: 0          IO Block: 4096   directory
    Device: 2ch/44d Inode: 3506170     Links: 1
    Access: (0755/drwxr-xr-x)  Uid: (    0/    root)   Gid: (    0/    root)
    Access: 2023-05-03 12:52:18.636392618 +0000
    Modify: 2023-05-03 12:52:17.178380923 +0000
    Change: 2023-05-03 12:52:17.178380923 +0000
     Birth: 2023-05-03 12:52:15.852370288 +0000

     > podman run --userns=keep-id --rm -it -v $(pwd):/share/ registry.suse.com/bci/bci-base stat /share/
      File: /share/
      Size: 318             Blocks: 0          IO Block: 4096   directory
    Device: 2ch/44d Inode: 3506170     Links: 1
    Access: (0755/drwxr-xr-x)  Uid: ( 1000/     user)   Gid: ( 1000/     users)
    Access: 2023-05-03 12:52:18.636392618 +0000
    Modify: 2023-05-03 12:52:17.178380923 +0000
    Change: 2023-05-03 12:52:17.178380923 +0000
     Birth: 2023-05-03 12:52:15.852370288 +0000

> podman unshare bash

    > id
    uid=0(root) gid=0(root) groups=0(root),65534(nobody)

> sudo systemctl start podman.socket

Tags are used to assign descriptive names to container images, thus making it easier to identify individual images.

Pull the SLE BCI-Base image from SUSE Registry:

> podman pull registry.suse.com/bci/bci-base
    Trying to pull registry.suse.com/bci/bci-base:latest...
    Getting image source signatures
    Copying blob bf6ca87723f2 done
    Copying config 34578a383c done
    Writing manifest to image destination
    Storing signatures
    34578a383c7b6fdcb85f90fbad59b7e7a16071cf47843688e90fe20ff64a684

List the pulled images:

> podman images
    REPOSITORY                      TAG         IMAGE ID      CREATED        SIZE
    registry.suse.com/bci/bci-base  latest      34578a383c7b  22 hours ago   122 MB

Rename the SLE BCI-Base image to my-base:

podman tag 34578a383c7b my-base

podman images
    REPOSITORY                      TAG         IMAGE ID      CREATED        SIZE
    registry.suse.com/bci/bci-base  latest      34578a383c7b  22 hours ago   122 MB
    localhost/my-base               latest      34578a383c7b  22 hours ago   122 MB

Add a custom tag 1 (indicating that this version 1 of the image) to my-base:

> podman tag 34578a383c7b my-base:1

> podman images
    REPOSITORY                      TAG         IMAGE ID      CREATED        SIZE
    registry.suse.com/bci/bci-base  latest      34578a383c7b  22 hours ago   122 MB
    localhost/my-base               latest      34578a383c7b  22 hours ago   122 MB
    localhost/my-base               1           34578a383c7b  22 hours ago   122 MB

Note that the default tag latest is still present.

Similar to Docker Open Source Engine, Podman can run containers in an interactive mode, allowing you to inspect and work with an image. To run the suse/sle15 image in interactive mode, use the following command:

> podman run --rm -ti suse/sle15

Note: Fixing the lost network access to rootful containers

Rootful containers may occasionally become inaccessible from the outside. The issue is caused by firewalld reloading its permanent rules and discarding any temporary rules created by Podman's networking back-end (either CNI or Netavark). A temporary workaround is to reload the Podman network using the podman network reload --all command. If you use Netavark 1.9.0 or higher as the network back-end, a permanent fix to the problem is to use the netavark-firewalld-reload.service service. Enable and start the service as follows:

# systemctl enable netavark-firewalld-reload.service
# systemctl restart netavark-firewalld-reload.service

You can check which back-end and version you are using by running podman info --format "{{.Host.NetworkBackend}}" and podman info --format "{{.Host.NetworkBackendInfo.Version}}", respectively.

We recommend adding permanent firewall rules for containers you want to be accessible from outside of the host. This ensures that the rules persist on firewall reloads and system reboots. This approach also offers greater flexibility (for example, it allows you to assign the rules to a certain firewalld zone).

Podman can build images from a Dockerfile. The podman build command behaves as docker build, and it accepts the same options.

Podman's companion tool Buildah provides an alternative way to build images. For further information about Buildah, refer to Section 18, “Buildah overview”.

Before installing any Docker-related packages, you need to enable the Containers Module:

Note: Built-in Docker orchestration support

Container orchestration is a part of Docker Open Source Engine. Even though this feature is available in SUSE Linux Enterprise, it is not supported by SUSE, and is only provided as a technology preview. Use Kubernetes for container orchestration. For details, refer to the Kubernetes documentation.

> sudo /usr/sbin/usermod -aG docker USERNAME

To give the containers access to the external network, enable the ipv4 ip_forward rule.

Docker Open Source Engine supports different storage drivers:

SUSE Linux Enterprise uses the Btrfs file system by default. This forces Docker Open Source Engine to use the btrfs driver.

It is possible to specify what driver to use by changing the value of the DOCKER_OPTS variable defined in the /etc/sysconfig/docker file. This can be done either manually or using YaST by browsing to the System › /etc/sysconfig Editor › System › Management › DOCKER_OPTS menu and entering the -s storage_driver string.

For example, to enable the devicemapper driver, enter the following text:

DOCKER_OPTS="-s devicemapper"

Important: Mounting /var/lib/docker

It is recommended to mount /var/lib/docker on a separate partition or volume. In case of file system corruption, this allows the operating system to run Docker Open Source Engine unaffected.

If you choose the Btrfs file system for /var/lib/docker, it is strongly recommended to create a subvolume for it. This ensures that the directory is excluded from file system snapshots. If you do not exclude /var/lib/docker from snapshots, there is a risk of the file system running out of disk space soon after you start deploying containers. Moreover, a rollback to a previous snapshot will also reset the Docker database and images. For more information, see https://documentation.suse.com/sles/html/SLES-all/cha-snapper.html#sec-snapper-setup-customizing-new-subvolume.

All updates to the docker package are marked as interactive (that is, no automatic updates) to avoid accidental updates that can break running container workloads. Stop all running containers before applying a Docker Open Source Engine update.

To prevent data loss, avoid workloads that rely on containers that automatically start after Docker Open Source Engine update. Although it is technically possible to keep containers running during an update via the --live-restore option, such updates can introduce regressions. SUSE does not support this feature.

The SUSE Registry provides a container image that makes it possible to run a local Docker Registry as a container. It stores the pushed images in a container volume corresponding to the directory /var/lib/docker-registry. It is recommended to either create a named volume for the registry or to bind mount a persistent directory on the host to /var/lib/docker-registry in the container. This ensures that pushed images persist deleting the container.

Run the following command to pull the registry container image from the SUSE Registry and start a container that can be accessed on port 5000 with the container storage bind mounted locally to /PATH/DIR/:

> podman run -d --restart=always --name registry -p 5000:5000 \
    -v /PATH/DIR:/var/lib/docker-registry registry.suse.com/suse/registry

Alternatively, create a named volume registry for the SUSE Registry container as follows:

> podman run -d --restart=always --name registry -p 5000:5000 \
     -v registry:/var/lib/docker-registry registry.suse.com/suse/registry

To make it easier to manage the registry, create a corresponding system unit:

>  podman generate systemd registry | \
     sudo tee /etc/systemd/system/suse_registry.service

Enable and start the registry service, then verify its status:

> sudo systemctl enable suse_registry.service
      > sudo systemctl start suse_registry.service
      > sudo systemctl status suse_registry.service

For more details about Docker Registry and its configuration, see the official documentation at https://docs.docker.com/registry/.

Docker Registry has two major limitations:

Signatures for images available through SUSE Registry are stored in the Notary. You can verify the signature of a specific image using the following command:

> docker trust inspect --pretty registry.suse.com/suse/IMAGE:TAG

For example, the command docker trust inspect --pretty registry.suse.com/suse/sle15:latest verifies the signature of the latest SLE15 base image.

To automatically validate an image when you pull it, set the environment DOCKER_CONTENT_TRUST to 1. For example:

env DOCKER_CONTENT_TRUST=1 docker pull registry.suse.com/suse/sle15:latest

To verify a SLE BCI, run Cosign in the container. The command below fetches the signing key from the SUSE server and uses it to verify the latest SLE BCI-Base container image.

> podman run --rm -it gcr.io/projectsigstore/cosign verify \
        --key https://ftp.suse.com/pub/projects/security/keys/container-key.pem \
        registry.suse.com/bci/bci-base:latest | tail -1 | jq
    
    [
      {
        "critical": {
          "identity": {
            "docker-reference": "registry.suse.com/bci/bci-base"
          },
          "image": {
            "docker-manifest-digest": "sha256:52a828600279746ef669cf02a599660cd53faf4b2430a6b211d593c3add047f5"
          },
          "type": "cosign container image signature"
        },
        "optional": {
          "creator": "OBS"
        }
      }
    ]

The signing key can be used to verify all SLE BCIs, and it also ships with SUSE Linux Enterprise (the /usr/share/container-keys/suse-container-key.pem file).

You can also check SLE BCIs against rekor, the immutable tamper resistant ledger. For example:

> podman run --rm -it -e COSIGN_EXPERIMENTAL=1 gcr.io/projectsigstore/cosign \
        verify --key https://ftp.suse.com/pub/projects/security/keys/container-key.pem \
        registry.suse.com/bci/bci-base:latest | tail -1 | jq
    [
      {
        "critical": {
          "identity": {
            "docker-reference": "registry.suse.com/bci/bci-base"
          },
          "image": {
            "docker-manifest-digest": "sha256:52a828600279746ef669cf02a599660cd53faf4b2430a6b211d593c3add047f5"
          },
          "type": "cosign container image signature"
        },
        "optional": {
          "creator": "OBS"
        }
      }
    ]

If verification fails, the output of the cosign verify command is similar to the one below.

Error: no matching signatures:
    crypto/rsa: verification error
    main.go:62: error during command execution: no matching signatures:
    crypto/rsa: verification error

Cosign can also be used to verify Helm charts. This can be done using the following command:

> cosign verify --key https://ftp.suse.com/pub/projects/security/keys/container-key.pem registry.suse.com/path/to/chart

Before you can verify SLE BCIs using Podman, you must specify registry.suse.com as the registry for image verification.

Note

Skip this step on SUSE Linux Enterprise, as the correct configuration is already in place.

To do this, add the following configuration to /etc/containers/registries.d/default.yaml:

docker:
      registry.suse.com:
        use-sigstore-attachments: true

Instead of editing the default.yaml, you can create a new file in /etc/containers/registries.d/ with a filename of your choice.

Next, modify the /etc/containers/policy.json file. Under the docker attribute, add the registry.suse.com configuration similar to the following:

{
      "default": [
        {
          "type": "insecureAcceptAnything"
        }
      ],
      "transports": {
        "docker-daemon": {
          "": [
            {
              "type": "insecureAcceptAnything"
            }
          ]
        },
        "docker": {
          "registry.suse.com": [
            {
              "type": "sigstoreSigned",
              "keyPath": "/usr/share/pki/containers/suse-container-key.pem",
              "signedIdentity": {
                "type": "matchRepository"
              }
            }
          ]
        }
      }
    }

The specified configuration instructs Podman, skopeo and Buildah to verify images under the registry.suse.com repository. This way,Podman checks the validity of the signature using the specified public key before pulling the image. It rejects the image if the validation fails.

Note

Do not remove existing entries in transports.docker. Append the entry for registry.suse.com to the list.

Fetch the public key used to sign SLE BCIs from SUSE Signing Keys, or use the following command:

> sudo curl -s https://ftp.suse.com/pub/projects/security/keys/container–key.pem \
        -o /usr/share/pki/containers/suse-container-key.pem

Note

This step is optional on SUSE Linux Enterprise. The signing key is already available in /usr/share/pki/containers/suse-container-key.pem

Buildah, Podman and skopeo automatically verifies every image pulled from registry.suse.com from now on. There are no additional steps required.

If verification fails, the command returns an error message as follows:

> podman pull registry.suse.com/bci/bci-base:latest
    Trying to pull registry.suse.com/bci/bci-base:latest...
    Error: copying system image from manifest list: Source image rejected: Signature for identity registry.suse.com/bci/bci-base is not accepted

If there are no issues with the signed image and your configuration, you can proceed with using the container image.

To install Buildah, run the command sudo zypper in buildah. Run the command buildah --version to check whether Buildah has been installed successfully.

If you already have Podman installed and set up for use in rootless mode, Buildah can be used in an unprivileged environment without any further configuration. If you need to enable rootless mode for Buildah, run the following command:

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

This command enables rootless mode for the current user. After running the command, log out and log in again to enable the changes.

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

Note: Buildah in rootless mode

In rootless mode, Buildah commands must be executed in a modified user namespace of the user. To enter this user namespace, run the command buildah unshare. Otherwise, the buildah mount command will fail.

Instead of a special file with instructions, Buildah uses individual commands to build an image. Building an image with Buildah involves the following steps:

While this process may include additional steps, such as mounting the container's file system and working with it, the basic workflow logic remains the same.

The following example can give you a general idea of how to build an image with Buildah.

container=$(buildah from suse/sle15) 1
    buildah run $container zypper up 2
    buildah copy $container . /usr/src/example/ 3
    buildah config --workingdir /usr/src/example $container 4
    buildah config --port 8000 $container
    buildah config --cmd "php -S 0.0.0.0:8000" $container
    buildah config --label maintainer="Tux" $container 5
    buildah config --label version="0.1" $container
    buildah commit $container example 6
    buildah rm $container 7

To obtain a pre-built base image, use the following command:

> podman pull registry.suse.com/suse/IMAGENAME

For example, for SUSE Linux Enterprise Server 15, the command is as follows:

> podman pull registry.suse.com/suse/sle15

For information on obtaining specific base images, refer to Section 3, “Introduction to SLE Base Container Images”.

When the container image is ready, you can customize it as described in Section 19.2, “Customizing container images”.

If your application needs a version of a package different from the package installed on the system, you can create a container image that includes the package version the application requires. The following example Dockerfile allows building an image based on an up-to-date version of SUSE Linux Enterprise Server with an older version of the example package:

FROM registry.suse.com/suse/sle15
    LABEL maintainer=EXAMPLEUSER_PLAIN
    RUN zypper ref && zypper in -f example-1.0.0-0
    COPY application.rpm /tmp/
    RUN zypper --non-interactive in /tmp/application.rpm
    ENTRYPOINT ["/etc/bin/application"]
    CMD ["-i"]

Build the image by running the following command in the directory that the Dockerfile resides in:

> podman build --tag tux_application:latest .

The Dockerfile example shown above performs the following operations during the image build process:

After a successful build of the tux_application image, you can start a container based on the new image using the following command:

> podman run -it --name application_instance tux_application:latest

Keep in mind that after closing the application, the container exits as well.

To run an instance using a different configuration, create a derived image and include the additional configuration with it. In the example below, an application called example is configured using the file /etc/example/configuration_example:

FROM registry.suse.com/suse/sle15 1
    RUN zypper ref && zypper --non-interactive in example 2
    ENV BACKUP=/backup 3
    RUN mkdir -p $BACKUP 4
    COPY configuration_example /etc/example/ 5
    ENTRYPOINT ["/etc/bin/example"] 6

The above example Dockerfile performs the following operations:

Podman allows sharing data between host and a container by using volumes. You can specify a mount point directly in the Dockerfile. However, you cannot specify a directory on the host system in the Dockerfile, as the directory may not be accessible at build time. Find the mounted directory under /var/lib/docker/volumes/ on the host system.

Note: Discarding changes to the directory to be shared

After you specify a mount point by using the VOLUME instruction, all changes made to the directory with the RUN instruction are discarded. After the mount point is specified, the volume becomes a part of a temporary container, which is removed after a successful build. This means that for certain actions to take effect, they must be performed before specifying a mount point. For example, if you need to change permissions, do this before you specify the directory as a mount point in the Dockerfile.

Specify a particular mount point on the host system when running a container by using the -v option:

> podman run -it --name testing -v /home/tux/data:/data sles12sp4:latest /bin/bash

Note

The -v option overwrites the VOLUME instruction if you specify the same mount point in the container.

The following Dockerfile example builds an image containing a Web server that reads Web content from the host's file system:

FROM registry.suse.com/suse/sles12sp4
    RUN zypper ref && zypper --non-interactive in apache2
    COPY apache2 /etc/sysconfig/
    RUN chown -R admin /data
    EXPOSE 80
    VOLUME /data
    ENTRYPOINT ["apache2ctl"]

The example above installs the Apache Web server to the image and copies the entire configuration to the image. The data directory is owned by the admin user and is used as a mount point to store Web pages.

If your application needs to run in the background as a daemon, or as an application exposing ports for communication, you can run the container in the background.

An example Dockerfile for an application exposing a port is as follows:

FROM registry.suse.com/suse/sle15 1
    LABEL maintainer=EXAMPLEUSER_PLAIN 2
    ADD etc/ /etc/zypp/ 3
    RUN zypper refs && zypper refresh 4
    RUN zypper --non-interactive in apache2 5
    RUN echo "The Web server is running" > /srv/www/htdocs/test.html 6
    # COPY data/* /srv/www/htdocs/ 7
    EXPOSE 80 8
    ENTRYPOINT ["/usr/sbin/httpd"]
    CMD ["-D", "FOREGROUND"]

Note

To use port 80, make sure there is no other server software running on this port on the host.

To use the container, proceed as follows:

You can use the resulting container to serve your data with the Apache2 Web server by following these steps:

To view the published data, point a browser at http://localhost:80/test.html.

To avoid copying Web site data into the container, share a directory of the host with the container. For more information, see https://docs.docker.com/storage/volumes/.

podman pod is the command-line tool for creating, removing, querying and inspecting pods. You can check all the subcommands of podman pod in the official upstream documentation.

podman pod create creates a pod with a random name. You can use the --name parameter to assign the desired name to a pod.

> podman pod create
    344940492c00b6a19ececbc5b109351bf0a3b8b19b3c279a097da7a653c592d0

You can list our pods using the podman pod list command:

> podman pod list
    POD ID        NAME          STATUS      CREATED        INFRA ID      # OF CONTAINERS
    344940492c00  suspicious_curie  Created     2 minutes ago  617d7e3ce399  1

You can also list all containers with the pods they are associated with:

> podman ps -a --pod
    CONTAINER ID  IMAGE                 COMMAND     CREATED        STATUS      PORTS       NAMES               POD ID        PODNAME
    617d7e3ce399  localhost/podman-pause:4.3.1-1669118400              5 minutes ago  Created                 344940492c00-infra  344940492c00  suspicious_curie

The created pod has an infra container identified by the localhost/podman-pause:4.x name. The purpose of this container is to reserve the namespaces associated with the pod and allow Podman to add other containers to the pod.

Using the podman run --pod command, you can run a container and add it to the desired pod. For example, the command below runs a container based on the suse/sle15 image and adds the container to the suspicious_curie pod:

> podman run -d --pod suspicious_curie registry.suse.com/bci/bci-base sleep 1h
    8f5af62a7c385bbd1a3a5cc3a53a8d0f8cf942adc26a065960d4232fcc93ac98

Warning

If this command shows the following warning, refer to Using container-suseconnect on non-SLE hosts or with Podman, Buildah, and nerdctl:

WARN[0005] Path "/etc/SUSEConnect" from "/etc/containers/mounts.conf" doesn't exist, skipping
    WARN[0005] Failed to mount subscriptions, skipping entry in /etc/containers/mounts.conf: open /etc/zypp/credentials.d/SCCcredentials: permission denied

The command above adds a container that sleeps for 60 minutes and then exits. Run the podman ps -a --pod command again and you should see that the pod now has two containers.

You can also check the command podman pod ps:

> podman pod ps
    POD ID        NAME          STATUS      CREATED         INFRA ID      # OF CONTAINERS
    344940492c00  suspicious_curie Running     21 minutes ago  617d7e3ce399  2

To stop our newly created container named objective_jemison

> podman ps -a --pod
    CONTAINER ID  IMAGE                                COMMAND     CREATED         STATUS            PORTS       NAMES               POD ID        PODNAME
    617d7e3ce399  localhost/podman-pause:4.3.1-1669118400                             14 minutes ago  Up 4 minutes ago              344940492c00-infra  344940492c00  suspicious_curie 8f5af62a7c38  registry.suse.com/bci/bci-base:latest  sleep 1h    4 minutes ago   Up 4 minutes ago              objective_jemison   344940492c00  suspicious_curie
    > podman stop objective_jemison
    objective_jemison
    > podman pod ps
    POD ID        NAME          STATUS      CREATED         INFRA ID      # OF CONTAINERS
    344940492c00  suspicious_curie  Degraded    25 minutes ago  617d7e3ce399  2
    > podman ps -a --pod
    CONTAINER ID  IMAGE                                COMMAND     CREATED         STATUS                       PORTS       NAMES               POD ID        PODNAME
    617d7e3ce399  localhost/podman-pause:4.3.1-1669118400                             25 minutes ago  Up 15 minutes ago                        344940492c00-infra  344940492c00  suspicious_curie 8f5af62a7c38  registry.suse.com/bci/bci-base:latest  sleep 1h    15 minutes ago  Exited (137) 14 seconds ago              objective_jemison   344940492c00  suspicious_curie

You can also stop the pod and all of its containers using podman pod stop:

# podman pod stop suspicious_curie
    344940492c00b6a19ececbc5b109351bf0a3b8b19b3c279a097da7a653c592d0
    > podman ps -ap
    CONTAINER ID  IMAGE                                COMMAND     CREATED         STATUS                      PORTS       NAMES               POD ID        PODNAME
    617d7e3ce399  localhost/podman-pause:4.3.1-1669118400                             29 minutes ago  Exited (0) 7 seconds ago                344940492c00-infra  344940492c00  suspicious_curie 8f5af62a7c38  registry.suse.com/bci/bci-base:latest  sleep 1h    19 minutes ago  Exited (137) 3 minutes ago              objective_jemison   344940492c00  suspicious_curie

You can also start and restart everything with sudo podman start CONTAINER_NAME, podman pod start POD_NAME or podman pod restart POD_NAME.

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 there is a risk of removing pods that are still in use.

A container runtime makes it easy to launch an application distributed as a single container. But things get more complicated when you need to run applications consisting of multiple containers, or when it's necessary to start the applications automatically on system boot and restart them after they crash. While container orchestration tools like Kubernetes are designed for that exact purpose, they are intended to be used for highly distributed and scalable systems with hundreds of nodes, and not for a single machine. systemd and Podman are much better suited for the single-machine scenario, as they do not add another layer of complexity to your existing setup.

Podman supports creating systemd unit files with the podman generate systemd subcommand. The subcommand creates a systemd unit file, making it possible to control a container or pod via systemd. Using the unit file, you can launch a container or pod on boot, automatically restart it if a failure occurs, and keep its logs in journald.

The following example uses a simple NGINX container:

> podman run -d --name web -p 8080:80 docker.io/nginx
    c0148d8476418a2da938a711542c55efc09e4119909aea70e287465c6fb51618

Generating a systemd unit for the container can be done as follows:

> podman generate systemd --name --new web
    # container-web.service
    # autogenerated by Podman 4.2.0
    # Tue Sep 13 10:58:54 CEST 2022

    [Unit]
    Description=Podman container-web.service
    Documentation=man:podman-generate-systemd(1)
    Wants=network-online.target
    After=network-online.target
    RequiresMountsFor=%t/containers

    [Service]
    Environment=PODMAN_SYSTEMD_UNIT=%n
    Restart=on-failure
    TimeoutStopSec=70
    ExecStartPre=/bin/rm -f %t/%n.ctr-id
    ExecStart=/usr/bin/podman run \
            --cidfile=%t/%n.ctr-id \
            --cgroups=no-conmon \
            --rm \
            --sdnotify=conmon \
            --replace \
            -d \
            --name web \
            -p 8080:80 docker.io/nginx
    ExecStop=/usr/bin/podman stop --ignore --cidfile=%t/%n.ctr-id
    ExecStopPost=/usr/bin/podman rm -f --ignore --cidfile=%t/%n.ctr-id
    Type=notify
    NotifyAccess=all

    [Install]
    WantedBy=default.target

Podman outputs a unit file to the console that can be put either into the user unit systemd directories (~/.config/systemd/user/ or /etc/systemd/user/) or into the system unit systemd directory (/etc/systemd/system) and control the container via systemd. The --new flag instructs Podman to recreate the container on a restart. This ensures that the systemd unit is self-contained, and it does not depend on any external state. The --name flag allows you to assign a user-friendly name to the container: without it, Podman uses container IDs instead of their names.

To control the container as a user unit, proceed as follows:

> podman generate systemd --name --new --files web
    /home/user/container-web.service
    > mv container-web.service ~/.config/systemd/user/
    > systemctl --user daemon-reload

Now the container can be started with systemctl --user start container-web:

> systemctl --user start container-web
    > systemctl --user is-active container-web.service
    active

Run the podman ps command to see the list of all running containers:

> podman ps
    CONTAINER ID  IMAGE                           COMMAND               CREATED         STATUS             PORTS                 NAMES
    af92743971d2  docker.io/library/nginx:latest  nginx -g daemon o...  15 minutes ago  Up 15 minutes ago  0.0.0.0:8080->80/tcp  web

One of the benefits of managing the container via systemd is the ability to automatically restart the container if it crashes. You can simulate a crash by sending SIGKILL to the main process in the container:

> podman ps
    CONTAINER ID  IMAGE                           COMMAND               CREATED             STATUS                 PORTS                 NAMES
    4c89582fa9cb  docker.io/library/nginx:latest  nginx -g daemon o...  About a minute ago  Up About a minute ago  0.0.0.0:8080->80/tcp  web

    > kill -9 $(podman inspect --format "{{.State.Pid}}" web)

    > podman ps
    CONTAINER ID  IMAGE                           COMMAND               CREATED        STATUS            PORTS                 NAMES
    0b5be4493251  docker.io/library/nginx:latest  nginx -g daemon o...  4 seconds ago  Up 4 seconds ago  0.0.0.0:8080->80/tcp  web

Note that the container is not restarted when it is stopped gracefully, for example, via podman stop web. To always restart it, add the flag --restart-policy=always to podman generate systemd.

Using the described approach means that the container image is never updated. You can solve this problem by adding the --pull=always flag to the ExecStart= entry in the unit file. But be aware that this increases the start-up time of the container and updates the image on every restart. The latter also means that a container image update can make the container unavailable outside of a scheduled maintenance window due to a newly introduced bug.

The auto-update subcommand in Podman provides a possible solution. Add the label io.containers.autoupdate=registry to a container to make Podman pull a new version of the container image from the registry when running podman auto-update. This makes it possible to update all container images with a single command at a desired time, and without increasing the start-up time of the systemd units.

The auto-update feature can be enabled by adding the line --label "io.containers.autoupdate=registry" \ to the ExecStart= entry of the container's systemd unit file. For the NGINX example, modify ~/.config/systemd/user/container-web.service as follows:

ExecStart=/usr/bin/podman run \
            --cidfile=%t/%n.ctr-id \
            --cgroups=no-conmon \
            --rm \
            --sdnotify=conmon \
            --replace \
            -d \
            --name web \
            --label "io.containers.autoupdate=registry" \
            -p 8080:80 docker.io/nginx

After reloading the daemons and restarting the container, perform a dry run of the update (it will most likely not report any updates):

> podman auto-update --dry-run
    UNIT                   CONTAINER           IMAGE            POLICY      UPDATED
    container-web.service  87d263489307 (web)  docker.io/nginx  registry    false

It is good practice to have external testing in place to make sure that image updates are generally safe to be deployed. If you are confident of the quality of our container image, you can let Podman automatically apply image updates periodically by enabling the podman-auto-update.timer:

# only for the current user
    > systemctl --user enable podman-auto-update.timer
    Created symlink /home/user/.config/systemd/user/timers.target.wants/podman-auto-update.timer → /usr/lib/systemd/user/podman-auto-update.timer.
    # or as root
    > sudo systemctl enable podman-auto-update.timer
    Created symlink /etc/systemd/system/timers.target.wants/podman-auto-update.timer → /usr/lib/systemd/system/podman-auto-update.timer.

Certain applications rely on more than one container to function, for example, a web front-end, a back-end server and a database. Docker compose is popular tool for deploying multi-container applications on a single machine. While Podman does not support the compose command natively, in most cases compose files can be ported to a Podman pod and multiple containers.

The following example deploys a Drupal and PostgreSQL container in a single pod and manages these via systemd units. First, create a new pod that exposes the Drupal web interface:

> podman pod create -p 8080:80 --name drupal
    736cab072c49e68ad368ba819e9117be13ef8fa048a2eb88736b5968b3a19a64

Once the pod has been created, launch the Drupal front-end and the PostgreSQL database inside it:

> podman run -d --name drupal-frontend --pod drupal docker.io/drupal
    ffd2fbd6d445e63fb0c28abb8d25ced78f819211d3bce9d6174fe4912d89f0ca

    > podman run -d --name drupal-pg --pod drupal \
          -e POSTGRES_DB=drupal \
          -e POSTGRES_USER=user \
          -e POSTGRES_PASSWORD=pass \
          docker.io/postgres:11
    a4dc31b24000780d9ffd81a486d0d144c47c3adfbecf0f7effee24a00273fcde

This results in three running containers: the Drupal web interface, the PostgreSQL database and the pod's infrastructure container.

> podman ps
    CONTAINER ID  IMAGE                                    COMMAND               CREATED             STATUS                 PORTS                 NAMES
    2948fa1476c6  localhost/podman-pause:4.2.0-1660228937                        2 minutes ago       Up About a minute ago  0.0.0.0:8080->80/tcp  736cab072c49-infra
    ffd2fbd6d445  docker.io/library/drupal:latest          apache2-foregroun...  About a minute ago  Up About a minute ago  0.0.0.0:8080->80/tcp  drupal-frontend
    a4dc31b24000  docker.io/library/postgres:11            postgres              40 seconds ago      Up 41 seconds ago      0.0.0.0:8080->80/tcp  drupal-pg

Creating a systemd unit for the pod is done similarly to a single container:

> podman generate systemd --name --new --files drupal
    /home/user/pod-drupal.service
    /home/user/container-drupal-frontend.service
    /home/user/container-drupal-pg.service
    > mv *service ~/.config/systemd/user/
    > systemctl daemon-reload --user

Since Podman is aware of which containers belong to the drupal pod and how their systemd units are called, it can correctly add the dependencies to the pod's unit file. This means that when you start or stop the pod, systemd ensures that all containers inside the pod are started or stopped automatically.

To check systemd's dependency handling, first stop the drupal pod and verify that no containers are currently running on the host:

> podman pod stop drupal
    736cab072c49e68ad368ba819e9117be13ef8fa048a2eb88736b5968b3a19a64
    > podman pod rm drupal
    736cab072c49e68ad368ba819e9117be13ef8fa048a2eb88736b5968b3a19a64
    > podman ps -a
    CONTAINER ID  IMAGE       COMMAND     CREATED     STATUS      PORTS       NAMES

Start the drupal pod via systemctl start --user pod-drupal.service, and systemd launches the containers inside the pod:

> systemctl start --user pod-drupal.service
    > podman ps
    CONTAINER ID  IMAGE                                    COMMAND               CREATED        STATUS            PORTS                 NAMES
    d1589d3ac68b  localhost/podman-pause:4.2.0-1660228937                        5 seconds ago  Up 5 seconds ago  0.0.0.0:8080->80/tcp  ca41b505bd13-infra
    a49bea53c20c  docker.io/library/postgres:11            postgres              4 seconds ago  Up 5 seconds ago  0.0.0.0:8080->80/tcp  drupal-pg
    dc9dca018dad  docker.io/library/drupal:latest          apache2-foregroun...  4 seconds ago  Up 5 seconds ago  0.0.0.0:8080->80/tcp  drupal-frontend

If you want to learn more about Podman and handling pod deployment, please check https://docs.podman.io/en/latest/ and https://github.com/containers/podman.

Kubernetes is an open source container orchestration engine for automating deployment, scaling and management of containerized applications. The open source project is hosted by the Cloud Native Computing Foundation (CNCF).

Kubernetes makes it possible for multiple machines (or servers or nodes) to work together and create a cluster that you can then interact with through APIs. We recommend using Rancher for deploying Kubernetes clusters and managing applications running on top of them. A single Rancher setup can manage multiple Kubernetes clusters running anywhere: from bare-metal, to on-prem or cloud service providers.

For more information on Rancher, refer to the official Rancher documentation.

K3s is a lightweight CNCF-certified Kubernetes distribution built for IoT and Edge computing. Unlike Kubernetes, K3s is packaged as a single <60 MB binary and optimized for the Arm architecture.

For more info, refer to Introduction to K3s and How to install K3s and Rancher on SUSE Linux Enterprise Server.

Consult the following support and compatibility matrix to make sure that the desired host system and container combination is compatible and supported.

✓ Fully supported

❋ Limited support (see the Limited support note)

Important: Limited support note

SUSE provides limited support for SLES 15 GA-based containers running on SLES 12 SP5 hosts due to the fact that containerized applications can make system calls not available in the host's kernel. To avoid potential risks and compatibility problems, SUSE recommends using the same Service Pack release for both containers and hosts.

SLE BCIs support the following architectures: AMD64/Intel 64, AArch64, POWER and IBM Z. Container architecture must match the architecture of the host. Mismatching container and host scenarios are not supported.

In most scenarios, all SLE containers are expected to be interoperable if the application and its dependencies do not interact directly with kernel version-specific data structures and their derivatives (ioctl, /proc, /sys, routing, iptables, nftables, BTF, (e)BPF, etc.) or modules (KVM, OVS, SystemTap, etc.). Support for ioctl and access to /proc is limited to the most common scenarios needed by unprivileged users.

While SUSE-based containers are fully supported, issues in the host environment must be handled by the host environment vendor. SUSE supports components that are part of the SUSE base containers. Packages from SUSE repositories are also supported. Additional components and applications in the containers are not covered by SUSE support. A SLE subscription is required for building derived containers.

Containers based on SLES 12 SP5 and SLES 15 (all service packs) are supported according to their official lifecycles and the following table.

The following third-party container host platforms are supported.

✓ Fully compatible and fully supported

❋ Workload specific: fully supported but compatibility depends on type of container (privileged or unprivileged) and on the application interactions (direct with kernel-version-specific data structures, kernel-version-specific modules, etc.)

Refer to the Rancher Support Matrix for more information regarding support for Rancher-related products.

There are three guiding principles of SUSE container support.

For further information, refer to the Product Support Lifecycle page and the documentation available for specific container images on SUSE Registry.

Container images can have different support status, and they can have limited support. Refer to the appropriate https://registry.suse.com page for the further information about a specific container image.

The following support options are valid for SLES containers on SUSE host environments.

Containers and host environments delivered by SUSE are fully supported. This also applies to all products under support, including both general support and Long Term Service Pack Support (LTSS).

Partner containers and host environments with a joint engineering collaboration agreement are fully supported. This applies to both the container and host environment as well as all products under support (both general and LTSS) covered by the agreement.

While SUSE-based containers are fully supported, issues in the host environment must be handled by the host environment vendor. SUSE supports components that come from the SUSE base containers. Packages from SUSE repositories are also supported. Additional components and applications in the containers are not covered by SUSE support. No subscription is required for building derived containers based on the content of the SLE BCIs or the SLE_BCI Repository. To build containers that include packages from the full SLE universe, you need a subscription that grants you access to the repositories containing these packages.

Any container and host environment not mentioned above has limited support. Details can be discussed with the SUSE Support Team responsible for triaging the issue and recommending alternative solutions. In any other case, issues in the host environment must be handled by the host environment vendor.

Container images labeled as Tech Preview are provided by SUSE to give you an opportunity to test new technologies within your environment and share your feedback. If you test a technology preview, contact your SUSE representative to share your experiences and use cases. Your input is helpful for future development.

Technology previews come with the following limitations:

Container images are labeled as Tech Preview and are marked as such at registry.suse.com. Additionally, container images that are technology previews include the com.suse.supportlevel="techpreview" label in the container image metadata. You can check whether the metadata includes the label using the docker inspect command, or an appropriate command in other container runtimes.

SLE Base Container Images are tested with the following platforms and environments:

SLE Base Container Images are tested using Podman and Docker. SLE Base Container Images that use FIPS-certified crypto libraries are tested on FIPS-certified platforms.

In case a custom Docker Open Source Engine container image built on top of the SLE-Base container image is not working as expected, the container-diff tool can help you analyze the image and collect information relevant for troubleshooting.

container-diff makes it possible to analyze image changes by computing differences between images and presenting the diff in a human-readable and actionable format. The tool can find differences in system packages, language-level packages, and files in a container image.

container-diff can handle local container images (using the prefix daemon://), images in a remote registry (using the prefix remote://), and images saved as .tar archives. You can use container-diff to compute the diff between a local version of an image and a remote version.

To install container-diff, run the sudo zypper in container-diff command.

> sudo container-diff analyze --type=history daemon://IMAGE
    > sudo container-diff analyze --type=file daemon://IMAGE

> sudo container-diff diff daemon://IMAGE1 daemon://IMAGE2 --type=history