docker/buildx
1
0
Fork 0
mirror of https://github.com/docker/buildx.git synced 2024-11-22 15:37:16 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #762 from crazy-max/remove-yaml

Browse Source 
Remove generated YAML docs
This commit is contained in:
CrazyMax 2021-09-09 13:39:53 +02:00 committed by GitHub
commit 7f0e05dfac
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
23 changed files with 77 additions and 2539 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
.github/workflows/validate.yml vendored
View File

@ -31,3 +31,18 @@ jobs:
name: Run
run: |
make ${{ matrix.target }}
validate-docs-yaml:
runs-on: ubuntu-latest
needs:
- validate
steps:
-
name: Checkout
uses: actions/checkout@v2
-
name: Run
run: |
make docs
env:
FORMATS: yaml

1
.yamllint.yml
View File

@ -1,6 +1,5 @@
ignore: |
/vendor
/docs/reference
extends: default

9
docker-bake.hcl
View File

@ -7,6 +7,9 @@ variable "BIN_OUT" {
variable "RELEASE_OUT" {
default = "./release-out"
}
variable "DOCS_FORMATS" {
default = "md"
}
// Special target: https://github.com/docker/metadata-action#bake-definition
target "meta-helper" {
@ -43,6 +46,9 @@ target "validate-vendor" {
target "validate-docs" {
inherits = ["_common"]
args = {
FORMATS = DOCS_FORMATS
}
dockerfile = "./hack/dockerfiles/docs.Dockerfile"
target = "validate"
output = ["type=cacheonly"]
@ -64,6 +70,9 @@ target "update-vendor" {
target "update-docs" {
inherits = ["_common"]
args = {
FORMATS = DOCS_FORMATS
}
dockerfile = "./hack/dockerfiles/docs.Dockerfile"
target = "update"
output = ["./docs/reference"]

55
docs/generate.go
View File

@ -8,19 +8,25 @@ import (
"github.com/docker/buildx/commands"
clidocstool "github.com/docker/cli-docs-tool"
"github.com/docker/cli/cli/command"
"github.com/pkg/errors"
"github.com/spf13/cobra"
"github.com/spf13/pflag"
)
const sourcePath = "docs/reference/"
const defaultSourcePath = "docs/reference/"
func main() {
type options struct {
source string
formats []string
}
func gen(opts *options) error {
log.SetFlags(0)
dockerCLI, err := command.NewDockerCli()
if err != nil {
log.Printf("ERROR: %+v", err)
return err
}
cmd := &cobra.Command{
Use: "docker [OPTIONS] COMMAND [ARG...]",
Short: "The base command for the Docker CLI.",
@ -31,12 +37,47 @@ func main() {
clidocstool.DisableFlagsInUseLine(cmd)
cwd, _ := os.Getwd()
source := filepath.Join(cwd, sourcePath)
source := filepath.Join(cwd, opts.source)
if err = os.MkdirAll(source, 0755); err != nil {
log.Printf("ERROR: %+v", err)
return err
}
if err = clidocstool.GenTree(cmd, source); err != nil {
for _, format := range opts.formats {
switch format {
case "md":
if err = clidocstool.GenMarkdownTree(cmd, source); err != nil {
return err
}
case "yaml":
if err = clidocstool.GenYamlTree(cmd, source); err != nil {
return err
}
default:
return errors.Errorf("unknwown doc format %q", format)
}
}
return nil
}
func run() error {
opts := &options{}
flags := pflag.NewFlagSet(os.Args[0], pflag.ContinueOnError)
flags.StringVar(&opts.source, "source", defaultSourcePath, "Docs source folder")
flags.StringSliceVar(&opts.formats, "formats", []string{}, "Format (md, yaml)")
if err := flags.Parse(os.Args[1:]); err != nil {
return err
}
if len(opts.formats) == 0 {
return errors.New("Docs format required")
}
return gen(opts)
}
func main() {
if err := run(); err != nil {
log.Printf("ERROR: %+v", err)
os.Exit(1)
}
}

46
docs/reference/docker_buildx.yaml
View File

@ -1,46 +0,0 @@
command: docker buildx
short: Build with BuildKit
long: Build with BuildKit
pname: docker
plink: docker.yaml
cname:
- docker buildx bake
- docker buildx build
- docker buildx create
- docker buildx du
- docker buildx imagetools
- docker buildx inspect
- docker buildx ls
- docker buildx prune
- docker buildx rm
- docker buildx stop
- docker buildx use
- docker buildx version
clink:
- docker_buildx_bake.yaml
- docker_buildx_build.yaml
- docker_buildx_create.yaml
- docker_buildx_du.yaml
- docker_buildx_imagetools.yaml
- docker_buildx_inspect.yaml
- docker_buildx_ls.yaml
- docker_buildx_prune.yaml
- docker_buildx_rm.yaml
- docker_buildx_stop.yaml
- docker_buildx_use.yaml
- docker_buildx_version.yaml
options:
- option: builder
value_type: string
description: Override the configured builder instance
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

946
docs/reference/docker_buildx_bake.yaml
View File

@ -1,946 +0,0 @@
command: docker buildx bake
aliases: f
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
options:
- option: file
shorthand: f
value_type: stringArray
default_value: '[]'
description: Build definition file
details_url: '#file'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: load
value_type: bool
default_value: "false"
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
kubernetes: false
swarm: false
- option: no-cache
value_type: bool
default_value: "false"
description: Do not use cache when building the image
details_url: '#no-cache'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: print
value_type: bool
default_value: "false"
description: Print the options without building
details_url: '#print'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: 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
details_url: '#progress'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: pull
value_type: bool
default_value: "false"
description: Always attempt to pull a newer version of the image
details_url: '#pull'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: push
value_type: bool
default_value: "false"
description: Shorthand for --set=*.output=type=registry
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: set
value_type: stringArray
default_value: '[]'
description: 'Override target value (eg: targetpattern.key=value)'
details_url: '#set'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### 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:
- `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.
The following example uses a Docker Compose file named `docker-compose.dev.yaml`
as build definition file, and builds all targets in the file:
```console
$ docker buildx bake -f docker-compose.dev.yaml
[+] Building 66.3s (30/30) FINISHED
=> [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 "git://github.com/docker/cli#master" --print
#1 [internal] load git source git://github.com/docker/cli#master
#1 0.686 2776a6d694f988c0c1df61cad4bfac0f54e481c8 refs/heads/master
#1 CACHED
{
"group": {
"default": [
"binary"
]
},
"target": {
"binary": {
"context": "git://github.com/docker/cli#master",
"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
{
"group": {
"default": [
"default"
]
},
"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#master" --print
#1 [internal] load git source git://github.com/tonistiigi/buildx#remote-test
#1 0.401 577303add004dd7efeb13434d69ea030d35f7888 refs/heads/remote-test
#1 CACHED
{
"group": {
"default": [
"default"
]
},
"target": {
"default": {
"context": "git://github.com/docker/cli#master",
"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#master"
...
> [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.
```console
$ docker buildx bake -f docker-bake.hcl --print db
{
"group": {
"default": [
"db"
]
},
"target": {
"db": {
"context": "./",
"dockerfile": "Dockerfile",
"tags": [
"docker.io/tiborvass/db"
]
}
}
}
```
### Set type of progress output (--progress) {#progress}
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:
```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}
Same as `build --pull`.
### Override target configurations from command line (--set) {#set}
```
--set targetpattern.key[.subkey]=value
```
Override target configurations from command line. The pattern matching syntax
is defined in https://golang.org/pkg/path/#Match.
**Examples**
```console
$ docker buildx bake --set target.args.mybuildarg=value
$ docker buildx bake --set target.platform=linux/arm64
$ 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`
### File definition
In addition to compose files, bake supports a JSON and an equivalent HCL file
format for defining build groups and targets.
A target reflects a single docker build invocation with the same options that
you would specify for `docker build`. A group is a grouping of targets.
Multiple files can include the same target and final build options will be
determined by merging them together.
In the case of compose files, each service corresponds to a target.
A group can specify its list of targets with the `targets` option. A target can
inherit build options by setting the `inherits` option to the list of targets or
groups to inherit from.
Note: Design of bake command is work in progress, the user experience may change
based on feedback.
**Example HCL definition**
```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`, `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": [
"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": [
"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}"]
}
```
```console
$ docker buildx bake --print webapp
{
"group": {
"default": [
"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": [
"webapp"
]
},
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"tags": [
"docker.io/username/webapp:985e9e9"
]
}
}
}
```
#### Using the `add` function
You can use [`go-cty` stdlib functions]([go-cty](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": [
"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": [
"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": [
"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": [
"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": [
"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": [
"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
{
"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
kubernetes: false
swarm: false

649
docs/reference/docker_buildx_build.yaml
View File

@ -1,649 +0,0 @@
command: docker buildx build
aliases: b
short: Start a build
long: |-
The `buildx build` command starts a build using BuildKit. This command is similar
to the UI of `docker build` command and takes the same flags and arguments.
For documentation on most of these flags, refer to the [`docker build`
documentation](/engine/reference/commandline/build/). In
here we’ll document a subset of the new flags.
usage: docker buildx build [OPTIONS] PATH | URL | -
pname: docker buildx
plink: docker_buildx.yaml
options:
- option: add-host
value_type: stringSlice
default_value: '[]'
description: Add a custom host-to-IP mapping (host:ip)
details_url: /engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: allow
value_type: stringSlice
default_value: '[]'
description: |
Allow extra privileged entitlement, e.g. network.host, security.insecure
details_url: '#allow'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: build-arg
value_type: stringArray
default_value: '[]'
description: Set build-time variables
details_url: /engine/reference/commandline/build/#set-build-time-variables---build-arg
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: cache-from
value_type: stringArray
default_value: '[]'
description: |
External cache sources (eg. user/app:cache, type=local,src=path/to/dir)
details_url: '#cache-from'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: cache-to
value_type: stringArray
default_value: '[]'
description: |
Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir)
details_url: '#cache-to'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: cgroup-parent
value_type: string
description: Optional parent cgroup for the container
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: compress
value_type: bool
default_value: "false"
description: Compress the build context using gzip
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: cpu-period
value_type: int64
default_value: "0"
description: Limit the CPU CFS (Completely Fair Scheduler) period
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: cpu-quota
value_type: int64
default_value: "0"
description: Limit the CPU CFS (Completely Fair Scheduler) quota
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: cpu-shares
shorthand: c
value_type: int64
default_value: "0"
description: CPU shares (relative weight)
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: cpuset-cpus
value_type: string
description: CPUs in which to allow execution (0-3, 0,1)
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: cpuset-mems
value_type: string
description: MEMs in which to allow execution (0-3, 0,1)
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: file
shorthand: f
value_type: string
description: Name of the Dockerfile (Default is 'PATH/Dockerfile')
details_url: /engine/reference/commandline/build/#specify-a-dockerfile--f
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: force-rm
value_type: bool
default_value: "false"
description: Always remove intermediate containers
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: iidfile
value_type: string
description: Write the image ID to the file
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: isolation
value_type: string
description: Container isolation technology
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: label
value_type: stringArray
default_value: '[]'
description: Set metadata for an image
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: load
value_type: bool
default_value: "false"
description: Shorthand for --output=type=docker
details_url: '#load'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: memory
shorthand: m
value_type: string
description: Memory limit
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: memory-swap
value_type: string
description: |
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
kubernetes: false
swarm: false
- option: network
value_type: string
default_value: default
description: Set the networking mode for the RUN instructions during build
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: no-cache
value_type: bool
default_value: "false"
description: Do not use cache when building the image
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: output
shorthand: o
value_type: stringArray
default_value: '[]'
description: 'Output destination (format: type=local,dest=path)'
details_url: '#output'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: platform
value_type: stringArray
default_value: '[]'
description: Set target platform for build
details_url: '#platform'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: 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
details_url: '#progress'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: pull
value_type: bool
default_value: "false"
description: Always attempt to pull a newer version of the image
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: push
value_type: bool
default_value: "false"
description: Shorthand for --output=type=registry
details_url: '#push'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: quiet
shorthand: q
value_type: bool
default_value: "false"
description: Suppress the build output and print image ID on success
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: rm
value_type: bool
default_value: "true"
description: Remove intermediate containers after a successful build
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: secret
value_type: stringArray
default_value: '[]'
description: 'Secret file to expose to the build: id=mysecret,src=/local/secret'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: security-opt
value_type: stringSlice
default_value: '[]'
description: Security options
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: shm-size
value_type: string
description: Size of /dev/shm
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: squash
value_type: bool
default_value: "false"
description: Squash newly built layers into a single new layer
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: ssh
value_type: stringArray
default_value: '[]'
description: |
SSH agent socket or keys to expose to the build (format: `default|<id>[=<socket>|<key>[,<key>]]`)
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: tag
shorthand: t
value_type: stringArray
default_value: '[]'
description: Name and optionally a tag in the 'name:tag' format
details_url: /engine/reference/commandline/build/#tag-an-image--t
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: target
value_type: string
description: Set the target build stage to build.
details_url: /engine/reference/commandline/build/#specifying-target-build-stage---target
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: ulimit
value_type: string
description: Ulimit options
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### Set the target platforms for the build (--platform) {#platform}
```
--platform=value[,value]
```
Set the target platform for the build. All `FROM` commands inside the Dockerfile
without their own `--platform` flag will pull base images for this platform and
this value will also be the platform of the resulting image. The default value
will be the current platform of the buildkit daemon.
When using `docker-container` driver with `buildx`, this flag can accept multiple
values as an input separated by a comma. With multiple values the result will be
built for all of the specified platforms and joined together into a single manifest
list.
If the `Dockerfile` needs to invoke the `RUN` command, the builder needs runtime
support for the specified platform. In a clean setup, you can only execute `RUN`
commands for your system architecture.
If your kernel supports [`binfmt_misc`](https://en.wikipedia.org/wiki/Binfmt_misc)
launchers for secondary architectures, buildx will pick them up automatically.
Docker desktop releases come with `binfmt_misc` automatically configured for `arm64`
and `arm` architectures. You can see what runtime platforms your current builder
instance supports by running `docker buildx inspect --bootstrap`.
Inside a `Dockerfile`, you can access the current platform value through
`TARGETPLATFORM` build argument. Please refer to the [`docker build`
documentation](/engine/reference/builder/#automatic-platform-args-in-the-global-scope)
for the full description of automatic platform argument variants .
The formatting for the platform specifier is defined in the [containerd source
code](https://github.com/containerd/containerd/blob/v1.4.3/platforms/platforms.go#L63).
**Examples**
```console
$ docker buildx build --platform=linux/arm64 .
$ docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 .
$ 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}
```
-o, --output=[PATH,-,type=TYPE[,KEY=VALUE]
```
Sets the export action for the build result. In `docker build` all builds finish
by creating a container image and exporting it to `docker images`. `buildx` makes
this step configurable allowing results to be exported directly to the client,
oci image tarballs, registry etc.
Buildx with `docker` driver currently only supports local, tarball exporter and
image exporter. `docker-container` driver supports all the exporters.
If just the path is specified as a value, `buildx` will use the local exporter
with this path as the destination. If the value is "-", `buildx` will use `tar`
exporter and write to `stdout`.
**Examples**
```console
$ docker buildx build -o . .
$ docker buildx build -o outdir .
$ docker buildx build -o - - > out.tar
$ docker buildx build -o type=docker .
$ docker buildx build -o type=docker,dest=- . > myimage.tar
$ docker buildx build -t tonistiigi/foo -o type=registry
```
Supported exported types are:
#### `local`
The `local` export type writes all result files to a directory on the client. The
new files will be owned by the current user. On multi-platform builds, all results
will be put in subdirectories by their platform.
Attribute key:
- `dest` - destination directory where files will be written
#### `tar`
The `tar` export type writes all result files as a single tarball on the client.
On multi-platform builds all results will be put in subdirectories by their platform.
Attribute key:
- `dest` - destination path where tarball will be written. “-” writes to stdout.
#### `oci`
The `oci` export type writes the result image or manifest list as an [OCI image
layout](https://github.com/opencontainers/image-spec/blob/v1.0.1/image-layout.md)
tarball on the client.
Attribute key:
- `dest` - destination path where tarball will be written. “-” writes to stdout.
#### `docker`
The `docker` export type writes the single-platform result image as a [Docker image
specification](https://github.com/docker/docker/blob/v20.10.2/image/spec/v1.2.md)
tarball on the client. Tarballs created by this exporter are also OCI compatible.
Currently, multi-platform images cannot be exported with the `docker` export type.
The most common usecase for multi-platform images is to directly push to a registry
(see [`registry`](#registry)).
Attribute keys:
- `dest` - destination path where tarball will be written. If not specified the
tar will be loaded automatically to the current docker instance.
- `context` - name for the docker context where to import the result
#### `image`
The `image` exporter writes the build result as an image or a manifest list. When
using `docker` driver the image will appear in `docker images`. Optionally, image
can be automatically pushed to a registry by specifying attributes.
Attribute keys:
- `name` - name (references) for the new image.
- `push` - boolean to automatically push the image.
#### `registry`
The `registry` exporter is a shortcut for `type=image,push=true`.
### Push the build result to a registry (--push) {#push}
Shorthand for [`--output=type=registry`](#registry). Will automatically push the
build result to registry.
### Load the single-platform build result to `docker images` (--load) {#load}
Shorthand for [`--output=type=docker`](#docker). Will automatically load the
single-platform build result to `docker images`.
### Use an external cache source for a build (--cache-from) {#cache-from}
```
--cache-from=[NAME|type=TYPE[,KEY=VALUE]]
```
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.
`docker` driver currently only supports importing build cache from the registry.
**Examples**
```console
$ docker buildx build --cache-from=user/app:cache .
$ 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`, `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
to trigger inline cache exporter.
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
all stages. Metadata is always exported for the whole build.
**Examples**
```console
$ docker buildx build --cache-to=user/app:cache .
$ 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}
```
--allow=ENTITLEMENT
```
Allow extra privileged entitlement. List of entitlements:
- `network.host` - Allows executions with host networking.
- `security.insecure` - Allows executions without sandbox. See
[related Dockerfile extensions](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/experimental.md#run---securityinsecuresandbox).
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-flags))
**Examples**
```console
$ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure'
$ docker buildx build --allow security.insecure .
```
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

297
docs/reference/docker_buildx_create.yaml
View File

@ -1,297 +0,0 @@
command: docker buildx create
short: Create a new builder instance
long: |-
Create makes a new builder instance pointing to a docker context or endpoint,
where context is the name of a context from `docker context ls` and endpoint is
the address for docker socket (eg. `DOCKER_HOST` value).
By default, the current Docker configuration is used for determining the
context/endpoint value.
Builder instances are isolated environments where builds can be invoked. All
Docker contexts also get the default builder instance.
usage: docker buildx create [OPTIONS] [CONTEXT|ENDPOINT]
pname: docker buildx
plink: docker_buildx.yaml
options:
- option: append
value_type: bool
default_value: "false"
description: Append a node to builder instead of changing it
details_url: '#append'
deprecated: false
experimental: false
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
details_url: '#buildkitd-flags'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: config
value_type: string
description: BuildKit config file
details_url: '#config'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: driver
value_type: string
description: 'Driver to use (available: [])'
details_url: '#driver'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: driver-opt
value_type: stringArray
default_value: '[]'
description: Options for the driver
details_url: '#driver-opt'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: leave
value_type: bool
default_value: "false"
description: Remove a node from builder instead of changing it
details_url: '#leave'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: name
value_type: string
description: Builder instance name
details_url: '#name'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: node
value_type: string
description: Create/modify node with given name
details_url: '#node'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: platform
value_type: stringArray
default_value: '[]'
description: Fixed platforms for current node
details_url: '#platform'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: use
value_type: bool
default_value: "false"
description: Set the current builder instance
details_url: '#use'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### Append a new node to an existing builder (--append) {#append}
The `--append` flag changes the action of the command to append a new node to an
existing builder specified by `--name`. Buildx will choose an appropriate node
for a build based on the platforms it supports.
**Examples**
```console
$ docker buildx create mycontext1
eager_beaver
$ docker buildx create --name eager_beaver --append mycontext2
eager_beaver
```
### Specify options for the buildkitd daemon (--buildkitd-flags) {#buildkitd-flags}
```
--buildkitd-flags FLAGS
```
Adds flags when starting the buildkitd daemon. They take precedence over the
configuration file specified by [`--config`](#--config-file). See `buildkitd --help`
for the available flags.
**Example**
```
--buildkitd-flags '--debug --debugaddr 0.0.0.0:6666'
```
### Specify a configuration file for the buildkitd daemon (--config) {#config}
```
--config FILE
```
Specifies the configuration file for the buildkitd daemon to use. The configuration
can be overridden by [`--buildkitd-flags`](#--buildkitd-flags-flags).
See an [example buildkitd configuration file](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md).
### Set the builder driver to use (--driver) {#driver}
```
--driver DRIVER
```
Sets the builder driver to be used. There are two available drivers, each have
their own specificities.
#### `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}
```
--driver-opt OPTIONS
```
Passes additional driver-specific options. Details for each driver:
- `docker` - No driver options
- `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
```
- `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`
### Remove a node from a builder (--leave) {#leave}
The `--leave` flag changes the action of the command to remove a node from a
builder. The builder needs to be specified with `--name` and node that is removed
is set with `--node`.
**Examples**
```console
$ docker buildx create --name mybuilder --node mybuilder0 --leave
```
### Specify the name of the builder (--name) {#name}
```
--name NAME
```
The `--name` flag specifies the name of the builder to be created or modified.
If none is specified, one will be automatically generated.
### Specify the name of the node (--node) {#node}
```
--node NODE
```
The `--node` flag specifies the name of the node to be created or modified. If
none is specified, it is the name of the builder it belongs to, with an index
number suffix.
### Set the platforms supported by the node {#platform}
```
--platform PLATFORMS
```
The `--platform` flag sets the platforms supported by the node. It expects a
comma-separated list of platforms of the form OS/architecture/variant. The node
will also automatically detect the platforms it supports, but manual values take
priority over the detected ones and can be used when multiple nodes support
building for the same platform.
**Examples**
```console
$ docker buildx create --platform linux/amd64
$ docker buildx create --platform linux/arm64,linux/arm/v8
```
### Automatically switch to the newly created builder {#use}
The `--use` flag automatically switches the current builder to the newly created
one. Equivalent to running `docker buildx use $(docker buildx create ...)`.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

39
docs/reference/docker_buildx_du.yaml
View File

@ -1,39 +0,0 @@
command: docker buildx du
short: Disk usage
long: Disk usage
usage: docker buildx du
pname: docker buildx
plink: docker_buildx.yaml
options:
- option: filter
value_type: filter
description: Provide filter values
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: verbose
value_type: bool
default_value: "false"
description: Provide a more verbose output
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

28
docs/reference/docker_buildx_imagetools.yaml
View File

@ -1,28 +0,0 @@
command: docker buildx imagetools
short: Commands to work on images in registry
long: |-
Imagetools contains commands for working with manifest lists in the registry.
These commands are useful for inspecting multi-platform build results.
pname: docker buildx
plink: docker_buildx.yaml
cname:
- docker buildx imagetools create
- docker buildx imagetools inspect
clink:
- docker_buildx_imagetools_create.yaml
- docker_buildx_imagetools_inspect.yaml
inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

118
docs/reference/docker_buildx_imagetools_create.yaml
View File

@ -1,118 +0,0 @@
command: docker buildx imagetools create
short: Create a new image based on source images
long: |-
Imagetools contains commands for working with manifest lists in the registry.
These commands are useful for inspecting multi-platform build results.
Create a new manifest list based on source manifests. The source manifests can
be manifest lists or single platform distribution manifests and must already
exist in the registry where the new manifest is created. If only one source is
specified, create performs a carbon copy.
usage: docker buildx imagetools create [OPTIONS] [SOURCE] [SOURCE...]
pname: docker buildx imagetools
plink: docker_buildx_imagetools.yaml
options:
- option: append
value_type: bool
default_value: "false"
description: Append to existing manifest
details_url: '#append'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: dry-run
value_type: bool
default_value: "false"
description: Show final image instead of pushing
details_url: '#dry-run'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: file
shorthand: f
value_type: stringArray
default_value: '[]'
description: Read source descriptor from file
details_url: '#file'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: tag
shorthand: t
value_type: stringArray
default_value: '[]'
description: Set reference for new image
details_url: '#tag'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### Append new sources to an existing manifest list (--append) {#append}
Use the `--append` flag to append the new sources to an existing manifest list
in the destination.
### Show final image instead of pushing (--dry-run) {#dry-run}
Use the `--dry-run` flag to not push the image, just show it.
### Read source descriptor from a file (-f, --file) {#file}
```
-f FILE or --file FILE
```
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}
```
-t IMAGE or --tag IMAGE
```
Use the `-t` or `--tag` flag to set the name of the image to be created.
**Examples**
```console
$ docker buildx imagetools create --dry-run alpine@sha256:5c40b3c27b9f13c873fefb2139765c56ce97fd50230f1f2d5c91e55dec171907 sha256:c4ba6347b0e4258ce6a6de2401619316f982b7bcc529f73d2a410d0097730204
$ docker buildx imagetools create -t tonistiigi/myapp -f image1 -f image2
```
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

58
docs/reference/docker_buildx_imagetools_inspect.yaml
View File

@ -1,58 +0,0 @@
command: docker buildx imagetools inspect
short: Show details of image in the registry
long: |-
Show details of image in the registry.
Example:
```console
$ docker buildx imagetools inspect alpine
Name: docker.io/library/alpine:latest
MediaType: application/vnd.docker.distribution.manifest.list.v2+json
Digest: sha256:28ef97b8686a0b5399129e9b763d5b7e5ff03576aa5580d6f4182a49c5fe1913
Manifests:
Name: docker.io/library/alpine:latest@sha256:5c40b3c27b9f13c873fefb2139765c56ce97fd50230f1f2d5c91e55dec171907
MediaType: application/vnd.docker.distribution.manifest.v2+json
Platform: linux/amd64
Name: docker.io/library/alpine:latest@sha256:c4ba6347b0e4258ce6a6de2401619316f982b7bcc529f73d2a410d0097730204
MediaType: application/vnd.docker.distribution.manifest.v2+json
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
options:
- option: raw
value_type: bool
default_value: "false"
description: Show original JSON manifest
details_url: '#raw'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

66
docs/reference/docker_buildx_inspect.yaml
View File

@ -1,66 +0,0 @@
command: docker buildx inspect
short: Inspect current builder instance
long: Shows information about the current or specified builder.
usage: docker buildx inspect [NAME]
pname: docker buildx
plink: docker_buildx.yaml
options:
- option: bootstrap
value_type: bool
default_value: "false"
description: Ensure builder has booted before inspecting
details_url: '#bootstrap'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### Get information about a builder instance
By default, `inspect` shows information about the current builder. Specify the
name of the builder to inspect to get information about that builder.
The following example shows information about a builder instance named
`elated_tesla`:
```console
$ docker buildx inspect elated_tesla
Name: elated_tesla
Driver: docker-container
Nodes:
Name: elated_tesla0
Endpoint: unix:///var/run/docker.sock
Status: running
Platforms: linux/amd64
Name: elated_tesla1
Endpoint: ssh://ubuntu@1.2.3.4
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
kubernetes: false
swarm: false

21
docs/reference/docker_buildx_install.yaml
View File

@ -1,21 +0,0 @@
command: docker buildx install
short: Install buildx as a 'docker builder' alias
long: Install buildx as a 'docker builder' alias
usage: docker buildx install
pname: docker buildx
plink: docker_buildx.yaml
inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

38
docs/reference/docker_buildx_ls.yaml
View File

@ -1,38 +0,0 @@
command: docker buildx ls
short: List builder instances
long: |-
Lists all builder instances and the nodes for each instance
**Example**
```console
$ docker buildx ls
NAME/NODE DRIVER/ENDPOINT STATUS PLATFORMS
elated_tesla * docker-container
elated_tesla0 unix:///var/run/docker.sock running linux/amd64
elated_tesla1 ssh://ubuntu@1.2.3.4 running linux/arm64, linux/arm/v7, linux/arm/v6
default docker
default default running linux/amd64
```
Each builder has one or more nodes associated with it. The current builder's
name is marked with a `*`.
usage: docker buildx ls
pname: docker buildx
plink: docker_buildx.yaml
inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

68
docs/reference/docker_buildx_prune.yaml
View File

@ -1,68 +0,0 @@
command: docker buildx prune
short: Remove build cache
long: Remove build cache
usage: docker buildx prune
pname: docker buildx
plink: docker_buildx.yaml
options:
- option: all
shorthand: a
value_type: bool
default_value: "false"
description: Remove all unused images, not just dangling ones
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: filter
value_type: filter
description: Provide filter values (e.g. 'until=24h')
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: force
shorthand: f
value_type: bool
default_value: "false"
description: Do not prompt for confirmation
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: keep-storage
value_type: bytes
default_value: "0"
description: Amount of disk space to keep for cache
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: verbose
value_type: bool
default_value: "false"
description: Provide a more verbose output
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

39
docs/reference/docker_buildx_rm.yaml
View File

@ -1,39 +0,0 @@
command: docker buildx rm
short: Remove a builder instance
long: |-
Removes the specified or current builder. It is a no-op attempting to remove the
default builder.
usage: docker buildx rm [NAME]
pname: docker buildx
plink: docker_buildx.yaml
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
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### 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
kubernetes: false
swarm: false

23
docs/reference/docker_buildx_stop.yaml
View File

@ -1,23 +0,0 @@
command: docker buildx stop
short: Stop builder instance
long: |-
Stops the specified or current builder. This will not prevent buildx build to
restart the builder. The implementation of stop depends on the driver.
usage: docker buildx stop [NAME]
pname: docker buildx
plink: docker_buildx.yaml
inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

21
docs/reference/docker_buildx_uninstall.yaml
View File

@ -1,21 +0,0 @@
command: docker buildx uninstall
short: Uninstall the 'docker builder' alias
long: Uninstall the 'docker builder' alias
usage: docker buildx uninstall
pname: docker buildx
plink: docker_buildx.yaml
inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

43
docs/reference/docker_buildx_use.yaml
View File

@ -1,43 +0,0 @@
command: docker buildx use
short: Set the current builder instance
long: |-
Switches the current builder instance. Build commands invoked after this command
will run on a specified builder. Alternatively, a context name can be used to
switch to the default builder of that context.
usage: docker buildx use [OPTIONS] NAME
pname: docker buildx
plink: docker_buildx.yaml
options:
- option: default
value_type: bool
default_value: "false"
description: Set builder as default for current context
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: global
value_type: bool
default_value: "false"
description: Builder persists context changes
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

29
docs/reference/docker_buildx_version.yaml
View File

@ -1,29 +0,0 @@
command: docker buildx version
short: Show buildx version information
long: Show buildx version information
usage: docker buildx version
pname: docker buildx
plink: docker_buildx.yaml
inherited_options:
- option: builder
value_type: string
description: Override the configured builder instance
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
examples: |-
### View version information
```console
$ docker buildx version
github.com/docker/buildx v0.5.1-docker 11057da37336192bfc57d81e02359ba7ba848e4a
```
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

4
hack/dockerfiles/docs.Dockerfile
View File

@ -1,6 +1,7 @@
# syntax=docker/dockerfile:1.3-labs
ARG GO_VERSION=1.17.0
ARG FORMATS=md,yaml
FROM golang:${GO_VERSION}-alpine AS docsgen
WORKDIR /src
@ -12,11 +13,12 @@ FROM alpine AS gen
RUN apk add --no-cache rsync git
WORKDIR /src
COPY --from=docsgen /out/docsgen /usr/bin
ARG FORMATS
RUN --mount=target=/context \
--mount=target=.,type=tmpfs <<EOT
set -e
rsync -a /context/. .
docsgen
docsgen --formats "$FORMATS" --source "docs/reference"
mkdir /out
cp -r docs/reference /out
EOT

3
hack/update-docs
View File

@ -3,9 +3,10 @@
set -eu -o pipefail
: ${BUILDX_CMD=docker buildx}
: ${FORMATS=md}
output=$(mktemp -d -t buildx-output.XXXXXXXXXX)
(set -x ; ${BUILDX_CMD} bake --set "*.output=$output" update-docs)
(set -x ; DOCS_FORMATS=$FORMATS ${BUILDX_CMD} bake --set "*.output=$output" update-docs)
rm -rf ./docs/reference/*
cp -R "$output"/out/* ./docs/
rm -rf $output