From ff749d8863f8495096b8887918731f578ca27c67 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 13 Jan 2021 15:21:39 +0100 Subject: [PATCH 1/9] docs: split reference docs to separate files Signed-off-by: Sebastiaan van Stijn --- README.md | 711 +------------------- docs/reference/buildx_bake.md | 300 +++++++++ docs/reference/buildx_build.md | 237 +++++++ docs/reference/buildx_create.md | 141 ++++ docs/reference/buildx_imagetools_create.md | 45 ++ docs/reference/buildx_imagetools_inspect.md | 29 + docs/reference/buildx_inspect.md | 33 + docs/reference/buildx_ls.md | 21 + docs/reference/buildx_rm.md | 6 + docs/reference/buildx_stop.md | 6 + docs/reference/buildx_use.md | 7 + 11 files changed, 835 insertions(+), 701 deletions(-) create mode 100644 docs/reference/buildx_bake.md create mode 100644 docs/reference/buildx_build.md create mode 100644 docs/reference/buildx_create.md create mode 100644 docs/reference/buildx_imagetools_create.md create mode 100644 docs/reference/buildx_imagetools_inspect.md create mode 100644 docs/reference/buildx_inspect.md create mode 100644 docs/reference/buildx_ls.md create mode 100644 docs/reference/buildx_rm.md create mode 100644 docs/reference/buildx_stop.md create mode 100644 docs/reference/buildx_use.md diff --git a/README.md b/README.md index 931c8926..c99ef048 100644 --- a/README.md +++ b/README.md @@ -29,16 +29,16 @@ Key features: * [Building multi-platform images](#building-multi-platform-images) * [High-level build options](#high-level-build-options) - [Documentation](#documentation) - + [`buildx build [OPTIONS] PATH | URL | -`](#buildx-build-options-path--url---) - + [`buildx create [OPTIONS] [CONTEXT|ENDPOINT]`](#buildx-create-options-contextendpoint) - + [`buildx use NAME`](#buildx-use-name) - + [`buildx inspect [NAME]`](#buildx-inspect-name) - + [`buildx ls`](#buildx-ls) - + [`buildx stop [NAME]`](#buildx-stop-name) - + [`buildx rm [NAME]`](#buildx-rm-name) - + [`buildx bake [OPTIONS] [TARGET...]`](#buildx-bake-options-target) - + [`buildx imagetools create [OPTIONS] [SOURCE] [SOURCE...]`](#buildx-imagetools-create-options-source-source) - + [`buildx imagetools inspect NAME`](#buildx-imagetools-inspect-name) + + [`buildx build [OPTIONS] PATH | URL | -`](docs/reference/buildx_build.md) + + [`buildx create [OPTIONS] [CONTEXT|ENDPOINT]`](docs/reference/buildx_create.md) + + [`buildx use NAME`](docs/reference/buildx_use.md) + + [`buildx inspect [NAME]`](docs/reference/buildx_inspect.md) + + [`buildx ls`](docs/reference/buildx_ls.md) + + [`buildx stop [NAME]`](docs/reference/buildx_stop.md) + + [`buildx rm [NAME]`](docs/reference/buildx_rm.md) + + [`buildx bake [OPTIONS] [TARGET...]`](docs/reference/buildx_bake.md) + + [`buildx imagetools create [OPTIONS] [SOURCE] [SOURCE...]`](docs/reference/buildx_imagetools_create.md) + + [`buildx imagetools inspect NAME`](docs/reference/buildx_imagetools_inspect.md) - [Setting buildx as default builder in Docker 19.03+](#setting-buildx-as-default-builder-in-docker-1903) - [Contributing](#contributing) @@ -159,697 +159,6 @@ Currently, the bake command supports building images from compose files, similar There is also support for custom build rules from HCL/JSON files allowing better code reuse and different target groups. The design of bake is in very early stages and we are looking for feedback from users. - - -# Documentation - -### `buildx build [OPTIONS] PATH | URL | -` - -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. - -Options: - -| Flag | Description | -| --- | --- | -| --add-host [] | Add a custom host-to-IP mapping (host:ip) -| --allow [] | Allow extra privileged entitlement, e.g. network.host, security.insecure -| --build-arg [] | Set build-time variables -| --cache-from [] | External cache sources (eg. user/app:cache, type=local,src=path/to/dir) -| --cache-to [] | Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir) -| --file string | Name of the Dockerfile (Default is 'PATH/Dockerfile') -| --iidfile string | Write the image ID to the file -| --label [] | 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 -| --output [] | Output destination (format: type=local,dest=path) -| --platform [] | 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 [] | Secret file to expose to the build: id=mysecret,src=/local/secret -| --ssh [] | SSH agent socket or keys to expose to the build (format: default\|<id>[=<socket>\|<key>[,<key>]]) -| --tag [] | Name and optionally a tag in the 'name:tag' format -| --target string | Set the target build stage to build. - -For documentation on most of these flags refer to `docker build` documentation in https://docs.docker.com/engine/reference/commandline/build/ . In here we’ll document a subset of the new flags. - -#### ` --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 `docker build` documentation for the full description of automatic platform argument variants https://docs.docker.com/engine/reference/builder/#automatic-platform-args-in-the-global-scope . - -The formatting for the platform specifier is defined in https://github.com/containerd/containerd/blob/v1.2.6/platforms/platforms.go#L63 . - -Examples: -``` -docker buildx build --platform=linux/arm64 . -docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 . -docker buildx build --platform=darwin . -``` - -#### `-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: - -``` -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 tarball https://github.com/opencontainers/image-spec/blob/master/image-layout.md 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 tarball https://github.com/moby/moby/blob/master/image/spec/v1.2.md 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` - -Shorthand for [`--output=type=registry`](#registry). Will automatically push the build result to registry. - -#### `--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. Supported types are `registry` and `local`. The `registry` source can import cache from a cache manifest or (special) image configuration on the registry. The `local` source can import cache from local files previously exported with `--cache-to`. - -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: -``` -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 . -``` - -#### `--cache-to=[NAME|type=TYPE[,KEY=VALUE]]` - -Export build cache to an external cache destination. Supported types are `registry`, `local` and `inline`. Registry exports build cache to a cache manifest in the registry, local exports cache to a local directory on the client and inline writes the cache metadata into the image configuration. - -`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: -``` -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 . -``` - -#### `--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`](#--buildkitd-flags-flags)) - -Example: -``` -$ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure' -$ docker buildx build --allow security.insecure . -``` - -### `buildx create [OPTIONS] [CONTEXT|ENDPOINT]` - -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. - -Options: - -| Flag | Description | -| --- | --- | -| --append | Append a node to builder instead of changing it -| --buildkitd-flags string | Flags for buildkitd daemon -| --config string | BuildKit config file -| --driver string | Driver to use (eg. docker-container) -| --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 - -#### `--append` - -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. - -Example: -``` -$ docker buildx create mycontext1 -eager_beaver -$ docker buildx create --name eager_beaver --append mycontext2 -eager_beaver -``` - -#### `--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' -``` - -#### `--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` - -Sets the builder driver to be used. There are two available drivers, each have their own specificities. - -- `docker` - Uses the builder that is built into the docker daemon. With this driver, the [`--load`](#--load) flag is implied by default on `buildx build`. However, building multi-platform images or exporting cache is not currently supported. - -- `docker-container` - Uses a buildkit container that will be spawned via docker. With this driver, both building multi-platform images and exporting cache are supported. However, images built will not automatically appear in `docker images` (see [`build --load`](#--load)). - -- `kubernetes` - Uses a kubernetes pods. With this driver , you can spin up pods with defined buildkit container image to build your images. - - -#### `--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: - ``` - --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. - - `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" - -#### `--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`. - -Example: -``` -docker buildx create --name mybuilder --node mybuilder0 --leave -``` - -#### `--name NAME` - -Specifies the name of the builder to be created or modified. If none is specified, one will be automatically generated. - -#### `--node NODE` - -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. - -#### `--platform PLATFORMS` - -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: -``` -docker buildx create --platform linux/amd64 -docker buildx create --platform linux/arm64,linux/arm/v8 -``` - -#### `--use` - -Automatically switches the current builder to the newly created one. Equivalent to running `docker buildx use $(docker buildx create ...)`. - -### `buildx use NAME` - -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. - -### `buildx inspect [NAME]` - -Shows information about the current or specified builder. - -Example: -``` -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 -``` - -#### `--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`). - -### `buildx ls` - -Lists all builder instances and the nodes for each instance - -Example: - -``` -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 `*`. - -### `buildx stop [NAME]` - -Stops the specified or current builder. This will not prevent buildx build to restart the builder. The implementation of stop depends on the driver. - -### `buildx rm [NAME]` - -Removes the specified or current builder. It is a no-op attempting to remove the default builder. - -### `buildx bake [OPTIONS] [TARGET...]` - -Bake is a high-level build command. - -Each specified target will run in parallel as part of the build. - -Options: - -| Flag | Description | -| --- | --- | -| -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) - -#### `-f, --file 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: -docker-compose.yml -docker-compose.yaml -docker-bake.json -docker-bake.override.json -docker-bake.hcl -docker-bake.override.hcl - -#### `--no-cache` - -Same as `build --no-cache`. Do not use cache when building the image. - -#### `--print` - -Prints the resulting options of the targets desired to be built, in a JSON format, without starting a build. - -``` -$ docker buildx bake -f docker-bake.hcl --print db -{ - "target": { - "db": { - "context": "./", - "dockerfile": "Dockerfile", - "tags": [ - "docker.io/tiborvass/db" - ] - } - } -} -``` - -#### `--progress` - -Same as `build --progress`. Set type of progress output (auto, plain, tty). Use plain to show container output (default "auto"). - -#### `--pull` - -Same as `build --pull`. - -#### `--set targetpattern.key[.subkey]=value` - -Override target configurations from command line. The pattern matching syntax is defined in https://golang.org/pkg/path/#Match. - -Example: -``` -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: - -``` -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 - -#### 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. - - - -Example of using interpolation to tag an image with the git sha: - -``` -$ cat <<'EOF' > docker-bake.hcl -variable "TAG" { - default = "latest" -} - -group "default" { - targets = ["webapp"] -} - -target "webapp" { - tags = ["docker.io/username/webapp:${TAG}"] -} -EOF - -$ docker buildx bake --print webapp -{ - "target": { - "webapp": { - "context": ".", - "dockerfile": "Dockerfile", - "tags": [ - "docker.io/username/webapp:latest" - ] - } - } -} - -$ TAG=$(git rev-parse --short HEAD) docker buildx bake --print webapp -{ - "target": { - "webapp": { - "context": ".", - "dockerfile": "Dockerfile", - "tags": [ - "docker.io/username/webapp:985e9e9" - ] - } - } -} -``` - - -A [set of generally useful functions](https://github.com/docker/buildx/blob/master/bake/hcl.go#L19-L65) provided by [go-cty](https://github.com/zclconf/go-cty/tree/master/cty/function/stdlib) are available for use in HCL files. In addition, [user defined functions](https://github.com/hashicorp/hcl/tree/hcl2/ext/userfunc) are also supported. - - - -Example of using the `add` function: - -``` -$ cat <<'EOF' > docker-bake.hcl -variable "TAG" { - default = "latest" -} - -group "default" { - targets = ["webapp"] -} - -target "webapp" { - args = { - buildno = "${add(123, 1)}" - } -} -EOF - -$ docker buildx bake --print webapp -{ - "target": { - "webapp": { - "context": ".", - "dockerfile": "Dockerfile", - "args": { - "buildno": "124" - } - } - } -} -``` - -Example of defining an `increment` function: - -``` -$ cat <<'EOF' > docker-bake.hcl -function "increment" { - params = [number] - result = number + 1 -} - -group "default" { - targets = ["webapp"] -} - -target "webapp" { - args = { - buildno = "${increment(123)}" - } -} -EOF - -$ docker buildx bake --print webapp -{ - "target": { - "webapp": { - "context": ".", - "dockerfile": "Dockerfile", - "args": { - "buildno": "124" - } - } - } -} -``` - -Example of only adding tags if a variable is not empty using an `notequal` function: - -``` -$ cat <<'EOF' > docker-bake.hcl -variable "TAG" {default="" } - -group "default" { - targets = [ - "webapp", - ] -} - -target "webapp" { - context="." - dockerfile="Dockerfile" - tags = [ - "my-image:latest", - notequal("",TAG) ? "my-image:${TAG}": "", - ] -} -EOF - -$ docker buildx bake --print webapp -{ - "target": { - "webapp": { - "context": ".", - "dockerfile": "Dockerfile", - "tags": [ - "my-image:latest" - ] - } - } -} -``` - - -### `buildx imagetools create [OPTIONS] [SOURCE] [SOURCE...]` - -Imagetools contains commands for working with manifest lists in the registry. These commands are useful for inspecting multi-platform build results. - -Create creates 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. - -Options: - -| Flag | Description | -| --- | --- | -| --append | Append to existing manifest -| --dry-run | Show final image instead of pushing -| -f, --file stringArray | Read source descriptor from file -| -t, --tag stringArray | Set reference for new image - -#### `--append` - -Append appends the new sources to an existing manifest list in the destination. - -#### `--dry-run` - -Do not push the image, just show it. - -#### `-f, --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` - -Name of the image to be created. - -Examples: - -``` -docker buildx imagetools create --dry-run alpine@sha256:5c40b3c27b9f13c873fefb2139765c56ce97fd50230f1f2d5c91e55dec171907 sha256:c4ba6347b0e4258ce6a6de2401619316f982b7bcc529f73d2a410d0097730204 - -docker buildx imagetools create -t tonistiigi/myapp -f image1 -f image2 -``` - - -### `buildx imagetools inspect NAME` - -Show details of image in the registry. - -Example: -``` -$ 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 - - ... -``` - -#### `--raw` - -Raw prints the original JSON bytes instead of the formatted output. - - # Setting buildx as default builder in Docker 19.03+ Running `docker buildx install` sets up `docker builder` command as an alias to `docker buildx`. This results in the ability to have `docker build` use the current buildx builder. diff --git a/docs/reference/buildx_bake.md b/docs/reference/buildx_bake.md new file mode 100644 index 00000000..d3a02178 --- /dev/null +++ b/docs/reference/buildx_bake.md @@ -0,0 +1,300 @@ +# `buildx bake [OPTIONS] [TARGET...]` + +Bake is a high-level build command. + +Each specified target will run in parallel as part of the build. + +Options: + +| Flag | Description | +| --- | --- | +| -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) + + +## Description + +Bake is a high-level build command. Each specified target will run in parallel +as part of the build. + + +### `-f, --file 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: + +- `docker-compose.yml` +- `docker-compose.yaml` +- `docker-bake.json` +- `docker-bake.override.json` +- `docker-bake.hcl` +- `docker-bake.override.hcl` + +### `--no-cache` + +Same as `build --no-cache`. Do not use cache when building the image. + +### `--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 +{ + "target": { + "db": { + "context": "./", + "dockerfile": "Dockerfile", + "tags": [ + "docker.io/tiborvass/db" + ] + } + } +} +``` + +### `--progress` + +Same as `build --progress`. Set type of progress output (auto, plain, tty). Use +plain to show container output (default "auto"). + +### `--pull` + +Same as `build --pull`. + +### `--set targetpattern.key[.subkey]=value` + +Override target configurations from command line. The pattern matching syntax is +defined in https://golang.org/pkg/path/#Match. + +Example: + +```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 + +### 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. + + +Example of using interpolation to tag an image with the git sha: + +```console +$ cat <<'EOF' > docker-bake.hcl +variable "TAG" { + default = "latest" +} + +group "default" { + targets = ["webapp"] +} + +target "webapp" { + tags = ["docker.io/username/webapp:${TAG}"] +} +EOF + +$ docker buildx bake --print webapp +{ + "target": { + "webapp": { + "context": ".", + "dockerfile": "Dockerfile", + "tags": [ + "docker.io/username/webapp:latest" + ] + } + } +} + +$ TAG=$(git rev-parse --short HEAD) docker buildx bake --print webapp +{ + "target": { + "webapp": { + "context": ".", + "dockerfile": "Dockerfile", + "tags": [ + "docker.io/username/webapp:985e9e9" + ] + } + } +} +``` + + +A [set of generally useful functions](https://github.com/docker/buildx/blob/master/bake/hcl.go#L19-L65) +provided by [go-cty](https://github.com/zclconf/go-cty/tree/master/cty/function/stdlib) +are available for use in HCL files. In addition, [user defined functions](https://github.com/hashicorp/hcl/tree/hcl2/ext/userfunc) +are also supported. + +Example of using the `add` function: + +```console +$ cat <<'EOF' > docker-bake.hcl +variable "TAG" { + default = "latest" +} + +group "default" { + targets = ["webapp"] +} + +target "webapp" { + args = { + buildno = "${add(123, 1)}" + } +} +EOF + +$ docker buildx bake --print webapp +{ + "target": { + "webapp": { + "context": ".", + "dockerfile": "Dockerfile", + "args": { + "buildno": "124" + } + } + } +} +``` + +Example of defining an `increment` function: + +```console +$ cat <<'EOF' > docker-bake.hcl +function "increment" { + params = [number] + result = number + 1 +} + +group "default" { + targets = ["webapp"] +} + +target "webapp" { + args = { + buildno = "${increment(123)}" + } +} +EOF + +$ docker buildx bake --print webapp +{ + "target": { + "webapp": { + "context": ".", + "dockerfile": "Dockerfile", + "args": { + "buildno": "124" + } + } + } +} +``` + +Example of only adding tags if a variable is not empty using an `notequal` +function: + +```console +$ cat <<'EOF' > docker-bake.hcl +variable "TAG" {default="" } + +group "default" { + targets = [ + "webapp", + ] +} + +target "webapp" { + context="." + dockerfile="Dockerfile" + tags = [ + "my-image:latest", + notequal("",TAG) ? "my-image:${TAG}": "", + ] +} +EOF + +$ docker buildx bake --print webapp +{ + "target": { + "webapp": { + "context": ".", + "dockerfile": "Dockerfile", + "tags": [ + "my-image:latest" + ] + } + } +} +``` diff --git a/docs/reference/buildx_build.md b/docs/reference/buildx_build.md new file mode 100644 index 00000000..fede860e --- /dev/null +++ b/docs/reference/buildx_build.md @@ -0,0 +1,237 @@ +# `buildx build [OPTIONS] PATH | URL | -` + +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. + +Options: + +| Flag | Description | +| --- | --- | +| --add-host [] | Add a custom host-to-IP mapping (host:ip) +| --allow [] | Allow extra privileged entitlement, e.g. network.host, security.insecure +| --build-arg [] | Set build-time variables +| --cache-from [] | External cache sources (eg. user/app:cache, type=local,src=path/to/dir) +| --cache-to [] | Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir) +| --file string | Name of the Dockerfile (Default is 'PATH/Dockerfile') +| --iidfile string | Write the image ID to the file +| --label [] | 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 +| --output [] | Output destination (format: type=local,dest=path) +| --platform [] | 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 [] | Secret file to expose to the build: id=mysecret,src=/local/secret +| --ssh [] | SSH agent socket or keys to expose to the build (format: default\|<id>[=<socket>\|<key>[,<key>]]) +| --tag [] | Name and optionally a tag in the 'name:tag' format +| --target string | Set the target build stage to build. + +## Description + +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](https://docs.docker.com/engine/reference/commandline/build/). In +here we’ll document a subset of the new flags. + +### `--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](https://docs.docker.com/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 . +``` + +### `-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` + +Shorthand for [`--output=type=registry`](#registry). Will automatically push the +build result to registry. + +### `--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. Supported types are `registry` and `local`. +The `registry` source can import cache from a cache manifest or (special) image +configuration on the registry. The `local` source can import cache from local +files previously exported with `--cache-to`. + +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 . +``` + +### `--cache-to=[NAME|type=TYPE[,KEY=VALUE]]` + +Export build cache to an external cache destination. Supported types are `registry`, +`local` and `inline`. Registry exports build cache to a cache manifest in the +registry, local exports cache to a local directory on the client and inline writes +the cache metadata into the image configuration. + +`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 . +``` + +### `--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 . +``` diff --git a/docs/reference/buildx_create.md b/docs/reference/buildx_create.md new file mode 100644 index 00000000..54501d7e --- /dev/null +++ b/docs/reference/buildx_create.md @@ -0,0 +1,141 @@ +# `buildx create [OPTIONS] [CONTEXT|ENDPOINT]` + +Options: + +| Flag | Description | +| --- | --- | +| --append | Append a node to builder instead of changing it +| --buildkitd-flags string | Flags for buildkitd daemon +| --config string | BuildKit config file +| --driver string | Driver to use (eg. docker-container) +| --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 + +## Description + +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. + +### `--append` + +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. + +Example: + +```console +$ docker buildx create mycontext1 +eager_beaver + +$ docker buildx create --name eager_beaver --append mycontext2 +eager_beaver +``` + +### `--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: + +```console +--buildkitd-flags '--debug --debugaddr 0.0.0.0:6666' +``` + +### `--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` + +Sets the builder driver to be used. There are two available drivers, each have +their own specificities. + +- `docker` - Uses the builder that is built into the docker daemon. With this + driver, the [`--load`](buildx_build.md#--load) flag is implied by default on + `buildx build`. However, building multi-platform images or exporting cache is + not currently supported. +- `docker-container` - Uses a buildkit container that will be spawned via docker. + With this driver, both building multi-platform images and exporting cache are + supported. However, images built will not automatically appear in `docker images` + (see [`build --load`](buildx_build.md#--load)). +- `kubernetes` - Uses a kubernetes pods. With this driver, you can spin up pods + with defined buildkit container image to build your images. + + +### `--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. + - `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" + +### `--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`. + +Example: + +```console +docker buildx create --name mybuilder --node mybuilder0 --leave +``` + +### `--name NAME` + +Specifies the name of the builder to be created or modified. If none is specified, +one will be automatically generated. + +### `--node NODE` + +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. + +### `--platform PLATFORMS` + +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: + +```console +docker buildx create --platform linux/amd64 +docker buildx create --platform linux/arm64,linux/arm/v8 +``` + +### `--use` + +Automatically switches the current builder to the newly created one. Equivalent +to running `docker buildx use $(docker buildx create ...)`. diff --git a/docs/reference/buildx_imagetools_create.md b/docs/reference/buildx_imagetools_create.md new file mode 100644 index 00000000..4131cee4 --- /dev/null +++ b/docs/reference/buildx_imagetools_create.md @@ -0,0 +1,45 @@ +# `buildx imagetools create [OPTIONS] [SOURCE] [SOURCE...]` + +Options: + +| Flag | Description | +| --- | --- | +| --append | Append to existing manifest +| --dry-run | Show final image instead of pushing +| -f, --file stringArray | Read source descriptor from file +| -t, --tag stringArray | Set reference for new image + +## Description + +Imagetools contains commands for working with manifest lists in the registry. +These commands are useful for inspecting multi-platform build results. + +Create creates 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. + +### `--append` + +Append appends the new sources to an existing manifest list in the destination. + +### `--dry-run` + +Do not push the image, just show it. + +### `-f, --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` + +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 +``` diff --git a/docs/reference/buildx_imagetools_inspect.md b/docs/reference/buildx_imagetools_inspect.md new file mode 100644 index 00000000..d57e482b --- /dev/null +++ b/docs/reference/buildx_imagetools_inspect.md @@ -0,0 +1,29 @@ +# `buildx imagetools inspect NAME` + +## Description + +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 + ... +``` + +### `--raw` + +Raw prints the original JSON bytes instead of the formatted output. diff --git a/docs/reference/buildx_inspect.md b/docs/reference/buildx_inspect.md new file mode 100644 index 00000000..e10d6f3c --- /dev/null +++ b/docs/reference/buildx_inspect.md @@ -0,0 +1,33 @@ +# `buildx inspect [NAME]` + +## Description + +Shows information about the current or specified builder. + +Example: + +```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 +``` + +### `--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`). diff --git a/docs/reference/buildx_ls.md b/docs/reference/buildx_ls.md new file mode 100644 index 00000000..1c080e70 --- /dev/null +++ b/docs/reference/buildx_ls.md @@ -0,0 +1,21 @@ +# `buildx ls` + +## Description + +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 `*`. diff --git a/docs/reference/buildx_rm.md b/docs/reference/buildx_rm.md new file mode 100644 index 00000000..ebb6d76c --- /dev/null +++ b/docs/reference/buildx_rm.md @@ -0,0 +1,6 @@ +# `buildx rm [NAME]` + +## Description + +Removes the specified or current builder. It is a no-op attempting to remove the +default builder. diff --git a/docs/reference/buildx_stop.md b/docs/reference/buildx_stop.md new file mode 100644 index 00000000..e6c11056 --- /dev/null +++ b/docs/reference/buildx_stop.md @@ -0,0 +1,6 @@ +# `buildx stop [NAME]` + +## Description + +Stops the specified or current builder. This will not prevent buildx build to +restart the builder. The implementation of stop depends on the driver. diff --git a/docs/reference/buildx_use.md b/docs/reference/buildx_use.md new file mode 100644 index 00000000..985c4280 --- /dev/null +++ b/docs/reference/buildx_use.md @@ -0,0 +1,7 @@ +# `buildx use NAME` + +## Description + +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. From 1a8af33ff6aa3fb8d9b6ef8d07d1f7dd33b7b719 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 13 Jan 2021 15:31:05 +0100 Subject: [PATCH 2/9] docs: standardize format for usage Use the usage output of `--help` for each subcommand, to make sure all flags/options are included on the page, and to make it easier to keep docs in sync. Note that the usage output is only used when reading these docs on GitHub; docs.docker.com only consumes the "description" and "example" sections (when present), and generates flag information and usage output from source Signed-off-by: Sebastiaan van Stijn --- docs/reference/buildx_bake.md | 32 ++++++------ docs/reference/buildx_build.md | 56 +++++++++++---------- docs/reference/buildx_create.md | 32 ++++++------ docs/reference/buildx_imagetools_create.md | 20 +++++--- docs/reference/buildx_imagetools_inspect.md | 12 ++++- docs/reference/buildx_inspect.md | 12 ++++- docs/reference/buildx_ls.md | 11 +++- docs/reference/buildx_rm.md | 11 +++- docs/reference/buildx_stop.md | 11 +++- docs/reference/buildx_use.md | 13 ++++- 10 files changed, 141 insertions(+), 69 deletions(-) diff --git a/docs/reference/buildx_bake.md b/docs/reference/buildx_bake.md index d3a02178..666dc180 100644 --- a/docs/reference/buildx_bake.md +++ b/docs/reference/buildx_bake.md @@ -1,22 +1,24 @@ -# `buildx bake [OPTIONS] [TARGET...]` +# buildx bake -Bake is a high-level build command. - -Each specified target will run in parallel as part of the build. +``` +Usage: docker buildx bake [OPTIONS] [TARGET...] -Options: +Build from a file -| Flag | Description | -| --- | --- | -| -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) +Aliases: + bake, f +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) +``` ## Description diff --git a/docs/reference/buildx_build.md b/docs/reference/buildx_build.md index fede860e..636c3a60 100644 --- a/docs/reference/buildx_build.md +++ b/docs/reference/buildx_build.md @@ -1,32 +1,36 @@ -# `buildx build [OPTIONS] PATH | URL | -` +# buildx build -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. +``` +Usage: docker buildx build [OPTIONS] PATH | URL | - -Options: +Start a build -| Flag | Description | -| --- | --- | -| --add-host [] | Add a custom host-to-IP mapping (host:ip) -| --allow [] | Allow extra privileged entitlement, e.g. network.host, security.insecure -| --build-arg [] | Set build-time variables -| --cache-from [] | External cache sources (eg. user/app:cache, type=local,src=path/to/dir) -| --cache-to [] | Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir) -| --file string | Name of the Dockerfile (Default is 'PATH/Dockerfile') -| --iidfile string | Write the image ID to the file -| --label [] | 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 -| --output [] | Output destination (format: type=local,dest=path) -| --platform [] | 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 [] | Secret file to expose to the build: id=mysecret,src=/local/secret -| --ssh [] | SSH agent socket or keys to expose to the build (format: default\|<id>[=<socket>\|<key>[,<key>]]) -| --tag [] | Name and optionally a tag in the 'name:tag' format -| --target string | Set the target build stage to build. +Aliases: + build, b + +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|[=|[,]]) + -t, --tag stringArray Name and optionally a tag in the 'name:tag' format + --target string Set the target build stage to build. +``` ## Description diff --git a/docs/reference/buildx_create.md b/docs/reference/buildx_create.md index 54501d7e..20eecd2f 100644 --- a/docs/reference/buildx_create.md +++ b/docs/reference/buildx_create.md @@ -1,19 +1,23 @@ -# `buildx create [OPTIONS] [CONTEXT|ENDPOINT]` +# buildx create -Options: +``` +Usage: docker buildx create [OPTIONS] [CONTEXT|ENDPOINT] + +Create a new builder instance -| Flag | Description | -| --- | --- | -| --append | Append a node to builder instead of changing it -| --buildkitd-flags string | Flags for buildkitd daemon -| --config string | BuildKit config file -| --driver string | Driver to use (eg. docker-container) -| --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: + --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 +``` ## Description diff --git a/docs/reference/buildx_imagetools_create.md b/docs/reference/buildx_imagetools_create.md index 4131cee4..1628b097 100644 --- a/docs/reference/buildx_imagetools_create.md +++ b/docs/reference/buildx_imagetools_create.md @@ -1,13 +1,17 @@ -# `buildx imagetools create [OPTIONS] [SOURCE] [SOURCE...]` +# buildx imagetools create -Options: +``` +Usage: docker buildx imagetools create [OPTIONS] [SOURCE] [SOURCE...] + +Create a new image based on source images -| Flag | Description | -| --- | --- | -| --append | Append to existing manifest -| --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: + --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 +``` ## Description diff --git a/docs/reference/buildx_imagetools_inspect.md b/docs/reference/buildx_imagetools_inspect.md index d57e482b..b9b4f696 100644 --- a/docs/reference/buildx_imagetools_inspect.md +++ b/docs/reference/buildx_imagetools_inspect.md @@ -1,4 +1,14 @@ -# `buildx imagetools inspect NAME` +# buildx imagetools inspect + +``` +Usage: docker buildx imagetools inspect [OPTIONS] NAME + +Show details of image in the registry + +Options: + --builder string Override the configured builder instance + --raw Show original JSON manifest +``` ## Description diff --git a/docs/reference/buildx_inspect.md b/docs/reference/buildx_inspect.md index e10d6f3c..c7002c7b 100644 --- a/docs/reference/buildx_inspect.md +++ b/docs/reference/buildx_inspect.md @@ -1,4 +1,14 @@ -# `buildx inspect [NAME]` +# buildx inspect + +``` +Usage: docker buildx inspect [NAME] + +Inspect current builder instance + +Options: + --bootstrap Ensure builder has booted before inspecting + --builder string Override the configured builder instance +``` ## Description diff --git a/docs/reference/buildx_ls.md b/docs/reference/buildx_ls.md index 1c080e70..7d4072e5 100644 --- a/docs/reference/buildx_ls.md +++ b/docs/reference/buildx_ls.md @@ -1,4 +1,13 @@ -# `buildx ls` +# buildx ls + +``` +Usage: docker buildx ls + +List builder instances + +Options: + --builder string Override the configured builder instance +``` ## Description diff --git a/docs/reference/buildx_rm.md b/docs/reference/buildx_rm.md index ebb6d76c..41524e1b 100644 --- a/docs/reference/buildx_rm.md +++ b/docs/reference/buildx_rm.md @@ -1,4 +1,13 @@ -# `buildx rm [NAME]` +# buildx rm + +``` +Usage: docker buildx rm [NAME] + +Remove a builder instance + +Options: + --builder string Override the configured builder instance +``` ## Description diff --git a/docs/reference/buildx_stop.md b/docs/reference/buildx_stop.md index e6c11056..e703936e 100644 --- a/docs/reference/buildx_stop.md +++ b/docs/reference/buildx_stop.md @@ -1,4 +1,13 @@ -# `buildx stop [NAME]` +# buildx stop + +``` +Usage: docker buildx stop [NAME] + +Stop builder instance + +Options: + --builder string Override the configured builder instance +``` ## Description diff --git a/docs/reference/buildx_use.md b/docs/reference/buildx_use.md index 985c4280..475ac19f 100644 --- a/docs/reference/buildx_use.md +++ b/docs/reference/buildx_use.md @@ -1,4 +1,15 @@ -# `buildx use NAME` +# buildx use + +``` +Usage: docker buildx use [OPTIONS] NAME + +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 +``` ## Description From 87ec3af5bb9d5d2b7aa33bb4ccda093bba738721 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 13 Jan 2021 15:47:03 +0100 Subject: [PATCH 3/9] docs: add stubs for all commands Signed-off-by: Sebastiaan van Stijn --- docs/reference/buildx.md | 32 +++++++++++++++++++++++++++++ docs/reference/buildx_du.md | 16 +++++++++++++++ docs/reference/buildx_imagetools.md | 19 +++++++++++++++++ docs/reference/buildx_prune.md | 19 +++++++++++++++++ docs/reference/buildx_version.md | 24 ++++++++++++++++++++++ 5 files changed, 110 insertions(+) create mode 100644 docs/reference/buildx.md create mode 100644 docs/reference/buildx_du.md create mode 100644 docs/reference/buildx_imagetools.md create mode 100644 docs/reference/buildx_prune.md create mode 100644 docs/reference/buildx_version.md diff --git a/docs/reference/buildx.md b/docs/reference/buildx.md new file mode 100644 index 00000000..5e00aa01 --- /dev/null +++ b/docs/reference/buildx.md @@ -0,0 +1,32 @@ +# 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. +``` + +## Description + +Build with BuildKit diff --git a/docs/reference/buildx_du.md b/docs/reference/buildx_du.md new file mode 100644 index 00000000..a928710e --- /dev/null +++ b/docs/reference/buildx_du.md @@ -0,0 +1,16 @@ +# 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 +``` + +## Description + +Disk usage diff --git a/docs/reference/buildx_imagetools.md b/docs/reference/buildx_imagetools.md new file mode 100644 index 00000000..59758671 --- /dev/null +++ b/docs/reference/buildx_imagetools.md @@ -0,0 +1,19 @@ +# buildx imagetools + +``` +Usage: docker buildx imagetools [OPTIONS] COMMAND + +Commands to work on images in registry + +Options: + --builder string Override the configured builder instance + +Commands: + create Create a new image based on source images + inspect Show details of image in the registry +``` + +## Description + +Imagetools contains commands for working with manifest lists in the registry. +These commands are useful for inspecting multi-platform build results. diff --git a/docs/reference/buildx_prune.md b/docs/reference/buildx_prune.md new file mode 100644 index 00000000..5a63bfda --- /dev/null +++ b/docs/reference/buildx_prune.md @@ -0,0 +1,19 @@ +# 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 +``` + +## Description + +Remove build cache diff --git a/docs/reference/buildx_version.md b/docs/reference/buildx_version.md new file mode 100644 index 00000000..a5f5ecb7 --- /dev/null +++ b/docs/reference/buildx_version.md @@ -0,0 +1,24 @@ +# buildx version + +``` +Usage: docker buildx version + +Show buildx version information + +Options: + --builder string Override the configured builder instance +``` + +## Description + +Show buildx version information + +## Examples + +### View version information + + +```console +$ docker buildx version +github.com/docker/buildx v0.5.1-docker 11057da37336192bfc57d81e02359ba7ba848e4a +``` From 442d38080ebfc2d91c63f08bff2bd6c1bb1d2e7e Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 13 Jan 2021 16:37:15 +0100 Subject: [PATCH 4/9] docs: use "examples" section, and rephrase headings 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 --- docs/reference/buildx_bake.md | 76 +++++++++++++++++--- docs/reference/buildx_build.md | 36 ++++++++-- docs/reference/buildx_create.md | 84 +++++++++++++++------- docs/reference/buildx_imagetools_create.md | 25 +++++-- docs/reference/buildx_inspect.md | 22 ++++-- 5 files changed, 187 insertions(+), 56 deletions(-) diff --git a/docs/reference/buildx_bake.md b/docs/reference/buildx_bake.md index 666dc180..1f4a5f5b 100644 --- a/docs/reference/buildx_bake.md +++ b/docs/reference/buildx_bake.md @@ -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. diff --git a/docs/reference/buildx_build.md b/docs/reference/buildx_build.md index 636c3a60..4862c94a 100644 --- a/docs/reference/buildx_build.md +++ b/docs/reference/buildx_build.md @@ -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: diff --git a/docs/reference/buildx_create.md b/docs/reference/buildx_create.md index 20eecd2f..bd784d1b 100644 --- a/docs/reference/buildx_create.md +++ b/docs/reference/buildx_create.md @@ -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 +``` + +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 +``` -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 `--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 ...)`. diff --git a/docs/reference/buildx_imagetools_create.md b/docs/reference/buildx_imagetools_create.md index 1628b097..1fc13157 100644 --- a/docs/reference/buildx_imagetools_create.md +++ b/docs/reference/buildx_imagetools_create.md @@ -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) + +``` +-t IMAGE or --tag IMAGE +``` -Name of the image to be created. +Use the `-t` or `--tag` flag to set the name of the image to be created. Examples: diff --git a/docs/reference/buildx_inspect.md b/docs/reference/buildx_inspect.md index c7002c7b..d6fe909c 100644 --- a/docs/reference/buildx_inspect.md +++ b/docs/reference/buildx_inspect.md @@ -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`). From 17d4106e1bdd47452a99c47f76fe33103fb48c80 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 13 Jan 2021 17:18:10 +0100 Subject: [PATCH 5/9] docs: fix markdown formatting and highlighting Signed-off-by: Sebastiaan van Stijn --- docs/reference/buildx_bake.md | 19 +++++---- docs/reference/buildx_build.md | 46 ++++++++++----------- docs/reference/buildx_create.md | 16 +++---- docs/reference/buildx_imagetools_create.md | 6 +-- docs/reference/buildx_imagetools_inspect.md | 5 ++- docs/reference/buildx_ls.md | 2 +- 6 files changed, 48 insertions(+), 46 deletions(-) diff --git a/docs/reference/buildx_bake.md b/docs/reference/buildx_bake.md index 1f4a5f5b..71e9e1b0 100644 --- a/docs/reference/buildx_bake.md +++ b/docs/reference/buildx_bake.md @@ -135,14 +135,14 @@ Same as `build --pull`. Override target configurations from command line. The pattern matching syntax is defined in https://golang.org/pkg/path/#Match. -Example: +**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' +$ 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: @@ -170,7 +170,7 @@ Note: Design of bake command is work in progress, the user experience may change based on feedback. -Example HCL definition: +**Example HCL definition** ```hcl group "default" { @@ -194,8 +194,9 @@ target "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 + +`args`, `cache-from`, `cache-to`, `context`, `dockerfile`, `inherits`, `labels`, +`no-cache`, `output`, `platform`, `pull`, `secrets`, `ssh`, `tags`, `target` ### HCL variables and functions diff --git a/docs/reference/buildx_build.md b/docs/reference/buildx_build.md index 4862c94a..571edad0 100644 --- a/docs/reference/buildx_build.md +++ b/docs/reference/buildx_build.md @@ -76,12 +76,12 @@ 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: +**Examples** ```console -docker buildx build --platform=linux/arm64 . -docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 . -docker buildx build --platform=darwin . +$ docker buildx build --platform=linux/arm64 . +$ 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) @@ -102,15 +102,15 @@ 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: +**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 +$ 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: @@ -201,13 +201,13 @@ 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: +**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=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 . ``` ### Export build cache to an external cache destination (--cache-to) @@ -231,18 +231,18 @@ Attribute key: exports layers already in the final build stage, “max” exports layers for all stages. Metadata is always exported for the whole build. -Examples: +**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=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 . ``` ### Allow extra privileged entitlement (--allow) -```console +``` --allow=ENTITLEMENT ``` @@ -255,7 +255,7 @@ Allow extra privileged entitlement. List of entitlements: 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: +**Examples** ```console $ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure' diff --git a/docs/reference/buildx_create.md b/docs/reference/buildx_create.md index bd784d1b..3504ddb3 100644 --- a/docs/reference/buildx_create.md +++ b/docs/reference/buildx_create.md @@ -39,7 +39,7 @@ 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: +**Examples** ```console $ docker buildx create mycontext1 @@ -59,9 +59,9 @@ 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: +**Example** -```console +``` --buildkitd-flags '--debug --debugaddr 0.0.0.0:6666' ``` @@ -127,10 +127,10 @@ 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: +**Examples** ```console -docker buildx create --name mybuilder --node mybuilder0 --leave +$ docker buildx create --name mybuilder --node mybuilder0 --leave ``` ### Specify the name of the builder (--name) @@ -164,11 +164,11 @@ 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: +**Examples** ```console -docker buildx create --platform linux/amd64 -docker buildx create --platform linux/arm64,linux/arm/v8 +$ docker buildx create --platform linux/amd64 +$ docker buildx create --platform linux/arm64,linux/arm/v8 ``` ### Automatically switch to the newly created builder diff --git a/docs/reference/buildx_imagetools_create.md b/docs/reference/buildx_imagetools_create.md index 1fc13157..52cbe42a 100644 --- a/docs/reference/buildx_imagetools_create.md +++ b/docs/reference/buildx_imagetools_create.md @@ -51,10 +51,10 @@ or a JSON of OCI descriptor object. Use the `-t` or `--tag` flag to set the name of the image to be created. -Examples: +**Examples** ```console -docker buildx imagetools create --dry-run alpine@sha256:5c40b3c27b9f13c873fefb2139765c56ce97fd50230f1f2d5c91e55dec171907 sha256:c4ba6347b0e4258ce6a6de2401619316f982b7bcc529f73d2a410d0097730204 +$ docker buildx imagetools create --dry-run alpine@sha256:5c40b3c27b9f13c873fefb2139765c56ce97fd50230f1f2d5c91e55dec171907 sha256:c4ba6347b0e4258ce6a6de2401619316f982b7bcc529f73d2a410d0097730204 -docker buildx imagetools create -t tonistiigi/myapp -f image1 -f image2 +$ docker buildx imagetools create -t tonistiigi/myapp -f image1 -f image2 ``` diff --git a/docs/reference/buildx_imagetools_inspect.md b/docs/reference/buildx_imagetools_inspect.md index b9b4f696..44cae5d8 100644 --- a/docs/reference/buildx_imagetools_inspect.md +++ b/docs/reference/buildx_imagetools_inspect.md @@ -34,6 +34,7 @@ Manifests: ... ``` -### `--raw` +### Show original, unformatted JSON manifest (--raw) -Raw prints the original JSON bytes instead of the formatted output. +Use the `--raw` option to print the original JSON bytes instead of the formatted +output. diff --git a/docs/reference/buildx_ls.md b/docs/reference/buildx_ls.md index 7d4072e5..bb868792 100644 --- a/docs/reference/buildx_ls.md +++ b/docs/reference/buildx_ls.md @@ -13,7 +13,7 @@ Options: Lists all builder instances and the nodes for each instance -Example: +**Example** ```console $ docker buildx ls From ca0f5dabea7f822fccd562b2dcd5caebb95a7bfa Mon Sep 17 00:00:00 2001 From: Tonis Tiigi Date: Mon, 22 Mar 2021 23:43:51 -0700 Subject: [PATCH 6/9] docs: add md generation Signed-off-by: Tonis Tiigi --- docs/docsgen/generate.go | 192 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 docs/docsgen/generate.go diff --git a/docs/docsgen/generate.go b/docs/docsgen/generate.go new file mode 100644 index 00000000..eb09c076 --- /dev/null +++ b/docs/docsgen/generate.go @@ -0,0 +1,192 @@ +package main + +import ( + "fmt" + "io/ioutil" + "log" + "os" + "path/filepath" + "strings" + + "github.com/docker/buildx/commands" + "github.com/docker/cli/cli/command" + "github.com/pkg/errors" + "github.com/spf13/cobra" + "github.com/spf13/pflag" +) + +const descriptionSourcePath = "docs/reference/" + +func generateDocs(opts *options) error { + dockerCLI, err := command.NewDockerCli() + if err != nil { + return err + } + cmd := &cobra.Command{ + Use: "docker [OPTIONS] COMMAND [ARG...]", + Short: "The base command for the Docker CLI.", + } + cmd.AddCommand(commands.NewRootCmd("buildx", true, dockerCLI)) + return genCmd(cmd, opts.target) +} + +func getMDFilename(cmd *cobra.Command) string { + name := cmd.CommandPath() + if i := strings.Index(name, " "); i >= 0 { + name = name[i+1:] + } + return strings.ReplaceAll(name, " ", "_") + ".md" +} + +func genCmd(cmd *cobra.Command, dir string) error { + for _, c := range cmd.Commands() { + if err := genCmd(c, dir); err != nil { + return err + } + } + if !cmd.HasParent() { + return nil + } + + mdFile := getMDFilename(cmd) + fullPath := filepath.Join(dir, mdFile) + + content, err := ioutil.ReadFile(fullPath) + if err != nil { + if errors.Is(err, os.ErrNotExist) { + return errors.Wrapf(err, "%s does not exist", mdFile) + } + } + + cs := string(content) + + markerStart := "" + markerEnd := "" + + start := strings.Index(cs, markerStart) + end := strings.Index(cs, markerEnd) + + if start == -1 { + return errors.Errorf("no start marker in %s", mdFile) + } + if end == -1 { + return errors.Errorf("no end marker in %s", mdFile) + } + + out, err := cmdOutput(cmd, cs) + if err != nil { + return err + } + cont := cs[:start] + markerStart + "\n" + out + "\n" + cs[end:] + + fi, err := os.Stat(fullPath) + if err != nil { + return err + } + if err := ioutil.WriteFile(fullPath, []byte(cont), fi.Mode()); err != nil { + return errors.Wrapf(err, "failed to write %s", fullPath) + } + log.Printf("updated %s", fullPath) + return nil +} + +func makeLink(txt, link string) string { + return "[" + txt + "](#" + link + ")" +} + +func cmdOutput(cmd *cobra.Command, old string) (string, error) { + b := &strings.Builder{} + + desc := cmd.Short + if cmd.Long != "" { + desc = cmd.Long + } + if desc != "" { + fmt.Fprintf(b, "%s\n\n", desc) + } + + if len(cmd.Aliases) != 0 { + fmt.Fprintf(b, "### Aliases\n\n`%s`", cmd.Name()) + for _, a := range cmd.Aliases { + fmt.Fprintf(b, ", `%s`", a) + } + fmt.Fprint(b, "\n\n") + } + + if len(cmd.Commands()) != 0 { + fmt.Fprint(b, "### Subcommands\n\n") + fmt.Fprint(b, "| Name | Description |\n") + fmt.Fprint(b, "| --- | --- |\n") + for _, c := range cmd.Commands() { + fmt.Fprintf(b, "| [`%s`](%s) | %s |\n", c.Name(), getMDFilename(c), c.Short) + } + fmt.Fprint(b, "\n\n") + } + + hasFlags := cmd.Flags().HasAvailableFlags() + + cmd.Flags().AddFlagSet(cmd.InheritedFlags()) + + if hasFlags { + fmt.Fprint(b, "### Options\n\n") + fmt.Fprint(b, "| Name | Description |\n") + fmt.Fprint(b, "| --- | --- |\n") + + cmd.Flags().VisitAll(func(f *pflag.Flag) { + if f.Hidden { + return + } + isLink := strings.Contains(old, "") + fmt.Fprint(b, "| ") + if f.Shorthand != "" { + name := "`-" + f.Shorthand + "`" + if isLink { + name = makeLink(name, f.Name) + } + fmt.Fprintf(b, "%s, ", name) + } + name := "`--" + f.Name + if f.Value.Type() != "bool" { + name += " " + f.Value.Type() + } + name += "`" + if isLink { + name = makeLink(name, f.Name) + } + fmt.Fprintf(b, "%s | %s |\n", name, f.Usage) + }) + fmt.Fprintln(b, "") + } + + return b.String(), nil +} + +type options struct { + target string +} + +func parseArgs() (*options, error) { + opts := &options{} + flags := pflag.NewFlagSet(os.Args[0], pflag.ContinueOnError) + flags.StringVar(&opts.target, "target", descriptionSourcePath, "Docs directory") + err := flags.Parse(os.Args[1:]) + return opts, err +} + +func main() { + if err := run(); err != nil { + log.Printf("error: %+v", err) + os.Exit(1) + } +} + +func run() error { + opts, err := parseArgs() + if err != nil { + return err + } + if err := generateDocs(opts); err != nil { + return err + } + return nil +} From c46407b2d36d479a4b08c3fc15faa387b4ff05be Mon Sep 17 00:00:00 2001 From: Tonis Tiigi Date: Mon, 22 Mar 2021 23:31:22 -0700 Subject: [PATCH 7/9] docs: reference docs updates Signed-off-by: Tonis Tiigi Signed-off-by: Sebastiaan van Stijn --- docs/reference/buildx.md | 43 ++++++------ docs/reference/buildx_bake.md | 50 ++++++++------ docs/reference/buildx_build.md | 76 ++++++++++++--------- docs/reference/buildx_create.md | 56 ++++++++------- docs/reference/buildx_du.md | 19 +++--- docs/reference/buildx_imagetools.md | 19 ++++-- docs/reference/buildx_imagetools_create.md | 31 +++++---- docs/reference/buildx_imagetools_inspect.md | 19 ++++-- docs/reference/buildx_inspect.md | 19 ++++-- docs/reference/buildx_install.md | 11 +++ docs/reference/buildx_ls.md | 9 +-- docs/reference/buildx_prune.md | 28 ++++---- docs/reference/buildx_rm.md | 9 +-- docs/reference/buildx_stop.md | 9 +-- docs/reference/buildx_uninstall.md | 11 +++ docs/reference/buildx_use.md | 19 ++++-- docs/reference/buildx_version.md | 13 ++-- 17 files changed, 263 insertions(+), 178 deletions(-) create mode 100644 docs/reference/buildx_install.md create mode 100644 docs/reference/buildx_uninstall.md diff --git a/docs/reference/buildx.md b/docs/reference/buildx.md index 5e00aa01..842f2538 100644 --- a/docs/reference/buildx.md +++ b/docs/reference/buildx.md @@ -1,32 +1,31 @@ # buildx ``` -Usage: docker buildx [OPTIONS] COMMAND +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 +### Subcommands -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 +| 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 | -Run 'docker buildx COMMAND --help' for more information on a command. -``` -## Description -Build with BuildKit + diff --git a/docs/reference/buildx_bake.md b/docs/reference/buildx_bake.md index 71e9e1b0..55821153 100644 --- a/docs/reference/buildx_bake.md +++ b/docs/reference/buildx_bake.md @@ -1,24 +1,32 @@ # buildx bake ``` -Usage: docker buildx bake [OPTIONS] [TARGET...] +docker buildx bake [OPTIONS] [TARGET...] +``` + Build from a file -Aliases: - bake, f - -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) -``` +### Aliases + +`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) | + + + ## Description @@ -27,7 +35,7 @@ as part of the build. ## Examples -### Specify a build definition file (-f, --file) +### 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) +### 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) +### 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) +### 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) +### Always attempt to pull a newer version of the image (--pull) Same as `build --pull`. -### Override target configurations from command line (--set) +### Override target configurations from command line (--set) ``` --set targetpattern.key[.subkey]=value diff --git a/docs/reference/buildx_build.md b/docs/reference/buildx_build.md index 571edad0..60d96ac7 100644 --- a/docs/reference/buildx_build.md +++ b/docs/reference/buildx_build.md @@ -1,36 +1,44 @@ # buildx build ``` -Usage: docker buildx build [OPTIONS] PATH | URL | - +docker buildx build [OPTIONS] PATH | URL | - +``` + Start a build -Aliases: - build, b - -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|[=|[,]]) - -t, --tag stringArray Name and optionally a tag in the 'name:tag' format - --target string Set the target build stage to build. -``` +### Aliases + +`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|[=|[,]]) | +| `-t`, `--tag stringArray` | Name and optionally a tag in the 'name:tag' format | +| `--target string` | Set the target build stage to build. | + + + ## Description @@ -43,7 +51,7 @@ here we’ll document a subset of the new flags. ## Examples -### Set the target platforms for the build (--platform) +### 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) +### 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) +### 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) +### 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) +### 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) +### 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) +### Allow extra privileged entitlement (--allow) ``` --allow=ENTITLEMENT diff --git a/docs/reference/buildx_create.md b/docs/reference/buildx_create.md index 3504ddb3..018800dc 100644 --- a/docs/reference/buildx_create.md +++ b/docs/reference/buildx_create.md @@ -1,23 +1,31 @@ # buildx create ``` -Usage: docker buildx create [OPTIONS] [CONTEXT|ENDPOINT] +docker buildx create [OPTIONS] [CONTEXT|ENDPOINT] +``` + 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 | + + + + ## Description @@ -33,7 +41,7 @@ docker contexts also get the default builder instance. ## Examples -### Append a new node to an existing builder (--append) +### 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) +### 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) +### 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) +### 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) +### 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) +### 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) +### 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) +### 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 +### 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 +### 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 ...)`. diff --git a/docs/reference/buildx_du.md b/docs/reference/buildx_du.md index a928710e..15da02b4 100644 --- a/docs/reference/buildx_du.md +++ b/docs/reference/buildx_du.md @@ -1,16 +1,19 @@ # buildx du ``` -Usage: docker buildx du +docker buildx du +``` + Disk usage -Options: - --builder string Override the configured builder instance - --filter filter Provide filter values - --verbose Provide a more verbose output -``` +### Options -## Description +| Name | Description | +| --- | --- | +| `--builder string` | Override the configured builder instance | +| `--filter filter` | Provide filter values | +| `--verbose` | Provide a more verbose output | -Disk usage + + \ No newline at end of file diff --git a/docs/reference/buildx_imagetools.md b/docs/reference/buildx_imagetools.md index 59758671..3d6b42fb 100644 --- a/docs/reference/buildx_imagetools.md +++ b/docs/reference/buildx_imagetools.md @@ -1,17 +1,22 @@ # buildx imagetools ``` -Usage: docker buildx imagetools [OPTIONS] COMMAND +docker buildx imagetools [OPTIONS] COMMAND +``` + 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 | + + + + ## Description diff --git a/docs/reference/buildx_imagetools_create.md b/docs/reference/buildx_imagetools_create.md index 52cbe42a..5a71ad74 100644 --- a/docs/reference/buildx_imagetools_create.md +++ b/docs/reference/buildx_imagetools_create.md @@ -1,17 +1,24 @@ # buildx imagetools create ``` -Usage: docker buildx imagetools create [OPTIONS] [SOURCE] [SOURCE...] +docker buildx imagetools create [OPTIONS] [SOURCE] [SOURCE...] +``` + 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 | + + + ## Description @@ -25,16 +32,16 @@ one source is specified create performs a carbon copy. ## Examples -### Append new sources to an existing manifest list (--append) +### 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) +### 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) +### 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) +### Set reference for new image (-t, --tag) ``` -t IMAGE or --tag IMAGE diff --git a/docs/reference/buildx_imagetools_inspect.md b/docs/reference/buildx_imagetools_inspect.md index 44cae5d8..e1af7a67 100644 --- a/docs/reference/buildx_imagetools_inspect.md +++ b/docs/reference/buildx_imagetools_inspect.md @@ -1,14 +1,21 @@ # buildx imagetools inspect ``` -Usage: docker buildx imagetools inspect [OPTIONS] NAME +docker buildx imagetools inspect [OPTIONS] NAME +``` + 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 | + + + ## Description @@ -34,7 +41,7 @@ Manifests: ... ``` -### Show original, unformatted JSON manifest (--raw) +### Show original, unformatted JSON manifest (--raw) Use the `--raw` option to print the original JSON bytes instead of the formatted output. diff --git a/docs/reference/buildx_inspect.md b/docs/reference/buildx_inspect.md index d6fe909c..764a4706 100644 --- a/docs/reference/buildx_inspect.md +++ b/docs/reference/buildx_inspect.md @@ -1,14 +1,21 @@ # buildx inspect ``` -Usage: docker buildx inspect [NAME] +docker buildx inspect [NAME] +``` + 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 | + + + ## 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) +### 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 diff --git a/docs/reference/buildx_install.md b/docs/reference/buildx_install.md new file mode 100644 index 00000000..4f8f370d --- /dev/null +++ b/docs/reference/buildx_install.md @@ -0,0 +1,11 @@ +# buildx install + +``` +docker buildx install +``` + + +Install buildx as a 'docker builder' alias + + + diff --git a/docs/reference/buildx_ls.md b/docs/reference/buildx_ls.md index bb868792..75dbaf8b 100644 --- a/docs/reference/buildx_ls.md +++ b/docs/reference/buildx_ls.md @@ -1,13 +1,14 @@ # buildx ls ``` -Usage: docker buildx ls +docker buildx ls +``` + List builder instances -Options: - --builder string Override the configured builder instance -``` + + ## Description diff --git a/docs/reference/buildx_prune.md b/docs/reference/buildx_prune.md index 5a63bfda..4ea3054c 100644 --- a/docs/reference/buildx_prune.md +++ b/docs/reference/buildx_prune.md @@ -1,19 +1,23 @@ # buildx prune ``` -Usage: docker buildx prune +docker buildx prune +``` -Remove build cache + +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 | -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 -``` -## Description + -Remove build cache diff --git a/docs/reference/buildx_rm.md b/docs/reference/buildx_rm.md index 41524e1b..12456b30 100644 --- a/docs/reference/buildx_rm.md +++ b/docs/reference/buildx_rm.md @@ -1,13 +1,14 @@ # buildx rm ``` -Usage: docker buildx rm [NAME] +docker buildx rm [NAME] +``` + Remove a builder instance -Options: - --builder string Override the configured builder instance -``` + + ## Description diff --git a/docs/reference/buildx_stop.md b/docs/reference/buildx_stop.md index e703936e..23db3040 100644 --- a/docs/reference/buildx_stop.md +++ b/docs/reference/buildx_stop.md @@ -1,13 +1,14 @@ # buildx stop ``` -Usage: docker buildx stop [NAME] +docker buildx stop [NAME] +``` + Stop builder instance -Options: - --builder string Override the configured builder instance -``` + + ## Description diff --git a/docs/reference/buildx_uninstall.md b/docs/reference/buildx_uninstall.md new file mode 100644 index 00000000..524762e3 --- /dev/null +++ b/docs/reference/buildx_uninstall.md @@ -0,0 +1,11 @@ +# buildx uninstall + +``` +docker buildx uninstall +``` + + +Uninstall the 'docker builder' alias + + + diff --git a/docs/reference/buildx_use.md b/docs/reference/buildx_use.md index 475ac19f..541016ed 100644 --- a/docs/reference/buildx_use.md +++ b/docs/reference/buildx_use.md @@ -1,15 +1,22 @@ # buildx use ``` -Usage: docker buildx use [OPTIONS] NAME +docker buildx use [OPTIONS] NAME +``` + 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 | + + + ## Description diff --git a/docs/reference/buildx_version.md b/docs/reference/buildx_version.md index a5f5ecb7..4493c9ff 100644 --- a/docs/reference/buildx_version.md +++ b/docs/reference/buildx_version.md @@ -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 + +Show buildx version information + -Show buildx version information + ## Examples From 363c0fdf4b3e5dcd4f710bb7b5dd6c1b82f5fb62 Mon Sep 17 00:00:00 2001 From: Tonis Tiigi Date: Tue, 23 Mar 2021 10:40:56 -0700 Subject: [PATCH 8/9] hack: add docs generation/validation Signed-off-by: Tonis Tiigi --- .github/workflows/validate.yml | 1 + Makefile | 10 ++++++++-- hack/dockerfiles/docs.Dockerfile | 29 +++++++++++++++++++++++++++++ hack/update-docs | 16 ++++++++++++++++ hack/validate-docs | 29 +++++++++++++++++++++++++++++ 5 files changed, 83 insertions(+), 2 deletions(-) create mode 100644 hack/dockerfiles/docs.Dockerfile create mode 100755 hack/update-docs create mode 100755 hack/validate-docs diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 73b03613..02de4cd4 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -23,6 +23,7 @@ jobs: target: - lint - validate-vendor + - validate-docs steps: - name: Checkout diff --git a/Makefile b/Makefile index 205441e3..9c67a1a9 100644 --- a/Makefile +++ b/Makefile @@ -23,12 +23,18 @@ test: validate-vendor: ./hack/validate-vendor -validate-all: lint test validate-vendor +validate-docs: + ./hack/validate-docs + +validate-all: lint test validate-vendor validate-docs vendor: ./hack/update-vendor +docs: + ./hack/update-docs + generate-authors: ./hack/generate-authors -.PHONY: vendor lint shell binaries install binaries-cross validate-all generate-authors +.PHONY: vendor lint shell binaries install binaries-cross validate-all generate-authors validate-docs docs diff --git a/hack/dockerfiles/docs.Dockerfile b/hack/dockerfiles/docs.Dockerfile new file mode 100644 index 00000000..c32bc7b4 --- /dev/null +++ b/hack/dockerfiles/docs.Dockerfile @@ -0,0 +1,29 @@ +# syntax = docker/dockerfile:1.2 + +FROM golang:1.16-alpine AS docsgen +WORKDIR /src +RUN --mount=target=. \ + --mount=target=/root/.cache,type=cache \ + go build -mod=vendor -o /out/docsgen ./docs/docsgen + +FROM alpine AS gen +RUN apk add --no-cache rsync git +WORKDIR /src +COPY --from=docsgen /out/docsgen /usr/bin +RUN --mount=target=/context \ + --mount=target=.,type=tmpfs,readwrite \ + rsync -a /context/. . && \ + docsgen && \ + mkdir /out && cp -r docs/reference /out + +FROM scratch AS update +COPY --from=gen /out /out + +FROM gen AS validate +RUN --mount=target=/context \ + --mount=target=.,type=tmpfs,readwrite \ + rsync -a /context/. . && \ + git add -A && \ + rm -rf docs/reference/* && \ + cp -rf /out/* ./docs/ && \ + ./hack/validate-docs check diff --git a/hack/update-docs b/hack/update-docs new file mode 100755 index 00000000..14d6ef7e --- /dev/null +++ b/hack/update-docs @@ -0,0 +1,16 @@ +#!/usr/bin/env bash + +. $(dirname $0)/util +set -eu + +output=$(mktemp -d -t buildx-output.XXXXXXXXXX) + +buildxCmd build \ + --target "update" \ + --output "type=local,dest=$output" \ + --file "./hack/dockerfiles/docs.Dockerfile" \ + . + +rm -rf ./docs/reference/* +cp -R "$output"/out/* ./docs/ +rm -rf $output diff --git a/hack/validate-docs b/hack/validate-docs new file mode 100755 index 00000000..4aa0cf26 --- /dev/null +++ b/hack/validate-docs @@ -0,0 +1,29 @@ +#!/usr/bin/env sh +set -eu + +case ${1:-} in + '') + . $(dirname $0)/util + buildxCmd build \ + --target validate \ + --file ./hack/dockerfiles/docs.Dockerfile \ + . + ;; + check) + status="$(git status --porcelain -- docs/reference 2>/dev/null)" + diffs=$(echo "$status" | grep -v '^[RAD] ' || true) + if [ "$diffs" ]; then + { + set +x + echo 'The result of ./hack/update-docs differs' + echo + echo "$diffs" + echo + echo 'Please vendor your package with ./hack/update-docs' + echo + } >&2 + exit 1 + fi + echo 'Congratulations! All docs changes are done the right way.' + ;; +esac From 4047bccf6cb8f4505f0cbfeccb4601203cf69428 Mon Sep 17 00:00:00 2001 From: Tonis Tiigi Date: Tue, 23 Mar 2021 11:07:57 -0700 Subject: [PATCH 9/9] docs: add external docs links support Signed-off-by: Tonis Tiigi --- commands/build.go | 6 ++++++ docs/docsgen/generate.go | 22 ++++++++++++++-------- docs/reference/buildx_build.md | 10 +++++----- 3 files changed, 25 insertions(+), 13 deletions(-) diff --git a/commands/build.go b/commands/build.go index 9a470d17..d1d66308 100644 --- a/commands/build.go +++ b/commands/build.go @@ -238,8 +238,12 @@ func buildCmd(dockerCli command.Cli, rootOpts *rootOptions) *cobra.Command { flags.BoolVar(&options.exportLoad, "load", false, "Shorthand for --output=type=docker") flags.StringArrayVarP(&options.tags, "tag", "t", []string{}, "Name and optionally a tag in the 'name:tag' format") + flags.SetAnnotation("tag", "docs.external.url", []string{"https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t"}) flags.StringArrayVar(&options.buildArgs, "build-arg", []string{}, "Set build-time variables") + flags.SetAnnotation("build-arg", "docs.external.url", []string{"https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg"}) + flags.StringVarP(&options.dockerfileName, "file", "f", "", "Name of the Dockerfile (Default is 'PATH/Dockerfile')") + flags.SetAnnotation("file", "docs.external.url", []string{"https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f"}) flags.StringArrayVar(&options.labels, "label", []string{}, "Set metadata for an image") @@ -247,6 +251,7 @@ func buildCmd(dockerCli command.Cli, rootOpts *rootOptions) *cobra.Command { flags.StringArrayVar(&options.cacheTo, "cache-to", []string{}, "Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir)") flags.StringVar(&options.target, "target", "", "Set the target build stage to build.") + flags.SetAnnotation("target", "docs.external.url", []string{"https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target"}) flags.StringSliceVar(&options.allow, "allow", []string{}, "Allow extra privileged entitlement, e.g. network.host, security.insecure") @@ -254,6 +259,7 @@ func buildCmd(dockerCli command.Cli, rootOpts *rootOptions) *cobra.Command { flags.BoolVarP(&options.quiet, "quiet", "q", false, "Suppress the build output and print image ID on success") flags.StringVar(&options.networkMode, "network", "default", "Set the networking mode for the RUN instructions during build") flags.StringSliceVar(&options.extraHosts, "add-host", []string{}, "Add a custom host-to-IP mapping (host:ip)") + flags.SetAnnotation("add-host", "docs.external.url", []string{"https://docs.docker.com/engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host"}) flags.StringVar(&options.imageIDFile, "iidfile", "", "Write the image ID to the file") flags.BoolVar(&options.squash, "squash", false, "Squash newly built layers into a single new layer") flags.MarkHidden("quiet") diff --git a/docs/docsgen/generate.go b/docs/docsgen/generate.go index eb09c076..e6e98e9f 100644 --- a/docs/docsgen/generate.go +++ b/docs/docsgen/generate.go @@ -90,8 +90,18 @@ func genCmd(cmd *cobra.Command, dir string) error { return nil } -func makeLink(txt, link string) string { - return "[" + txt + "](#" + link + ")" +func makeLink(txt, link string, f *pflag.Flag, isAnchor bool) string { + link = "#" + link + annotations, ok := f.Annotations["docs.external.url"] + if ok && len(annotations) > 0 { + link = annotations[0] + } else { + if !isAnchor { + return txt + } + } + + return "[" + txt + "](" + link + ")" } func cmdOutput(cmd *cobra.Command, old string) (string, error) { @@ -140,9 +150,7 @@ func cmdOutput(cmd *cobra.Command, old string) (string, error) { fmt.Fprint(b, "| ") if f.Shorthand != "" { name := "`-" + f.Shorthand + "`" - if isLink { - name = makeLink(name, f.Name) - } + name = makeLink(name, f.Name, f, isLink) fmt.Fprintf(b, "%s, ", name) } name := "`--" + f.Name @@ -150,9 +158,7 @@ func cmdOutput(cmd *cobra.Command, old string) (string, error) { name += " " + f.Value.Type() } name += "`" - if isLink { - name = makeLink(name, f.Name) - } + name = makeLink(name, f.Name, f, isLink) fmt.Fprintf(b, "%s | %s |\n", name, f.Usage) }) fmt.Fprintln(b, "") diff --git a/docs/reference/buildx_build.md b/docs/reference/buildx_build.md index 60d96ac7..aef600c7 100644 --- a/docs/reference/buildx_build.md +++ b/docs/reference/buildx_build.md @@ -15,13 +15,13 @@ Start a build | Name | Description | | --- | --- | -| `--add-host stringSlice` | Add a custom host-to-IP mapping (host:ip) | +| [`--add-host stringSlice`](https://docs.docker.com/engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host) | 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 | +| [`--build-arg stringArray`](https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg) | 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') | +| [`-f`](https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f), [`--file string`](https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f) | 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 | @@ -34,8 +34,8 @@ Start a build | [`--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|[=|[,]]) | -| `-t`, `--tag stringArray` | Name and optionally a tag in the 'name:tag' format | -| `--target string` | Set the target build stage to build. | +| [`-t`](https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t), [`--tag stringArray`](https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t) | Name and optionally a tag in the 'name:tag' format | +| [`--target string`](https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target) | Set the target build stage to build. |