docker/buildx
1
0
Fork 0
mirror of https://gitea.com/Lydanne/buildx.git synced 2025-07-10 05:27:07 +08:00
Code Issues Packages Projects Releases 1 Wiki Activity

docs: use "examples" section, and rephrase headings

Browse Source 
Put the flag descriptions/examples under an "examples"
section (used at docs.docker.com), and rephrase the
headings to be more consistent with other pages in the
docker documentation.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn
2021-01-13 16:37:15 +01:00
parent 87ec3af5bb
commit 442d38080e
5 changed files with 187 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
docs/reference/buildx_bake.md
View File

@ -25,12 +25,12 @@ Options:
Bake is a high-level build command. Each specified target will run in parallel
as part of the build.
## Examples
### `-f, --file FILE`
### Specify a build definition file (-f, --file)
Specifies the bake definition file. The file can be a Docker Compose, JSON or HCL
file. If multiple files are specified they are all read and configurations are
combined. By default, if no files are specified, the following are parsed:
By default, `buildx bake` looks for build definition files in the current directory,
the following are parsed:
- `docker-compose.yml`
- `docker-compose.yaml`
@ -39,11 +39,48 @@ combined. By default, if no files are specified, the following are parsed:
- `docker-bake.hcl`
- `docker-bake.override.hcl`
### `--no-cache`
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
...
```
### Do not use cache when building the image (--no-cache)
Same as `build --no-cache`. Do not use cache when building the image.
### `--print`
### 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.
@ -63,16 +100,37 @@ $ docker buildx bake -f docker-bake.hcl --print db
}
```
### `--progress`
### 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").
### `--pull`
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)
Same as `build --pull`.
### `--set targetpattern.key[.subkey]=value`
### Override target configurations from command line (--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.

36
docs/reference/buildx_build.md
View File

