Categorygithub.com/containers/buildah
modulepackage
1.39.0
Repository: https://github.com/containers/buildah.git
Documentation: pkg.go.dev
Versions
2
Dependencies
112
Dependents
134
Files
9.4k SLOC

# README

buildah logo (light) buildah logo (dark)

Buildah - a tool that facilitates building Open Container Initiative (OCI) container images

Go Report Card

The Buildah package provides a command line tool that can be used to

  • create a working container, either from scratch or using an image as a starting point
  • create an image, either from a working container or via the instructions in a Dockerfile
  • images can be built in either the OCI image format or the traditional upstream docker image format
  • mount a working container's root filesystem for manipulation
  • unmount a working container's root filesystem
  • use the updated contents of a container's root filesystem as a filesystem layer to create a new image
  • delete a working container or an image
  • rename a local container

Buildah Information for Developers

For blogs, release announcements and more, please checkout the buildah.io website!

Buildah Container Images

Buildah Demos

Changelog

Contributing

Development Plan

Installation notes

Troubleshooting Guide

Tutorials

Buildah and Podman relationship

Buildah and Podman are two complementary open-source projects that are available on most Linux platforms and both projects reside at GitHub.com with Buildah here and Podman here. Both, Buildah and Podman are command line tools that work on Open Container Initiative (OCI) images and containers. The two projects differentiate in their specialization.

Buildah specializes in building OCI images. Buildah's commands replicate all of the commands that are found in a Dockerfile. This allows building images with and without Dockerfiles while not requiring any root privileges. Buildah’s ultimate goal is to provide a lower-level coreutils interface to build images. The flexibility of building images without Dockerfiles allows for the integration of other scripting languages into the build process. Buildah follows a simple fork-exec model and does not run as a daemon but it is based on a comprehensive API in golang, which can be vendored into other tools.

Podman specializes in all of the commands and functions that help you to maintain and modify OCI images, such as pulling and tagging. It also allows you to create, run, and maintain those containers created from those images. For building container images via Dockerfiles, Podman uses Buildah's golang API and can be installed independently from Buildah.

A major difference between Podman and Buildah is their concept of a container. Podman allows users to create "traditional containers" where the intent of these containers is to be long lived. While Buildah containers are really just created to allow content to be added back to the container image. An easy way to think of it is the buildah run command emulates the RUN command in a Dockerfile while the podman run command emulates the docker run command in functionality. Because of this and their underlying storage differences, you can not see Podman containers from within Buildah or vice versa.

In short, Buildah is an efficient way to create OCI images while Podman allows you to manage and maintain those images and containers in a production environment using familiar container cli commands. For more details, see the Container Tools Guide.

Example

From ./examples/lighttpd.sh:

$ cat > lighttpd.sh <<"EOF"
#!/usr/bin/env bash

set -x

ctr1=$(buildah from "${1:-fedora}")

## Get all updates and install our minimal httpd server
buildah run "$ctr1" -- dnf update -y
buildah run "$ctr1" -- dnf install -y lighttpd

## Include some buildtime annotations
buildah config --annotation "com.example.build.host=$(uname -n)" "$ctr1"

## Run our server and expose the port
buildah config --cmd "/usr/sbin/lighttpd -D -f /etc/lighttpd/lighttpd.conf" "$ctr1"
buildah config --port 80 "$ctr1"

## Commit this container to an image name
buildah commit "$ctr1" "${2:-$USER/lighttpd}"
EOF

$ chmod +x lighttpd.sh
$ ./lighttpd.sh

Commands

CommandDescription
buildah-add(1)Add the contents of a file, URL, or a directory to the container.
buildah-build(1)Build an image using instructions from Containerfiles or Dockerfiles.
buildah-commit(1)Create an image from a working container.
buildah-config(1)Update image configuration settings.
buildah-containers(1)List the working containers and their base images.
buildah-copy(1)Copies the contents of a file, URL, or directory into a container's working directory.
buildah-from(1)Creates a new working container, either from scratch or using a specified image as a starting point.
buildah-images(1)List images in local storage.
buildah-info(1)Display Buildah system information.
buildah-inspect(1)Inspects the configuration of a container or image.
buildah-mount(1)Mount the working container's root filesystem.
buildah-pull(1)Pull an image from the specified location.
buildah-push(1)Push an image from local storage to elsewhere.
buildah-rename(1)Rename a local container.
buildah-rm(1)Removes one or more working containers.
buildah-rmi(1)Removes one or more images.
buildah-run(1)Run a command inside of the container.
buildah-tag(1)Add an additional name to a local image.
buildah-umount(1)Unmount a working container's root file system.
buildah-unshare(1)Launch a command in a user namespace with modified ID mappings.
buildah-version(1)Display the Buildah Version Information

Future goals include:

  • more CI tests
  • additional CLI commands (?)

# Packages

This package is deprecated.

# Functions

