mirror of https://github.com/docker/docs.git
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
parent
0cf06b617f
commit
d04c833e69
|
|
@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -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.
|
||||
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)
|
||||
- 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)
|
||||
- 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
|
||||
|
|
|
|||
|
|
@ -1959,10 +1959,10 @@ Manuals:
|
|||
title: Inheritance
|
||||
- path: /build/bake/variables/
|
||||
title: Variables
|
||||
- path: /build/bake/overrides/
|
||||
title: Overriding configuration
|
||||
- path: /build/bake/reference/
|
||||
title: Bake file reference
|
||||
- path: /build/bake/configuring-build/
|
||||
title: Configuring builds
|
||||
- path: /build/bake/advanced/
|
||||
title: Advanced patterns
|
||||
- path: /build/bake/build-contexts/
|
||||
|
|
|
|||
Loading…
Reference in New Issue