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

docs: reference docs updates

Browse Source 
Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Tonis Tiigi 2021-03-22 23:31:22 -07:00 committed by Sebastiaan van Stijn
parent ca0f5dabea
commit c46407b2d3
No known key found for this signature in database
GPG Key ID: 76698F39D527CE8C
17 changed files with 268 additions and 183 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
docs/reference/buildx.md
View File

@ -1,32 +1,31 @@
# buildx
```
Usage: docker buildx [OPTIONS] COMMAND
Build with BuildKit
Options:
--builder string Override the configured builder instance
Management Commands:
imagetools Commands to work on images in registry
Commands:
bake Build from a file
build Start a build
create Create a new builder instance
du Disk usage
inspect Inspect current builder instance
ls List builder instances
prune Remove build cache
rm Remove a builder instance
stop Stop builder instance
use Set the current builder instance
version Show buildx version information
Run 'docker buildx COMMAND --help' for more information on a command.
docker buildx [OPTIONS] COMMAND
```
## Description
<!---MARKER_GEN_START-->
Build with BuildKit
### Subcommands
| Name | Description |
| --- | --- |
| [`bake`](buildx_bake.md) | Build from a file |
| [`build`](buildx_build.md) | Start a build |
| [`create`](buildx_create.md) | Create a new builder instance |
| [`du`](buildx_du.md) | Disk usage |
| [`imagetools`](buildx_imagetools.md) | Commands to work on images in registry |
| [`inspect`](buildx_inspect.md) | Inspect current builder instance |
| [`install`](buildx_install.md) | Install buildx as a 'docker builder' alias |
| [`ls`](buildx_ls.md) | List builder instances |
| [`prune`](buildx_prune.md) | Remove build cache |
| [`rm`](buildx_rm.md) | Remove a builder instance |
| [`stop`](buildx_stop.md) | Stop builder instance |
| [`uninstall`](buildx_uninstall.md) | Uninstall the 'docker builder' alias |
| [`use`](buildx_use.md) | Set the current builder instance |
| [`version`](buildx_version.md) | Show buildx version information |
<!---MARKER_GEN_END-->

48
docs/reference/buildx_bake.md
View File

