From 0cf06b617f42126ed56aabecdb39cf7342fc8b00 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Mon, 17 Jun 2024 13:22:00 +0200
Subject: [PATCH] build(bake): add variables description

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 content/build/bake/variables.md | 126 ++++++++++++++++++++++++++++++++
 data/toc.yaml                   |   2 +
 2 files changed, 128 insertions(+)
 create mode 100644 content/build/bake/variables.md

diff --git a/content/build/bake/variables.md b/content/build/bake/variables.md
new file mode 100644
index 0000000000..6f5725d86a
--- /dev/null
+++ b/content/build/bake/variables.md
@@ -0,0 +1,126 @@
+---
+title: Variables in Bake
+description: 
+keywords: build, buildx, bake, buildkit, hcl, variables
+---
+
+You can define and use variables in a Bake file to set attribute values,
+interpolate them into other values, and perform arithmetic operations.
+Variables can be defined with default values, and can be overridden with
+environment variables.
+
+## Using variables as attribute values
+
+Use the `variable` block to define a variable.
+
+```hcl
+variable "TAG" {
+  default = "docker.io/username/webapp:latest"
+}
+```
+
+The following example shows how to use the `TAG` variable in a target.
+
+```hcl
+target "default" {
+  context = "."
+  dockerfile = "Dockerfile"
+  tags = [ TAG ]
+}
+```
+
+## Interpolate variables into values
+
+Bake supports string interpolation of variables into values. You can use the
+`${}` syntax to interpolate a variable into a value. The following example
+defines a `TAG` variable with a value of `latest`.
+
+```hcl
+variable "TAG" {
+  default = "latest"
+}
+```
+
+To interpolate the `TAG` variable into the value of an attribute, use the
+`${TAG}` syntax.
+
+```hcl
+target "default" {
+  context = "."
+  dockerfile = "Dockerfile"
+  tags = ["docker.io/username/webapp:${TAG}"]
+}
+```
+
+Printing the Bake file with the `--print` flag shows the interpolated value in
+the resolved build configuration.
+
+```console
+$ docker buildx bake --print
+```
+
+```json
+{
+  "group": {
+    "default": {
+      "targets": ["webapp"]
+    }
+  },
+  "target": {
+    "webapp": {
+      "context": ".",
+      "dockerfile": "Dockerfile",
+      "tags": ["docker.io/username/webapp:latest"]
+    }
+  }
+}
+```
+
+## Using variables in variables across files
+
+When multiple files are specified, one file can use variables defined in
+another file. In the following example, the `vars.hcl` file defines a
+`BASE_IMAGE` variable with a default value of `docker.io/library/alpine`.
+
+```hcl {title=vars.hcl}
+variable "BASE_IMAGE" {
+  default = "docker.io/library/alpine"
+}
+```
+
+The following `docker-bake.hcl` file defines a `BASE_LATEST` variable that
+references the `BASE_IMAGE` variable.
+
+```hcl {title=docker-bake.hcl}
+variable "BASE_LATEST" {
+  default = "${BASE_IMAGE}:latest"
+}
+
+target "default" {
+  contexts = {
+    base = BASE_LATEST
+  }
+}
+```
+
+When you print the resolved build configuration, using the `-f` flag to specify
+the `vars.hcl` and `docker-bake.hcl` files, you see that the `BASE_LATEST`
+variable is resolved to `docker.io/library/alpine:latest`.
+
+```console
+$ docker buildx bake -f vars.hcl -f docker-bake.hcl --print app
+```
+
+```json
+{
+  "target": {
+    "default": {
+      "context": ".",
+      "contexts": {
+        "base": "docker.io/library/alpine:latest"
+      },
+      "dockerfile": "Dockerfile"
+    }
+  }
+}
+```
diff --git a/data/toc.yaml b/data/toc.yaml
index e5c3ef2508..fb8f1b53f1 100644
--- a/data/toc.yaml
+++ b/data/toc.yaml
@@ -1957,6 +1957,8 @@ Manuals:
           title: Targets
         - path: /build/bake/inheritance/
           title: Inheritance
+        - path: /build/bake/variables/
+          title: Variables
         - path: /build/bake/reference/
           title: Bake file reference
         - path: /build/bake/configuring-build/