Chapter 19. Building container images with Buildah
Chapter 19. Building container images with Buildah Buildah facilitates building OCI container images that meet the OCI Runtime Specification . With Buildah, you can create a working container, either from scratch or using an image as a starting point. You can create an image either from a working container, using the instructions in a Containerfile , or by using a series of Buildah commands that emulate the commands found in a Containerfile . 19.1. The Buildah tool Buildah is a command-line tool for creating Open Container Initiative (OCI) container images and a working container from the image. With Buildah, you can create containers and container images in different ways: Container image from scratch You can create minimal container images from scratch with the buildah from scratch command. Minimal container images have the following benefits: Avoid including any unnecessary files or dependencies, enhanced security, and optimized performance. For more information, see Creating images from scratch with Buildah . Containers from a container image You can create a working container from the container image by using the buildah from <image> command. Then you can modify the container by using the buildah mount and buildah copy commands. For more information, see Working with containers using Buildah . Container image from an existing container You can create a new container image by using the bulidah commit command. Optionally, you can push the newly created container image to a container registry by using the buildah push command. For more information, see Working with containers using Buildah . Container image from instructions in a Containerfile You can build a container image from instructions in a Containerfile by using the buildah build or buildah bud commands. For more information, see Building and image from a Containerfile using Buildah . Using Buildah differs from building images with the docker command in the following ways: No Daemon Buildah requires no container runtime daemon. Base image or scratch You can build an image based on another container or start from scratch with an empty image . Reduced image size Buildah images do not include build tools, such as gcc , make , and dnf . As a result, the images are more secure and you can more easily transport the images. Compatibility You can easily migrate from Docker to Buildah because Buildah supports building container images with a Containerfile. You can use the same commands inside a Containerfile as in a Dockerfile . Interactive image building You can build images step-by-step interactively by creating and committing changes to containers. Simplified image creation You can create rootfs , generate JSON files, and build OCI-compliant images with Buildah. Flexibility You can script container builds directly in Bash. Additional resources Building with Buildah: Dockerfiles, command line, or scripts article How rootless Buildah works: Building containers in unprivileged environments article 19.2. Buildah and Podman relationship Buildah is a daemonless tool for building Open Container Initiative (OCI) images. Buildah's commands replicate the commands of a Containerfile . Buildah provides a lower-level interface to build images without requiring a Containerfile . You can also use other scripting languages to build container images. Although you can create containers with Buildah, Buildah containers are primarily created temporarily for the purpose of defining the container image. Podman is a daemonless tool for maintaining and modifying OCI images, such as pulling and tagging. You can create, run, and maintain containers created from those images. Some of the Podman and Buildah commands have the same names but they differ in some aspects: run The podman run command runs a container. The buildah run command is similar to the RUN directive in a Containerfile . commit You can commit Podman containers only with Podman and Buildah containers only with Buildah. rm You can remove Podman containers only with Podman and Buildah containers only with Buildah. Note The default container storage for Buildah is /var/lib/containers/storage for root users and USDHOME/.local/share/containers/storage for non-root users. This is the same as the location the CRI-O container engine uses for storing local copies of images. As a result, the images pulled from a registry by either CRI-O or Buildah, or committed by the buildah command, are stored in the same directory structure. However, even though CRI-O and Buildah currently can share images, they cannot share containers. 19.3. Installing Buildah Install the Buildah tool using the dnf command. Procedure Install the Buildah tool: Verification Display the help message: 19.4. Getting images with Buildah Use the buildah from command to create a new working container from scratch or based on a specified image as a starting point. Prerequisites The container-tools meta-package is installed. Procedure Create a new working container based on the registry.redhat.io/ubi9/ubi image: Verification List all images in local storage: List the working containers and their base images: Additional resources buildah-from , buildah-images , and buildah-containers man pages on your system 19.5. Building an image from a Containerfile with Buildah Use the buildah bud command to build an image using instructions from a Containerfile . Note The buildah bud command uses a Containerfile if found in the context directory, if it is not found the buildah bud command uses a Dockerfile ; otherwise any file can be specified with the --file option. The available commands that are usable inside a Containerfile and a Dockerfile are equivalent. Prerequisites The container-tools meta-package is installed. Procedure Create a Containerfile : Create a myecho script: Change the access permissions of myecho script: Build the myecho image using Containerfile in the current directory: Verification List all images: Run the myecho container based on the localhost/myecho image: List all containers: Note You can use the podman history command to display the information about each layer used in the image. Additional resources buildah-bud man page on your system 19.6. Creating images from scratch with Buildah Instead of starting with a base image, you can create a new container that holds only a minimal amount of container metadata. When creating an image from scratch container, consider: You can copy the executable with no dependencies into the scratch image and make a few configuration settings to get a minimal container to work. You must initialize an RPM database and add a release package in the container to use tools like dnf or rpm . If you add a lot of packages, consider using the standard UBI or minimal UBI images instead of scratch images. Prerequisites The container-tools meta-package is installed. Procedure You can adds a web service httpd to a container and configures it to run. Create an empty container: Mount the working-container container and save the mount point path to the scratchmnt variable: Initialize an RPM database within the scratch image and add the redhat-release package: Install the httpd service to the scratch directory: Create the USDscratchmnt/var/www/html/index.html file: Configure working-container to run the httpd daemon directly from the container: Verification List all images in local storage: Run the localhost/myhttpd image and configure port mappings between the container and the host system: Test the web server: Additional resources buildah-config and buildah-commit man pages on your system 19.7. Removing images with Buildah Use the buildah rmi command to remove locally stored container images. You can remove an image by its ID or name. Prerequisites The container-tools meta-package is installed. Procedure List all images on your local system: Remove the localhost/myecho image: To remove multiple images: To remove all images from your system: To remove images that have multiple names (tags) associated with them, add the -f option to remove them: Verification Ensure that images were removed: Additional resources buildah-rmi man page on your system
dnf -y install buildah buildah -h buildah from registry.access.redhat.com/ubi9/ubi Getting image source signatures Copying blob... Writing manifest to image destination Storing signatures ubi-working-container buildah images REPOSITORY TAG IMAGE ID CREATED SIZE registry.access.redhat.com/ubi9/ubi latest 272209ff0ae5 2 weeks ago 234 MB buildah containers CONTAINER ID BUILDER IMAGE ID IMAGE NAME CONTAINER NAME 01eab9588ae1 * 272209ff0ae5 registry.access.redhat.com/ub... ubi-working-container cat Containerfile FROM registry.access.redhat.com/ubi9/ubi ADD myecho /usr/local/bin ENTRYPOINT "/usr/local/bin/myecho" cat myecho echo "This container works!" chmod 755 myecho buildah bud -t myecho . STEP 1: FROM registry.access.redhat.com/ubi9/ubi STEP 2: ADD myecho /usr/local/bin STEP 3: ENTRYPOINT "/usr/local/bin/myecho" STEP 4: COMMIT myecho Storing signatures buildah images REPOSITORY TAG IMAGE ID CREATED SIZE localhost/myecho latest b28cd00741b3 About a minute ago 234 MB podman run --name=myecho localhost/myecho This container works! podman ps -a 0d97517428d localhost/myecho 12 seconds ago Exited (0) 13 seconds ago myecho buildah from scratch working-container scratchmnt=USD(buildah mount working-container) echo USDscratchmnt /var/lib/containers/storage/overlay/be2eaecf9f74b6acfe4d0017dd5534fde06b2fa8de9ed875691f6ccc791c1836/merged dnf install -y --releasever=8 --installroot=USDscratchmnt redhat-release dnf install -y --setopt=reposdir=/etc/yum.repos.d --installroot=USDscratchmnt --setopt=cachedir=/var/cache/dnf httpd mkdir -p USDscratchmnt/var/www/html echo "Your httpd container from scratch works!" > USDscratchmnt/var/www/html/index.html buildah config --cmd "/usr/sbin/httpd -DFOREGROUND" working-container buildah config --port 80/tcp working-container buildah commit working-container localhost/myhttpd:latest podman images REPOSITORY TAG IMAGE ID CREATED SIZE localhost/myhttpd latest 08da72792f60 2 minutes ago 121 MB podman run -p 8080:80 -d --name myhttpd 08da72792f60 curl localhost:8080 Your httpd container from scratch works! buildah images REPOSITORY TAG IMAGE ID CREATED SIZE localhost/johndoe/webserver latest dc5fcc610313 46 minutes ago 263 MB docker.io/library/mynewecho latest fa2091a7d8b6 17 hours ago 234 MB docker.io/library/myecho2 latest 4547d2c3e436 6 days ago 234 MB localhost/myecho latest b28cd00741b3 6 days ago 234 MB localhost/ubi-micro-httpd latest c6a7678c4139 12 days ago 152 MB registry.access.redhat.com/ubi9/ubi latest 272209ff0ae5 3 weeks ago 234 MB buildah rmi localhost/myecho buildah rmi docker.io/library/mynewecho docker.io/library/myecho2 buildah rmi -a buildah rmi -f localhost/ubi-micro-httpd buildah images