diff --git a/docs/guides/bake/configuring-build.md b/docs/guides/bake/configuring-build.md index aa5851a8..66149726 100644 --- a/docs/guides/bake/configuring-build.md +++ b/docs/guides/bake/configuring-build.md @@ -3,6 +3,14 @@ title: "Configuring builds" keywords: build, buildx, bake, buildkit, hcl, json --- +Bake supports loading build definition from files, but sometimes you need even +more flexibility to configure this definition. + +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 @@ -85,7 +93,8 @@ $ docker buildx bake -f docker-bake.hcl -f env.hcl --print app ## From command line -You can also override target configurations from the command line with [`--set` flag](https://docs.docker.com/engine/reference/commandline/buildx_bake/#set): +You can also override target configurations from the command line with the +[`--set` flag](https://docs.docker.com/engine/reference/commandline/buildx_bake/#set): ```hcl # docker-bake.hcl @@ -148,3 +157,63 @@ Complete list of overridable fields: * `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/docs/guides/bake/file-definition.md b/docs/guides/bake/file-definition.md index 0ce787f7..be1e4563 100644 --- a/docs/guides/bake/file-definition.md +++ b/docs/guides/bake/file-definition.md @@ -4,9 +4,9 @@ keywords: build, buildx, bake, buildkit, hcl, json, compose --- `buildx bake` supports HCL, JSON and Compose file format for defining build -groups, targets as well as [variables and functions](hcl-vars-funcs.md). It -looks for build definition files in the current directory in the following -order: +[groups](#group), [targets](#target) as well as [variables](#variable) and +[functions](#functions). It looks for build definition files in the current +directory in the following order: * `docker-compose.yml` * `docker-compose.yaml` @@ -87,7 +87,9 @@ $ docker buildx bake build ### Variable -You can define variables with values provided by the current environment, or a +Similar to how Terraform provides a way to [define variables](https://www.terraform.io/docs/configuration/variables.html#declaring-an-input-variable), +the HCL file format also supports variable block definitions. These can be used +to define variables with values provided by the current environment, or a default value when unset: ```hcl @@ -112,7 +114,9 @@ $ TAG=dev docker buildx bake webapp-dev # will use the TAG environment variable ### Functions -A set of generally useful functions are available for use in HCL files: +A [set of generally useful functions](https://github.com/docker/buildx/blob/master/bake/hclparser/stdlib.go) +provided by [go-cty](https://github.com/zclconf/go-cty/tree/main/cty/function/stdlib) +are available for use in HCL files: ```hcl # docker-bake.hcl @@ -125,7 +129,8 @@ target "webapp-dev" { } ``` -User defined functions are also supported: +In addition, [user defined functions](https://github.com/hashicorp/hcl/tree/main/ext/userfunc) +are also supported: ```hcl # docker-bake.hcl @@ -145,7 +150,14 @@ target "webapp-dev" { > **Note** > -> See [HCL variables and functions](hcl-vars-funcs.md) page for more details. +> See [User defined HCL functions](hcl-funcs.md) page for more details. + +## Built-in variables + +* `BAKE_CMD_CONTEXT` can be used to access the main `context` for bake command + from a bake file that has been [imported remotely](file-definition.md#remote-definition). +* `BAKE_LOCAL_PLATFORM` returns the current platform's default platform + specification (e.g. `linux/amd64`). ## Merging and inheritance @@ -363,7 +375,7 @@ As you can see the context is fixed to `https://github.com/docker/cli.git` even in the definition. If you want to access the main context for bake command from a bake file -that has been imported remotely, you can use the [`BAKE_CMD_CONTEXT` built-in var](hcl-vars-funcs.md#built-in-variables). +that has been imported remotely, you can use the [`BAKE_CMD_CONTEXT` built-in var](#built-in-variables). ```console $ cat https://raw.githubusercontent.com/tonistiigi/buildx/remote-test/docker-bake.hcl diff --git a/docs/guides/bake/hcl-vars-funcs.md b/docs/guides/bake/hcl-funcs.md similarity index 72% rename from docs/guides/bake/hcl-vars-funcs.md rename to docs/guides/bake/hcl-funcs.md index 6197a26c..56196f80 100644 --- a/docs/guides/bake/hcl-vars-funcs.md +++ b/docs/guides/bake/hcl-funcs.md @@ -1,18 +1,8 @@ --- -title: "HCL variables and functions" +title: "User defined HCL functions" keywords: build, buildx, bake, buildkit, hcl --- -Similar to how Terraform provides a way to [define variables](https://www.terraform.io/docs/configuration/variables.html#declaring-an-input-variable), -the HCL file format also supports variable block definitions. These can be used -to define variables with values provided by the current environment, or a -default value when unset. - -A [set of generally useful functions](https://github.com/docker/buildx/blob/master/bake/hclparser/stdlib.go) -provided by [go-cty](https://github.com/zclconf/go-cty/tree/main/cty/function/stdlib) -are available for use in HCL files. In addition, [user defined functions](https://github.com/hashicorp/hcl/tree/main/ext/userfunc) -are also supported. - ## Using interpolation to tag an image with the git sha As shown in the [File definition](file-definition.md#variable) page, `bake` @@ -291,66 +281,6 @@ $ docker buildx bake --print webapp } ``` -## 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" - } - } - } -} -``` - ## Using typed variables Non-string variables are also accepted. The value passed with env is parsed @@ -398,10 +328,3 @@ $ docker buildx bake --print app } } ``` - -## Built-in variables - -* `BAKE_CMD_CONTEXT` can be used to access the main `context` for bake command - from a bake file that has been [imported remotely](file-definition.md#remote-definition). -* `BAKE_LOCAL_PLATFORM` returns the current platform's default platform - specification (e.g. `linux/amd64`). diff --git a/docs/guides/bake/index.md b/docs/guides/bake/index.md index 94d6a38b..8f90db58 100644 --- a/docs/guides/bake/index.md +++ b/docs/guides/bake/index.md @@ -34,6 +34,6 @@ and also allows better code reuse, different target groups and extended features * [File definition](file-definition.md) * [Configuring builds](configuring-build.md) -* [HCL variables and functions](hcl-vars-funcs.md) +* [User defined HCL functions](hcl-funcs.md) * [Defining additional build contexts and linking targets](build-contexts.md) * [Extension field with Compose](compose-xbake.md)