diff --git a/docs/guides/bake/configuring-build.md b/docs/guides/bake/configuring-build.md new file mode 100644 index 00000000..aa5851a8 --- /dev/null +++ b/docs/guides/bake/configuring-build.md @@ -0,0 +1,150 @@ +--- +title: "Configuring builds" +keywords: build, buildx, bake, buildkit, hcl, json +--- + +## 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" + } + } + } +} +``` + +## 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): + +```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` diff --git a/docs/guides/bake/file-definition.md b/docs/guides/bake/file-definition.md index 7c2bd80c..528c4572 100644 --- a/docs/guides/bake/file-definition.md +++ b/docs/guides/bake/file-definition.md @@ -105,7 +105,7 @@ $ TAG=dev docker buildx bake webapp-dev # will use the TAG environment variable > **Tip** > -> You can also define [global scope attributes](#global-scope-attributes). +> See also the [Configuring builds](configuring-build.md) page for advanced usage. ### Functions @@ -440,83 +440,3 @@ $ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test" "htt #8 0.136 -rwxrwxrwx 1 root root 9620 Jul 27 18:31 vendor.conf #8 0.136 /bin/sh: stop: not found ``` - -## 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" - } - } - } -} -``` diff --git a/docs/guides/bake/hcl-vars-funcs.md b/docs/guides/bake/hcl-vars-funcs.md index 3f7a76f2..6197a26c 100644 --- a/docs/guides/bake/hcl-vars-funcs.md +++ b/docs/guides/bake/hcl-vars-funcs.md @@ -15,8 +15,9 @@ are also supported. ## Using interpolation to tag an image with the git sha -Bake supports variable blocks which are assigned to matching environment -variables or default values. +As shown in the [File definition](file-definition.md#variable) page, `bake` +supports variable blocks which are assigned to matching environment variables +or default values: ```hcl # docker-bake.hcl diff --git a/docs/guides/bake/index.md b/docs/guides/bake/index.md index 88c5fecb..94d6a38b 100644 --- a/docs/guides/bake/index.md +++ b/docs/guides/bake/index.md @@ -33,6 +33,7 @@ and also allows better code reuse, different target groups and extended features ## Next steps * [File definition](file-definition.md) +* [Configuring builds](configuring-build.md) * [HCL variables and functions](hcl-vars-funcs.md) * [Defining additional build contexts and linking targets](build-contexts.md) * [Extension field with Compose](compose-xbake.md)