2018-07-28 05:51:37 +08:00
# buildah-pull "1" "July 2018" "buildah"
## NAME
2019-04-24 19:51:03 +08:00
buildah\-pull - Pull an image from a registry.
2018-07-28 05:51:37 +08:00
## SYNOPSIS
**buildah pull** [*options*] *image*
## DESCRIPTION
2021-06-23 16:35:06 +08:00
Pulls an image based upon the specified input. It supports all transports from `containers-transports(5)` (see examples below). If no transport is specified, the input is subject to short-name resolution (see `containers-registries.conf(5)` ) and the `docker` (i.e., container registry) transport is used.
2018-07-28 05:51:37 +08:00
### DEPENDENCIES
Buildah resolves the path to the registry to pull from by using the /etc/containers/registries.conf
2020-01-08 01:23:23 +08:00
file, containers-registries.conf(5). If the `buildah pull` command fails with an "image not known" error,
2018-07-28 05:51:37 +08:00
first verify that the registries.conf file is installed and configured appropriately.
## RETURN VALUE
The image ID of the image that was pulled. On error 1 is returned.
## OPTIONS
New CI check: xref --help vs man pages
Run 'buildah --help', recursively against all subcommands,
then cross-reference the results against docs/buildah*.md.
Report differences in subcommands and/or flags.
The majority of the changes in this PR are trivial (see
below) but a handful may be controversial and require
careful review:
* Making 'bud' the default output of 'buildah help',
with 'build-using-dockerfile' as an alias. This is
the inverse of the situation until now: buildah
would list build-using-dockerfile as the primary
name. The man page, OTOH, lists 'bud'. The source
file name is 'bud'. I suspect that most people
type 'bud'. So, for consistency, I choose to make
'bud' the default visible command.
* add --encryption-key and --encrypt-layer documentation
to buildah-commit.md, and --encrypt-layer to -push.md.
Please double-check the wording here.
* remove --notruncate from buildah-images.md. The option
does not exist (although there is a TODO comment in
the code). If it should exist, it is left to the
reader to implement. I would humbly suggest that this
is a good idea, for consistency with buildah containers.
* remove --shm-size from buildah-pull.md. The option
does not exist, and I suspect this was a copy-paste error.
* remove --security-opt from run.go. It was unimplemented
and undocumented.
* remove --userns-[gu]id-map from buildah-bud.md. These
are global options, not bud options, and are documented
well enough in buildah.bud.
Trivial (IMO) changes:
* split options in man pages, from '**--foo, -f**'
to '**--foo**, **-f**'. This conforms with the style
used in podman man pages.
* add missing one-letter aliases (usually "-q", "-a")
* add missing man page entries for some easy options
* sort out-of-order subcommand listings in man pages
Finally, do note that this is a copy-and-alter duplicate of the
original script in podman, and that is horrible. In an ideal
world I would've been able to refactor the podman version into
something usable on both repos (and then more). It turns out the
differences in man page format and in special-case handling are
too broad to let me do a clean refactor.
Signed-off-by: Ed Santiago <santiago@redhat.com>
2020-09-21 22:51:19 +08:00
**--all-tags**, ** -a**
2019-01-07 15:06:36 +08:00
All tagged images in the repository will be pulled.
2020-12-23 05:12:38 +08:00
**--arch**="ARCH"
bud: teach --platform to take a list
Add a pkg/parse.PlatformsFromOptions() which understands a "variant"
value as an optional third value in an OS/ARCH[/VARIANT] argument value,
which accepts a comma-separated list of them, and which returns a list
of platforms.
Teach "from" and "pull" about the --platform option and add integration
tests for them, warning if --platform was given multiple values.
Add a define.BuildOptions.JobSemaphore which an imagebuildah executor
will use in preference to one that it might allocate for itself.
In main(), allocate a JobSemaphore if the number of jobs is not 0 (which
we treat as "unlimited", and continue to allow executors to do).
In addManifest(), take a lock on the manifest list's image ID so that we
don't overwrite changes that another thread might be making while we're
attempting to make changes to it. In main(), create an empty list if
the list doesn't already exist before we start down this path, so that
we don't get two threads trying to create that manifest list at the same
time later on. Two processes could still try to create the same list
twice, but it's an incremental improvement.
Finally, if we've been given multiple platforms to build for, run their
builds concurrently and gather up their results.
Signed-off-by: Nalin Dahyabhai <nalin@redhat.com>
2021-06-22 22:52:49 +08:00
Set the ARCH of the image to be pulled to the provided value instead of using the architecture of the host. (Examples: arm, arm64, 386, amd64, ppc64le, s390x)
2020-12-23 05:12:38 +08:00
2018-07-28 05:51:37 +08:00
**--authfile** *path*
2024-01-26 04:50:33 +08:00
Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/containers/auth.json. See containers-auth.json(5) for more information. This file is created using `buildah login` .
2021-04-30 03:36:15 +08:00
2018-07-28 05:51:37 +08:00
If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login` .
2021-04-30 03:36:15 +08:00
Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
environment variable. `export REGISTRY_AUTH_FILE=path`
2018-07-28 05:51:37 +08:00
**--cert-dir** *path*
Use 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 required.
If one or both values are not supplied, a command line prompt will appear and the
value can be entered. The password is entered without echo.
2020-05-20 03:12:29 +08:00
**--decryption-key** *key[:passphrase]*
2020-04-02 02:15:56 +08:00
2020-08-11 17:28:41 +08:00
The [key[:passphrase]] to be used for decryption of images. Key can point to keys and/or certificates. Decryption will be tried with all keys. If the key is protected by a passphrase, it is required to be passed in the argument and omitted otherwise.
2020-04-02 02:15:56 +08:00
2020-12-23 05:12:38 +08:00
**--os**="OS"
Set the OS of the image to be pulled instead of using the current operating system of the host.
bud: teach --platform to take a list
Add a pkg/parse.PlatformsFromOptions() which understands a "variant"
value as an optional third value in an OS/ARCH[/VARIANT] argument value,
which accepts a comma-separated list of them, and which returns a list
of platforms.
Teach "from" and "pull" about the --platform option and add integration
tests for them, warning if --platform was given multiple values.
Add a define.BuildOptions.JobSemaphore which an imagebuildah executor
will use in preference to one that it might allocate for itself.
In main(), allocate a JobSemaphore if the number of jobs is not 0 (which
we treat as "unlimited", and continue to allow executors to do).
In addManifest(), take a lock on the manifest list's image ID so that we
don't overwrite changes that another thread might be making while we're
attempting to make changes to it. In main(), create an empty list if
the list doesn't already exist before we start down this path, so that
we don't get two threads trying to create that manifest list at the same
time later on. Two processes could still try to create the same list
twice, but it's an incremental improvement.
Finally, if we've been given multiple platforms to build for, run their
builds concurrently and gather up their results.
Signed-off-by: Nalin Dahyabhai <nalin@redhat.com>
2021-06-22 22:52:49 +08:00
**--platform**="OS/ARCH[/VARIANT]"
Set the OS/ARCH of the image to be pulled
to the provided value instead of using the current operating system and
2021-10-11 00:26:45 +08:00
architecture of the host (for example `linux/arm` ).
2020-12-30 20:16:24 +08:00
bud: teach --platform to take a list
Add a pkg/parse.PlatformsFromOptions() which understands a "variant"
value as an optional third value in an OS/ARCH[/VARIANT] argument value,
which accepts a comma-separated list of them, and which returns a list
of platforms.
Teach "from" and "pull" about the --platform option and add integration
tests for them, warning if --platform was given multiple values.
Add a define.BuildOptions.JobSemaphore which an imagebuildah executor
will use in preference to one that it might allocate for itself.
In main(), allocate a JobSemaphore if the number of jobs is not 0 (which
we treat as "unlimited", and continue to allow executors to do).
In addManifest(), take a lock on the manifest list's image ID so that we
don't overwrite changes that another thread might be making while we're
attempting to make changes to it. In main(), create an empty list if
the list doesn't already exist before we start down this path, so that
we don't get two threads trying to create that manifest list at the same
time later on. Two processes could still try to create the same list
twice, but it's an incremental improvement.
Finally, if we've been given multiple platforms to build for, run their
builds concurrently and gather up their results.
Signed-off-by: Nalin Dahyabhai <nalin@redhat.com>
2021-06-22 22:52:49 +08:00
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 such as
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 can also be found by running `go tool dist list` .
2020-12-30 20:16:24 +08:00
2021-10-11 00:26:45 +08:00
**NOTE:** The `--platform` option may not be used in combination with the `--arch` , `--os` , or `--variant` options.
2022-07-07 22:29:43 +08:00
**--policy**=**always**|**missing**|**never**|**newer**
2020-11-10 19:58:31 +08:00
Pull image policy. The default is **missing** .
2022-07-07 22:29:43 +08:00
- **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.
2020-11-10 19:58:31 +08:00
2022-03-24 20:03:06 +08:00
**--quiet**, ** -q**
If an image needs to be pulled from the registry, suppress progress output.
2020-01-16 01:23:38 +08:00
**--remove-signatures**
Don't copy signatures when pulling images.
2022-08-22 14:46:39 +08:00
**--retry** *attempts*
Number of times to retry in case of failure when performing pull of images from registry.
Defaults to `3` .
**--retry-delay** *duration*
Duration of delay between retry attempts in case of failure when performing pull of images from registry.
Defaults to `2s` .
2018-07-28 05:51:37 +08:00
**--tls-verify** *bool-value*
2020-12-30 20:16:24 +08:00
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.
2018-07-28 05:51:37 +08:00
2020-12-23 05:12:38 +08:00
**--variant**=""
Set the architecture variant of the image to be pulled.
2018-07-28 05:51:37 +08:00
## 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
2020-12-23 05:12:38 +08:00
buildah pull --arch=aarch64 myregistry/myrepository/imagename:imagetag
buildah pull --arch=arm --variant=v7 myregistry/myrepository/imagename:imagetag
2019-08-13 12:23:28 +08:00
## ENVIRONMENT
2018-07-28 05:51:37 +08:00
2019-08-13 12:23:28 +08:00
**BUILD\_REGISTRY\_SOURCES**
BUILD\_REGISTRY\_SOURCES, if set, is 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.
If there are registries in the `allowedRegistries` list, and the registry's
name is not in the list, the pull attempt is denied.
2019-12-18 00:01:52 +08:00
**TMPDIR**
The TMPDIR environment variable allows the user to specify where temporary files
are stored while pulling and pushing images. Defaults to '/var/tmp'.
2019-08-13 12:23:28 +08:00
## FILES
2018-07-28 05:51:37 +08:00
**registries.conf** (`/etc/containers/registries.conf`)
registries.conf is the configuration file which specifies which container registries should be consulted when completing image names which do not include a registry or domain portion.
2019-02-27 23:29:09 +08:00
**policy.json** (`/etc/containers/policy.json`)
Signature policy file. This defines the trust policy for container images. Controls which container registries can be used for image, and whether or not the tool should trust the images.
2018-07-28 05:51:37 +08:00
## SEE ALSO
2024-01-26 04:50:33 +08:00
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)
