publicWagsHome
/
buildx
1
0
Fork 1
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: rework bake "Configuring builds" page

Browse Source 
Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>
pull/1140/head
CrazyMax 3 years ago
parent 824b0268d8
commit ff9517cbf0
No known key found for this signature in database
GPG Key ID: 3248E46B6BB8C7F7
4 changed files with 92 additions and 88 deletions
Show Stats Download Patch File Download Diff File

71
docs/guides/bake/configuring-build.md
Unescape Escape View File

@ -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"
}
}
}
}
```

28
docs/guides/bake/file-definition.md
Unescape Escape View File

@ -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

79
docs/guides/bake/hcl-vars-funcs.md → docs/guides/bake/hcl-funcs.md
Unescape Escape View File

@ -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`).

2
docs/guides/bake/index.md
Unescape Escape View File

@ -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)

Write Preview
Loading…
Cancel
Save