From d04c833e6917752cf7cd3de44b320640fe83aef1 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Mon, 17 Jun 2024 13:32:59 +0200
Subject: [PATCH] build(bake): add overrides page, remove configuring-build

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 content/build/bake/configuring-build.md | 261 -------------------
 content/build/bake/overrides.md         | 332 ++++++++++++++++++++++++
 content/build/release-notes.md          |   2 +-
 data/toc.yaml                           |   4 +-
 4 files changed, 335 insertions(+), 264 deletions(-)
 delete mode 100644 content/build/bake/configuring-build.md
 create mode 100644 content/build/bake/overrides.md

diff --git a/content/build/bake/configuring-build.md b/content/build/bake/configuring-build.md
deleted file mode 100644
index e4a0447ec6..0000000000
--- a/content/build/bake/configuring-build.md
+++ /dev/null
@@ -1,261 +0,0 @@
----
-title: Configure builds with Bake
-description: Learn how to create a flexible build configuration with Bake
-keywords: build, buildx, bake, buildkit, hcl, json
-aliases:
-  - /build/customize/bake/configuring-build/
----
-
-Bake supports loading build definitions from files, but sometimes you need even
-more flexibility to configure these definitions.
-
-For this use case, you can define variables inside the bake files that can be
-set by the user with environment variables or by [attribute definitions](#global-scope-attributes)
-in other bake files. If you wish to change a specific value for a single
-invocation you can use the `--set` flag [from the command line](#from-command-line).
-
-## Global scope attributes
-
-You can define global scope attributes in HCL/JSON and use them for code reuse
-and setting values for variables. This means you can do a "data-only" HCL file
-with the values you want to set/override and use it in the list of regular
-output files.
-
-```hcl
-# docker-bake.hcl
-variable "FOO" {
-  default = "abc"
-}
-
-target "app" {
-  args = {
-    v1 = "pre-${FOO}"
-  }
-}
-```
-
-You can use this file directly:
-
-```console
-$ docker buildx bake --print app
-```
-
-```json
-{
-  "group": {
-    "default": {
-      "targets": ["app"]
-    }
-  },
-  "target": {
-    "app": {
-      "context": ".",
-      "dockerfile": "Dockerfile",
-      "args": {
-        "v1": "pre-abc"
-      }
-    }
-  }
-}
-```
-
-Or create an override configuration file:
-
-```hcl
-# env.hcl
-WHOAMI="myuser"
-FOO="def-${WHOAMI}"
-```
-
-And invoke bake together with both of the files:
-
-```console
-$ docker buildx bake -f docker-bake.hcl -f env.hcl --print app
-```
-
-```json
-{
-  "group": {
-    "default": {
-      "targets": ["app"]
-    }
-  },
-  "target": {
-    "app": {
-      "context": ".",
-      "dockerfile": "Dockerfile",
-      "args": {
-        "v1": "pre-def-myuser"
-      }
-    }
-  }
-}
-```
-
-## Resource interpolation
-
-You can also refer to attributes defined as part of other targets, to help
-reduce duplication between targets.
-
-```hcl
-# docker-bake.hcl
-target "foo" {
-  dockerfile = "${target.foo.name}.Dockerfile"
-  tags       = [target.foo.name]
-}
-target "bar" {
-  dockerfile = "${target.foo.name}.Dockerfile"
-  tags       = [target.bar.name]
-}
-```
-
-You can use this file directly:
-
-```console
-$ docker buildx bake --print foo bar
-```
-
-```json
-{
-  "group": {
-    "default": {
-      "targets": ["foo", "bar"]
-    }
-  },
-  "target": {
-    "foo": {
-      "context": ".",
-      "dockerfile": "foo.Dockerfile",
-      "tags": ["foo"]
-    },
-    "bar": {
-      "context": ".",
-      "dockerfile": "foo.Dockerfile",
-      "tags": ["bar"]
-    }
-  }
-}
-```
-
-## From command line
-
-You can also override target configurations from the command line with the
-[`--set` flag](../../reference/cli/docker/buildx/bake.md#set):
-
-```hcl
-# docker-bake.hcl
-target "app" {
-  args = {
-    mybuildarg = "foo"
-  }
-}
-```
-
-```console
-$ docker buildx bake --set app.args.mybuildarg=bar --set app.platform=linux/arm64 app --print
-```
-
-```json
-{
-  "group": {
-    "default": {
-      "targets": ["app"]
-    }
-  },
-  "target": {
-    "app": {
-      "context": ".",
-      "dockerfile": "Dockerfile",
-      "args": {
-        "mybuildarg": "bar"
-      },
-      "platforms": ["linux/arm64"]
-    }
-  }
-}
-```
-
-Pattern matching syntax defined in [https://golang.org/pkg/path/#Match](https://golang.org/pkg/path/#Match)
-is also supported:
-
-```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"
-```
-
-Complete list of overridable fields:
-
-- `args`
-- `cache-from`
-- `cache-to`
-- `context`
-- `dockerfile`
-- `labels`
-- `no-cache`
-- `output`
-- `platform`
-- `pull`
-- `secrets`
-- `ssh`
-- `tags`
-- `target`
-
-## Using variables in variables across files
-
-When multiple files are specified, one file can use variables defined in
-another file.
-
-```hcl
-# docker-bake1.hcl
-variable "FOO" {
-  default = upper("${BASE}def")
-}
-
-variable "BAR" {
-  default = "-${FOO}-"
-}
-
-target "app" {
-  args = {
-    v1 = "pre-${BAR}"
-  }
-}
-```
-
-```hcl
-# docker-bake2.hcl
-variable "BASE" {
-  default = "abc"
-}
-
-target "app" {
-  args = {
-    v2 = "${FOO}-post"
-  }
-}
-```
-
-```console
-$ docker buildx bake -f docker-bake1.hcl -f docker-bake2.hcl --print app
-```
-
-```json
-{
-  "group": {
-    "default": {
-      "targets": ["app"]
-    }
-  },
-  "target": {
-    "app": {
-      "context": ".",
-      "dockerfile": "Dockerfile",
-      "args": {
-        "v1": "pre--ABCDEF-",
-        "v2": "ABCDEF-post"
-      }
-    }
-  }
-}
-```
diff --git a/content/build/bake/overrides.md b/content/build/bake/overrides.md
new file mode 100644
index 0000000000..6523b262b7
--- /dev/null
+++ b/content/build/bake/overrides.md
@@ -0,0 +1,332 @@
+---
+title: Overriding configurations
+description: Learn how to override configurations in Bake files to build with different attributes.
+keywords: build, buildx, bake, buildkit, hcl, json, overrides, configuration
+aliases:
+  - /build/bake/configuring-build/
+---
+
+Bake supports loading build definitions from files, but sometimes you need even
+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`
+- `cache-from`
+- `cache-to`
+- `context`
+- `dockerfile`
+- `labels`
+- `no-cache`
+- `output`
+- `platform`
+- `pull`
+- `secrets`
+- `ssh`
+- `tags`
+- `target`
+
+To override these attributes, you can use the following methods:
+
+- [File overrides](#file-overrides)
+- [CLI overrides](#command-line)
+- [Environment variable overrides](#environment-variables)
+
+## File overrides
+
+You can load multiple Bake files that define build configurations for your
+targets. This is useful when you want to separate configurations into different
+files for better organization, or to conditionally override configurations
+based on which files are loaded.
+
+### Default file lookup
+
+You can use the `--file` or `-f` flag to specify which files to load.
+If you don't specify any files, Bake will use the following lookup order:
+
+1. `compose.yaml`
+2. `compose.yml`
+3. `docker-compose.yml`
+4. `docker-compose.yaml`
+5. `docker-bake.json`
+6. `docker-bake.override.json`
+7. `docker-bake.hcl`
+8. `docker-bake.override.hcl`
+
+If more than one Bake file is found, all files are loaded and merged into a
+single definition. Files are merged according to the lookup order.
+
+```console
+$ docker buildx bake bake --print
+[+] Building 0.0s (1/1) FINISHED                                                                                                                                                                                            
+ => [internal] load local bake definitions                                                                                                                                                                             0.0s
+ => => reading compose.yaml 45B / 45B                                                                                                                                                                                  0.0s
+ => => reading docker-bake.hcl 113B / 113B                                                                                                                                                                             0.0s
+ => => reading docker-bake.override.hcl 65B / 65B
+```
+
+If merged files contain duplicate attribute definitions, those definitions are
+either merged or overridden by the last occurrence, depending on the attribute.
+
+Bake will attempt to load all of the files in the order they are found. If
+multiple files define the same target, attributes are either merged or
+overridden. In the case of overrides, the last one loaded takes precedence.
+
+For example, given the following files:
+
+```hcl {title=docker-bake.hcl}
+variable "TAG" {
+  default = "foo"
+}
+
+target "default" {
+  tags = ["username/my-app:${TAG}"]
+}
+```
+
+```hcl {title=docker-bake.override.hcl}
+variable "TAG" {
+  default = "bar"
+}
+```
+
+Since `docker-bake.override.hcl` is loaded last in the default lookup order,
+the `TAG` variable is overridden with the value `bar`.
+
+```console
+$ docker buildx bake --print
+{
+  "target": {
+    "default": {
+      "context": ".",
+      "dockerfile": "Dockerfile",
+      "tags": ["username/my-app:bar"]
+    }
+  }
+}
+```
+
+### Manual file overrides
+
+You can use the `--file` flag to explicitly specify which files to load,
+and use this as a way to conditionally apply override files.
+
+For example, you can create a file that defines a set of configurations for a
+specific environment, and load it only when building for that environment. The
+following example shows how to load an `override.hcl` file that sets the `TAG`
+variable to `bar`. The `TAG` variable is then used in the `default` target.
+
+```hcl {title=docker-bake.hcl}
+variable "TAG" {
+  default = "foo"
+}
+
+target "default" {
+  tags = ["username/my-app:${TAG}"]
+}
+```
+
+```hcl {title=overrides.hcl}
+variable "TAG" {
+  default = "bar"
+}
+```
+
+Printing the build configuration without the `--file` flag shows the `TAG`
+variable is set to the default value `foo`.
+
+```console
+$ docker buildx bake --print
+{
+  "target": {
+    "default": {
+      "context": ".",
+      "dockerfile": "Dockerfile",
+      "tags": [
+        "username/my-app:foo"
+      ]
+    }
+  }
+}
+```
+
+Using the `--file` flag to load the `overrides.hcl` file overrides the `TAG`
+variable with the value `bar`.
+
+```console
+$ docker buildx bake -f docker-bake.hcl -f overrides.hcl --print
+{
+  "target": {
+    "default": {
+      "context": ".",
+      "dockerfile": "Dockerfile",
+      "tags": [
+        "username/my-app:bar"
+      ]
+    }
+  }
+}
+```
+
+## Command line
+
+You can also override target configurations from the command line with the
+[`--set` flag](../../reference/cli/docker/buildx/bake.md#set):
+
+```hcl
+# docker-bake.hcl
+target "app" {
+  args = {
+    mybuildarg = "foo"
+  }
+}
+```
+
+```console
+$ docker buildx bake --set app.args.mybuildarg=bar --set app.platform=linux/arm64 app --print
+```
+
+```json
+{
+  "group": {
+    "default": {
+      "targets": ["app"]
+    }
+  },
+  "target": {
+    "app": {
+      "context": ".",
+      "dockerfile": "Dockerfile",
+      "args": {
+        "mybuildarg": "bar"
+      },
+      "platforms": ["linux/arm64"]
+    }
+  }
+}
+```
+
+Pattern matching syntax defined in [https://golang.org/pkg/path/#Match](https://golang.org/pkg/path/#Match)
+is also supported:
+
+```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"
+```
+
+Complete list of attributes that can be overridden with `--set` are:
+
+- `args`
+- `cache-from`
+- `cache-to`
+- `context`
+- `dockerfile`
+- `labels`
+- `no-cache`
+- `output`
+- `platform`
+- `pull`
+- `secrets`
+- `ssh`
+- `tags`
+- `target`
+
+## Environment variables
+
+You can also use environment variables to override configurations.
+
+Bake lets you use environment variables to override the value of a `variable`
+block. Only `variable` blocks can be overridden with environment variables.
+This means you need to define the variables in the bake file and then set the
+environment variable with the same name to override it.
+
+The following example shows how you can define a `TAG` variable with a default
+value in the Bake file, and override it with an environment variable.
+
+```hcl
+variable "TAG" {
+  default = "latest"
+}
+
+target "default" {
+  context = "."
+  dockerfile = "Dockerfile"
+  tags = ["docker.io/username/webapp:${TAG}"]
+}
+```
+
+```console
+$ export TAG=$(git rev-parse --short HEAD)
+$ docker buildx bake --print webapp
+```
+
+The `TAG` variable is overridden with the value of the environment variable,
+which is the short commit hash generated by `git rev-parse --short HEAD`.
+
+```json
+{
+  "group": {
+    "default": {
+      "targets": ["webapp"]
+    }
+  },
+  "target": {
+    "webapp": {
+      "context": ".",
+      "dockerfile": "Dockerfile",
+      "tags": ["docker.io/username/webapp:985e9e9"]
+    }
+  }
+}
+```
+
+### Type coercion
+
+Overriding non-string variables with environment variables is supported. Values
+passed as environment variables are coerced into suitable types first.
+
+The following example defines a `PORT` variable with a default value of `8080`.
+The `default` target uses a [ternary operator](expressions.md#ternary-operators)
+to set the `PORT` variable to the value of the environment variable `PORT`
+if it is greater than `1024`, otherwise it uses the default value.
+
+In this case, the `PORT` variable is coerced to an integer before the ternary
+operator is evaluated.
+
+```hcl
+default_port = 8080
+
+variable "PORT" {
+  default = default_port
+}
+
+target "default" {
+  args = {
+    PORT = PORT > 1024 ? PORT : default_port
+  }
+}
+```
+
+Attempting to set the `PORT` variable with a value less than `1024` will result
+in the default value being used.
+
+```console
+$ PORT=80 docker buildx bake --print
+```
+
+```json
+{
+  "target": {
+    "default": {
+      "context": ".",
+      "dockerfile": "Dockerfile",
+      "args": {
+        "PORT": "8080"
+      }
+    }
+  }
+}
+```
diff --git a/content/build/release-notes.md b/content/build/release-notes.md
index 8134c90df9..83c2916701 100644
--- a/content/build/release-notes.md
+++ b/content/build/release-notes.md
@@ -415,7 +415,7 @@ The full release note for this release is available
   for initializing the context with a value of a local OCI layout directory.
   E.g. `--build-context stagename=oci-layout://path/to/dir`. This feature
   requires BuildKit v0.11.0+ and Dockerfile 1.5.0+. [docker/buildx#1456](https://github.com/docker/buildx/issues/1456)
-- Bake now supports [resource interpolation](bake/configuring-build.md#resource-interpolation)
+- Bake now supports [resource interpolation](bake/inheritance.md#reusing-single-attribute-from-targets)
   where you can reuse the values from other target definitions. [docker/buildx#1434](https://github.com/docker/buildx/issues/1434)
 - Buildx will now automatically forward `SOURCE_DATE_EPOCH` environment variable
   if it is defined in your environment. This feature is meant to be used with
diff --git a/data/toc.yaml b/data/toc.yaml
index fb8f1b53f1..becf110fef 100644
--- a/data/toc.yaml
+++ b/data/toc.yaml
@@ -1959,10 +1959,10 @@ Manuals:
           title: Inheritance
         - path: /build/bake/variables/
           title: Variables
+        - path: /build/bake/overrides/
+          title: Overriding configuration
         - path: /build/bake/reference/
           title: Bake file reference
-        - path: /build/bake/configuring-build/
-          title: Configuring builds
         - path: /build/bake/advanced/
           title: Advanced patterns
         - path: /build/bake/build-contexts/