@ -1,24 +1,32 @@
# buildx bake
```
Usage: docker buildx bake [OPTIONS] [TARGET...]
docker buildx bake [OPTIONS] [TARGET...]
```
<!---MARKER_GEN_START-->
Build from a file
Aliases:
bake, f
### Aliases
Options:
--builder string Override the configured builder instance
-f, --file stringArray Build definition file
--load Shorthand for --set=*.output=type=docker
--no-cache Do not use cache when building the image
--print Print the options without building
--progress string Set type of progress output (auto, plain, tty). Use plain to show container output (default "auto")
--pull Always attempt to pull a newer version of the image
--push Shorthand for --set=*.output=type=registry
--set stringArray Override target value (eg: targetpattern.key=value)
```
`bake`, `f`
### Options
| Name | Description |
| --- | --- |
| `--builder string` | Override the configured builder instance |
| [`-f`](#file), [`--file stringArray`](#file) | Build definition file |
| `--load` | Shorthand for --set=*.output=type=docker |
| [`--no-cache`](#no-cache) | Do not use cache when building the image |
| [`--print`](#print) | Print the options without building |
| [`--progress string`](#progress) | Set type of progress output (auto, plain, tty). Use plain to show container output |
| [`--pull`](#pull) | Always attempt to pull a newer version of the image |
| `--push` | Shorthand for --set=*.output=type=registry |
| [`--set stringArray`](#set) | Override target value (eg: targetpattern.key=value) |
<!---MARKER_GEN_END-->
## Description
@ -27,7 +35,7 @@ as part of the build.
## Examples
### Specify a build definition file (-f, --file)
### <a name="file"></a> Specify a build definition file (-f, --file)
By default, `buildx bake` looks for build definition files in the current directory,
the following are parsed:
@ -76,11 +84,11 @@ $ docker buildx bake -f docker-compose.dev.yaml backend database
...
```
### Do not use cache when building the image (--no-cache)
### <a name="no-cache"></a> Do not use cache when building the image (--no-cache)
Same as `build --no-cache`. Do not use cache when building the image.
### Print the options without building (--print)
### <a name="print"></a> Print the options without building (--print)
Prints the resulting options of the targets desired to be built, in a JSON format,
without starting a build.
@ -100,7 +108,7 @@ $ docker buildx bake -f docker-bake.hcl --print db
}
```
### Set type of progress output (--progress)
### <a name="progress"></a> Set type of progress output (--progress)
Same as `build --progress`. Set type of progress output (auto, plain, tty). Use
plain to show container output (default "auto").
@ -122,11 +130,11 @@ $ docker buildx bake --progress=plain
```
### Always attempt to pull a newer version of the image (--pull)
### <a name="pull"></a> Always attempt to pull a newer version of the image (--pull)
Same as `build --pull`.
### Override target configurations from command line (--set)
### <a name="set"></a> Override target configurations from command line (--set)
```
--set targetpattern.key[.subkey]=value

74
docs/reference/buildx_build.md
View File

@ -1,36 +1,44 @@
# buildx build
```
Usage: docker buildx build [OPTIONS] PATH | URL | -
docker buildx build [OPTIONS] PATH | URL | -
```
<!---MARKER_GEN_START-->
Start a build
Aliases:
build, b
### Aliases
Options:
--add-host strings Add a custom host-to-IP mapping (host:ip)
--allow strings Allow extra privileged entitlement, e.g. network.host, security.insecure
--build-arg stringArray Set build-time variables
--builder string Override the configured builder instance
--cache-from stringArray External cache sources (eg. user/app:cache, type=local,src=path/to/dir)
--cache-to stringArray Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir)
-f, --file string Name of the Dockerfile (Default is 'PATH/Dockerfile')
--iidfile string Write the image ID to the file
--label stringArray Set metadata for an image
--load Shorthand for --output=type=docker
--network string Set the networking mode for the RUN instructions during build (default "default")
--no-cache Do not use cache when building the image
-o, --output stringArray Output destination (format: type=local,dest=path)
--platform stringArray Set target platform for build
--progress string Set type of progress output (auto, plain, tty). Use plain to show container output (default "auto")
--pull Always attempt to pull a newer version of the image
--push Shorthand for --output=type=registry
--secret stringArray Secret file to expose to the build: id=mysecret,src=/local/secret
--ssh stringArray SSH agent socket or keys to expose to the build (format: default|<id>[=<socket>|<key>[,<key>]])
-t, --tag stringArray Name and optionally a tag in the 'name:tag' format
--target string Set the target build stage to build.
```
`build`, `b`
### Options
| Name | Description |
| --- | --- |
| `--add-host stringSlice` | Add a custom host-to-IP mapping (host:ip) |
| [`--allow stringSlice`](#allow) | Allow extra privileged entitlement, e.g. network.host, security.insecure |
| `--build-arg stringArray` | Set build-time variables |
| `--builder string` | Override the configured builder instance |
| [`--cache-from stringArray`](#cache-from) | External cache sources (eg. user/app:cache, type=local,src=path/to/dir) |
| [`--cache-to stringArray`](#cache-to) | Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir) |
| `-f`, `--file string` | Name of the Dockerfile (Default is 'PATH/Dockerfile') |
| `--iidfile string` | Write the image ID to the file |
| `--label stringArray` | Set metadata for an image |
| [`--load`](#load) | Shorthand for --output=type=docker |
| `--network string` | Set the networking mode for the RUN instructions during build |
| `--no-cache` | Do not use cache when building the image |
| [`-o`](#output), [`--output stringArray`](#output) | Output destination (format: type=local,dest=path) |
| [`--platform stringArray`](#platform) | Set target platform for build |
| `--progress string` | Set type of progress output (auto, plain, tty). Use plain to show container output |
| `--pull` | Always attempt to pull a newer version of the image |
| [`--push`](#push) | Shorthand for --output=type=registry |
| `--secret stringArray` | Secret file to expose to the build: id=mysecret,src=/local/secret |
| `--ssh stringArray` | SSH agent socket or keys to expose to the build (format: default|<id>[=<socket>|<key>[,<key>]]) |
| `-t`, `--tag stringArray` | Name and optionally a tag in the 'name:tag' format |
| `--target string` | Set the target build stage to build. |
<!---MARKER_GEN_END-->
## Description
@ -43,7 +51,7 @@ here we’ll document a subset of the new flags.
## Examples
### Set the target platforms for the build (--platform)
### <a name="platform"></a> Set the target platforms for the build (--platform)
```
--platform=value[,value]
@ -84,7 +92,7 @@ $ docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 .
$ docker buildx build --platform=darwin .
```
### Set the export action for the build result (-o, --output)
### <a name="output"></a> Set the export action for the build result (-o, --output)
```
-o, --output=[PATH,-,type=TYPE[,KEY=VALUE]
@ -176,17 +184,17 @@ Attribute keys:
The `registry` exporter is a shortcut for `type=image,push=true`.
### Push the build result to a registry (--push)
### <a name="push"></a> Push the build result to a registry (--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)
### <a name="load"></a> Load the single-platform build result to `docker images` (--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)
### <a name="cache-from"></a> Use an external cache source for a build (--cache-from)
```
--cache-from=[NAME|type=TYPE[,KEY=VALUE]]
@ -210,7 +218,7 @@ $ docker buildx build --cache-from=type=registry,ref=user/app .
$ docker buildx build --cache-from=type=local,src=path/to/cache .
```
### Export build cache to an external cache destination (--cache-to)
### <a name="cache-to"></a> Export build cache to an external cache destination (--cache-to)
```
--cache-to=[NAME|type=TYPE[,KEY=VALUE]]
@ -240,7 +248,7 @@ $ docker buildx build --cache-to=type=registry,ref=user/app .
$ docker buildx build --cache-to=type=local,dest=path/to/cache .
```
### Allow extra privileged entitlement (--allow)
### <a name="allow"></a> Allow extra privileged entitlement (--allow)
```
--allow=ENTITLEMENT

56
docs/reference/buildx_create.md
View File

@ -1,23 +1,31 @@
# buildx create
```
Usage: docker buildx create [OPTIONS] [CONTEXT|ENDPOINT]
docker buildx create [OPTIONS] [CONTEXT|ENDPOINT]
```
<!---MARKER_GEN_START-->
Create a new builder instance
Options:
--append Append a node to builder instead of changing it
--builder string Override the configured builder instance
--buildkitd-flags string Flags for buildkitd daemon
--config string BuildKit config file
--driver string Driver to use (available: [docker docker-container kubernetes])
--driver-opt stringArray Options for the driver
--leave Remove a node from builder instead of changing it
--name string Builder instance name
--node string Create/modify node with given name
--platform stringArray Fixed platforms for current node
--use Set the current builder instance
```
### Options
| Name | Description |
| --- | --- |
| [`--append`](#append) | Append a node to builder instead of changing it |
| `--builder string` | Override the configured builder instance |
| [`--buildkitd-flags string`](#buildkitd-flags) | Flags for buildkitd daemon |
| [`--config string`](#config) | BuildKit config file |
| [`--driver string`](#driver) | Driver to use (available: []) |
| [`--driver-opt stringArray`](#driver-opt) | Options for the driver |
| [`--leave`](#leave) | Remove a node from builder instead of changing it |
| [`--name string`](#name) | Builder instance name |
| [`--node string`](#node) | Create/modify node with given name |
| [`--platform stringArray`](#platform) | Fixed platforms for current node |
| [`--use`](#use) | Set the current builder instance |
<!---MARKER_GEN_END-->
## Description
@ -33,7 +41,7 @@ docker contexts also get the default builder instance.
## Examples
### Append a new node to an existing builder (--append)
### <a name="append"></a> Append a new node to an existing builder (--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
@ -49,7 +57,7 @@ $ docker buildx create --name eager_beaver --append mycontext2
eager_beaver
```
### Specify options for the buildkitd daemon (--buildkitd-flags)
### <a name="buildkitd-flags"></a> Specify options for the buildkitd daemon (--buildkitd-flags)
```
--buildkitd-flags FLAGS
@ -65,7 +73,7 @@ for the available flags.
--buildkitd-flags '--debug --debugaddr 0.0.0.0:6666'
```
### Specify a configuration file for the buildkitd daemon (--config)
### <a name="config"></a> Specify a configuration file for the buildkitd daemon (--config)
```
--config FILE
@ -75,7 +83,7 @@ Specifies the configuration file for the buildkitd daemon to use. The configurat
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)
### <a name="driver"></a> Set the builder driver to use (--driver)
```
--driver DRIVER
@ -96,7 +104,7 @@ their own specificities.
with defined buildkit container image to build your images.
### Set additional driver-specific options (--driver-opt)
### <a name="driver-opt"></a> Set additional driver-specific options (--driver-opt)
```
--driver-opt OPTIONS
@ -121,7 +129,7 @@ Passes additional driver-specific options. Details for each driver:
- `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"
### Remove a node from a builder (--leave)
### <a name="leave"></a> Remove a node from a builder (--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
@ -133,7 +141,7 @@ is set with `--node`.
$ docker buildx create --name mybuilder --node mybuilder0 --leave
```
### Specify the name of the builder (--name)
### <a name="name"></a> Specify the name of the builder (--name)
```
--name NAME
@ -142,7 +150,7 @@ $ docker buildx create --name mybuilder --node mybuilder0 --leave
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)
### <a name="node"></a> Specify the name of the node (--node)
```
--node NODE
@ -152,7 +160,7 @@ 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
### <a name="platform"></a> Set the platforms supported by the node
```
--platform PLATFORMS
@ -171,7 +179,7 @@ $ docker buildx create --platform linux/amd64
$ docker buildx create --platform linux/arm64,linux/arm/v8
```
### Automatically switch to the newly created builder
### <a name="use"></a> Automatically switch to the newly created builder
The `--use` flag automatically switches the current builder to the newly created
one. Equivalent to running `docker buildx use $(docker buildx create ...)`.

23
docs/reference/buildx_du.md
View File

@ -1,16 +1,19 @@
# buildx du
```
Usage: docker buildx du
Disk usage
Options:
--builder string Override the configured builder instance
--filter filter Provide filter values
--verbose Provide a more verbose output
docker buildx du
```
## Description
<!---MARKER_GEN_START-->
Disk usage
### Options
| Name | Description |
| --- | --- |
| `--builder string` | Override the configured builder instance |
| `--filter filter` | Provide filter values |
| `--verbose` | Provide a more verbose output |
<!---MARKER_GEN_END-->

19
docs/reference/buildx_imagetools.md
View File

@ -1,17 +1,22 @@
# buildx imagetools
```
Usage: docker buildx imagetools [OPTIONS] COMMAND
docker buildx imagetools [OPTIONS] COMMAND
```
<!---MARKER_GEN_START-->
Commands to work on images in registry
Options:
--builder string Override the configured builder instance
### Subcommands
Commands:
create Create a new image based on source images
inspect Show details of image in the registry
```
| Name | Description |
| --- | --- |
| [`create`](buildx_imagetools_create.md) | Create a new image based on source images |
| [`inspect`](buildx_imagetools_inspect.md) | Show details of image in the registry |
<!---MARKER_GEN_END-->
## Description

31
docs/reference/buildx_imagetools_create.md
View File

@ -1,17 +1,24 @@
# buildx imagetools create
```
Usage: docker buildx imagetools create [OPTIONS] [SOURCE] [SOURCE...]
docker buildx imagetools create [OPTIONS] [SOURCE] [SOURCE...]
```
<!---MARKER_GEN_START-->
Create a new image based on source images
Options:
--append Append to existing manifest
--builder string Override the configured builder instance
--dry-run Show final image instead of pushing
-f, --file stringArray Read source descriptor from file
-t, --tag stringArray Set reference for new image
```
### Options
| Name | Description |
| --- | --- |
| [`--append`](#append) | Append to existing manifest |
| `--builder string` | Override the configured builder instance |
| [`--dry-run`](#dry-run) | Show final image instead of pushing |
| [`-f`](#file), [`--file stringArray`](#file) | Read source descriptor from file |
| [`-t`](#tag), [`--tag stringArray`](#tag) | Set reference for new image |
<!---MARKER_GEN_END-->
## Description
@ -25,16 +32,16 @@ one source is specified create performs a carbon copy.
## Examples
### Append new sources to an existing manifest list (--append)
### <a name="append"></a> Append new sources to an existing manifest list (--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)
### <a name="dry-run"></a> Show final image instead of pushing (--dry-run)
Use the `--dry-run` flag to not push the image, just show it.
### Read source descriptor from a file (-f, --file)
### <a name="file"></a> Read source descriptor from a file (-f, --file)
```
-f FILE or --file FILE
@ -43,7 +50,7 @@ Use the `--dry-run` flag to not push the image, just show it.
Reads source from files. A source can be a manifest digest, manifest reference,
or a JSON of OCI descriptor object.
### Set reference for new image (-t, --tag)
### <a name="tag"></a> Set reference for new image (-t, --tag)
```
-t IMAGE or --tag IMAGE

19
docs/reference/buildx_imagetools_inspect.md
View File

@ -1,14 +1,21 @@
# buildx imagetools inspect
```
Usage: docker buildx imagetools inspect [OPTIONS] NAME
docker buildx imagetools inspect [OPTIONS] NAME
```
<!---MARKER_GEN_START-->
Show details of image in the registry
Options:
--builder string Override the configured builder instance
--raw Show original JSON manifest
```
### Options
| Name | Description |
| --- | --- |
| `--builder string` | Override the configured builder instance |
| [`--raw`](#raw) | Show original JSON manifest |
<!---MARKER_GEN_END-->
## Description
@ -34,7 +41,7 @@ Manifests:
...
```
### Show original, unformatted JSON manifest (--raw)
### <a name="raw"></a> Show original, unformatted JSON manifest (--raw)
Use the `--raw` option to print the original JSON bytes instead of the formatted
output.

19
docs/reference/buildx_inspect.md
View File

@ -1,14 +1,21 @@
# buildx inspect
```
Usage: docker buildx inspect [NAME]
docker buildx inspect [NAME]
```
<!---MARKER_GEN_START-->
Inspect current builder instance
Options:
--bootstrap Ensure builder has booted before inspecting
--builder string Override the configured builder instance
```
### Options
| Name | Description |
| --- | --- |
| [`--bootstrap`](#bootstrap) | Ensure builder has booted before inspecting |
| `--builder string` | Override the configured builder instance |
<!---MARKER_GEN_END-->
## Description
@ -41,7 +48,7 @@ Status: running
Platforms: linux/arm64, linux/arm/v7, linux/arm/v6
```
### Ensure that the builder is running before inspecting (--bootstrap)
### <a name="bootstrap"></a> Ensure that the builder is running before inspecting (--bootstrap)
Use the `--bootstrap` option to ensures that the builder is running before
inspecting it. If the driver is `docker-container`, then `--bootstrap` starts

11
docs/reference/buildx_install.md Normal file
View File

@ -0,0 +1,11 @@
# buildx install
```
docker buildx install
```
<!---MARKER_GEN_START-->
Install buildx as a 'docker builder' alias
<!---MARKER_GEN_END-->

9
docs/reference/buildx_ls.md
View File

@ -1,13 +1,14 @@
# buildx ls
```
Usage: docker buildx ls
docker buildx ls
```
<!---MARKER_GEN_START-->
List builder instances
Options:
--builder string Override the configured builder instance
```
<!---MARKER_GEN_END-->
## Description

30
docs/reference/buildx_prune.md
View File

@ -1,19 +1,23 @@
# buildx prune
```
Usage: docker buildx prune
Remove build cache
Options:
-a, --all Remove all unused images, not just dangling ones
--builder string Override the configured builder instance
--filter filter Provide filter values (e.g. 'until=24h')
-f, --force Do not prompt for confirmation
--keep-storage bytes Amount of disk space to keep for cache
--verbose Provide a more verbose output
docker buildx prune
```
## Description
<!---MARKER_GEN_START-->
Remove build cache
### Options
| Name | Description |
| --- | --- |
| `-a`, `--all` | Remove all unused images, not just dangling ones |
| `--builder string` | Override the configured builder instance |
| `--filter filter` | Provide filter values (e.g. 'until=24h') |
| `-f`, `--force` | Do not prompt for confirmation |
| `--keep-storage bytes` | Amount of disk space to keep for cache |
| `--verbose` | Provide a more verbose output |
<!---MARKER_GEN_END-->
Remove build cache

9
docs/reference/buildx_rm.md
View File

@ -1,13 +1,14 @@
# buildx rm
```
Usage: docker buildx rm [NAME]
docker buildx rm [NAME]
```
<!---MARKER_GEN_START-->
Remove a builder instance
Options:
--builder string Override the configured builder instance
```
<!---MARKER_GEN_END-->
## Description

9
docs/reference/buildx_stop.md
View File

@ -1,13 +1,14 @@
# buildx stop
```
Usage: docker buildx stop [NAME]
docker buildx stop [NAME]
```
<!---MARKER_GEN_START-->
Stop builder instance
Options:
--builder string Override the configured builder instance
```
<!---MARKER_GEN_END-->
## Description

11
docs/reference/buildx_uninstall.md Normal file
View File

@ -0,0 +1,11 @@
# buildx uninstall
```
docker buildx uninstall
```
<!---MARKER_GEN_START-->
Uninstall the 'docker builder' alias
<!---MARKER_GEN_END-->

19
docs/reference/buildx_use.md
View File

@ -1,15 +1,22 @@
# buildx use
```
Usage: docker buildx use [OPTIONS] NAME
docker buildx use [OPTIONS] NAME
```
<!---MARKER_GEN_START-->
Set the current builder instance
Options:
--builder string Override the configured builder instance
--default Set builder as default for current context
--global Builder persists context changes
```
### Options
| Name | Description |
| --- | --- |
| `--builder string` | Override the configured builder instance |
| `--default` | Set builder as default for current context |
| `--global` | Builder persists context changes |
<!---MARKER_GEN_END-->
## Description

13
docs/reference/buildx_version.md
View File

@ -1,17 +1,14 @@
# buildx version
```
Usage: docker buildx version
Show buildx version information
Options:
--builder string Override the configured builder instance
docker buildx version
```
## Description
<!---MARKER_GEN_START-->
Show buildx version information
Show buildx version information
<!---MARKER_GEN_END-->
## Examples