Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarify definition of --pull options #5407

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+45 −41
Open

Clarify definition of --pull options #5407

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
7 changes: 6 additions & 1 deletion cmd/buildah/from.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,12 @@ func init() {
flags.StringVar(&opts.creds, "creds", "", "use `[username[:password]]` for accessing the registry")
flags.StringVarP(&opts.format, "format", "f", defaultFormat(), "`format` of the image manifest and metadata")
flags.StringVar(&opts.name, "name", "", "`name` for the working container")
flags.StringVar(&opts.pull, "pull", "true", "pull images from the registry if newer or not present in store, if false, only pull images if not present, if always, pull images even if the named images are present in store, if never, only use images present in store if available")
flags.StringVar(&opts.pull, "pull", "missing", `pull images from the registry values:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The commit log and PR description don't mention this change in the default. It seems important.

always: pull images even if the named images are present in store,
missing: pull images if the named images are not present in store,
never: only use images present in store if available,
newer: only pull images when newer images exist on the registry than those in the store.`)

flags.Lookup("pull").NoOptDefVal = "true" //allow `--pull ` to be set to `true` as expected.

flags.BoolVar(&opts.pullAlways, "pull-always", false, "pull the image even if the named image is present in store")
Expand Down
42 changes: 17 additions & 25 deletions docs/buildah-build.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -746,31 +746,23 @@ The `buildah build` command allows building images for all Linux architectures,

**--pull**

When the *--pull* flag is enabled or set explicitly to `true` (with
*--pull=true*), attempt to pull the latest versions of base and SBOM scanner
images from the registries listed in registries.conf if a local base or SBOM
scanner image does not exist or the image in the registry is newer than the one
in local storage. Raise an error if the base or SBOM scanner image is not in
any listed registry and is not present locally.

If the flag is disabled (with *--pull=false*), do not pull base and SBOM
scanner images from registries, use only local versions. Raise an error if a
base or SBOM scanner image is not present locally.

If the pull flag is set to `always` (with *--pull=always*), pull base and SBOM
scanner images from the registries listed in registries.conf. Raise an error
if a base or SBOM scanner image is not found in the registries, even if an
image with the same name is present locally.

If the pull flag is set to `missing` (with *--pull=missing*), pull base and
SBOM scanner images only if they could not be found in the local containers
storage. Raise an error if no image could be found and the pull fails.

If the pull flag is set to `never` (with *--pull=never*), do not pull base and
SBOM scanner images from registries, use only the local versions. Raise an
error if the image is not present locally.

Defaults to *true*.
Pull image policy. The default is **missing**.

- **always**: Pull base and SBOM scanner images from the registries listed in
registries.conf. Raise an error if a base or SBOM scanner image is not found
in the registries, even if an image with the same name is present locally.

- **missing**: SBOM scanner images only if they could not be found in the local
containers storage. Raise an error if no image could be found and the pull
fails.

- **never**: Do not pull base and SBOM scanner images from registries, use only
the local versions. Raise an error if the image is not present locally.

- **newer**: Pull base and SBOM scanner images from the registries listed in
registries.conf if newer. Raise an error if a base or SBOM scanner image is
not found in the registries when image with the same name is not present
locally.

**--quiet**, **-q**

Expand Down
27 changes: 13 additions & 14 deletions docs/buildah-from.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -388,24 +388,23 @@ the help of emulation provided by packages like `qemu-user-static`.

**--pull**

When the flag is enabled or set explicitly to `true` (with *--pull=true*), attempt to pull the latest image from the registries
listed in registries.conf if a local image does not exist or the image is newer
than the one in storage. Raise an error if the image is not in any listed
registry and is not present locally.
Pull image policy. The default is **missing**.

If the flag is disabled (with *--pull=false*), do not pull the image from the
registry, use only the local version. Raise an error if the image is not
present locally.
- **always**: Pull base and SBOM scanner images from the registries listed in
registries.conf. Raise an error if a base or SBOM scanner image is not found
in the registries, even if an image with the same name is present locally.

If the pull flag is set to `always` (with *--pull=always*),
pull the image from the first registry it is found in as listed in registries.conf.
Raise an error if not found in the registries, even if the image is present locally.
- **missing**: SBOM scanner images only if they could not be found in the local
containers storage. Raise an error if no image could be found and the pull
fails.

If the pull flag is set to `never` (with *--pull=never*),
Do not pull the image from the registry, use only the local version. Raise an error
if the image is not present locally.
- **never**: Do not pull base and SBOM scanner images from registries, use only
the local versions. Raise an error if the image is not present locally.

Defaults to *true*.
- **newer**: Pull base and SBOM scanner images from the registries listed in
registries.conf if newer. Raise an error if a base or SBOM scanner image is
not found in the registries when image with the same name is not present
locally.

**--quiet**, **-q**

Expand Down
6 changes: 5 additions & 1 deletion pkg/cli/common.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -263,7 +263,11 @@ func GetBudFlags(flags *BudResults) pflag.FlagSet {
fs.String("os", runtime.GOOS, "set the OS to the provided value instead of the current operating system of the host")
fs.StringArrayVar(&flags.OSFeatures, "os-feature", []string{}, "set required OS `feature` for the target image in addition to values from the base image")
fs.StringVar(&flags.OSVersion, "os-version", "", "set required OS `version` for the target image instead of the value from the base image")
fs.StringVar(&flags.Pull, "pull", "true", "pull base and SBOM scanner images from the registry if newer or not present in store, if false, only pull base and SBOM scanner images if not present, if always, pull base and SBOM scanner images even if the named images are present in store, if never, only use images present in store if available")
fs.StringVar(&flags.Pull, "pull", "missing", `pull base and SBOM scanner images from the registry. Values:
always: pull base and SBOM scanner images even if the named images are present in store.
missing: pull base and SBOM scanner images if the named images are not present in store.
never: only use images present in store if available.
newer: only pull base and SBOM scanner images when newer images exist on the registry than those in the store.`)
fs.Lookup("pull").NoOptDefVal = "true" //allow `--pull ` to be set to `true` as expected.
fs.BoolVar(&flags.PullAlways, "pull-always", false, "pull the image even if the named image is present in store")
if err := fs.MarkHidden("pull-always"); err != nil {
Expand Down
4 changes: 4 additions & 0 deletions tests/from.bats
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,10 @@ load helpers
run_buildah from --pull=false $WITH_POLICY_JSON scratch3
expect_output --substring "scratch3-working-container"
run_buildah rm $output
# Set --pull=never to prevent looking for a newer scratch3 image.
run_buildah from --pull=never $WITH_POLICY_JSON scratch3
nalind marked this conversation as resolved.
Show resolved Hide resolved
expect_output --substring "scratch3-working-container"
run_buildah rm $output
run_buildah rmi scratch2 scratch3

# GitHub https://github.com/containers/buildah/issues/396#issuecomment-360949396
Expand Down