s0sta
EN NL عربي
Filters
How to search
  • Plain words find names, texts and examples.
  • "two words" finds the exact phrase.
  • --name or -x finds an option.
  • #word looks only inside commands.
  • @grep finds lessons and labs that use grep.
  • Filters: cat:network · in:labs · in:notes · level:rhcsa · ch:8 · root:yes. Put ! before a word to leave it out. OR between words means one of them.
  • ↑ ↓ to move · Enter to open · Esc to close · / to search

buildah

Build OCI container images without a Docker daemon — from a Dockerfile or step by step from a script, also rootless in CI.

Level
DevOps tool
Group
Containers and Kubernetes
Needs root
For changes
Package
buildah

What it does

buildah is the image builder of the Red Hat container tools (with podman to run and skopeo to copy images). It needs no daemon and no root, so it is a safe choice in CI runners and Kubernetes pods (no privileged docker-in-docker).

Two ways to work: buildah bud / buildah build reads a Dockerfile (Containerfile); or buildah from, run, copy, config, commit build an image step by step in a shell script.

How to write it

buildah build [OPTIONS] -t NAME[:TAG] [CONTEXT]
buildah from IMAGE → run / copy / config / commit

Main parts

Commands

build, bud
Build from a Containerfile/Dockerfile.
from IMAGE
Start a working container from a base image.
run CTR -- CMD
Run a command in the working container.
copy CTR SRC DEST
Copy files into it.
config --cmd/--env/--port/--user CTR
Set image settings.
commit CTR NAME
Save the working container as an image.
push IMAGE docker://REG/IMAGE
Push to a registry.
images / containers / rm / rmi
List and remove.
login REGISTRY
Log in to a registry.
manifest create/add/push
Multi-arch images.

Options 9

Most used

build options

-t, --tag NAME
Name and tag of the image.
-f, --file FILE
The Containerfile to use.
--build-arg K=V
Build argument.
--layers
Cache layers between builds.
--platform linux/arm64
Build for another CPU.
--format oci|docker
Image format.
--isolation chroot
Simple isolation (works in unprivileged CI pods).
--squash
One layer only.
--pull=always|never
Pull the base image.

Examples 10

$ run as a normal user# run as root (or with sudo)

  1. 1Build from a Dockerfile, rootless

    buildah build -t shop:1.4.0 .
buildah images

  2. 2Push to a registry

    buildah login ghcr.io
buildah push shop:1.4.0 docker://ghcr.io/acme/shop:1.4.0

  3. 3Build step by step in a script

    ctr=$(buildah from registry.access.redhat.com/ubi9/ubi-minimal)
buildah run $ctr -- microdnf -y install nginx
buildah copy $ctr ./site /usr/share/nginx/html
buildah config --port 8080 --user 1001 --cmd "nginx -g 'daemon off;'" $ctr
buildah commit $ctr web:1.0
buildah rm $ctr

  4. 4Build inside an unprivileged GitLab CI job

    cat .gitlab-ci.yml
build:
  image: quay.io/buildah/stable
  script:
    - buildah build --isolation chroot -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA .
    - buildah push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA

  5. 5Use a build argument

    buildah build --build-arg VERSION=1.4.0 -t shop:1.4.0 .

  6. 6Build for ARM

    buildah build --platform linux/arm64 -t shop:1.4.0-arm64 .

  7. 7A multi-arch image

    buildah manifest create shop:1.4.0
buildah build --platform linux/amd64,linux/arm64 --manifest shop:1.4.0 .
buildah manifest push --all shop:1.4.0 docker://ghcr.io/acme/shop:1.4.0

  8. 8Use the layer cache

    buildah build --layers -t shop:dev .

  9. 9List working containers and clean up

    buildah containers
buildah rm --all

  10. 10Images built by buildah are seen by podman

    podman run --rm -p 8080:8080 web:1.0

Watch out

  • Rootless builds need /etc/subuid and /etc/subgid entries for the user.
  • buildah run runs as root inside the container by default; set a non-root --user in the image config.

Files

/etc/containers/registries.conf
Registries and short-name rules.
~/.local/share/containers/
Rootless image storage.

Exit codes

0OK.
1Error.

Full manual

This page explains the command in simple words. The original manual has every detail.

In your terminal: man buildah

Open the man page (linux.die.net)