Applies to Container Guide

14 Buildah overview #

Buildah is tool for building OCI-compliant container images. Buildah can handle the following tasks:

Create containers from scratch or from existing images.
Create an image from a working container or via a Dockerfile.
Build images in the OCI or Docker Open Source Engine image formats.
Mount a working container’s root file system for manipulation.
Use the updated contents of a container’s root file system as a file system layer to create a new image.
Delete a working container or an image and rename a local container.

Compared to Docker Open Source Engine, Buildah offers the following advantages:

The tool makes it possible to mount a working container’s file system, so it becomes accessible by the host.
The process of building container images using Buildah can be automated via scripts by using Buildah’s subcommands instead of a Containerfile or Dockerfile.
Similar to Podman, Buildah does not require a daemon to run and can be used by unprivileged users.
It is possible to build images inside a container without mounting the Docker socket, which improves security.

14.1 Podman and Buildah #

Both Podman and Buildah can be used to build container images. While Podman makes it possible to build images using Dockerfiles, Buildah offers an expanded range of image building options and capabilities.

14.2 Buildah installation #

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 SLES 15 SP4 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.

14.3 Building images with Buildah #

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

run a container based on the specified image
edit the container (install packages, configure settings, etc.)
configure the container options
commit all changes into a new image

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

1	Specify a container (also called a working container) based on the specified image (in this case, `sle15`).
2	Run a command in the working container you just created. In this example, Buildah runs the `zypper up` command.
3	Copy files and directories to the specified location in the container. In this example, Buildah copies the entire contents of the current directory to `/usr/src/example/`.
4	The `buildah config` commands specify container options. These include defining a working directory, exposing a port, and running a command inside the container.
5	The `buildah config --label` command allows you to assign labels to the container. This may include `maintainer`, `description`, `version`, and so on.
6	Create an image from the working container by committing all the modifications.
7	Delete the working container.