buildah-add(1)

📦
version 1.45.0 · 9 versions
, in centos-stream 10

💅 buildah-add — the add-to-container glow-up

Hey bestie, welcome to buildah-add(1) — part of the buildah manual, and honestly? She's kind of a big deal. This is the command that yeets files, URLs, and whole directories straight into your container, no cap. Let's get into it ✨

🌸 SYNOPSIS 🌸

buildah add [options] container src [[src ...] dest]

That's the whole vibe: you got options, you got your container, you got one or more src things, and optionally a dest. Easy. 🫶

🦋 DESCRIPTION 🦋

Okay so what does she actually do? buildah add takes the contents of a file, a URL, or a directory and drops them into a container's working directory — or into whatever specific location in the container you point at. Main character energy, she goes where you tell her. 💅

Two things to know, and they're lowkey important:

  • If a local source file looks like an archive, she doesn't just copy the archive — she extracts its contents and adds those instead. Surprise! 🎁
  • If a local directory is your source, its contents get copied to the destination.

No guessing, that's just how it works, fr fr.

✨ OPTIONS ✨

  • --add-history — Adds a history entry noting the digest of the added content. Defaults to false. 📝
Note: you can also override the default value of --add-history by setting the BUILDAH_HISTORY environment variable: export BUILDAH_HISTORY=true
  • --allow-empty-wildcard — If set to true, she won't throw an error when globbing matches literally nothing. Only meaningful when --allow-wildcard is true. Defaults to false. 🙈
  • --allow-wildcard — Lets you use glob patterns in source paths. When set to false, source paths containing wildcard characters (*, ?, [) get rejected with an error. Defaults to true. 🎯
  • --cert-dir path — Uses the certificates at path (*.crt, *.cert, *.key) when connecting to registries to pull images named with the --from flag, and when connecting to HTTPS servers while fetching sources from locations specified with HTTPS URLs. The default certs directory is /etc/containers/certs.d. 🔐
  • --checksum checksum — Checksums the source content. The value of checksum has to be a standard container digest string. Only supported for HTTP sources, bestie. 🧾
  • --chmod permissions — Sets the access permissions of the destination content. Takes numerical or symbolic format. 👑
  • --chown owner:group — Sets the user and group ownership of the destination content. 🫶
  • --contextdir directory — Build context directory. Specifying one makes Buildah chroot into that context directory — which means copying files pointed at by symlinks outside of the chroot will fail. Fair warning. 💀
  • --exclude pattern — Excludes files matching the specified pattern from being copied. You can pass this option multiple times. Patterns are matched against each file's path relative to the context directory (or, with --from, relative to the source container or image root). See containerignore(5) for the supported formats. 🌈
  • --from containerOrImage — Uses the root directory of the specified working container or image as the root directory when resolving absolute source paths and the path of the context directory. If an image needs to be pulled, options recognized by buildah pull can be used. 🚀
  • --ignorefile file — Path to an alternative .containerignore (.dockerignore) file. Requires --contextdir to be specified. 📄
  • --link — Creates an independent image layer for the added files instead of modifying the working container's filesystem. Real talk: if buildah run creates a file and buildah add --link adds a file to the same path, the file from buildah add --link is the one that shows up in the committed image. The --link layer gets applied after all container filesystem changes at commit time. 🔥
  • --no-follow-symlinks — When a local source is a symbolic link, copies the link as a symbolic link instead of dereferencing it and copying the contents of the target. 🪞
  • --quiet, -q — Refrains from printing a digest of the added content. Shhh. 🤫
  • --retry attempts — Number of times to retry on failure when pulling images from registries or retrieving content from HTTPS URLs. Defaults to 3. 🔁
  • --retry-delay duration — Duration of delay between retry attempts on failure when pulling images from registries or retrieving content from HTTPS URLs. Defaults to 2s. ⏳
  • --timestamp seconds — Sets the timestamp ("mtime") for added content to exactly this number of seconds since the epoch (Unix time 0, i.e., 00:00:00 UTC on 1 January 1970) to help allow for deterministic builds. ⭐

Heads up though: the destination directory the content is being copied into will most likely reflect the time at which the content was added to it. So don't be shocked. 😭

  • --tls-verify bool-value — Requires verification of certificates when retrieving sources from HTTPS locations, or when pulling images referred to with the --from* flag (defaults to true). Important: TLS verification cannot be used when talking to an insecure registry. 🛡️

🧚 EXAMPLE 🧚

Some iconic little demos, go off bestie:

buildah add containerID '/myapp/app.conf' '/myapp/app.conf'

buildah add --chown myuser:mygroup containerID '/myapp/app.conf' '/myapp/app.conf'

buildah add --chmod 660 containerID '/myapp/app.conf' '/myapp/app.conf'

buildah add containerID '/home/myuser/myproject.go'

buildah add containerID '/home/myuser/myfiles.tar' '/tmp'

buildah add containerID '/tmp/workingdir' '/tmp/workingdir'

buildah add containerID 'https://github.com/containers/buildah/blob/main/README.md' '/tmp'

buildah add containerID 'passwd' 'certs.d' /etc

buildah add containerID '/tmp/myfiles-*' '/dest/'

buildah add --allow-empty-wildcard=true containerID '/tmp/logs-*' '/dest/'

🍓 FILES 🍓

.containerignore or .dockerignore

If a .containerignore or .dockerignore file exists in the context directory, buildah add reads its contents. And if both exist? .containerignore wins, obviously. 👑

When the --ignorefile option is specified, Buildah reads that file and uses it to decide which content to exclude when copying content into the working container.

You can drop a series of Unix shell glob patterns in an ignore file to identify files/directories to exclude. Very cute, very useful. 💖

Buildah also supports a special wildcard string ** which matches any number of directories (including zero). For example, */.go will exclude all files that end with .go that are found in all directories.

Example .containerignore/.dockerignore file:

# here are files we want to exclude
*/*.c
**/output*
src

Breaking that down, because we love clarity:

  • */*.c — Excludes files and directories whose names end with .c in any top level subdirectory. For example, the source file include/rootless.c. 🧐
  • **/output* — Excludes files and directories starting with output from any directory. 📂
  • src — Excludes files named src and the directory src, plus any content in it. 💀

Lines starting with ! (exclamation mark) can be used to make exceptions to exclusions. The following is an example .containerignore file that uses this mechanism:

*.doc
!Help.doc

That one excludes all doc files except Help.doc when copying content into the container. Not me making an exception for the one file that ate. 💅

This functionality is compatible with the handling of .containerignore files described here:

https://github.com/containers/common/blob/main/docs/containerignore.5.md

🌟 SEE ALSO 🌟

buildah(1), containerignore(5)

And that's the whole page, bestie! 🎀 This gem comes to you from the buildah manual, dated April 2021, and you just read buildah-add(1) — go forth and add things to containers, you absolute icon. 💜🦋

📦 where this page comes from