From f2924ef0e9e129935f07be2a4b76dc066424f553 Mon Sep 17 00:00:00 2001 From: CrazyMax <1951866+crazy-max@users.noreply.github.com> Date: Mon, 26 Oct 2026 11:41:03 +0100 Subject: [PATCH 1/2] build: explain Bake secret source overrides The overrides guide omits the named secret override supported by Bake. Show environment and file sources, and explain the declared-ID and replacement constraints. Signed-off-by: CrazyMax <1951866+crazy-max@users.noreply.github.com> --- content/manuals/build/bake/overrides.md | 34 +++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/content/manuals/build/bake/overrides.md b/content/manuals/build/bake/overrides.md index 51ef54a9a76b..4ed3f22f6f70 100644 --- a/content/manuals/build/bake/overrides.md +++ b/content/manuals/build/bake/overrides.md @@ -27,6 +27,7 @@ The following list of attributes can be overridden: - `output` - `platform` - `pull` +- `secret.` - `secrets` - `ssh` - `tags` @@ -242,11 +243,44 @@ Complete list of attributes that can be overridden with `--set` are: - `output` - `platform` - `pull` +- `secret.` - `secrets` - `ssh` - `tags` - `target` +### Override a secret source + +Use `--set .secret.=` to change the source of an existing +secret without replacing the target's secret list. The secret ID must already +be declared by the target. + +For example, declare an `aws` secret in the Bake file: + +```hcl {title=docker-bake.hcl} +target "app" { + secret = [{ + id = "aws" + src = "./credentials" + }] +} +``` + +Supply its value from an environment variable or a different file: + +```console +$ docker buildx bake --set app.secret.aws=env=AWS_CREDENTIALS app +$ docker buildx bake --set app.secret.aws=src=/path/to/credentials app +``` + +The build still receives the secret as `aws`. Other declared secrets keep +their sources. The override fails if the target doesn't declare `aws`, or if +an `id=` in the override value names a different secret. This form doesn't +support `+=`. + +To add or replace secrets instead, use the `secrets` list override described +in the [`--set` reference](/reference/cli/docker/buildx/bake/#set). + ## Environment variables You can also use environment variables to override configurations. From eb9609762265a9d9b2d40f8cdfaa84fa46cea92f Mon Sep 17 00:00:00 2001 From: CrazyMax <1951866+crazy-max@users.noreply.github.com> Date: Mon, 26 Oct 2026 11:41:04 +0100 Subject: [PATCH 2/2] build: align Bake override guidance with canonical keys The guide duplicates incomplete key lists and uses older plural selectors. Link to the CLI reference for exhaustive keys, distinguish selectors from Bake file attributes, and explain aliases and inline list operations. Signed-off-by: CrazyMax <1951866+crazy-max@users.noreply.github.com> --- content/manuals/build/bake/overrides.md | 104 ++++++++++++------------ 1 file changed, 50 insertions(+), 54 deletions(-) diff --git a/content/manuals/build/bake/overrides.md b/content/manuals/build/bake/overrides.md index 4ed3f22f6f70..8dfac805c661 100644 --- a/content/manuals/build/bake/overrides.md +++ b/content/manuals/build/bake/overrides.md @@ -11,29 +11,7 @@ more flexibility to configure these definitions. For example, you might want to override an attribute when building in a particular environment or for a specific target. -The following list of attributes can be overridden: - -- `args` -- `attest` -- `cache-from` -- `cache-to` -- `context` -- `contexts` -- `dockerfile` -- `entitlements` -- `labels` -- `network` -- `no-cache` -- `output` -- `platform` -- `pull` -- `secret.` -- `secrets` -- `ssh` -- `tags` -- `target` - -To override these attributes, you can use the following methods: +To override target attributes or the variables used to configure them, use: - [File overrides](#file-overrides) - [CLI overrides](#command-line) @@ -190,7 +168,8 @@ target "app" { ``` ```console -$ docker buildx bake --set app.args.mybuildarg=bar --set app.platform=linux/arm64 app --print +$ docker buildx bake --set app.arg.mybuildarg=bar \ + --set app.platform=linux/arm64 app --print ``` ```json @@ -215,39 +194,54 @@ $ docker buildx bake --set app.args.mybuildarg=bar --set app.platform=linux/arm6 > [!NOTE] > -> `--set` is a repeatable flag. For array fields such as `tags`, repeat `--set` to provide multiple values or use the `+=` operator to append without replacing. -> Array literal syntax like `--set target.tags=[a,b]` is not supported. +> `--set` is a repeatable flag. For array fields such as `tag`, repeat `--set` +> to provide multiple values or use `+=` to append without replacing. +> An empty assignment, such as `--set app.tag=`, clears the array. Subsequent +> assignments add values to the cleared array. Array literal syntax such as +> `--set app.tag=[a,b]` is not supported. -Pattern matching syntax defined in [https://golang.org/pkg/path/#Match](https://golang.org/pkg/path/#Match) -is also supported: +Override keys use singular names such as `arg`, `secret`, and `tag`. These +names apply to `--set` selectors; Bake file attributes keep their existing +names, such as `args` and `tags`. Older plural override spellings remain +supported as aliases. + +`context` and `contexts` aren't aliases: `context` sets the main build +context, while `contexts.` sets one named context. The alias `secrets` +applies to the secret list override only; `secrets.` is invalid. + +You can match multiple targets with a pattern. Quote the override so your +shell doesn't expand the pattern before Bake reads it: + +```console +$ docker buildx bake --set 'foo*.arg.mybuildarg=value' +$ docker buildx bake --set '*.platform=linux/arm64' +$ docker buildx bake --set 'foo*.no-cache' +``` + +The first and third commands affect targets whose names start with `foo`. +The second sets the platform for all targets. For the full list of override +keys, aliases, pattern syntax, and fields supporting `+=`, see the +[`--set` reference](/reference/cli/docker/buildx/bake/#set). + +### Override list attributes + +Attributes such as `secret`, `ssh`, and `output` can use lists of objects in a +Bake file. In a `--set` value, use the inline syntax of the corresponding +build flag, rather than an HCL object or array. For example, `secret` uses the +same `id=...,src=...` syntax as +[`build --secret`](/reference/cli/docker/buildx/build/#secret). + +Use `=` to replace the secret list, `+=` to add a secret, or an empty value +to clear the list: ```console -$ docker buildx bake --set foo*.args.mybuildarg=value # overrides build arg for all targets starting with "foo" -$ docker buildx bake --set *.platform=linux/arm64 # overrides platform for all targets -$ docker buildx bake --set foo*.no-cache # bypass caching only for targets starting with "foo" +$ docker buildx bake --set app.secret=id=aws,src=./credentials app +$ docker buildx bake --set app.secret+=id=gcp,env=GCP_CREDENTIALS app +$ docker buildx bake --set app.secret= app ``` -Complete list of attributes that can be overridden with `--set` are: - -- `args` -- `attest` -- `cache-from` -- `cache-to` -- `context` -- `contexts` -- `dockerfile` -- `entitlements` -- `labels` -- `network` -- `no-cache` -- `output` -- `platform` -- `pull` -- `secret.` -- `secrets` -- `ssh` -- `tags` -- `target` +These operations affect the list as a whole. To change only the source of one +declared secret while preserving the others, use `secret.`. ### Override a secret source @@ -278,8 +272,10 @@ their sources. The override fails if the target doesn't declare `aws`, or if an `id=` in the override value names a different secret. This form doesn't support `+=`. -To add or replace secrets instead, use the `secrets` list override described -in the [`--set` reference](/reference/cli/docker/buildx/bake/#set). +Named source overrides are applied after secret list overrides, so the ID +must exist in the resulting list. The value describes the complete source +using `env=...` or `src=...`; it doesn't address an object field such as +`secret.aws.env`. ## Environment variables