@ -41,7 +41,13 @@ For documentation on most of these flags refer to the [`docker build`
documentation](https://docs.docker.com/engine/reference/commandline/build/). In
here we’ll document a subset of the new flags.
### `--platform=value[,value]`
## Examples
### Set the target platforms for the build (--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
@ -78,7 +84,11 @@ docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 .
docker buildx build --platform=darwin .
```
### `-o, --output=[PATH,-,type=TYPE[,KEY=VALUE]`
### Set the export action for the build result (-o, --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
@ -166,17 +176,21 @@ Attribute keys:
The `registry` exporter is a shortcut for `type=image,push=true`.
### `--push`
### Push the build result to a registry (--push)
Shorthand for [`--output=type=registry`](#registry). Will automatically push the
build result to registry.
### `--load`
### 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`.
### `--cache-from=[NAME|type=TYPE[,KEY=VALUE]]`
### Use an external cache source for a build (--cache-from)
```
--cache-from=[NAME|type=TYPE[,KEY=VALUE]]
```
Use an external cache source for a build. Supported types are `registry` and `local`.
The `registry` source can import cache from a cache manifest or (special) image
@ -196,7 +210,11 @@ docker buildx build --cache-from=type=registry,ref=user/app .
docker buildx build --cache-from=type=local,src=path/to/cache .
```
### `--cache-to=[NAME|type=TYPE[,KEY=VALUE]]`
### Export build cache to an external cache destination (--cache-to)
```
--cache-to=[NAME|type=TYPE[,KEY=VALUE]]
```
Export build cache to an external cache destination. Supported types are `registry`,
`local` and `inline`. Registry exports build cache to a cache manifest in the
@ -222,7 +240,11 @@ docker buildx build --cache-to=type=registry,ref=user/app .
docker buildx build --cache-to=type=local,dest=path/to/cache .
```
### `--allow=ENTITLEMENT`
### Allow extra privileged entitlement (--allow)
```console
--allow=ENTITLEMENT
```
Allow extra privileged entitlement. List of entitlements:

84
docs/reference/buildx_create.md
View File

@ -31,11 +31,13 @@ context/endpoint value.
Builder instances are isolated environments where builds can be invoked. All
docker contexts also get the default builder instance.
### `--append`
## Examples
Changes the action of the command to appends 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.
### 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
for a build based on the platforms it supports.
Example:
@ -47,7 +49,11 @@ $ docker buildx create --name eager_beaver --append mycontext2
eager_beaver
```
### `--buildkitd-flags FLAGS`
### Specify options for the buildkitd daemon (--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`
@ -59,13 +65,21 @@ Example:
--buildkitd-flags '--debug --debugaddr 0.0.0.0:6666'
```
### `--config FILE`
### Specify a configuration file for the buildkitd daemon (--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).
### `--driver DRIVER`
### Set the builder driver to use (--driver)
```
--driver DRIVER
```
Sets the builder driver to be used. There are two available drivers, each have
their own specificities.
@ -82,7 +96,11 @@ their own specificities.
with defined buildkit container image to build your images.
### `--driver-opt OPTIONS`
### Set additional driver-specific options (--driver-opt)
```
--driver-opt OPTIONS
```
Passes additional driver-specific options. Details for each driver:
@ -103,10 +121,11 @@ 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"
### `--leave`
### Remove a node from a builder (--leave)
Changes the action of the command to removes a node from a builder. The builder
needs to be specified with `--name` and node that is removed is set with `--node`.
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`.
Example:
@ -114,23 +133,36 @@ Example:
docker buildx create --name mybuilder --node mybuilder0 --leave
```
### `--name NAME`
### Specify the name of the builder (--name)
Specifies the name of the builder to be created or modified. If none is specified,
one will be automatically generated.
```
--name NAME
```
### `--node NODE`
The `--name` flag specifies the name of the builder to be created or modified.
If none is specified, one will be automatically generated.
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.
### Specify the name of the node (--node)
### `--platform PLATFORMS`
```
--node NODE
```
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.
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 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.
Example:
@ -139,7 +171,7 @@ docker buildx create --platform linux/amd64
docker buildx create --platform linux/arm64,linux/arm/v8
```
### `--use`
### Automatically switch to the newly created builder
Automatically switches the current builder to the newly created one. Equivalent
to running `docker buildx use $(docker buildx create ...)`.
The `--use` flag automatically switches the current builder to the newly created
one. Equivalent to running `docker buildx use $(docker buildx create ...)`.

25
docs/reference/buildx_imagetools_create.md
View File

@ -23,22 +23,33 @@ 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.
### `--append`
## Examples
Append appends the new sources to an existing manifest list in the destination.
### Append new sources to an existing manifest list (--append)
### `--dry-run`
Use the `--append` flag to append the new sources to an existing manifest list
in the destination.
Do not push the image, just show it.
### Show final image instead of pushing (--dry-run)
### `-f, --file FILE`
Use the `--dry-run` flag to not push the image, just show it.
### Read source descriptor from a file (-f, --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.
### `-t, --tag IMAGE`
### Set reference for new image (-t, --tag)
Name of the image to be created.
```
-t IMAGE or --tag IMAGE
```
Use the `-t` or `--tag` flag to set the name of the image to be created.
Examples:

22
docs/reference/buildx_inspect.md
View File

@ -14,7 +14,14 @@ Options:
Shows information about the current or specified builder.
Example:
## 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
@ -34,10 +41,11 @@ Status: running
Platforms: linux/arm64, linux/arm/v7, linux/arm/v6
```
### `--bootstrap`
### Ensure that the builder is running before inspecting (--bootstrap)
Ensures 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, it is
thus not necessary. The same BuildKit container is used during the lifetime of
the associated builder node (as displayed in `buildx ls`).
Use the `--bootstrap` option to ensures 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, it is thus not necessary. The same BuildKit
container is used during the lifetime of the associated builder node (as
displayed in `buildx ls`).