DOCSEARCHbyAlgolia
Submit Docs

Buildah Documentation

repository·main·Indexed 27 days ago

https://github.com/podman-container-tools/buildah

Buildah is a specialized tool for building OCI-compliant container images. It provides a low-level interface for image construction via a CLI or Go API without requiring a daemon or root privileges. Key capabilities include building images from scratch, using Dockerfiles, mounting container filesystems for direct manipulation, and integrating as a library into custom build tools.

Tokens
57.5K
Snippets
130
Records
407
Agent score
93%

What's inside Buildah

  1. Overview of Buildah

    main

    Buildah is a tool designed to facilitate building Open Container Initiative (OCI) container images. Unlike traditional container engines, Buildah specializes in the build process, allowing you to create images either from scratch, from an existing image, or via instructions in a Dockerfile/Containerfile.

    Key capabilities include:

    • Creating working containers (from scratch or base images).
    • Building images from working containers or Dockerfiles.
    • Supporting both OCI and traditional upstream Docker image formats.
    • Mounting and unmounting a container's root filesystem for direct manipulation.
    • Using container filesystem contents as layers for new images.
    • Managing local containers and images (rename, delete, etc.).

    Buildah follows a fork-exec model and does not run as a daemon. It can be used without root privileges and provides a comprehensive Go API that can be vendored into other tools.

  2. Overview of Container Tools (Buildah, CRI-O, Podman, Skopeo)

    main

    This guide provides a high-level overview of several open-source projects that operate on Open Container Initiative (OCI) images and containers:

    • Buildah: A tool for creating OCI or traditional Docker images and building working containers. It allows mounting and modifying containers before saving them as images.
    • CRI-O: An implementation of the Kubernetes Container Runtime Interface (CRI) using OCI-conformant runtimes. It manages image formats, downloads, lifecycle, monitoring, and logging for Kubernetes.
    • Podman: A tool for full container lifecycle management (creation through removal). It supports OCI and Docker formats, manages pods, and handles image verification and resource isolation.
    • Skopeo: A command-line tool for inspecting, copying, and deleting images in various container registries and storage mechanisms without requiring a full image pull.

  4. Manage source images with buildah source

    main

    The buildah source command is used to create, push, pull, and manage source images and their associated source artifacts. A source image contains all the artifacts (such as source RPMs, entire source trees, or text files) that an ordinary OCI image was built with.

    Warning: The buildah source command and all its subcommands are currently experimental and may be subject to future changes.

  5. Introduction to building OCI compliant images with Buildah

    main

    Buildah is a tool for building Open Container Initiative (OCI) compliant container images. The introduction tutorial covers:

    • Configure and Setup: How to install and configure Buildah for your environment.
    • Using Dockerfiles: How to build containers using existing Dockerfiles.
    • Building from scratch: How to build containers manually without a Dockerfile by interacting with the container filesystem directly.

  7. Remove and tag a manifest list before pushing

    main

    When renaming or moving a manifest list, use buildah tag to create the new reference, buildah manifest rm to remove the local manifest list, and buildah manifest push --all to push the contents to the destination. Using manifest rm and push --all is critical when handling manifest lists rather than individual images.

    $ buildah tag localhost/shazam example.com/example/shazam
$ buildah manifest rm localhost/shazam
$ buildah manifest push --all example.com/example/shazam

  8. Commit a container to an image

    main

    To save the changes made to a container (files, configuration, etc.) into a permanent image, use buildah commit. It is recommended to unmount the container before committing.

    Workflow:

    1. buildah unmount $newcontainer
    2. buildah commit $newcontainer <image_name>

    Example:

    buildah unmount $newcontainer
buildah commit $newcontainer fedora-bashecho

  9. Set up Buildah in a rootless OpenShift container

    main
    To build images within a rootless OpenShift environment, you must configure the builder container to use chroot isolation and the overlay storage driver. This ensures compatibility where the default runc fails in rootless mode. Additionally, ensure the container's storage is mounted to an emptyDir volume to provide copy-on-write capabilities.

  10. Expose SSH agent to builds with --ssh

    main

    Use --ssh to expose an SSH agent socket or keys to the build process. By default, it uses $SSH_AUTH_SOCK.

    To use the SSH agent inside a RUN instruction, use the --mount=type=ssh flag. If running as a non-root user, you must specify uid or gid in the mount options.

    Example for non-root users:

    USER app
RUN --mount=type=ssh,uid=50000 \
    ssh-add -L