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

Merge pull request #15422 from docker-tools-robot/dispatch/buildx-ref-v0.9.1 

Update buildx reference to v0.9.1
This commit is contained in:
CrazyMax 2022-09-07 12:03:36 +02:00 committed by GitHub
parent 573da07d2f 732459ba3f
commit c21f31badf
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
17 changed files with 2341 additions and 3045 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

918
_data/buildx/docker_buildx_bake.yaml
View File

@ -1,16 +1,18 @@
command: docker buildx bake command: docker buildx bake
aliases: f aliases: docker buildx bake, docker buildx f
short: Build from a file short: Build from a file
long: |- long: |-
Bake is a high-level build command. Each specified target will run in parallel Bake is a high-level build command. Each specified target will run in parallel
as part of the build. as part of the build.
Read [High-level build options](https://github.com/docker/buildx#high-level-build-options) Read [High-level build options with Bake](/build/bake/)
for introduction. guide for introduction to writing bake files.
Please note that `buildx bake` command may receive backwards incompatible > **Note**
features in the future if needed. We are looking for feedback on improving the >
command and extending the functionality further. > `buildx bake` command may receive backwards incompatible features in the future
> if needed. We are looking for feedback on improving the command and extending
> the functionality further.
usage: docker buildx bake [OPTIONS] [TARGET...] usage: docker buildx bake [OPTIONS] [TARGET...]
pname: docker buildx pname: docker buildx
plink: docker_buildx.yaml plink: docker_buildx.yaml
@ -130,166 +132,42 @@ examples: |-
### Specify a build definition file (-f, --file) {#file} ### Specify a build definition file (-f, --file) {#file}
By default, `buildx bake` looks for build definition files in the current Use the `-f` / `--file` option to specify the build definition file to use.
directory, the following are parsed: The file can be an HCL, JSON or Compose file. If multiple files are specified
- `docker-compose.yml`
- `docker-compose.yaml`
- `docker-bake.json`
- `docker-bake.override.json`
- `docker-bake.hcl`
- `docker-bake.override.hcl`
Use the `-f` / `--file` option to specify the build definition file to use. The
file can be a Docker Compose, JSON or HCL file. If multiple files are specified
they are all read and configurations are combined. they are all read and configurations are combined.
The following example uses a Docker Compose file named `docker-compose.dev.yaml` You can pass the names of the targets to build, to build only specific target(s).
as build definition file, and builds all targets in the file: The following example builds the `db` and `webapp-release` targets that are
defined in the `docker-bake.dev.hcl` file:
```console ```hcl
$ docker buildx bake -f docker-compose.dev.yaml # docker-bake.dev.hcl
group "default" {
[+] Building 66.3s (30/30) FINISHED targets = ["db", "webapp-dev"]
=> [frontend internal] load build definition from Dockerfile 0.1s
=> => transferring dockerfile: 36B 0.0s
=> [backend internal] load build definition from Dockerfile 0.2s
=> => transferring dockerfile: 3.73kB 0.0s
=> [database internal] load build definition from Dockerfile 0.1s
=> => transferring dockerfile: 5.77kB 0.0s
...
```
Pass the names of the targets to build, to build only specific target(s). The
following example builds the `backend` and `database` targets that are defined
in the `docker-compose.dev.yaml` file, skipping the build for the `frontend`
target:
```console
$ docker buildx bake -f docker-compose.dev.yaml backend database
[+] Building 2.4s (13/13) FINISHED
=> [backend internal] load build definition from Dockerfile 0.1s
=> => transferring dockerfile: 81B 0.0s
=> [database internal] load build definition from Dockerfile 0.2s
=> => transferring dockerfile: 36B 0.0s
=> [backend internal] load .dockerignore 0.3s
...
```
You can also use a remote `git` bake definition:
```console
$ docker buildx bake "https://github.com/docker/cli.git#v20.10.11" --print
#1 [internal] load git source https://github.com/docker/cli.git#v20.10.11
#1 0.745 e8f1871b077b64bcb4a13334b7146492773769f7 refs/tags/v20.10.11
#1 2.022 From https://github.com/docker/cli
#1 2.022 * [new tag] v20.10.11 -> v20.10.11
#1 DONE 2.9s
{
"group": {
"default": {
"targets": [
"binary"
]
} }
},
"target": {
"binary": {
"context": "https://github.com/docker/cli.git#v20.10.11",
"dockerfile": "Dockerfile",
"args": {
"BASE_VARIANT": "alpine",
"GO_STRIP": "",
"VERSION": ""
},
"target": "binary",
"platforms": [
"local"
],
"output": [
"build"
]
}
}
}
```
As you can see the context is fixed to `https://github.com/docker/cli.git` even if target "webapp-dev" {
[no context is actually defined](https://github.com/docker/cli/blob/2776a6d694f988c0c1df61cad4bfac0f54e481c8/docker-bake.hcl#L17-L26) dockerfile = "Dockerfile.webapp"
in the definition. tags = ["docker.io/username/webapp"]
}
If you want to access the main context for bake command from a bake file target "webapp-release" {
that has been imported remotely, you can use the `BAKE_CMD_CONTEXT` builtin var: inherits = ["webapp-dev"]
platforms = ["linux/amd64", "linux/arm64"]
}
```console target "db" {
$ cat https://raw.githubusercontent.com/tonistiigi/buildx/remote-test/docker-bake.hcl dockerfile = "Dockerfile.db"
target "default" { tags = ["docker.io/username/db"]
context = BAKE_CMD_CONTEXT
dockerfile-inline = <<EOT
FROM alpine
WORKDIR /src
COPY . .
RUN ls -l && stop
EOT
} }
``` ```
```console ```console
$ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test" --print $ docker buildx bake -f docker-bake.dev.hcl db webapp-release
{
"target": {
"default": {
"context": ".",
"dockerfile": "Dockerfile",
"dockerfile-inline": "FROM alpine\nWORKDIR /src\nCOPY . .\nRUN ls -l \u0026\u0026 stop\n"
}
}
}
``` ```
```console See our [file definition](/build/bake/file-definition/)
$ touch foo bar guide for more details.
$ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test"
...
> [4/4] RUN ls -l && stop:
#8 0.101 total 0
#8 0.102 -rw-r--r-- 1 root root 0 Jul 27 18:47 bar
#8 0.102 -rw-r--r-- 1 root root 0 Jul 27 18:47 foo
#8 0.102 /bin/sh: stop: not found
```
```console
$ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test" "https://github.com/docker/cli.git#v20.10.11" --print
#1 [internal] load git source https://github.com/tonistiigi/buildx.git#remote-test
#1 0.429 577303add004dd7efeb13434d69ea030d35f7888 refs/heads/remote-test
#1 CACHED
{
"target": {
"default": {
"context": "https://github.com/docker/cli.git#v20.10.11",
"dockerfile": "Dockerfile",
"dockerfile-inline": "FROM alpine\nWORKDIR /src\nCOPY . .\nRUN ls -l \u0026\u0026 stop\n"
}
}
}
```
```console
$ docker buildx bake "https://github.com/tonistiigi/buildx.git#remote-test" "https://github.com/docker/cli.git#v20.10.11"
...
> [4/4] RUN ls -l && stop:
#8 0.136 drwxrwxrwx 5 root root 4096 Jul 27 18:31 kubernetes
#8 0.136 drwxrwxrwx 3 root root 4096 Jul 27 18:31 man
#8 0.136 drwxrwxrwx 2 root root 4096 Jul 27 18:31 opts
#8 0.136 -rw-rw-rw- 1 root root 1893 Jul 27 18:31 poule.yml
#8 0.136 drwxrwxrwx 7 root root 4096 Jul 27 18:31 scripts
#8 0.136 drwxrwxrwx 3 root root 4096 Jul 27 18:31 service
#8 0.136 drwxrwxrwx 2 root root 4096 Jul 27 18:31 templates
#8 0.136 drwxrwxrwx 10 root root 4096 Jul 27 18:31 vendor
#8 0.136 -rwxrwxrwx 1 root root 9620 Jul 27 18:31 vendor.conf
#8 0.136 /bin/sh: stop: not found
```
### Do not use cache when building the image (--no-cache) {#no-cache} ### Do not use cache when building the image (--no-cache) {#no-cache}
@ -324,26 +202,7 @@ examples: |-
### Set type of progress output (--progress) {#progress} ### Set type of progress output (--progress) {#progress}
Same as [`build --progress`](buildx_build.md#progress). Set type of progress Same as [`build --progress`](buildx_build.md#progress).
output (auto, plain, tty). Use plain to show container output (default "auto").
> You can also use the `BUILDKIT_PROGRESS` environment variable to set its value.
The following example uses `plain` output during the build:
```console
$ docker buildx bake --progress=plain
#2 [backend internal] load build definition from Dockerfile.test
#2 sha256:de70cb0bb6ed8044f7b9b1b53b67f624e2ccfb93d96bb48b70c1fba562489618
#2 ...
#1 [database internal] load build definition from Dockerfile.test
#1 sha256:453cb50abd941762900a1212657a35fc4aad107f5d180b0ee9d93d6b74481bce
#1 transferring dockerfile: 36B done
#1 DONE 0.1s
...
```
### Always attempt to pull a newer version of the image (--pull) {#pull} ### Always attempt to pull a newer version of the image (--pull) {#pull}
@ -367,704 +226,23 @@ examples: |-
``` ```
Complete list of overridable fields: Complete list of overridable fields:
`args`, `cache-from`, `cache-to`, `context`, `dockerfile`, `labels`, `no-cache`,
`output`, `platform`, `pull`, `secrets`, `ssh`, `tags`, `target`
### File definition * `args`
* `cache-from`
In addition to compose files, bake supports a JSON and an equivalent HCL file * `cache-to`
format for defining build groups and targets. * `context`
* `dockerfile`
A target reflects a single docker build invocation with the same options that * `labels`
you would specify for `docker build`. A group is a grouping of targets. * `no-cache`
* `no-cache-filter`
Multiple files can include the same target and final build options will be * `output`
determined by merging them together. * `platform`
* `pull`
In the case of compose files, each service corresponds to a target. * `push`
* `secrets`
A group can specify its list of targets with the `targets` option. A target can * `ssh`
inherit build options by setting the `inherits` option to the list of targets or * `tags`
groups to inherit from. * `target`
Note: Design of bake command is work in progress, the user experience may change
based on feedback.
HCL definition example:
```hcl
group "default" {
targets = ["db", "webapp-dev"]
}
target "webapp-dev" {
dockerfile = "Dockerfile.webapp"
tags = ["docker.io/username/webapp"]
}
target "webapp-release" {
inherits = ["webapp-dev"]
platforms = ["linux/amd64", "linux/arm64"]
}
target "db" {
dockerfile = "Dockerfile.db"
tags = ["docker.io/username/db"]
}
```
Complete list of valid target fields:
`args`, `cache-from`, `cache-to`, `context`, `contexts`, `dockerfile`, `inherits`, `labels`,
`no-cache`, `no-cache-filter`, `output`, `platform`, `pull`, `secrets`, `ssh`, `tags`, `target`
### 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
{
"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
{
"group": {
"default": {
"targets": [
"app"
]
}
},
"target": {
"app": {
"context": ".",
"dockerfile": "Dockerfile",
"args": {
"v1": "pre-def-myuser"
}
}
}
}
```
### HCL variables and functions
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
Bake supports variable blocks which are assigned to matching environment
variables or default values.
```hcl
# docker-bake.hcl
variable "TAG" {
default = "latest"
}
group "default" {
targets = ["webapp"]
}
target "webapp" {
tags = ["docker.io/username/webapp:${TAG}"]
}
```
alternatively, in json format:
```json
{
"variable": {
"TAG": {
"default": "latest"
}
}
"group": {
"default": {
"targets": ["webapp"]
}
},
"target": {
"webapp": {
"tags": ["docker.io/username/webapp:${TAG}"]
}
}
}
```
```console
$ docker buildx bake --print webapp
{
"group": {
"default": {
"targets": [
"webapp"
]
}
},
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"tags": [
"docker.io/username/webapp:latest"
]
}
}
}
```
```console
$ TAG=$(git rev-parse --short HEAD) docker buildx bake --print webapp
{
"group": {
"default": {
"targets": [
"webapp"
]
}
},
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"tags": [
"docker.io/username/webapp:985e9e9"
]
}
}
}
```
#### Using the `add` function
You can use [`go-cty` stdlib functions](https://github.com/zclconf/go-cty/tree/main/cty/function/stdlib).
Here we are using the `add` function.
```hcl
# docker-bake.hcl
variable "TAG" {
default = "latest"
}
group "default" {
targets = ["webapp"]
}
target "webapp" {
args = {
buildno = "${add(123, 1)}"
}
}
```
```console
$ docker buildx bake --print webapp
{
"group": {
"default": {
"targets": [
"webapp"
]
}
},
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"args": {
"buildno": "124"
}
}
}
}
```
#### Defining an `increment` function
It also supports [user defined functions](https://github.com/hashicorp/hcl/tree/main/ext/userfunc).
The following example defines a simple an `increment` function.
```hcl
# docker-bake.hcl
function "increment" {
params = [number]
result = number + 1
}
group "default" {
targets = ["webapp"]
}
target "webapp" {
args = {
buildno = "${increment(123)}"
}
}
```
```console
$ docker buildx bake --print webapp
{
"group": {
"default": {
"targets": [
"webapp"
]
}
},
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"args": {
"buildno": "124"
}
}
}
}
```
#### Only adding tags if a variable is not empty using an `notequal`
Here we are using the conditional `notequal` function which is just for
symmetry with the `equal` one.
```hcl
# docker-bake.hcl
variable "TAG" {default="" }
group "default" {
targets = [
"webapp",
]
}
target "webapp" {
context="."
dockerfile="Dockerfile"
tags = [
"my-image:latest",
notequal("",TAG) ? "my-image:${TAG}": "",
]
}
```
```console
$ docker buildx bake --print webapp
{
"group": {
"default": {
"targets": [
"webapp"
]
}
},
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"tags": [
"my-image:latest"
]
}
}
}
```
#### Using variables in functions
You can refer variables to other variables like the target blocks can. Stdlib
functions can also be called but user functions can't at the moment.
```hcl
# docker-bake.hcl
variable "REPO" {
default = "user/repo"
}
function "tag" {
params = [tag]
result = ["${REPO}:${tag}"]
}
target "webapp" {
tags = tag("v1")
}
```
```console
$ docker buildx bake --print webapp
{
"group": {
"default": {
"targets": [
"webapp"
]
}
},
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"tags": [
"user/repo:v1"
]
}
}
}
```
#### 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
{
"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
into suitable type first.
```hcl
# docker-bake.hcl
variable "FOO" {
default = 3
}
variable "IS_FOO" {
default = true
}
target "app" {
args = {
v1 = FOO > 5 ? "higher" : "lower"
v2 = IS_FOO ? "yes" : "no"
}
}
```
```console
$ docker buildx bake --print app
{
"group": {
"default": {
"targets": [
"app"
]
}
},
"target": {
"app": {
"context": ".",
"dockerfile": "Dockerfile",
"args": {
"v1": "lower",
"v2": "yes"
}
}
}
}
```
### Defining additional build contexts and linking targets
In addition to the main `context` key that defines the build context each target can also define additional named contexts with a map defined with key `contexts`. These values map to the `--build-context` flag in the [build command](buildx_build.md#build-context).
Inside the Dockerfile these contexts can be used with the `FROM` instruction or `--from` flag.
The value can be a local source directory, container image (with docker-image:// prefix), Git URL, HTTP URL or a name of another target in the Bake file (with target: prefix).
#### Pinning alpine image
```Dockerfile
# Dockerfile
FROM alpine
RUN echo "Hello world"
```
```hcl
# docker-bake.hcl
target "app" {
contexts = {
alpine = "docker-image://alpine:3.13"
}
}
```
#### Using a secondary source directory
```Dockerfile
# Dockerfile
FROM scratch AS src
FROM golang
COPY --from=src . .
```
```hcl
# docker-bake.hcl
target "app" {
contexts = {
src = "../path/to/source"
}
}
```
#### Using a result of one target as a base image in another target
To use a result of one target as a build context of another, specity the target name with `target:` prefix.
```Dockerfile
# Dockerfile
FROM baseapp
RUN echo "Hello world"
```
```hcl
# docker-bake.hcl
target "base" {
dockerfile = "baseapp.Dockerfile"
}
target "app" {
contexts = {
baseapp = "target:base"
}
}
```
Please note that in most cases you should just use a single multi-stage Dockerfile with multiple targets for similar behavior. This case is recommended when you have multiple Dockerfiles that can't be easily merged into one.
### Extension field with Compose
[Special extension](https://github.com/compose-spec/compose-spec/blob/master/spec.md#extension)
field `x-bake` can be used in your compose file to evaluate fields that are not
(yet) available in the [build definition](https://github.com/compose-spec/compose-spec/blob/master/build.md#build-definition).
```yaml
# docker-compose.yml
services:
addon:
image: ct-addon:bar
build:
context: .
dockerfile: ./Dockerfile
args:
CT_ECR: foo
CT_TAG: bar
x-bake:
tags:
- ct-addon:foo
- ct-addon:alp
platforms:
- linux/amd64
- linux/arm64
cache-from:
- user/app:cache
- type=local,src=path/to/cache
cache-to: type=local,dest=path/to/cache
pull: true
aws:
image: ct-fake-aws:bar
build:
dockerfile: ./aws.Dockerfile
args:
CT_ECR: foo
CT_TAG: bar
x-bake:
secret:
- id=mysecret,src=./secret
- id=mysecret2,src=./secret2
platforms: linux/arm64
output: type=docker
no-cache: true
```
```console
$ docker buildx bake --print
{
"group": {
"default": {
"targets": [
"aws",
"addon"
]
}
},
"target": {
"addon": {
"context": ".",
"dockerfile": "./Dockerfile",
"args": {
"CT_ECR": "foo",
"CT_TAG": "bar"
},
"tags": [
"ct-addon:foo",
"ct-addon:alp"
],
"cache-from": [
"user/app:cache",
"type=local,src=path/to/cache"
],
"cache-to": [
"type=local,dest=path/to/cache"
],
"platforms": [
"linux/amd64",
"linux/arm64"
],
"pull": true
},
"aws": {
"context": ".",
"dockerfile": "./aws.Dockerfile",
"args": {
"CT_ECR": "foo",
"CT_TAG": "bar"
},
"tags": [
"ct-fake-aws:bar"
],
"secret": [
"id=mysecret,src=./secret",
"id=mysecret2,src=./secret2"
],
"platforms": [
"linux/arm64"
],
"output": [
"type=docker"
],
"no-cache": true
}
}
}
```
Complete list of valid fields for `x-bake`:
`tags`, `cache-from`, `cache-to`, `secret`, `ssh`, `platforms`, `output`,
`pull`, `no-cache`, `no-cache-filter`
### 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).
* `BAKE_LOCAL_PLATFORM` returns the current platform's default platform
specification (e.g. `linux/amd64`).
deprecated: false deprecated: false
experimental: false experimental: false
experimentalcli: false experimentalcli: false

77
_data/buildx/docker_buildx_build.yaml
View File

@ -1,5 +1,5 @@
command: docker buildx build command: docker buildx build
aliases: b aliases: docker buildx build, docker buildx b
short: Start a build short: Start a build
long: |- long: |-
The `buildx build` command starts a build using BuildKit. This command is similar The `buildx build` command starts a build using BuildKit. This command is similar
@ -180,6 +180,15 @@ options:
experimentalcli: false experimentalcli: false
kubernetes: false kubernetes: false
swarm: false swarm: false
- option: invoke
value_type: string
description: Invoke a command after the build [experimental]
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: isolation - option: isolation
value_type: string value_type: string
description: Container isolation technology description: Container isolation technology
@ -293,6 +302,16 @@ options:
experimentalcli: false experimentalcli: false
kubernetes: false kubernetes: false
swarm: false swarm: false
- option: print
value_type: string
description: |
Print result of information request (e.g., outline, targets) [experimental]
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: progress - option: progress
value_type: string value_type: string
default_value: auto default_value: auto
@ -457,7 +476,7 @@ examples: |-
- `network.host` - Allows executions with host networking. - `network.host` - Allows executions with host networking.
- `security.insecure` - Allows executions without sandbox. See - `security.insecure` - Allows executions without sandbox. See
[related Dockerfile extensions](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/experimental.md#run---securityinsecuresandbox). [related Dockerfile extensions](/engine/reference/builder/#run---securitysandbox).
For entitlements to be enabled, the `buildkitd` daemon also needs to allow them For entitlements to be enabled, the `buildkitd` daemon also needs to allow them
with `--allow-insecure-entitlement` (see [`create --buildkitd-flags`](buildx_create.md#buildkitd-flags)) with `--allow-insecure-entitlement` (see [`create --buildkitd-flags`](buildx_create.md#buildkitd-flags))
@ -478,13 +497,15 @@ examples: |-
* `BUILDKIT_CONTEXT_KEEP_GIT_DIR=<bool>` trigger git context to keep the `.git` directory * `BUILDKIT_CONTEXT_KEEP_GIT_DIR=<bool>` trigger git context to keep the `.git` directory
* `BUILDKIT_INLINE_BUILDINFO_ATTRS=<bool>` inline build info attributes in image config or not * `BUILDKIT_INLINE_BUILDINFO_ATTRS=<bool>` inline build info attributes in image config or not
* `BUILDKIT_INLINE_CACHE=<bool>` inline cache metadata to image config or not * `BUILDKIT_INLINE_CACHE=<bool>` inline cache metadata to image config or not
* `BUILDKIT_MULTI_PLATFORM=<bool>` opt into determnistic output regardless of multi-platform output or not * `BUILDKIT_MULTI_PLATFORM=<bool>` opt into deterministic output regardless of multi-platform output or not
```console ```console
$ docker buildx build --build-arg BUILDKIT_MULTI_PLATFORM=1 . $ docker buildx build --build-arg BUILDKIT_MULTI_PLATFORM=1 .
``` ```
More built-in build args can be found in [dockerfile frontend docs](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/syntax.md#built-in-build-args). > **Note**
>
> More built-in build args can be found in [Dockerfile reference docs](/engine/reference/builder/#buildkit-built-in-build-args).
### Additional build contexts (--build-context) {#build-context} ### Additional build contexts (--build-context) {#build-context}
@ -495,7 +516,7 @@ examples: |-
Define additional build context with specified contents. In Dockerfile the context can be accessed when `FROM name` or `--from=name` is used. Define additional build context with specified contents. In Dockerfile the context can be accessed when `FROM name` or `--from=name` is used.
When Dockerfile defines a stage with the same name it is overwritten. When Dockerfile defines a stage with the same name it is overwritten.
The value can be a local source directory, container image (with docker-image:// prefix), Git or HTTP URL. The value can be a local source directory, [local OCI layout compliant directory](https://github.com/opencontainers/image-spec/blob/main/image-layout.md), container image (with docker-image:// prefix), Git or HTTP URL.
Replace `alpine:latest` with a pinned one: Replace `alpine:latest` with a pinned one:
@ -515,6 +536,32 @@ examples: |-
COPY --from=project myfile / COPY --from=project myfile /
``` ```
#### Source image from OCI layout directory {#source-oci-layout}
Source an image from a local [OCI layout compliant directory](https://github.com/opencontainers/image-spec/blob/main/image-layout.md):
```console
$ docker buildx build --build-context foo=oci-layout:///path/to/local/layout@sha256:abcd12345 .
```
```Dockerfile
FROM alpine
RUN apk add git
COPY --from=foo myfile /
FROM foo
```
The OCI layout directory must be compliant with the [OCI layout specification](https://github.com/opencontainers/image-spec/blob/main/image-layout.md). It looks _solely_ for hashes. It does not
do any form of `image:tag` resolution to find the hash of the manifest; that is up to you.
The format of the `--build-context` must be: `<context>=oci-layout://<path-to-local-layout>@sha256:<hash-of-manifest>`, where:
* `context` is the name of the build context as used in the `Dockerfile`.
* `path-to-local-layout` is the path on the local machine, where you are running `docker build`, to the spec-compliant OCI layout.
* `hash-of-manifest` is the hash of the manifest for the image. It can be a single-architecture manifest or a multi-architecture index.
### Override the configured builder instance (--builder) {#builder} ### Override the configured builder instance (--builder) {#builder}
Same as [`buildx --builder`](buildx.md#builder). Same as [`buildx --builder`](buildx.md#builder).
@ -776,8 +823,9 @@ examples: |-
Set type of progress output (auto, plain, tty). Use plain to show container Set type of progress output (auto, plain, tty). Use plain to show container
output (default "auto"). output (default "auto").
> You can also use the `BUILDKIT_PROGRESS` environment variable to set > **Note**
> its value. >
> You can also use the `BUILDKIT_PROGRESS` environment variable to set its value.
The following example uses `plain` output during the build: The following example uses `plain` output during the build:
@ -794,6 +842,11 @@ examples: |-
... ...
``` ```
> **Note**
>
> Check also our [Color output controls guide](https://github.com/docker/buildx/blob/master/docs/guides/color-output.md)
> for modifying the colors that are used to output information to the terminal.
### Push the build result to a registry (--push) {#push} ### Push the build result to a registry (--push) {#push}
Shorthand for [`--output=type=registry`](#registry). Will automatically push the Shorthand for [`--output=type=registry`](#registry). Will automatically push the
@ -806,7 +859,7 @@ examples: |-
``` ```
Exposes secret to the build. The secret can be used by the build using Exposes secret to the build. The secret can be used by the build using
[`RUN --mount=type=secret` mount](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/syntax.md#run---mounttypesecret). [`RUN --mount=type=secret` mount](/engine/reference/builder/#run---mounttypesecret).
If `type` is unset it will be detected. Supported types are: If `type` is unset it will be detected. Supported types are:
@ -818,7 +871,7 @@ examples: |-
- `src`, `source` - Secret filename. `id` used if unset. - `src`, `source` - Secret filename. `id` used if unset.
```dockerfile ```dockerfile
# syntax=docker/dockerfile:1.3 # syntax=docker/dockerfile:1.4
FROM python:3 FROM python:3
RUN pip install awscli RUN pip install awscli
RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \ RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
@ -837,7 +890,7 @@ examples: |-
- `env` - Secret environment variable. `id` used if unset, otherwise will look for `src`, `source` if `id` unset. - `env` - Secret environment variable. `id` used if unset, otherwise will look for `src`, `source` if `id` unset.
```dockerfile ```dockerfile
# syntax=docker/dockerfile:1.3 # syntax=docker/dockerfile:1.4
FROM node:alpine FROM node:alpine
RUN --mount=type=bind,target=. \ RUN --mount=type=bind,target=. \
--mount=type=secret,id=SECRET_TOKEN \ --mount=type=secret,id=SECRET_TOKEN \
@ -864,12 +917,12 @@ examples: |-
authentication (e.g., cloning a private repository). authentication (e.g., cloning a private repository).
`--ssh` exposes SSH agent socket or keys to the build and can be used with the `--ssh` exposes SSH agent socket or keys to the build and can be used with the
[`RUN --mount=type=ssh` mount](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/syntax.md#run---mounttypessh). [`RUN --mount=type=ssh` mount](/engine/reference/builder/#run---mounttypessh).
Example to access Gitlab using an SSH agent socket: Example to access Gitlab using an SSH agent socket:
```dockerfile ```dockerfile
# syntax=docker/dockerfile:1.3 # syntax=docker/dockerfile:1.4
FROM alpine FROM alpine
RUN apk add --no-cache openssh-client RUN apk add --no-cache openssh-client
RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan gitlab.com >> ~/.ssh/known_hosts RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan gitlab.com >> ~/.ssh/known_hosts

46
_data/buildx/docker_buildx_create.yaml
View File

@ -58,7 +58,7 @@ options:
- option: driver - option: driver
value_type: string value_type: string
description: | description: |
Driver to use (available: `docker`, `docker-container`, `kubernetes`) Driver to use (available: `docker-container`, `kubernetes`, `remote`)
details_url: '#driver' details_url: '#driver'
deprecated: false deprecated: false
hidden: false hidden: false
@ -179,6 +179,11 @@ examples: |-
can be overridden by [`--buildkitd-flags`](#buildkitd-flags). can be overridden by [`--buildkitd-flags`](#buildkitd-flags).
See an [example buildkitd configuration file](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md). See an [example buildkitd configuration file](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md).
If the configuration file is not specified, will look for one by default in:
* `$BUILDX_CONFIG/buildkitd.default.toml`
* `$DOCKER_CONFIG/buildx/buildkitd.default.toml`
* `~/.docker/buildx/buildkitd.default.toml`
Note that if you create a `docker-container` builder and have specified Note that if you create a `docker-container` builder and have specified
certificates for registries in the `buildkitd.toml` configuration, the files certificates for registries in the `buildkitd.toml` configuration, the files
will be copied into the container under `/etc/buildkit/certs` and configuration will be copied into the container under `/etc/buildkit/certs` and configuration
@ -218,20 +223,39 @@ examples: |-
`docker images` and [`build --load`](buildx_build.md#load) needs to be used `docker images` and [`build --load`](buildx_build.md#load) needs to be used
to achieve that. to achieve that.
#### `remote` driver
Uses a remote instance of buildkitd over an arbitrary connection. With this
driver, you manually create and manage instances of buildkit yourself, and
configure buildx to point at it.
Unlike `docker` driver, built images will not automatically appear in
`docker images` and [`build --load`](buildx_build.md#load) needs to be used
to achieve that.
### Set additional driver-specific options (--driver-opt) {#driver-opt} ### Set additional driver-specific options (--driver-opt) {#driver-opt}
``` ```
--driver-opt OPTIONS --driver-opt OPTIONS
``` ```
Passes additional driver-specific options. Details for each driver: Passes additional driver-specific options.
Note: When using quoted values for example for the `nodeselector` or
`tolerations` options, ensure that quotes are escaped correctly for your shell.
#### `docker` driver
No driver options.
#### `docker-container` driver
- `docker` - No driver options
- `docker-container`
- `image=IMAGE` - Sets the container image to be used for running buildkit. - `image=IMAGE` - Sets the container image to be used for running buildkit.
- `network=NETMODE` - Sets the network mode for running the buildkit container. - `network=NETMODE` - Sets the network mode for running the buildkit container.
- `cgroup-parent=CGROUP` - Sets the cgroup parent of the buildkit container if docker is using the "cgroupfs" driver. Defaults to `/docker/buildx`. - `cgroup-parent=CGROUP` - Sets the cgroup parent of the buildkit container if docker is using the "cgroupfs" driver. Defaults to `/docker/buildx`.
- `kubernetes`
#### `kubernetes` driver
- `image=IMAGE` - Sets the container image to be used for running buildkit. - `image=IMAGE` - Sets the container image to be used for running buildkit.
- `namespace=NS` - Sets the Kubernetes namespace. Defaults to the current namespace. - `namespace=NS` - Sets the Kubernetes namespace. Defaults to the current namespace.
- `replicas=N` - Sets the number of `Pod` replicas. Defaults to 1. - `replicas=N` - Sets the number of `Pod` replicas. Defaults to 1.
@ -239,12 +263,20 @@ examples: |-
- `requests.memory` - Sets the request memory value specified in bytes or with a valid suffix. Example `requests.memory=500Mi`, `requests.memory=4G` - `requests.memory` - Sets the request memory value specified in bytes or with a valid suffix. Example `requests.memory=500Mi`, `requests.memory=4G`
- `limits.cpu` - Sets the limit CPU value specified in units of Kubernetes CPU. Example `limits.cpu=100m`, `limits.cpu=2` - `limits.cpu` - Sets the limit CPU value specified in units of Kubernetes CPU. Example `limits.cpu=100m`, `limits.cpu=2`
- `limits.memory` - Sets the limit memory value specified in bytes or with a valid suffix. Example `limits.memory=500Mi`, `limits.memory=4G` - `limits.memory` - Sets the limit memory value specified in bytes or with a valid suffix. Example `limits.memory=500Mi`, `limits.memory=4G`
- `nodeselector="label1=value1,label2=value2"` - Sets the kv of `Pod` nodeSelector. No Defaults. Example `nodeselector=kubernetes.io/arch=arm64` - `"nodeselector=label1=value1,label2=value2"` - Sets the kv of `Pod` nodeSelector. No Defaults. Example `nodeselector=kubernetes.io/arch=arm64`
- `rootless=(true|false)` - Run the container as a non-root user without `securityContext.privileged`. [Using Ubuntu host kernel is recommended](https://github.com/moby/buildkit/blob/master/docs/rootless.md). Defaults to false. - `"tolerations=key=foo,value=bar;key=foo2,operator=exists;key=foo3,effect=NoSchedule"` - Sets the `Pod` tolerations. Accepts the same values as the kube manifest tolera>tions. Key-value pairs are separated by `,`, tolerations are separated by `;`. No Defaults. Example `tolerations=operator=exists`
- `rootless=(true|false)` - Run the container as a non-root user without `securityContext.privileged`. Needs Kubernetes 1.19 or later. [Using Ubuntu host kernel is recommended](https://github.com/moby/buildkit/blob/master/docs/rootless.md). Defaults to false.
- `loadbalance=(sticky|random)` - Load-balancing strategy. If set to "sticky", the pod is chosen using the hash of the context path. Defaults to "sticky" - `loadbalance=(sticky|random)` - Load-balancing strategy. If set to "sticky", the pod is chosen using the hash of the context path. Defaults to "sticky"
- `qemu.install=(true|false)` - Install QEMU emulation for multi platforms support. - `qemu.install=(true|false)` - Install QEMU emulation for multi platforms support.
- `qemu.image=IMAGE` - Sets the QEMU emulation image. Defaults to `tonistiigi/binfmt:latest` - `qemu.image=IMAGE` - Sets the QEMU emulation image. Defaults to `tonistiigi/binfmt:latest`
#### `remote` driver
- `key=KEY` - Sets the TLS client key.
- `cert=CERT` - Sets the TLS client certificate to present to buildkitd.
- `cacert=CACERT` - Sets the TLS certificate authority used for validation.
- `servername=SERVER` - Sets the TLS server name to be used in requests (defaults to the endpoint hostname).
### Remove a node from a builder (--leave) {#leave} ### Remove a node from a builder (--leave) {#leave}
The `--leave` flag changes the action of the command to remove a node from a The `--leave` flag changes the action of the command to remove a node from a

11
_data/buildx/docker_buildx_imagetools_create.yaml
View File

@ -43,6 +43,17 @@ options:
experimentalcli: false experimentalcli: false
kubernetes: false kubernetes: false
swarm: false swarm: false
- option: progress
value_type: string
default_value: auto
description: |
Set type of progress output (`auto`, `plain`, `tty`). Use plain to show container output
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: tag - option: tag
shorthand: t shorthand: t
value_type: stringArray value_type: stringArray

8
_data/buildx/docker_buildx_inspect.yaml
View File

@ -48,6 +48,10 @@ examples: |-
The following example shows information about a builder instance named The following example shows information about a builder instance named
`elated_tesla`: `elated_tesla`:
> **Note**
>
> Asterisk `*` next to node build platform(s) indicate they had been set manually during `buildx create`. Otherwise, it had been autodetected.
```console ```console
$ docker buildx inspect elated_tesla $ docker buildx inspect elated_tesla
@ -58,12 +62,14 @@ examples: |-
Name: elated_tesla0 Name: elated_tesla0
Endpoint: unix:///var/run/docker.sock Endpoint: unix:///var/run/docker.sock
Status: running Status: running
Buildkit: v0.10.3
Platforms: linux/amd64 Platforms: linux/amd64
Name: elated_tesla1 Name: elated_tesla1
Endpoint: ssh://ubuntu@1.2.3.4 Endpoint: ssh://ubuntu@1.2.3.4
Status: running Status: running
Platforms: linux/arm64, linux/arm/v7, linux/arm/v6 Buildkit: v0.10.3
Platforms: linux/arm64*, linux/arm/v7, linux/arm/v6
``` ```
deprecated: false deprecated: false
experimental: false experimental: false

9
_data/buildx/docker_buildx_ls.yaml
View File

@ -5,13 +5,12 @@ long: |-
```console ```console
$ docker buildx ls $ docker buildx ls
NAME/NODE DRIVER/ENDPOINT STATUS BUILDKIT PLATFORMS
NAME/NODE DRIVER/ENDPOINT STATUS PLATFORMS
elated_tesla * docker-container elated_tesla * docker-container
elated_tesla0 unix:///var/run/docker.sock running linux/amd64 elated_tesla0 unix:///var/run/docker.sock running v0.10.3 linux/amd64
elated_tesla1 ssh://ubuntu@1.2.3.4 running linux/arm64*, linux/arm/v7, linux/arm/v6 elated_tesla1 ssh://ubuntu@1.2.3.4 running v0.10.3 linux/arm64*, linux/arm/v7, linux/arm/v6
default docker default docker
default default running linux/amd64 default default running 20.10.14 linux/amd64
``` ```
Each builder has one or more nodes associated with it. The current builder's Each builder has one or more nodes associated with it. The current builder's

21
_data/buildx/docker_buildx_prune.yaml
View File

@ -1,6 +1,23 @@
command: docker buildx prune command: docker buildx prune
short: Remove build cache short: Remove build cache
long: Remove build cache long: |-
Clears the build cache of the selected builder.
You can finely control what cache data is kept using:
- The `--filter=until=<duration>` flag to keep images that have been used in
the last `<duration>` time.
`<duration>` is a duration string, e.g. `24h` or `2h30m`, with allowable
units of `(h)ours`, `(m)inutes` and `(s)econds`.
- The `--keep-storage=<size>` flag to keep `<size>` bytes of data in the cache.
`<size>` is a human-readable memory string, e.g. `128mb`, `2gb`, etc. Units
are case-insensitive.
- The `--all` flag to allow clearing internal helper images and frontend images
set using the `#syntax=` directive or the `BUILDKIT_SYNTAX` build argument.
usage: docker buildx prune usage: docker buildx prune
pname: docker buildx pname: docker buildx
plink: docker_buildx.yaml plink: docker_buildx.yaml
@ -9,7 +26,7 @@ options:
shorthand: a shorthand: a
value_type: bool value_type: bool
default_value: "false" default_value: "false"
description: Remove all unused images, not just dangling ones description: Include internal/frontend images
deprecated: false deprecated: false
hidden: false hidden: false
experimental: false experimental: false