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

reference: update buildx reference docs for v0.7.1 

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>
This commit is contained in:
CrazyMax 2021-12-09 11:09:54 +01:00
parent f25c0e2def
commit 4208de2578
No known key found for this signature in database
GPG Key ID: 3248E46B6BB8C7F7
13 changed files with 917 additions and 162 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
_data/buildx/docker_buildx.yaml
View File

@ -1,6 +1,6 @@
command: docker buildx
short: Build with BuildKit
long: Build with BuildKit
short: Docker Buildx
long: Extended build capabilities with BuildKit
pname: docker
plink: docker.yaml
cname:
@ -33,11 +33,16 @@ options:
- option: builder
value_type: string
description: Override the configured builder instance
details_url: '#builder'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### Override the configured builder instance (--builder) {#builder}
You can also use the `BUILDX_BUILDER` environment variable.
deprecated: false
experimental: false
experimentalcli: false

727
_data/buildx/docker_buildx_bake.yaml
View File

@ -4,6 +4,13 @@ short: Build from a file
long: |-
Bake is a high-level build command. Each specified target will run in parallel
as part of the build.
Read [High-level build options](https://github.com/docker/buildx#high-level-build-options)
for introduction.
Please note that `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...]
pname: docker buildx
plink: docker_buildx.yaml
@ -22,7 +29,15 @@ options:
- option: load
value_type: bool
default_value: "false"
description: Shorthand for --set=*.output=type=docker
description: Shorthand for `--set=*.output=type=docker`
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: metadata-file
value_type: string
description: Write build result metadata to the file
deprecated: false
experimental: false
experimentalcli: false
@ -52,7 +67,7 @@ options:
value_type: string
default_value: auto
description: |
Set type of progress output (auto, plain, tty). Use plain to show container output
Set type of progress output (`auto`, `plain`, `tty`). Use plain to show container output
details_url: '#progress'
deprecated: false
experimental: false
@ -72,7 +87,7 @@ options:
- option: push
value_type: bool
default_value: "false"
description: Shorthand for --set=*.output=type=registry
description: Shorthand for `--set=*.output=type=registry`
deprecated: false
experimental: false
experimentalcli: false
@ -81,7 +96,7 @@ options:
- option: set
value_type: stringArray
default_value: '[]'
description: 'Override target value (eg: targetpattern.key=value)'
description: Override target value (e.g., `targetpattern.key=value`)
details_url: '#set'
deprecated: false
experimental: false
@ -92,16 +107,21 @@ inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
details_url: '#builder'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### Override the configured builder instance (--builder) {#builder}
Same as [`buildx --builder`](buildx.md#builder).
### Specify a build definition file (-f, --file) {#file}
By default, `buildx bake` looks for build definition files in the current directory,
the following are parsed:
By default, `buildx bake` looks for build definition files in the current
directory, the following are parsed:
- `docker-compose.yml`
- `docker-compose.yaml`
@ -147,34 +167,157 @@ examples: |-
...
```
You can also use a remote `git` bake definition:
```console
$ docker buildx bake "git://github.com/docker/cli#v20.10.11" --print
#1 [internal] load git source git://github.com/docker/cli#v20.10.11
#1 0.745 e8f1871b077b64bcb4a13334b7146492773769f7 refs/tags/v20.10.11
#1 2.022 From git://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": "git://github.com/docker/cli#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 `git://github.com/docker/cli` even if
[no context is actually defined](https://github.com/docker/cli/blob/2776a6d694f988c0c1df61cad4bfac0f54e481c8/docker-bake.hcl#L17-L26)
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` builtin var:
```console
$ cat https://raw.githubusercontent.com/tonistiigi/buildx/remote-test/docker-bake.hcl
target "default" {
context = BAKE_CMD_CONTEXT
dockerfile-inline = <<EOT
FROM alpine
WORKDIR /src
COPY . .
RUN ls -l && stop
EOT
}
```
```console
$ docker buildx bake "git://github.com/tonistiigi/buildx#remote-test" --print
{
"target": {
"default": {
"context": ".",
"dockerfile": "Dockerfile",
"dockerfile-inline": "FROM alpine\nWORKDIR /src\nCOPY . .\nRUN ls -l \u0026\u0026 stop\n"
}
}
}
```
```console
$ touch foo bar
$ docker buildx bake "git://github.com/tonistiigi/buildx#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 "git://github.com/tonistiigi/buildx#remote-test" "git://github.com/docker/cli#v20.10.11" --print
#1 [internal] load git source git://github.com/tonistiigi/buildx#remote-test
#1 0.429 577303add004dd7efeb13434d69ea030d35f7888 refs/heads/remote-test
#1 CACHED
{
"target": {
"default": {
"context": "git://github.com/docker/cli#v20.10.11",
"dockerfile": "Dockerfile",
"dockerfile-inline": "FROM alpine\nWORKDIR /src\nCOPY . .\nRUN ls -l \u0026\u0026 stop\n"
}
}
}
```
```console
$ docker buildx bake "git://github.com/tonistiigi/buildx#remote-test" "git://github.com/docker/cli#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}
Same as `build --no-cache`. Do not use cache when building the image.
### Print the options without building (--print) {#print}
Prints the resulting options of the targets desired to be built, in a JSON format,
without starting a build.
Prints the resulting options of the targets desired to be built, in a JSON
format, without starting a build.
```console
$ docker buildx bake -f docker-bake.hcl --print db
{
"target": {
"db": {
"context": "./",
"dockerfile": "Dockerfile",
"tags": [
"docker.io/tiborvass/db"
]
}
}
"group": {
"default": {
"targets": [
"db"
]
}
},
"target": {
"db": {
"context": "./",
"dockerfile": "Dockerfile",
"tags": [
"docker.io/tiborvass/db"
]
}
}
}
```
### Set type of progress output (--progress) {#progress}
Same as `build --progress`. Set type of progress output (auto, plain, tty). Use
plain to show container output (default "auto").
Same as [`build --progress`](buildx_build.md#progress). Set type of 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:
@ -203,8 +346,9 @@ examples: |-
--set targetpattern.key[.subkey]=value
```
Override target configurations from command line. The pattern matching syntax is
defined in https://golang.org/pkg/path/#Match.
Override target configurations from command line. The pattern matching syntax
is defined in https://golang.org/pkg/path/#Match.
**Examples**
@ -217,8 +361,8 @@ examples: |-
```
Complete list of overridable fields:
args, cache-from, cache-to, context, dockerfile, labels, no-cache, output, platform,
pull, secrets, ssh, tags, target
`args`, `cache-from`, `cache-to`, `context`, `dockerfile`, `labels`, `no-cache`,
`output`, `platform`, `pull`, `secrets`, `ssh`, `tags`, `target`
### File definition
@ -269,18 +413,101 @@ examples: |-
`args`, `cache-from`, `cache-to`, `context`, `dockerfile`, `inherits`, `labels`,
`no-cache`, `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.
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.
Example of using interpolation to tag an image with the git sha:
#### Using interpolation to tag an image with the git sha
```console
$ cat <<'EOF' > docker-bake.hcl
Bake supports variable blocks which are assigned to matching environment
variables or default values.
```hcl
# docker-bake.hcl
variable "TAG" {
default = "latest"
}
@ -292,45 +519,59 @@ examples: |-
target "webapp" {
tags = ["docker.io/username/webapp:${TAG}"]
}
EOF
```
```console
$ docker buildx bake --print webapp
{
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"tags": [
"docker.io/username/webapp:latest"
]
}
}
}
$ TAG=$(git rev-parse --short HEAD) docker buildx bake --print webapp
{
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"tags": [
"docker.io/username/webapp:985e9e9"
]
}
}
"group": {
"default": {
"targets": [
"webapp"
]
}
},
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"tags": [
"docker.io/username/webapp:latest"
]
}
}
}
```
A [set of generally useful functions](https://github.com/docker/buildx/blob/master/bake/hcl.go#L19-L65)
provided by [go-cty](https://github.com/zclconf/go-cty/tree/master/cty/function/stdlib)
are available for use in HCL files. In addition, [user defined functions](https://github.com/hashicorp/hcl/tree/hcl2/ext/userfunc)
are also supported.
Example of using the `add` function:
```console
$ cat <<'EOF' > docker-bake.hcl
$ 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"
}
@ -344,26 +585,37 @@ examples: |-
buildno = "${add(123, 1)}"
}
}
EOF
```
```console
$ docker buildx bake --print webapp
{
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"args": {
"buildno": "124"
}
"group": {
"default": {
"targets": [
"webapp"
]
}
},
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"args": {
"buildno": "124"
}
}
}
}
}
```
Example of defining an `increment` function:
#### Defining an `increment` function
```console
$ cat <<'EOF' > docker-bake.hcl
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
@ -378,27 +630,37 @@ examples: |-
buildno = "${increment(123)}"
}
}
EOF
```
```console
$ docker buildx bake --print webapp
{
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"args": {
"buildno": "124"
}
"group": {
"default": {
"targets": [
"webapp"
]
}
},
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"args": {
"buildno": "124"
}
}
}
}
}
```
Example of only adding tags if a variable is not empty using an `notequal`
function:
#### Only adding tags if a variable is not empty using an `notequal`
```console
$ cat <<'EOF' > docker-bake.hcl
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" {
@ -415,21 +677,296 @@ examples: |-
notequal("",TAG) ? "my-image:${TAG}": "",
]
}
EOF
```
```console
$ docker buildx bake --print webapp
{
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"tags": [
"my-image:latest"
]
}
}
"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"
}
}
}
}
```
### 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`
### 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
experimental: false
experimentalcli: false

145
_data/buildx/docker_buildx_build.yaml
View File

@ -15,7 +15,7 @@ options:
- option: add-host
value_type: stringSlice
default_value: '[]'
description: Add a custom host-to-IP mapping (host:ip)
description: 'Add a custom host-to-IP mapping (format: `host:ip`)'
details_url: /engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host
deprecated: false
experimental: false
@ -26,7 +26,7 @@ options:
value_type: stringSlice
default_value: '[]'
description: |
Allow extra privileged entitlement, e.g. network.host, security.insecure
Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`)
details_url: '#allow'
deprecated: false
experimental: false
@ -47,7 +47,7 @@ options:
value_type: stringArray
default_value: '[]'
description: |
External cache sources (eg. user/app:cache, type=local,src=path/to/dir)
External cache sources (e.g., `user/app:cache`, `type=local,src=path/to/dir`)
details_url: '#cache-from'
deprecated: false
experimental: false
@ -58,7 +58,7 @@ options:
value_type: stringArray
default_value: '[]'
description: |
Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir)
Cache export destinations (e.g., `user/app:cache`, `type=local,dest=path/to/dir`)
details_url: '#cache-to'
deprecated: false
experimental: false
@ -68,6 +68,7 @@ options:
- option: cgroup-parent
value_type: string
description: Optional parent cgroup for the container
details_url: /engine/reference/commandline/build/#use-a-custom-parent-cgroup---cgroup-parent
deprecated: false
experimental: false
experimentalcli: false
@ -112,7 +113,7 @@ options:
swarm: false
- option: cpuset-cpus
value_type: string
description: CPUs in which to allow execution (0-3, 0,1)
description: CPUs in which to allow execution (`0-3`, `0,1`)
deprecated: false
experimental: false
experimentalcli: false
@ -120,7 +121,7 @@ options:
swarm: false
- option: cpuset-mems
value_type: string
description: MEMs in which to allow execution (0-3, 0,1)
description: MEMs in which to allow execution (`0-3`, `0,1`)
deprecated: false
experimental: false
experimentalcli: false
@ -129,7 +130,7 @@ options:
- option: file
shorthand: f
value_type: string
description: Name of the Dockerfile (Default is 'PATH/Dockerfile')
description: 'Name of the Dockerfile (default: `PATH/Dockerfile`)'
details_url: /engine/reference/commandline/build/#specify-a-dockerfile--f
deprecated: false
experimental: false
@ -173,7 +174,7 @@ options:
- option: load
value_type: bool
default_value: "false"
description: Shorthand for --output=type=docker
description: Shorthand for `--output=type=docker`
details_url: '#load'
deprecated: false
experimental: false
@ -192,7 +193,15 @@ options:
- option: memory-swap
value_type: string
description: |
Swap limit equal to memory plus swap: '-1' to enable unlimited swap
Swap limit equal to memory plus swap: `-1` to enable unlimited swap
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: metadata-file
value_type: string
description: Write build result metadata to the file
deprecated: false
experimental: false
experimentalcli: false
@ -201,8 +210,7 @@ options:
- option: network
value_type: string
default_value: default
description: |
Set the networking mode for the RUN instructions during build
description: Set the networking mode for the RUN instructions during build
deprecated: false
experimental: false
experimentalcli: false
@ -221,7 +229,7 @@ options:
shorthand: o
value_type: stringArray
default_value: '[]'
description: 'Output destination (format: type=local,dest=path)'
description: 'Output destination (format: `type=local,dest=path`)'
details_url: '#output'
deprecated: false
experimental: false
@ -242,7 +250,8 @@ options:
value_type: string
default_value: auto
description: |
Set type of progress output (auto, plain, tty). Use plain to show container output
Set type of progress output (`auto`, `plain`, `tty`). Use plain to show container output
details_url: '#progress'
deprecated: false
experimental: false
experimentalcli: false
@ -260,7 +269,7 @@ options:
- option: push
value_type: bool
default_value: "false"
description: Shorthand for --output=type=registry
description: Shorthand for `--output=type=registry`
details_url: '#push'
deprecated: false
experimental: false
@ -290,7 +299,7 @@ options:
value_type: stringArray
default_value: '[]'
description: |
Secret file to expose to the build: id=mysecret,src=/local/secret
Secret file to expose to the build (format: `id=mysecret,src=/local/secret`)
deprecated: false
experimental: false
experimentalcli: false
@ -306,8 +315,10 @@ options:
kubernetes: false
swarm: false
- option: shm-size
value_type: string
description: Size of /dev/shm
value_type: bytes
default_value: "0"
description: Size of `/dev/shm`
details_url: '#shm-size'
deprecated: false
experimental: false
experimentalcli: false
@ -326,7 +337,7 @@ options:
value_type: stringArray
default_value: '[]'
description: |
SSH agent socket or keys to expose to the build (format: default|<id>[=<socket>|<key>[,<key>]])
SSH agent socket or keys to expose to the build (format: `default|<id>[=<socket>|<key>[,<key>]]`)
deprecated: false
experimental: false
experimentalcli: false
@ -336,7 +347,7 @@ options:
shorthand: t
value_type: stringArray
default_value: '[]'
description: Name and optionally a tag in the 'name:tag' format
description: 'Name and optionally a tag (format: `name:tag`)'
details_url: /engine/reference/commandline/build/#tag-an-image--t
deprecated: false
experimental: false
@ -353,8 +364,10 @@ options:
kubernetes: false
swarm: false
- option: ulimit
value_type: string
value_type: ulimit
default_value: '[]'
description: Ulimit options
details_url: '#ulimit'
deprecated: false
experimental: false
experimentalcli: false
@ -364,12 +377,17 @@ inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
details_url: '#builder'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### Override the configured builder instance (--builder) {#builder}
Same as [`buildx --builder`](buildx.md#builder).
### Set the target platforms for the build (--platform) {#platform}
```
@ -411,6 +429,33 @@ examples: |-
$ docker buildx build --platform=darwin .
```
### Set type of progress output (--progress) {#progress}
```
--progress=VALUE
```
Set type of 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 build --load --progress=plain .
#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 227B 0.0s done
#1 DONE 0.1s
#2 [internal] load .dockerignore
#2 transferring context: 129B 0.0s done
#2 DONE 0.0s
...
```
### Set the export action for the build result (-o, --output) {#output}
```
@ -519,10 +564,17 @@ examples: |-
--cache-from=[NAME|type=TYPE[,KEY=VALUE]]
```
Use an external cache source for a build. Supported types are `registry` and `local`.
The `registry` source can import cache from a cache manifest or (special) image
configuration on the registry. The `local` source can import cache from local
files previously exported with `--cache-to`.
Use an external cache source for a build. Supported types are `registry`,
`local` and `gha`.
- [`registry` source](https://github.com/moby/buildkit#registry-push-image-and-cache-separately)
can import cache from a cache manifest or (special) image configuration on the
registry.
- [`local` source](https://github.com/moby/buildkit#local-directory-1) can
import cache from local files previously exported with `--cache-to`.
- [`gha` source](https://github.com/moby/buildkit#github-actions-cache-experimental)
can import cache from a previously exported cache with `--cache-to` in your
GitHub repository
If no type is specified, `registry` exporter is used with a specified reference.
@ -535,18 +587,27 @@ examples: |-
$ docker buildx build --cache-from=user/app .
$ docker buildx build --cache-from=type=registry,ref=user/app .
$ docker buildx build --cache-from=type=local,src=path/to/cache .
$ docker buildx build --cache-from=type=gha .
```
More info about cache exporters and available attributes: https://github.com/moby/buildkit#export-cache
### Export build cache to an external cache destination (--cache-to) {#cache-to}
```
--cache-to=[NAME|type=TYPE[,KEY=VALUE]]
```
Export build cache to an external cache destination. Supported types are `registry`,
`local` and `inline`. Registry exports build cache to a cache manifest in the
registry, local exports cache to a local directory on the client and inline writes
the cache metadata into the image configuration.
Export build cache to an external cache destination. Supported types are
`registry`, `local`, `inline` and `gha`.
- [`registry` type](https://github.com/moby/buildkit#registry-push-image-and-cache-separately) exports build cache to a cache manifest in the registry.
- [`local` type](https://github.com/moby/buildkit#local-directory-1) type
exports cache to a local directory on the client.
- [`inline` type](https://github.com/moby/buildkit#inline-push-image-and-cache-together)
type writes the cache metadata into the image configuration.
- [`gha` type](https://github.com/moby/buildkit#github-actions-cache-experimental)
type exports cache through the [Github Actions Cache service API](https://github.com/tonistiigi/go-actions-cache/blob/master/api.md#authentication).
`docker` driver currently only supports exporting inline cache metadata to image
configuration. Alternatively, `--build-arg BUILDKIT_INLINE_CACHE=1` can be used
@ -554,8 +615,8 @@ examples: |-
Attribute key:
- `mode` - Specifies how many layers are exported with the cache. “min” on only
exports layers already in the final build stage, “max” exports layers for
- `mode` - Specifies how many layers are exported with the cache. `min` on only
exports layers already in the final build stage, `max` exports layers for
all stages. Metadata is always exported for the whole build.
**Examples**
@ -565,8 +626,11 @@ examples: |-
$ docker buildx build --cache-to=type=inline .
$ docker buildx build --cache-to=type=registry,ref=user/app .
$ docker buildx build --cache-to=type=local,dest=path/to/cache .
$ docker buildx build --cache-to=type=gha .
```
More info about cache exporters and available attributes: https://github.com/moby/buildkit#export-cache
### Allow extra privileged entitlement (--allow) {#allow}
```
@ -588,6 +652,27 @@ examples: |-
$ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure'
$ docker buildx build --allow security.insecure .
```
### Size of `/dev/shm` (--shm-size) {#shm-size}
The format is `<number><unit>`. `number` must be greater than `0`. Unit is
optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g`
(gigabytes). If you omit the unit, the system uses bytes.
### Set ulimits (--ulimit) {#ulimit}
`--ulimit` is specified with a soft and hard limit as such:
`<type>=<soft limit>[:<hard limit>]`, for example:
```console
$ docker buildx build --ulimit nofile=1024:1024 .
```
> **Note**
>
> If you do not provide a `hard limit`, the `soft limit` is used
> for both values. If no `ulimits` are set, they are inherited from
> the default `ulimits` set on the daemon.
deprecated: false
experimental: false
experimentalcli: false

86
_data/buildx/docker_buildx_create.yaml
View File

@ -24,6 +24,15 @@ options:
experimentalcli: false
kubernetes: false
swarm: false
- option: bootstrap
value_type: bool
default_value: "false"
description: Boot builder after creation
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: buildkitd-flags
value_type: string
description: Flags for buildkitd daemon
@ -44,7 +53,8 @@ options:
swarm: false
- option: driver
value_type: string
description: 'Driver to use (available: [])'
description: |
Driver to use (available: `docker`, `docker-container`, `kubernetes`)
details_url: '#driver'
deprecated: false
experimental: false
@ -161,6 +171,11 @@ examples: |-
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).
Note that if you create a `docker-container` builder and have specified
certificates for registries in the `buildkitd.toml` configuration, the files
will be copied into the container under `/etc/buildkit/certs` and configuration
will be updated to reflect that.
### Set the builder driver to use (--driver) {#driver}
```
@ -170,17 +185,30 @@ examples: |-
Sets the builder driver to be used. There are two available drivers, each have
their own specificities.
- `docker` - Uses the builder that is built into the docker daemon. With this
driver, the [`--load`](buildx_build.md#load) flag is implied by default on
`buildx build`. However, building multi-platform images or exporting cache is
not currently supported.
- `docker-container` - Uses a buildkit container that will be spawned via docker.
With this driver, both building multi-platform images and exporting cache are
supported. However, images built will not automatically appear in `docker images`
(see [`build --load`](buildx_build.md#load)).
- `kubernetes` - Uses a kubernetes pods. With this driver, you can spin up pods
with defined buildkit container image to build your images.
#### `docker` driver
Uses the builder that is built into the docker daemon. With this driver,
the [`--load`](buildx_build.md#load) flag is implied by default on
`buildx build`. However, building multi-platform images or exporting cache is
not currently supported.
#### `docker-container` driver
Uses a BuildKit container that will be spawned via docker. With this driver,
both building multi-platform images and exporting cache are supported.
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.
#### `kubernetes` driver
Uses a kubernetes pods. With this driver, you can spin up pods with defined
BuildKit container image to build your images.
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}
@ -194,18 +222,44 @@ examples: |-
- `docker-container`
- `image=IMAGE` - Sets the container image to be used for running buildkit.
- `network=NETMODE` - Sets the network mode for running the buildkit container.
- Example:
```console
--driver docker-container --driver-opt image=moby/buildkit:master,network=host
```
- `cgroup-parent=CGROUP` - Sets the cgroup parent of the buildkit container if docker is using the "cgroupfs" driver. Defaults to `/docker/buildx`.
- `kubernetes`
- `image=IMAGE` - Sets the container image to be used for running buildkit.
- `namespace=NS` - Sets the Kubernetes namespace. Defaults to the current namespace.
- `replicas=N` - Sets the number of `Pod` replicas. Defaults to 1.
- `requests.cpu` - Sets the request CPU value specified in units of Kubernetes CPU. Example `requests.cpu=100m`, `requests.cpu=2`
- `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.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`
- `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.
- `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.image=IMAGE` - Sets the QEMU emulation image. Defaults to `tonistiigi/binfmt:latest`
**Examples**
#### Use a custom network
```console
$ docker network create foonet
$ docker buildx create --name builder --driver docker-container --driver-opt network=foonet --use
$ docker buildx inspect --bootstrap
$ docker inspect buildx_buildkit_builder0 --format={{.NetworkSettings.Networks}}
map[foonet:0xc00018c0c0]
```
#### OpenTelemetry support
To capture the trace to [Jaeger](https://github.com/jaegertracing/jaeger), set
`JAEGER_TRACE` environment variable to the collection address using the `driver-opt`:
```console
$ docker run -d --name jaeger -p 6831:6831/udp -p 16686:16686 jaegertracing/all-in-one
$ docker buildx create --name builder --driver docker-container --driver-opt network=host --driver-opt env.JAEGER_TRACE=localhost:6831 --use
$ docker buildx inspect --bootstrap
# buildx command should be traced at http://127.0.0.1:16686/
```
### Remove a node from a builder (--leave) {#leave}

5
_data/buildx/docker_buildx_du.yaml
View File

@ -26,11 +26,16 @@ inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
details_url: '#builder'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### Override the configured builder instance (--builder) {#builder}
Same as [`buildx --builder`](buildx.md#builder).
deprecated: false
experimental: false
experimentalcli: false

5
_data/buildx/docker_buildx_imagetools.yaml
View File

@ -15,11 +15,16 @@ inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
details_url: '#builder'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### Override the configured builder instance (--builder) {#builder}
Same as [`buildx --builder`](buildx.md#builder).
deprecated: false
experimental: false
experimentalcli: false

18
_data/buildx/docker_buildx_imagetools_create.yaml
View File

@ -58,6 +58,7 @@ inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
details_url: '#builder'
deprecated: false
experimental: false
experimentalcli: false
@ -69,6 +70,10 @@ examples: |-
Use the `--append` flag to append the new sources to an existing manifest list
in the destination.
### Override the configured builder instance (--builder) {#builder}
Same as [`buildx --builder`](buildx.md#builder).
### Show final image instead of pushing (--dry-run) {#dry-run}
Use the `--dry-run` flag to not push the image, just show it.
@ -82,6 +87,19 @@ examples: |-
Reads source from files. A source can be a manifest digest, manifest reference,
or a JSON of OCI descriptor object.
In order to define annotations or additional platform properties like `os.version` and
`os.features` you need to add them in the OCI descriptor object encoded in JSON.
```
docker buildx imagetools inspect --raw alpine | jq '.manifests[0] | .platform."os.version"="10.1"' > descr.json
docker buildx imagetools create -f descr.json myuser/image
```
The descriptor in the file is merged with existing descriptor in the registry if it exists.
The supported fields for the descriptor are defined in [OCI spec](https://github.com/opencontainers/image-spec/blob/master/descriptor.md#properties) .
### Set reference for new image (-t, --tag) {#tag}
```

15
_data/buildx/docker_buildx_imagetools_inspect.yaml
View File

@ -22,11 +22,6 @@ long: |-
Platform: linux/arm/v6
...
```
### Show original, unformatted JSON manifest (--raw) {#raw}
Use the `--raw` option to print the original JSON bytes instead of the formatted
output.
usage: docker buildx imagetools inspect [OPTIONS] NAME
pname: docker buildx imagetools
plink: docker_buildx_imagetools.yaml
@ -45,11 +40,21 @@ inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
details_url: '#builder'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### Override the configured builder instance (--builder) {#builder}
Same as [`buildx --builder`](buildx.md#builder).
### Show original, unformatted JSON manifest (--raw) {#raw}
Use the `--raw` option to print the original JSON bytes instead of the formatted
output.
deprecated: false
experimental: false
experimentalcli: false

23
_data/buildx/docker_buildx_inspect.yaml
View File

@ -19,12 +19,26 @@ inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
details_url: '#builder'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### Ensure that the builder is running before inspecting (--bootstrap) {#bootstrap}
Use the `--bootstrap` option to ensure that the builder is running before
inspecting it. If the driver is `docker-container`, then `--bootstrap` starts
the buildkit container and waits until it is operational. Bootstrapping is
automatically done during build, and therefore not necessary. The same BuildKit
container is used during the lifetime of the associated builder node (as
displayed in `buildx ls`).
### Override the configured builder instance (--builder) {#builder}
Same as [`buildx --builder`](buildx.md#builder).
### Get information about a builder instance
By default, `inspect` shows information about the current builder. Specify the
@ -49,15 +63,6 @@ examples: |-
Status: running
Platforms: linux/arm64, linux/arm/v7, linux/arm/v6
```
### Ensure that the builder is running before inspecting (--bootstrap) {#bootstrap}
Use the `--bootstrap` option to ensure that the builder is running before
inspecting it. If the driver is `docker-container`, then `--bootstrap` starts
the buildkit container and waits until it is operational. Bootstrapping is
automatically done during build, and therefore not necessary. The same BuildKit
container is used during the lifetime of the associated builder node (as
displayed in `buildx ls`).
deprecated: false
experimental: false
experimentalcli: false

7
_data/buildx/docker_buildx_prune.yaml
View File

@ -17,7 +17,7 @@ options:
swarm: false
- option: filter
value_type: filter
description: Provide filter values (e.g. 'until=24h')
description: Provide filter values (e.g., `until=24h`)
deprecated: false
experimental: false
experimentalcli: false
@ -55,11 +55,16 @@ inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
details_url: '#builder'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### Override the configured builder instance (--builder) {#builder}
Same as [`buildx --builder`](buildx.md#builder).
deprecated: false
experimental: false
experimentalcli: false

29
_data/buildx/docker_buildx_rm.yaml
View File

@ -6,15 +6,36 @@ long: |-
usage: docker buildx rm [NAME]
pname: docker buildx
plink: docker_buildx.yaml
inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
options:
- option: keep-state
value_type: bool
default_value: "false"
description: Keep BuildKit state
details_url: '#keep-state'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
details_url: '#builder'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### Override the configured builder instance (--builder) {#builder}
Same as [`buildx --builder`](buildx.md#builder).
### Keep BuildKit state (--keep-state) {#keep-state}
Keep BuildKit state, so it can be reused by a new builder with the same name.
Currently, only supported by the [`docker-container` driver](buildx_create.md#driver).
deprecated: false
experimental: false
experimentalcli: false

5
_data/buildx/docker_buildx_stop.yaml
View File

@ -10,11 +10,16 @@ inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
details_url: '#builder'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### Override the configured builder instance (--builder) {#builder}
Same as [`buildx --builder`](buildx.md#builder).
deprecated: false
experimental: false
experimentalcli: false

5
_data/buildx/docker_buildx_use.yaml
View File

@ -30,11 +30,16 @@ inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
details_url: '#builder'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### Override the configured builder instance (--builder) {#builder}
Same as [`buildx --builder`](buildx.md#builder).
deprecated: false
experimental: false
experimentalcli: false