docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

build(bake): add overrides page, remove configuring-build 

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
This commit is contained in:
David Karlsson 2024-06-17 13:32:59 +02:00
parent 0cf06b617f
commit d04c833e69
4 changed files with 335 additions and 264 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

261
content/build/bake/configuring-build.md
View File

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

332
content/build/bake/overrides.md Normal file
View File

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

2
content/build/release-notes.md
View File

@ -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. 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 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) 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) 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 - 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 if it is defined in your environment. This feature is meant to be used with

4
data/toc.yaml
View File

@ -1959,10 +1959,10 @@ Manuals:
title: Inheritance title: Inheritance
- path: /build/bake/variables/ - path: /build/bake/variables/
title: Variables title: Variables
- path: /build/bake/overrides/
title: Overriding configuration
- path: /build/bake/reference/ - path: /build/bake/reference/
title: Bake file reference title: Bake file reference
- path: /build/bake/configuring-build/
title: Configuring builds
- path: /build/bake/advanced/ - path: /build/bake/advanced/
title: Advanced patterns title: Advanced patterns
- path: /build/bake/build-contexts/ - path: /build/bake/build-contexts/