diff --git a/content/build/attestations/_index.md b/content/build/attestations/_index.md index 7abc7c2a06b6..1f57d6181823 100644 --- a/content/build/attestations/_index.md +++ b/content/build/attestations/_index.md @@ -64,7 +64,7 @@ $ docker buildx build --sbom=true --provenance=true . > > Provenance attestations are enabled by default, with the `mode=min` option. > You can disable provenance attestations using the `--provenance=false` flag, -> or by setting the [`BUILDX_NO_DEFAULT_ATTESTATIONS`](../building/env-vars.md#buildx_no_default_attestations) environment variable. +> or by setting the [`BUILDX_NO_DEFAULT_ATTESTATIONS`](../building/variables.md#buildx_no_default_attestations) environment variable. > > Using the `--provenance=true` flag attaches provenance attestations with `mode=max` > by default. See [Provenance attestation](./slsa-provenance.md) for more details. diff --git a/content/build/builders/_index.md b/content/build/builders/_index.md index ed2b30b35e13..15907cd28655 100644 --- a/content/build/builders/_index.md +++ b/content/build/builders/_index.md @@ -41,7 +41,7 @@ build commands. When you run a build, or interact with builders in some way using the CLI, you can use the optional `--builder` flag, or the `BUILDX_BUILDER` -[environment variable](../building/env-vars.md#buildx_builder), +[environment variable](../building/variables.md#buildx_builder), to specify a builder by name. If you don't specify a builder, the selected builder is used. diff --git a/content/build/building/env-vars.md b/content/build/building/env-vars.md deleted file mode 100644 index 769dcdf798ab..000000000000 --- a/content/build/building/env-vars.md +++ /dev/null @@ -1,253 +0,0 @@ ---- -title: Environment variables for Docker Build -description: Use environment variables to configure builds -keywords: docker build, buildx, buildkit, env, environment variables, config -aliases: -- /build/buildkit/color-output-controls/ ---- - -You can set the following environment variables to enable, disable, or change -the behavior of features related to building: - -| Variable | Type | Description | -| --------------------------------------------------------------------------- | ----------------- | ---------------------------------------------------- | -| [BUILDKIT_COLORS](#buildkit_colors) | String | Configure text color for the terminal output. | -| [BUILDKIT_HOST](#buildkit_host) | String | Specify host to use for remote builders. | -| [BUILDKIT_PROGRESS](#buildkit_progress) | String | Configure type of progress output. | -| [BUILDKIT_TTY_LOG_LINES](#buildkit_tty_log_lines) | String | Number of log lines (for active steps in tty mode). | -| [BUILDX_BUILDER](#buildx_builder) | String | Specify the builder instance to use. | -| [BUILDX_CONFIG](#buildx_config) | String | Specify location for configuration, state, and logs. | -| [BUILDX_EXPERIMENTAL](#buildx_experimental) | Boolean | Turn on experimental features. | -| [BUILDX_GIT_CHECK_DIRTY](#buildx_git_check_dirty) | Boolean | Enable dirty Git checkout detection. | -| [BUILDX_GIT_INFO](#buildx_git_info) | Boolean | Remove Git information in provenance attestations. | -| [BUILDX_GIT_LABELS](#buildx_git_labels) | String \| Boolean | Add Git provenance labels to images. | -| [BUILDX_NO_DEFAULT_ATTESTATIONS](#buildx_no_default_attestations) | Boolean | Turn off default provenance attestations. | -| [BUILDX_NO_DEFAULT_LOAD](#buildx_no_default_load) | Boolean | Turn off loading images to image store by default. | -| [EXPERIMENTAL_BUILDKIT_SOURCE_POLICY](#experimental_buildkit_source_policy) | String | Specify a BuildKit source policy file. | - -See also -[BuildKit built-in build args](../../engine/reference/builder.md#buildkit-built-in-build-args). - -You can express Boolean values for environment variables in different ways. For -example, `true`, `1`, and `T` all evaluate to true. Evaluation is done using the -`strconv.ParseBool` function in the Go standard library. See the -[reference documentation](https://pkg.go.dev/strconv#ParseBool) -for details. - -## BUILDKIT_COLORS - -Changes the colors of the terminal output. Set `BUILDKIT_COLORS` to a CSV string -in the following format: - -```console -$ export BUILDKIT_COLORS="run=123,20,245:error=yellow:cancel=blue:warning=white" -``` - -Color values can be any valid RGB hex code, or one of the -[BuildKit predefined colors](https://github.com/moby/buildkit/blob/master/util/progress/progressui/colors.go). - -Setting `NO_COLOR` to anything turns off colorized output, as recommended by -[no-color.org](https://no-color.org/). - -## BUILDKIT_HOST - -_Introduced in [Buildx v0.9.0](../release-notes.md#090)_ - -You use the `BUILDKIT_HOST` to specify the address of a BuildKit daemon to use -as a remote builder. This is the same as specifying the address as a positional -argument to `docker buildx create`. - -Usage: - -```console -$ export BUILDKIT_HOST=tcp://localhost:1234 -$ docker buildx create --name=remote --driver=remote -``` - -If you specify both the `BUILDKIT_HOST` environment variable and a positional -argument, the argument takes priority. - -## BUILDKIT_PROGRESS - -Sets the type of the BuildKit progress output. Valid values are: - -- `auto` (default) -- `plain` -- `tty` - -Usage: - -```console -$ export BUILDKIT_PROGRESS=plain -``` - -## BUILDKIT_TTY_LOG_LINES - -You can change how many log lines are visible for active steps in tty mode by -setting `BUILDKIT_TTY_LOG_LINES` to a number (default to `6`). - -```console -$ export BUILDKIT_TTY_LOG_LINES=8 -``` - -## EXPERIMENTAL_BUILDKIT_SOURCE_POLICY - -Lets you specify a -[BuildKit source policy](https://github.com/moby/buildkit/blob/master/docs/build-repro.md#reproducing-the-pinned-dependencies) -file for creating reproducible builds with pinned dependencies. - -```console -$ export EXPERIMENTAL_BUILDKIT_SOURCE_POLICY=./policy.json -``` - -Example: - -```json -{ - "rules": [ - { - "action": "CONVERT", - "selector": { - "identifier": "docker-image://docker.io/library/alpine:latest" - }, - "updates": { - "identifier": "docker-image://docker.io/library/alpine:latest@sha256:4edbd2beb5f78b1014028f4fbb99f3237d9561100b6881aabbf5acce2c4f9454" - } - }, - { - "action": "CONVERT", - "selector": { - "identifier": "https://raw.githubusercontent.com/moby/buildkit/v0.10.1/README.md" - }, - "updates": { - "attrs": {"http.checksum": "sha256:6e4b94fc270e708e1068be28bd3551dc6917a4fc5a61293d51bb36e6b75c4b53"} - } - }, - { - "action": "DENY", - "selector": { - "identifier": "docker-image://docker.io/library/golang*" - } - } - ] -} -``` - -## BUILDX_BUILDER - -Overrides the configured builder instance. Same as the `docker buildx --builder` -CLI flag. - -Usage: - -```console -$ export BUILDX_BUILDER=my-builder -``` - -## BUILDX_CONFIG - -You can use `BUILDX_CONFIG` to specify the directory to use for build -configuration, state, and logs. The lookup order for this directory is as -follows: - -- `$BUILDX_CONFIG` -- `$DOCKER_CONFIG/buildx` -- `~/.docker/buildx` (default) - -Usage: - -```console -$ export BUILDX_CONFIG=/usr/local/etc -``` - -## BUILDX_EXPERIMENTAL - -Enables experimental build features. - -Usage: - -```console -$ export BUILDX_EXPERIMENTAL=1 -``` - -## BUILDX_GIT_CHECK_DIRTY - -_Introduced in [Buildx v0.10.4](../release-notes.md#0104)_ - -When set to true, checks for dirty state in source control information for -[provenance attestations](../attestations/slsa-provenance.md). - -Usage: - -```console -$ export BUILDX_GIT_CHECK_DIRTY=1 -``` - -## BUILDX_GIT_INFO - -_Introduced in [Buildx v0.10.0](../release-notes.md#0100)_ - -When set to false, removes source control information from -[provenance attestations](../attestations/slsa-provenance.md). - -Usage: - -```console -$ export BUILDX_GIT_INFO=0 -``` - -## BUILDX_GIT_LABELS - -_Introduced in [Buildx v0.10.0](../release-notes.md#0100)_ - -Adds provenance labels, based on Git information, to images that you build. The -labels are: - -- `com.docker.image.source.entrypoint`: Location of the Dockerfile relative to - the project root -- `org.opencontainers.image.revision`: Git commit revision -- `org.opencontainers.image.source`: SSH or HTTPS address of the repository - -Example: - -```json - "Labels": { - "com.docker.image.source.entrypoint": "Dockerfile", - "org.opencontainers.image.revision": "5734329c6af43c2ae295010778cd308866b95d9b", - "org.opencontainers.image.source": "git@github.com:foo/bar.git" - } -``` - -Usage: - -- Set `BUILDX_GIT_LABELS=1` to include the `entrypoint` and `revision` labels. -- Set `BUILDX_GIT_LABELS=full` to include all labels. - -If the repository is in a dirty state, the `revision` gets a `-dirty` suffix. - -## BUILDX_NO_DEFAULT_ATTESTATIONS - -_Introduced in [Buildx v0.10.4](../release-notes.md#0104)_ - -By default, BuildKit v0.11 and later adds -[provenance attestations](../attestations/slsa-provenance.md) to images you -build. Set `BUILDX_NO_DEFAULT_ATTESTATIONS=1` to disable the default provenance -attestations. - -Usage: - -```console -$ export BUILDX_NO_DEFAULT_ATTESTATIONS=1 -``` - -## BUILDX_NO_DEFAULT_LOAD - -When you build an image using the `docker` driver, the image is automatically -loaded to the image store when the build finishes. Set `BUILDX_NO_DEFAULT_LOAD` -to disable automatic loading of images to the local container store. - -Usage: - -```console -$ export BUILDX_NO_DEFAULT_LOAD=1 -``` diff --git a/content/build/building/variables.md b/content/build/building/variables.md new file mode 100644 index 000000000000..a558b1d99016 --- /dev/null +++ b/content/build/building/variables.md @@ -0,0 +1,547 @@ +--- +title: Build variables +description: Using build arguments and environment variables to configure builds +keywords: build, args, variables, parameters, env, environment variables, config +aliases: +- /build/buildkit/color-output-controls/ +- /build/building/env-vars/ +--- + +In Docker Build, build arguments (`ARG`) and environment variables (`ENV`) +both serve as a means to pass information into the build process. +You can use them to parameterize the build, allowing for more flexible and configurable builds. + +> **Warning** +> +> Build arguments and environment variables are inappropriate for passing secrets +> to your build, because they're exposed in the final image. Instead, use +> secret mounts or SSH mounts, which expose secrets to your builds securely. +> +> See [Build secrets](./secrets.md) for more information. +{ .warning } + +## Similarities and differences + +Build arguments and environment variables are similar. +They're both declared in the Dockerfile and can be set using flags for the `docker build` command. +Both can be used to parametrize the build. +But they each serve a distinct purpose. + +### Build arguments + +Build arguments are variables for the Dockerfile itself. +Use them to parametrize values of Dockerfile instructions. +For example, you might use a build argument to specify the version of a dependency to install. + +Build arguments have no effect on the build unless it's used in an instruction. +They're not accessible or present in containers instantiated from the image +unless explicitly passed through from the Dockerfile into the image filesystem or configuration. +They may persist in the image metadata, as provenance attestations and in the image history, +which is why they're not suitable for holding secrets. + +They make Dockerfiles more flexible, and easier to maintain. + +For an example on how you can use build arguments, +see [`ARG` usage example](#arg-usage-example). + +### Environment variables + +Environment variables are passed through to the build execution environment, +and persist in containers instantiated from the image. + +Environment variables are primarily used to: + +- Configure the execution environment for builds +- Set default environment variables for containers + +Environment variables, if set, can directly influence the execution of your build, +and the behavior or configuration of the application. + +You can't override or set an environment variable at build-time. +Values for environment variables must be declared in the Dockerfile. +You can combine environment variables and build arguments to allow +environment variables to be configured at build-time. + +For an example on how to use environment variables for configuring builds, +see [`ENV` usage example](#env-usage-example). + +## `ARG` usage example + +Build arguments are commonly used to specify versions of components, +such as image variants or package versions, used in a build. + +Specifying versions as build arguments lets build with different versions +without having to manually update the Dockerfile. +It also makes it easier to maintain the Dockerfile, +since it lets you declare versions at the top of the file. + +Build arguments can also be a way to reuse a value in multiple places. +For example, if you use multiple flavors of `alpine` in your build, +you can ensure you're using the same version of `alpine` everywhere: + +- `golang:1.22-alpine${ALPINE_VERSION}` +- `python:3.12-alpine${ALPINE_VERSION}` +- `nginx:1-alpine${ALPINE_VERSION}` + +The following example defines the version of `node` and `alpine` using build arguments. + +```dockerfile +# syntax=docker/dockerfile:1 + +ARG NODE_VERSION="{{% param example_node_version %}}" +ARG ALPINE_VERSION="{{% param example_alpine_version %}}" + +FROM node:${NODE_VERSION}-alpine${ALPINE_VERSION} AS base +WORKDIR /src + +FROM base AS build +COPY package*.json ./ +RUN npm ci +RUN npm run build + +FROM base AS production +COPY package*.json ./ +RUN npm ci --omit=dev && npm cache clean --force +COPY --from=build /src/dist/ . +CMD ["node", "app.js"] +``` + +In this case, the build arguments have default values. +Specifying their values when you invoke a build is optional. +To override the defaults, you would use the `--build-arg` CLI flag: + +```console +$ docker build --build-arg NODE_VERSION=current . +``` + +For more information on how to use build arguments, refer to: + +- [`ARG` Dockerfile reference](../../engine/reference/commandline/builder.md#arg) +- [`docker build --build-arg` reference](../../engine/reference/commandline/image_build.md#build-arg) + +## `ENV` usage example + +Declaring an environment variable with `ENV` makes the variable +available to all subsequent instructions in the build stage. +The following example shows an example setting `NODE_ENV` to `production` +before installing JavaScript dependencies with `npm`. +Setting the variable makes `npm` omits packages needed only for local development. + +```dockerfile +# syntax=docker/dockerfile:1 + +FROM node:20 +WORKDIR /app +COPY package*.json ./ +ENV NODE_ENV=production +RUN npm ci && npm cache clean --force +COPY . . +CMD ["node", "app.js"] +``` + +Environment variables aren't configurable at build-time by default. +If you want to change the value of an `ENV` at build-time, +you can combine environment variables and build arguments: + +```dockerfile +# syntax=docker/dockerfile:1 + +FROM node:20 +ARG NODE_ENV=production +ENV NODE_ENV=$NODE_ENV +WORKDIR /app +COPY package*.json ./ +RUN npm ci && npm cache clean --force +COPY . . +CMD ["node", "app.js"] +``` + +With this Dockerfile, you can use `--build-arg` to override the default value of `ENV`: + +```console +$ docker build --build-arg NODE_ENV=development . +``` + +Note that, because the environment variables you set persist in containers, +using them can lead to unintended side-effects for the application's runtime. + +For more information on how to use environment variables in builds, refer to: + +- [`ENV` Dockerfile reference](../../engine/reference/commandline/builder.md#env) + +## Scoping + +Build arguments declared in the global scope of a Dockerfile +aren't automatically inherited into the build stages. +They're only accessible in the global scope. + +```dockerfile +# syntax=docker/dockerfile:1 + +# The following build argument is declared in the global scope: +ARG NAME="joe" + +FROM alpine +# The following instruction doesn't have access to the $NAME build argument +# because the argument was defined in the global scope, not for this stage. +RUN echo "hello ${NAME}!" +``` + +The `echo` command in this example evaluates to `hello !` +because the value of the `NAME` build argument is out of scope. +To inherit global build arguments into a stage, you must consume them: + +```dockerfile +# syntax=docker/dockerfile:1 + +# Declare the build argument in the global scope +ARG NAME="joe" + +FROM alpine +# Consume the build argument in the build stage +ARG NAME +RUN echo $NAME +``` + +Once a build argument is declared or consumed in a stage, +it's automatically inherited by child stages. + +```dockerfile +# syntax=docker/dockerfile:1 +FROM alpine AS base +# Declare the build argument in the build stage +ARG NAME="joe" + +# Create a new stage based on "base" +FROM base AS build +# The NAME build argument is available here +# since it's declared in a parent stage +RUN echo "hello $NAME!" +``` + +The following diagram further exemplifies how build argument +and environment variable inheritance works for multi-stage builds. + +{{< figure src="../../images/build-variables.svg" class="invertible" >}} + +## Pre-defined build arguments + +This section describes pre-defined build arguments available to all builds by default. + +### Multi-platform build arguments + +Multi-platform build arguments describe the build and target platforms for the build. + +The build platform is the operating system, architecture, and platform variant +of the host system where the builder (the BuildKit daemon) is running. + +- `BUILDPLATFORM` +- `BUILDOS` +- `BUILDARCH` +- `BUILDVARIANT` + +The target platform arguments hold the same values for the target platforms for the build, +specified using the `--platform` flag for the `docker build` command. + +- `TARGETPLATFORM` +- `TARGETOS` +- `TARGETARCH` +- `TARGETVARIANT` + +These arguments are useful for doing cross-compilation in multi-platform builds. +They're available in the global scope of the Dockerfile, +but they aren't automatically inherited by build stages. +To use them inside stage, you must declare them: + +```dockerfile +# syntax=docker/dockerfile:1 + +# Pre-defined build arguments are available in the global scope +FROM --platform=$BUILDPLATFORM golang +# To inherit them to a stage, declare them with ARG +ARG TARGETOS +RUN GOOS=$TARGETOS go build -o ./exe . +``` + +For more information about multi-platform build arguments, refer to +[Multi-platform arguments](/engine/reference/builder/#automatic-platform-args-in-the-global-scope) + +### Proxy arguments + +Proxy build arguments let you specify proxies to use for your build. +You don't need to declare or reference these arguments in the Dockerfile. +Specifying a proxy with `--build-arg` is enough to make your build use the proxy. + +Proxy arguments are automatically excluded from the build cache +and the output of `docker history` by default. +If you do reference the arguments in your Dockerfile, +the proxy configuration ends up in the build cache. + +The builder respects the following proxy build arguments. +The variables are case insensitive. + +- `HTTP_PROXY` +- `HTTPS_PROXY` +- `FTP_PROXY` +- `NO_PROXY` +- `ALL_PROXY` + +To configure a proxy for your build: + +```console +$ docker build --build-arg HTTP_PROXY=https://my-proxy.example.com . +``` + +For more information about proxy build arguments, refer to +[Proxy arguments](/engine/reference/builder/#predefined-args). + +## Build tool configuration variables + +The following environment variables enable, disable, or change the behavior of Buildx and BuildKit. +Note that these variables aren't used to configure the build container; +they aren't available inside the build and they have no relation to the `ENV` instruction. +They're used to configure the Buildx client, or the BuildKit daemon. + +| Variable | Type | Description | +| --------------------------------------------------------------------------- | ----------------- | ---------------------------------------------------- | +| [BUILDKIT_COLORS](#buildkit_colors) | String | Configure text color for the terminal output. | +| [BUILDKIT_HOST](#buildkit_host) | String | Specify host to use for remote builders. | +| [BUILDKIT_PROGRESS](#buildkit_progress) | String | Configure type of progress output. | +| [BUILDKIT_TTY_LOG_LINES](#buildkit_tty_log_lines) | String | Number of log lines (for active steps in tty mode). | +| [BUILDX_BUILDER](#buildx_builder) | String | Specify the builder instance to use. | +| [BUILDX_CONFIG](#buildx_config) | String | Specify location for configuration, state, and logs. | +| [BUILDX_EXPERIMENTAL](#buildx_experimental) | Boolean | Turn on experimental features. | +| [BUILDX_GIT_CHECK_DIRTY](#buildx_git_check_dirty) | Boolean | Enable dirty Git checkout detection. | +| [BUILDX_GIT_INFO](#buildx_git_info) | Boolean | Remove Git information in provenance attestations. | +| [BUILDX_GIT_LABELS](#buildx_git_labels) | String \| Boolean | Add Git provenance labels to images. | +| [BUILDX_NO_DEFAULT_ATTESTATIONS](#buildx_no_default_attestations) | Boolean | Turn off default provenance attestations. | +| [BUILDX_NO_DEFAULT_LOAD](#buildx_no_default_load) | Boolean | Turn off loading images to image store by default. | +| [EXPERIMENTAL_BUILDKIT_SOURCE_POLICY](#experimental_buildkit_source_policy) | String | Specify a BuildKit source policy file. | + +BuildKit also supports a few additional configuration parameters. Refer to +[BuildKit built-in build args](../../engine/reference/builder.md#buildkit-built-in-build-args). + +You can express Boolean values for environment variables in different ways. +For example, `true`, `1`, and `T` all evaluate to true. +Evaluation is done using the `strconv.ParseBool` function in the Go standard library. +See the [reference documentation](https://pkg.go.dev/strconv#ParseBool) for details. + +### BUILDKIT_COLORS + +Changes the colors of the terminal output. Set `BUILDKIT_COLORS` to a CSV string +in the following format: + +```console +$ export BUILDKIT_COLORS="run=123,20,245:error=yellow:cancel=blue:warning=white" +``` + +Color values can be any valid RGB hex code, or one of the +[BuildKit predefined colors](https://github.com/moby/buildkit/blob/master/util/progress/progressui/colors.go). + +Setting `NO_COLOR` to anything turns off colorized output, as recommended by +[no-color.org](https://no-color.org/). + +### BUILDKIT_HOST + +_Introduced in [Buildx v0.9.0](../release-notes.md#090)_ + +You use the `BUILDKIT_HOST` to specify the address of a BuildKit daemon to use +as a remote builder. This is the same as specifying the address as a positional +argument to `docker buildx create`. + +Usage: + +```console +$ export BUILDKIT_HOST=tcp://localhost:1234 +$ docker buildx create --name=remote --driver=remote +``` + +If you specify both the `BUILDKIT_HOST` environment variable and a positional +argument, the argument takes priority. + +### BUILDKIT_PROGRESS + +Sets the type of the BuildKit progress output. Valid values are: + +- `auto` (default) +- `plain` +- `tty` +- `rawjson` + +Usage: + +```console +$ export BUILDKIT_PROGRESS=plain +``` + +### BUILDKIT_TTY_LOG_LINES + +You can change how many log lines are visible for active steps in tty mode by +setting `BUILDKIT_TTY_LOG_LINES` to a number (default to `6`). + +```console +$ export BUILDKIT_TTY_LOG_LINES=8 +``` + +### EXPERIMENTAL_BUILDKIT_SOURCE_POLICY + +Lets you specify a +[BuildKit source policy](https://github.com/moby/buildkit/blob/master/docs/build-repro.md#reproducing-the-pinned-dependencies) +file for creating reproducible builds with pinned dependencies. + +```console +$ export EXPERIMENTAL_BUILDKIT_SOURCE_POLICY=./policy.json +``` + +Example: + +```json +{ + "rules": [ + { + "action": "CONVERT", + "selector": { + "identifier": "docker-image://docker.io/library/alpine:latest" + }, + "updates": { + "identifier": "docker-image://docker.io/library/alpine:latest@sha256:4edbd2beb5f78b1014028f4fbb99f3237d9561100b6881aabbf5acce2c4f9454" + } + }, + { + "action": "CONVERT", + "selector": { + "identifier": "https://raw.githubusercontent.com/moby/buildkit/v0.10.1/README.md" + }, + "updates": { + "attrs": {"http.checksum": "sha256:6e4b94fc270e708e1068be28bd3551dc6917a4fc5a61293d51bb36e6b75c4b53"} + } + }, + { + "action": "DENY", + "selector": { + "identifier": "docker-image://docker.io/library/golang*" + } + } + ] +} +``` + +### BUILDX_BUILDER + +Overrides the configured builder instance. Same as the `docker buildx --builder` +CLI flag. + +Usage: + +```console +$ export BUILDX_BUILDER=my-builder +``` + +### BUILDX_CONFIG + +You can use `BUILDX_CONFIG` to specify the directory to use for build +configuration, state, and logs. The lookup order for this directory is as +follows: + +- `$BUILDX_CONFIG` +- `$DOCKER_CONFIG/buildx` +- `~/.docker/buildx` (default) + +Usage: + +```console +$ export BUILDX_CONFIG=/usr/local/etc +``` + +### BUILDX_EXPERIMENTAL + +Enables experimental build features. + +Usage: + +```console +$ export BUILDX_EXPERIMENTAL=1 +``` + +### BUILDX_GIT_CHECK_DIRTY + +_Introduced in [Buildx v0.10.4](../release-notes.md#0104)_ + +When set to true, checks for dirty state in source control information for +[provenance attestations](../attestations/slsa-provenance.md). + +Usage: + +```console +$ export BUILDX_GIT_CHECK_DIRTY=1 +``` + +### BUILDX_GIT_INFO + +_Introduced in [Buildx v0.10.0](../release-notes.md#0100)_ + +When set to false, removes source control information from +[provenance attestations](../attestations/slsa-provenance.md). + +Usage: + +```console +$ export BUILDX_GIT_INFO=0 +``` + +### BUILDX_GIT_LABELS + +_Introduced in [Buildx v0.10.0](../release-notes.md#0100)_ + +Adds provenance labels, based on Git information, to images that you build. The +labels are: + +- `com.docker.image.source.entrypoint`: Location of the Dockerfile relative to + the project root +- `org.opencontainers.image.revision`: Git commit revision +- `org.opencontainers.image.source`: SSH or HTTPS address of the repository + +Example: + +```json + "Labels": { + "com.docker.image.source.entrypoint": "Dockerfile", + "org.opencontainers.image.revision": "5734329c6af43c2ae295010778cd308866b95d9b", + "org.opencontainers.image.source": "git@github.com:foo/bar.git" + } +``` + +Usage: + +- Set `BUILDX_GIT_LABELS=1` to include the `entrypoint` and `revision` labels. +- Set `BUILDX_GIT_LABELS=full` to include all labels. + +If the repository is in a dirty state, the `revision` gets a `-dirty` suffix. + +### BUILDX_NO_DEFAULT_ATTESTATIONS + +_Introduced in [Buildx v0.10.4](../release-notes.md#0104)_ + +By default, BuildKit v0.11 and later adds +[provenance attestations](../attestations/slsa-provenance.md) to images you +build. Set `BUILDX_NO_DEFAULT_ATTESTATIONS=1` to disable the default provenance +attestations. + +Usage: + +```console +$ export BUILDX_NO_DEFAULT_ATTESTATIONS=1 +``` + +### BUILDX_NO_DEFAULT_LOAD + +When you build an image using the `docker` driver, the image is automatically +loaded to the image store when the build finishes. Set `BUILDX_NO_DEFAULT_LOAD` +to disable automatic loading of images to the local container store. + +Usage: + +```console +$ export BUILDX_NO_DEFAULT_LOAD=1 +``` + diff --git a/content/build/cloud/usage.md b/content/build/cloud/usage.md index 1619300e177e..3286540488da 100644 --- a/content/build/cloud/usage.md +++ b/content/build/cloud/usage.md @@ -66,7 +66,7 @@ $ docker compose build In addition to `docker buildx use`, you can also use the `docker compose build --builder` flag or the [`BUILDX_BUILDER` environment -variable](../building/env-vars.md#buildx_builder) to select the cloud builder. +variable](../building/variables.md#buildx_builder) to select the cloud builder. ## Loading build results diff --git a/content/build/images/build-variables.svg b/content/build/images/build-variables.svg new file mode 100644 index 000000000000..6bd6d77689c6 --- /dev/null +++ b/content/build/images/build-variables.svg @@ -0,0 +1,3 @@ + + + Global scope# Build arguments declared here are in the global scopeARG GLOBAL_ARG="global default value"ARG VERSION="3.19"# You can't declare environment variables in the global scopeENV GLOBAL_ENV=false# GLOBAL_ARG was not redeclared in this stageRUN echo $GLOBAL_ARG# LOCAL_ARG was declared in stage-aRUN echo $LOCAL_ARGstage-bFROM --platform=$BUILDPLATFORM alpine:${VERSION} as stage-bstage-a# FROM-lines belong to the global scope and have access to global ARGsFROM alpine:${VERSION} as stage-a# Redeclaring GLOBAL_ARG without a value inherits the global defaultARG GLOBAL_ARGRUN echo $GLOBAL_ARG# ARG here this scope creates a local argumentARG LOCAL_ARG="local arg in stage-a"# Set an environment variable in this scopeENV LOCAL_ENV=true# Set an environment variable to the value of a build argumentENV MY_VAR=$LOCAL_ARGstage-c# New stage based on "stage-a"FROM stage-a AS stage-c# Arguments and variables are inherited from parent stagesRUN echo $LOCAL_ARGRUN echo $LOCAL_ENV<- prints an emptry string<- prints an emptry string<- prints "global default value"<- prints "local arg in stage-a"<- prints "true"ARG TARGETPLATFORM# You must redeclare pre-defined arguments to use them in a stageRUN echo $TARGETPLATFORM<- prints os/arch/variant of --platform# Pre-defined multi-platform arguments like $BUILDPLATFORM are global diff --git a/content/build/release-notes.md b/content/build/release-notes.md index 0c78c8821383..150390a73ac9 100644 --- a/content/build/release-notes.md +++ b/content/build/release-notes.md @@ -167,7 +167,7 @@ The full release note for this release is available that lets you start a debug session in your builds. [docker/buildx#1626](https://github.com/docker/buildx/pull/1626), [docker/buildx#1640](https://github.com/docker/buildx/pull/1640) -- New [`EXPERIMENTAL_BUILDKIT_SOURCE_POLICY` environment variable](./building/env-vars.md#experimental_buildkit_source_policy) +- New [`EXPERIMENTAL_BUILDKIT_SOURCE_POLICY` environment variable](./building/variables.md#experimental_buildkit_source_policy) for applying a BuildKit source policy file. [docker/buildx#1628](https://github.com/docker/buildx/pull/1628) diff --git a/data/toc.yaml b/data/toc.yaml index adc05a6721dd..ceae4c2d9cf5 100644 --- a/data/toc.yaml +++ b/data/toc.yaml @@ -1755,10 +1755,10 @@ Manuals: title: Context - path: /build/building/multi-stage/ title: Multi-stage builds + - path: /build/building/variables/ + title: Variables - path: /build/building/multi-platform/ title: Multi-platform images - - path: /build/building/env-vars/ - title: Environment variables - path: /build/building/secrets/ title: Build secrets - path: /build/building/annotations/ diff --git a/hugo.yaml b/hugo.yaml index 06ad3126b215..6c02ea3b9cda 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -100,7 +100,8 @@ params: example_go_version: "1.21" example_golangci_lint_version: "v1.52" - example_alpine_version: "1.19" + example_alpine_version: "3.19" + example_node_version: "20" min_api_threshold: 1.41