buildah-pull(1)

💖 buildah-pull(1) 💖

okay bestie, welcome to the General Commands Manual corner where we talk about buildah-pull — yes, that's the one, and no, we're not skipping a single line of it. let's go 🫶

---

✨ NAME ✨

buildah-pull — pull an image from a registry. that's it. that's the whole job. iconic behavior honestly 💅

---

🌸 SYNOPSIS 🌸

buildah pull [options] image

---

🦋 DESCRIPTION 🦋

So basically, buildah pull pulls an image based on whatever input you hand it. It supports all the transports from containers-transports(5) — there's examples down below so you can peek. 👀

If you don't specify a transport, then your input gets subjected to short-name resolution (see containers-registries.conf(5)), and the docker transport — as in, the container registry one — is what gets used. periodt.

🎀 DEPENDENCIES 🎀

Buildah figures out the path to the registry it's pulling from by using the /etc/containers/registries.conf file, aka containers-registries.conf(5).

lowkey important: if buildah pull fails with an "image not known" error, the very first thing you check is whether the registries.conf file is actually installed and configured correctly. do not skip this step bestie, it's literally the first thing to check.

---

💫 RETURN VALUE 💫

It gives you back the image ID of the image that got pulled. 🎉

On error, 1 is returned. 😭

---

💅 OPTIONS 💅

• --all-tags, -a — every single tagged image in the repository gets pulled. all of them. the whole squad. 👑
• --arch="ARCH" — set the ARCH of the image you're pulling to whatever value you give it, instead of just using the architecture of the host. examples: arm, arm64, 386, amd64, ppc64le, s390x.
• --authfile path — the path of the authentication file. default is ${XDG_RUNTIME_DIR}/containers/auth.json. see containers-auth.json(5) for more info. this file is created using buildah login.

If the authorization state isn't found there, then $HOME/.docker/config.json gets checked instead, which is the one set using docker login.

note: you can also override the default path of the authentication file by setting the REGISTRY_AUTH_FILE environment variable. like: export REGISTRY_AUTH_FILE=path

• --cert-dir path — use the certificates at path (*.crt, *.cert, *.key) to connect to the registry. the default certificates directory is /etc/containers/certs.d. 🔐
• --creds creds — the [username[:password]] to use to authenticate with the registry if it's required. if one or both values aren't supplied, a command line prompt pops up and you can enter the value there. the password is entered without echo — so no, you won't see it, that's on purpose. 🙈
• --decryption-key key[:passphrase] — the [key[:passphrase]] to be used for decryption of images. the key can point to keys and/or certificates. decryption will be tried with all keys. if the key is protected by a passphrase, then you're required to pass it in the argument — and omit it otherwise. 🗝️
• --os="OS" — set the OS of the image to be pulled, instead of using the current operating system of the host.
• --platform="OS/ARCH[/VARIANT]" — set the OS/ARCH of the image to be pulled to the value you provide, instead of using the current operating system and architecture of the host (for example linux/arm).

OS/ARCH pairs are those used by the Go Programming Language. in several cases the ARCH value for a platform differs from one produced by other tools, like the arch command. valid OS and architecture name combinations are listed as values for $GOOS and $GOARCH at https://golang.org/doc/install/source#environment, and you can also find them by running go tool dist list.

NOTE: the --platform option may not be used in combination with the --arch, --os, or --variant options. pick a lane bestie 🚫

• --policy=always|missing|never|newer — pull image policy. the default is missing.
  • always: always pull the image and throw an error if the pull fails.
  • missing: pull the image only if it could not be found in the local containers storage. throw an error if no image could be found and the pull fails.
  • never: never pull the image but use the one from the local containers storage. throw an error if no image could be found.
  • newer: pull if the image on the registry is newer than the one in the local containers storage. an image is considered to be newer when the digests are different. comparing the time stamps is prone to errors. pull errors are suppressed if a local image was found.
• --quiet, -q — if an image needs to be pulled from the registry, suppress the progress output. 🤫
• --remove-signatures — don't copy signatures when pulling images.
• --retry attempts — number of times to retry in case of failure when performing a pull of images from a registry.

defaults to 3.

• --retry-delay duration — duration of delay between retry attempts in case of failure when performing a pull of images from a registry.

defaults to 2s.

• --tls-verify bool-value — require HTTPS and verification of certificates when talking to container registries (defaults to true). TLS verification cannot be used when talking to an insecure registry.
• --variant="" — set the architecture variant of the image to be pulled.

---

🌈 EXAMPLE 🌈

buildah pull imagename

buildah pull docker://myregistry.example.com/imagename

buildah pull docker-daemon:imagename:imagetag

buildah pull docker-archive:filename

buildah pull oci-archive:filename

buildah pull dir:directoryname

buildah pull --tls-verify=false
myregistry/myrepository/imagename:imagetag

buildah pull --creds=myusername:mypassword --cert-dir ~/auth
myregistry/myrepository/imagename:imagetag

buildah pull --authfile=/tmp/auths/myauths.json
myregistry/myrepository/imagename:imagetag

buildah pull --arch=aarch64 myregistry/myrepository/imagename:imagetag

buildah pull --arch=arm --variant=v7
myregistry/myrepository/imagename:imagetag

---

🍓 ENVIRONMENT 🍓

• BUILD_REGISTRY_SOURCES — if set, it's treated as a JSON object which contains lists of registry names under the keys insecureRegistries, blockedRegistries, and allowedRegistries.

When pulling an image from a registry, if the name of the registry matches any of the items in the blockedRegistries list, the image pull attempt is denied. And if there are registries in the allowedRegistries list, and the registry's name is not in that list, the pull attempt is also denied. 🚫

• TMPDIR — the TMPDIR environment variable lets you specify where temporary files are stored while pulling and pushing images. defaults to /var/tmp.

---

🧚 FILES 🧚

• registries.conf (/etc/containers/registries.conf)

registries.conf is the configuration file which specifies which container registries should be consulted when completing image names that don't include a registry or domain portion.

• policy.json (/etc/containers/policy.json)

Signature policy file. this defines the trust policy for container images. it controls which container registries can be used for an image, and whether or not the tool should trust the images. 🛡️

---

⭐ SEE ALSO ⭐

buildah(1), buildah-from(1), buildah-login(1), docker-login(1), containers-policy.json(5), containers-registries.conf(5), containers-transports(5), containers-auth.json(5)

---

and that's the whole page bestie, you ate it up 💖 this little love letter was brought to you by buildah, dated July 2018, and yes, it lives in section buildah-pull(1). go pull something cute 🎀✨