CWConvertImage takes the rootfs and configuration from one image, generates a LUKS-encrypted disk image that more or less includes them both, and puts the result into a new container image.
DefaultNamespaceOptions returns the default namespace settings from the runtime-tools generator library.
GetBuildInfo gets a pointer to a Builder object and returns a BuilderInfo object from it.
ImportBuilder creates a new build configuration using an already-present container.
ImportBuilderFromImage creates a new builder configuration using an image.
Info returns the store and host information.
InitReexec is a wrapper for reexec.Init().
IsContainer identifies if the specified container id is a buildah container in the specified store.
NewBuilder creates a new build container.
OpenAllBuilders loads all containers which have a state file that we use in their data directory, typically so that they can be listed.
OpenBuilder loads information about a build container given its name or ID.
OpenBuilderByPath loads information about a build container given a path to the container's root filesystem.
Pull copies the contents of the image from somewhere else to local storage.
Push copies the contents of the image to a new location.
ReserveSELinuxLabels reads containers storage and reserves SELinux contexts which are already being used by buildah containers.

# Constants

BaseImageFakeName is the "name" of a source image which we interpret as "no image".
BuilderIdentityAnnotation is the name of the annotation key containing the name and version of the producer of the image stored as an annotation on commit.
DefaultTerminal indicates that this Run invocation should be connected to a pseudoterminal if we're connected to a terminal.
DOCKER used to define the "docker" image format.
Dockerv2ImageManifest is the MIME type of a Docker v2s2 image manifest, suitable for specifying as a value of the PreferredManifestType member of a CommitOptions structure.
IsolationChroot is a more chroot-like environment: less isolation, but with fewer requirements.
IsolationDefault is whatever we think will work best.
IsolationOCI is a proper OCI runtime.
IsolationOCIRootless is a proper OCI runtime in rootless mode.
NetworkDefault is one of the values that BuilderOptions.ConfigureNetwork can take, signalling that the default behavior should be used.
NetworkDisabled is one of the values that BuilderOptions.ConfigureNetwork can take, signalling that network interfaces should NOT be configured for newly-created network namespaces.
NetworkEnabled is one of the values that BuilderOptions.ConfigureNetwork can take, signalling that network interfaces should be configured for newly-created network namespaces.
OCI used to define the "oci" image format.
OCIv1ImageManifest is the MIME type of an OCIv1 image manifest, suitable for specifying as a value of the PreferredManifestType member of a CommitOptions structure.
Package is the name of this package, used in help output and to identify working containers.
PullAlways is one of the values that BuilderOptions.PullPolicy can take, signalling that a fresh, possibly updated, copy of the image should be pulled from a registry before the build proceeds.
PullIfMissing is one of the values that BuilderOptions.PullPolicy can take, signalling that the source image should be pulled from a registry if a local copy of it is not already present.
PullIfNewer is one of the values that BuilderOptions.PullPolicy can take, signalling that the source image should only be pulled from a registry if a local copy is not already present or if a newer version the image is present on the repository.
PullNever is one of the values that BuilderOptions.PullPolicy can take, signalling that the source image should not be pulled from a registry if a local copy of it is not already present.
Version for the Package.
WithoutTerminal indicates that this Run invocation should NOT be connected to a pseudoterminal.
WithTerminal indicates that this Run invocation should be connected to a pseudoterminal.

# Structs

AddAndCopyOptions holds options for add and copy commands.
Builder objects are used to represent containers which are being used to build images.
BuilderInfo are used as objects to display container information.
BuilderOptions are used to initialize a new Builder.
CommitOptions can be used to alter how an image is committed.
CompositeDigester can compute a digest over multiple items.
CWConvertImageOptions provides both required and optional bits of configuration for CWConvertImage().
ExtractRootfsOptions is consumed by ExtractRootfs() which allows users to control whether various information like the like setuid and setgid bits and xattrs are preserved when extracting file system objects.
IDMaps are the UIDs, GID, and maps for the run.
ImportFromImageOptions are used to initialize a Builder from an image.
ImportOptions are used to initialize a Builder from an existing container which was created elsewhere.
InfoData holds the info type, i.e store, host etc and the data for each type.
LinkedLayer combines a history entry with the location of either a directory tree (if it's a directory, per os.Stat()) or an uncompressed layer blob which should be added to the image at commit-time.
PullOptions can be used to alter how an image is copied in from somewhere.
PushOptions can be used to alter how an image is copied somewhere.
RunOptions can be used to alter how a command is run in the container.

# Type aliases

CommonBuildOptions are resources that can be defined by flags for both buildah from and build.
ConfidentialWorkloadOptions encapsulates options which control whether or not we output an image whose rootfs contains a LUKS-compatibly-encrypted disk image instead of the usual rootfs contents.
IDMappingOptions controls how we set up UID/GID mapping when we set up a user namespace.
Isolation provides a way to specify whether we're supposed to use a proper OCI runtime, or some other method for running commands.
NamespaceOption controls how we set up a namespace when launching processes.
NamespaceOptions provides some helper methods for a slice of NamespaceOption structs.
NetworkConfigurationPolicy takes the value NetworkDefault, NetworkDisabled, or NetworkEnabled.
PullPolicy takes the value PullIfMissing, PullAlways, PullIfNewer, or PullNever.
SBOMScanOptions encapsulates options which control whether or not we run a scanner on the rootfs that we're about to commit, and how.
TerminalPolicy takes the value DefaultTerminal, WithoutTerminal, or WithTerminal.