Merge pull request #12092 from thaJeztah/buildx_reference

Update buildx reference docs

_data/buildx/docker_buildx.yaml

@@ -40,7 +40,7 @@ options:
   swarm: false
 deprecated: false
 experimental: false
-experimentalcli: true
+experimentalcli: false
 kubernetes: false
 swarm: false
 

_data/buildx/docker_buildx_bake.yaml

@@ -1,7 +1,9 @@
 command: docker buildx bake
 aliases: f
 short: Build from a file
-long: Build from a file
+long: |-
+  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...]
 pname: docker buildx
 plink: docker_buildx.yaml
@@ -11,6 +13,7 @@ options:
   value_type: stringArray
   default_value: '[]'
   description: Build definition file
+  details_url: '#file'
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -29,6 +32,7 @@ options:
   value_type: bool
   default_value: "false"
   description: Do not use cache when building the image
+  details_url: '#no-cache'
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -38,6 +42,7 @@ options:
   value_type: bool
   default_value: "false"
   description: Print the options without building
+  details_url: '#print'
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -48,6 +53,7 @@ options:
   default_value: auto
   description: |
     Set type of progress output (auto, plain, tty). Use plain to show container output
+  details_url: '#progress'
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -57,6 +63,7 @@ options:
   value_type: bool
   default_value: "false"
   description: Always attempt to pull a newer version of the image
+  details_url: '#pull'
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -75,6 +82,7 @@ options:
   value_type: stringArray
   default_value: '[]'
   description: 'Override target value (eg: targetpattern.key=value)'
+  details_url: '#set'
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -89,9 +97,342 @@ inherited_options:
   experimentalcli: false
   kubernetes: false
   swarm: false
+examples: |-
+  ### Specify a build definition file (-f, --file) {#file}
+
+  By default, `buildx bake` looks for build definition files in the current directory,
+  the following are parsed:
+
+  - `docker-compose.yml`
+  - `docker-compose.yaml`
+  - `docker-bake.json`
+  - `docker-bake.override.json`
+  - `docker-bake.hcl`
+  - `docker-bake.override.hcl`
+
+  Use the `-f` / `--file` option to specify the build definition file to use. The
+  file can be a Docker Compose, JSON or HCL file. If multiple files are specified
+  they are all read and configurations are combined.
+
+  The following example uses a Docker Compose file named `docker-compose.dev.yaml`
+  as build definition file, and builds all targets in the file:
+
+  ```console
+  $ docker buildx bake -f docker-compose.dev.yaml
+
+  [+] Building 66.3s (30/30) FINISHED
+   => [frontend internal] load build definition from Dockerfile  0.1s
+   => => transferring dockerfile: 36B                            0.0s
+   => [backend internal] load build definition from Dockerfile   0.2s
+   => => transferring dockerfile: 3.73kB                         0.0s
+   => [database internal] load build definition from Dockerfile  0.1s
+   => => transferring dockerfile: 5.77kB                         0.0s
+   ...
+  ```
+
+  Pass the names of the targets to build, to build only specific target(s). The
+  following example builds the `backend` and `database` targets that are defined
+  in the `docker-compose.dev.yaml` file, skipping the build for the `frontend`
+  target:
+
+  ```console
+  $ docker buildx bake -f docker-compose.dev.yaml backend database
+
+  [+] Building 2.4s (13/13) FINISHED
+   => [backend internal] load build definition from Dockerfile  0.1s
+   => => transferring dockerfile: 81B                           0.0s
+   => [database internal] load build definition from Dockerfile 0.2s
+   => => transferring dockerfile: 36B                           0.0s
+   => [backend internal] load .dockerignore                     0.3s
+   ...
+  ```
+
+  ### Do not use cache when building the image (--no-cache) {#no-cache}
+
+  Same as `build --no-cache`. Do not use cache when building the image.
+
+  ### Print the options without building (--print) {#print}
+
+  Prints the resulting options of the targets desired to be built, in a JSON format,
+  without starting a build.
+
+  ```console
+  $ docker buildx bake -f docker-bake.hcl --print db
+  {
+     "target": {
+        "db": {
+           "context": "./",
+           "dockerfile": "Dockerfile",
+           "tags": [
+              "docker.io/tiborvass/db"
+           ]
+        }
+     }
+  }
+  ```
+
+  ### Set type of progress output (--progress) {#progress}
+
+  Same as `build --progress`. Set type of progress output (auto, plain, tty). Use
+  plain to show container output (default "auto").
+
+  The following example uses `plain` output during the build:
+
+  ```console
+  $ docker buildx bake --progress=plain
+
+  #2 [backend internal] load build definition from Dockerfile.test
+  #2 sha256:de70cb0bb6ed8044f7b9b1b53b67f624e2ccfb93d96bb48b70c1fba562489618
+  #2 ...
+
+  #1 [database internal] load build definition from Dockerfile.test
+  #1 sha256:453cb50abd941762900a1212657a35fc4aad107f5d180b0ee9d93d6b74481bce
+  #1 transferring dockerfile: 36B done
+  #1 DONE 0.1s
+  ...
+  ```
+
+
+  ### Always attempt to pull a newer version of the image (--pull) {#pull}
+
+  Same as `build --pull`.
+
+  ### Override target configurations from command line (--set) {#set}
+
+  ```
+  --set targetpattern.key[.subkey]=value
+  ```
+
+  Override target configurations from command line. The pattern matching syntax is
+  defined in https://golang.org/pkg/path/#Match.
+
+  **Examples**
+
+  ```console
+  $ docker buildx bake --set target.args.mybuildarg=value
+  $ docker buildx bake --set target.platform=linux/arm64
+  $ docker buildx bake --set foo*.args.mybuildarg=value # overrides build arg for all targets starting with 'foo'
+  $ docker buildx bake --set *.platform=linux/arm64     # overrides platform for all targets
+  $ docker buildx bake --set foo*.no-cache              # bypass caching only for targets starting with 'foo'
+  ```
+
+  Complete list of overridable fields:
+  args, cache-from, cache-to, context, dockerfile, labels, no-cache, output, platform,
+  pull, secrets, ssh, tags, target
+
+  ### File definition
+
+  In addition to compose files, bake supports a JSON and an equivalent HCL file
+  format for defining build groups and targets.
+
+  A target reflects a single docker build invocation with the same options that
+  you would specify for `docker build`. A group is a grouping of targets.
+
+  Multiple files can include the same target and final build options will be
+  determined by merging them together.
+
+  In the case of compose files, each service corresponds to a target.
+
+  A group can specify its list of targets with the `targets` option. A target can
+  inherit build options by setting the `inherits` option to the list of targets or
+  groups to inherit from.
+
+  Note: Design of bake command is work in progress, the user experience may change
+  based on feedback.
+
+
+  **Example HCL definition**
+
+  ```hcl
+  group "default" {
+      targets = ["db", "webapp-dev"]
+  }
+
+  target "webapp-dev" {
+      dockerfile = "Dockerfile.webapp"
+      tags = ["docker.io/username/webapp"]
+  }
+
+  target "webapp-release" {
+      inherits = ["webapp-dev"]
+      platforms = ["linux/amd64", "linux/arm64"]
+  }
+
+  target "db" {
+      dockerfile = "Dockerfile.db"
+      tags = ["docker.io/username/db"]
+  }
+  ```
+
+  Complete list of valid target fields:
+
+  `args`, `cache-from`, `cache-to`, `context`, `dockerfile`, `inherits`, `labels`,
+  `no-cache`, `output`, `platform`, `pull`, `secrets`, `ssh`, `tags`, `target`
+
+  ### 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"
+           ]
+        }
+     }
+  }
+  ```
 deprecated: false
 experimental: false
-experimentalcli: true
+experimentalcli: false
 kubernetes: false
 swarm: false
 

_data/buildx/docker_buildx_build.yaml

@@ -1,7 +1,13 @@
 command: docker buildx build
 aliases: b
 short: Start a build
-long: Start a build
+long: |-
+  The `buildx build` command starts a build using BuildKit. This command is similar
+  to the UI of `docker build` command and takes the same flags and arguments.
+
+  For documentation on most of these flags, refer to the [`docker build`
+  documentation](/engine/reference/commandline/build/). In
+  here we’ll document a subset of the new flags.
 usage: docker buildx build [OPTIONS] PATH | URL | -
 pname: docker buildx
 plink: docker_buildx.yaml
@@ -10,6 +16,7 @@ options:
   value_type: stringSlice
   default_value: '[]'
   description: Add a custom host-to-IP mapping (host:ip)
+  details_url: /engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -20,6 +27,7 @@ options:
   default_value: '[]'
   description: |
     Allow extra privileged entitlement, e.g. network.host, security.insecure
+  details_url: '#allow'
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -29,6 +37,7 @@ options:
   value_type: stringArray
   default_value: '[]'
   description: Set build-time variables
+  details_url: /engine/reference/commandline/build/#set-build-time-variables---build-arg
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -39,6 +48,7 @@ options:
   default_value: '[]'
   description: |
     External cache sources (eg. user/app:cache, type=local,src=path/to/dir)
+  details_url: '#cache-from'
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -49,6 +59,7 @@ options:
   default_value: '[]'
   description: |
     Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir)
+  details_url: '#cache-to'
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -119,6 +130,7 @@ options:
   shorthand: f
   value_type: string
   description: Name of the Dockerfile (Default is 'PATH/Dockerfile')
+  details_url: /engine/reference/commandline/build/#specify-a-dockerfile--f
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -162,6 +174,7 @@ options:
   value_type: bool
   default_value: "false"
   description: Shorthand for --output=type=docker
+  details_url: '#load'
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -209,6 +222,7 @@ options:
   value_type: stringArray
   default_value: '[]'
   description: 'Output destination (format: type=local,dest=path)'
+  details_url: '#output'
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -218,6 +232,7 @@ options:
   value_type: stringArray
   default_value: '[]'
   description: Set target platform for build
+  details_url: '#platform'
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -246,6 +261,7 @@ options:
   value_type: bool
   default_value: "false"
   description: Shorthand for --output=type=registry
+  details_url: '#push'
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -321,6 +337,7 @@ options:
   value_type: stringArray
   default_value: '[]'
   description: Name and optionally a tag in the 'name:tag' format
+  details_url: /engine/reference/commandline/build/#tag-an-image--t
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -329,6 +346,7 @@ options:
 - option: target
   value_type: string
   description: Set the target build stage to build.
+  details_url: /engine/reference/commandline/build/#specifying-target-build-stage---target
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -351,9 +369,228 @@ inherited_options:
   experimentalcli: false
   kubernetes: false
   swarm: false
+examples: |-
+  ### Set the target platforms for the build (--platform) {#platform}
+
+  ```
+  --platform=value[,value]
+  ```
+
+  Set the target platform for the build. All `FROM` commands inside the Dockerfile
+  without their own `--platform` flag will pull base images for this platform and
+  this value will also be the platform of the resulting image. The default value
+  will be the current platform of the buildkit daemon.
+
+  When using `docker-container` driver with `buildx`, this flag can accept multiple
+  values as an input separated by a comma. With multiple values the result will be
+  built for all of the specified platforms and joined together into a single manifest
+  list.
+
+  If the `Dockerfile` needs to invoke the `RUN` command, the builder needs runtime
+  support for the specified platform. In a clean setup, you can only execute `RUN`
+  commands for your system architecture.
+  If your kernel supports [`binfmt_misc`](https://en.wikipedia.org/wiki/Binfmt_misc)
+  launchers for secondary architectures, buildx will pick them up automatically.
+  Docker desktop releases come with `binfmt_misc` automatically configured for `arm64`
+  and `arm` architectures. You can see what runtime platforms your current builder
+  instance supports by running `docker buildx inspect --bootstrap`.
+
+  Inside a `Dockerfile`, you can access the current platform value through
+  `TARGETPLATFORM` build argument. Please refer to the [`docker build`
+  documentation](/engine/reference/builder/#automatic-platform-args-in-the-global-scope)
+  for the full description of automatic platform argument variants .
+
+  The formatting for the platform specifier is defined in the [containerd source
+  code](https://github.com/containerd/containerd/blob/v1.4.3/platforms/platforms.go#L63).
+
+  **Examples**
+
+  ```console
+  $ docker buildx build --platform=linux/arm64 .
+  $ docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 .
+  $ docker buildx build --platform=darwin .
+  ```
+
+  ### Set the export action for the build result (-o, --output) {#output}
+
+  ```
+  -o, --output=[PATH,-,type=TYPE[,KEY=VALUE]
+  ```
+
+  Sets the export action for the build result. In `docker build` all builds finish
+  by creating a container image and exporting it to `docker images`. `buildx` makes
+  this step configurable allowing results to be exported directly to the client,
+  oci image tarballs, registry etc.
+
+  Buildx with `docker` driver currently only supports local, tarball exporter and
+  image exporter. `docker-container` driver supports all the exporters.
+
+  If just the path is specified as a value, `buildx` will use the local exporter
+  with this path as the destination. If the value is "-", `buildx` will use `tar`
+  exporter and write to `stdout`.
+
+  **Examples**
+
+  ```console
+  $ docker buildx build -o . .
+  $ docker buildx build -o outdir .
+  $ docker buildx build -o - - > out.tar
+  $ docker buildx build -o type=docker .
+  $ docker buildx build -o type=docker,dest=- . > myimage.tar
+  $ docker buildx build -t tonistiigi/foo -o type=registry
+  ```
+
+  Supported exported types are:
+
+  #### `local`
+
+  The `local` export type writes all result files to a directory on the client. The
+  new files will be owned by the current user. On multi-platform builds, all results
+  will be put in subdirectories by their platform.
+
+  Attribute key:
+
+  - `dest` - destination directory where files will be written
+
+  #### `tar`
+
+  The `tar` export type writes all result files as a single tarball on the client.
+  On multi-platform builds all results will be put in subdirectories by their platform.
+
+  Attribute key:
+
+  - `dest` - destination path where tarball will be written. “-” writes to stdout.
+
+  #### `oci`
+
+  The `oci` export type writes the result image or manifest list as an [OCI image
+  layout](https://github.com/opencontainers/image-spec/blob/v1.0.1/image-layout.md)
+  tarball on the client.
+
+  Attribute key:
+
+  - `dest` - destination path where tarball will be written. “-” writes to stdout.
+
+  #### `docker`
+
+  The `docker` export type writes the single-platform result image as a [Docker image
+  specification](https://github.com/docker/docker/blob/v20.10.2/image/spec/v1.2.md)
+  tarball on the client. Tarballs created by this exporter are also OCI compatible.
+
+  Currently, multi-platform images cannot be exported with the `docker` export type.
+  The most common usecase for multi-platform images is to directly push to a registry
+  (see [`registry`](#registry)).
+
+  Attribute keys:
+
+  - `dest` - destination path where tarball will be written. If not specified the
+  tar will be loaded automatically to the current docker instance.
+  - `context` - name for the docker context where to import the result
+
+  #### `image`
+
+  The `image` exporter writes the build result as an image or a manifest list. When
+  using `docker` driver the image will appear in `docker images`. Optionally, image
+  can be automatically pushed to a registry by specifying attributes.
+
+  Attribute keys:
+
+  - `name` - name (references) for the new image.
+  - `push` - boolean to automatically push the image.
+
+  #### `registry`
+
+  The `registry` exporter is a shortcut for `type=image,push=true`.
+
+
+  ### Push the build result to a registry (--push) {#push}
+
+  Shorthand for [`--output=type=registry`](#registry). Will automatically push the
+  build result to registry.
+
+  ### Load the single-platform build result to `docker images` (--load) {#load}
+
+  Shorthand for [`--output=type=docker`](#docker). Will automatically load the
+  single-platform build result to `docker images`.
+
+  ### Use an external cache source for a build (--cache-from) {#cache-from}
+
+  ```
+  --cache-from=[NAME|type=TYPE[,KEY=VALUE]]
+  ```
+
+  Use an external cache source for a build. Supported types are `registry` 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 .
+  ```
+
+  ### Export build cache to an external cache destination (--cache-to) {#cache-to}
+
+  ```
+  --cache-to=[NAME|type=TYPE[,KEY=VALUE]]
+  ```
+
+  Export build cache to an external cache destination. Supported types are `registry`,
+  `local` and `inline`. Registry exports build cache to a cache manifest in the
+  registry, local exports cache to a local directory on the client and inline writes
+  the cache metadata into the image configuration.
+
+  `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 extra privileged entitlement (--allow) {#allow}
+
+  ```
+  --allow=ENTITLEMENT
+  ```
+
+  Allow extra privileged entitlement. List of entitlements:
+
+  - `network.host` - Allows executions with host networking.
+  - `security.insecure` - Allows executions without sandbox. See
+  [related Dockerfile extensions](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/experimental.md#run---securityinsecuresandbox).
+
+  For entitlements to be enabled, the `buildkitd` daemon also needs to allow them
+  with `--allow-insecure-entitlement` (see [`create --buildkitd-flags`](buildx_create.md#--buildkitd-flags-flags))
+
+  **Examples**
+
+  ```console
+  $ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure'
+  $ docker buildx build --allow security.insecure .
+  ```
 deprecated: false
 experimental: false
-experimentalcli: true
+experimentalcli: false
 kubernetes: false
 swarm: false
 

_data/buildx/docker_buildx_create.yaml

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

_data/buildx/docker_buildx_du.yaml

@@ -33,7 +33,7 @@ inherited_options:
   swarm: false
 deprecated: false
 experimental: false
-experimentalcli: true
+experimentalcli: false
 kubernetes: false
 swarm: false
 

_data/buildx/docker_buildx_imagetools.yaml

@@ -1,6 +1,8 @@
 command: docker buildx imagetools
 short: Commands to work on images in registry
-long: Commands to work on images in registry
+long: |-
+  Imagetools contains commands for working with manifest lists in the registry.
+  These commands are useful for inspecting multi-platform build results.
 pname: docker buildx
 plink: docker_buildx.yaml
 cname:
@@ -20,7 +22,7 @@ inherited_options:
   swarm: false
 deprecated: false
 experimental: false
-experimentalcli: true
+experimentalcli: false
 kubernetes: false
 swarm: false
 

_data/buildx/docker_buildx_imagetools_create.yaml

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

_data/buildx/docker_buildx_imagetools_inspect.yaml

@@ -1,6 +1,32 @@
 command: docker buildx imagetools inspect
 short: Show details of image in the registry
-long: Show details of image in the registry
+long: |-
+  Show details of image in the registry.
+
+  Example:
+
+  ```console
+  $ docker buildx imagetools inspect alpine
+
+  Name:      docker.io/library/alpine:latest
+  MediaType: application/vnd.docker.distribution.manifest.list.v2+json
+  Digest:    sha256:28ef97b8686a0b5399129e9b763d5b7e5ff03576aa5580d6f4182a49c5fe1913
+
+  Manifests:
+    Name:      docker.io/library/alpine:latest@sha256:5c40b3c27b9f13c873fefb2139765c56ce97fd50230f1f2d5c91e55dec171907
+    MediaType: application/vnd.docker.distribution.manifest.v2+json
+    Platform:  linux/amd64
+
+    Name:      docker.io/library/alpine:latest@sha256:c4ba6347b0e4258ce6a6de2401619316f982b7bcc529f73d2a410d0097730204
+    MediaType: application/vnd.docker.distribution.manifest.v2+json
+    Platform:  linux/arm/v6
+   ...
+  ```
+
+  ### Show original, unformatted JSON manifest (--raw) {#raw}
+
+  Use the `--raw` option to print the original JSON bytes instead of the formatted
+  output.
 usage: docker buildx imagetools inspect [OPTIONS] NAME
 pname: docker buildx imagetools
 plink: docker_buildx_imagetools.yaml
@@ -9,6 +35,7 @@ options:
   value_type: bool
   default_value: "false"
   description: Show original JSON manifest
+  details_url: '#raw'
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -25,7 +52,7 @@ inherited_options:
   swarm: false
 deprecated: false
 experimental: false
-experimentalcli: true
+experimentalcli: false
 kubernetes: false
 swarm: false
 

_data/buildx/docker_buildx_inspect.yaml

@@ -1,6 +1,6 @@
 command: docker buildx inspect
 short: Inspect current builder instance
-long: Inspect current builder instance
+long: Shows information about the current or specified builder.
 usage: docker buildx inspect [NAME]
 pname: docker buildx
 plink: docker_buildx.yaml
@@ -9,6 +9,7 @@ options:
   value_type: bool
   default_value: "false"
   description: Ensure builder has booted before inspecting
+  details_url: '#bootstrap'
   deprecated: false
   experimental: false
   experimentalcli: false
@@ -23,9 +24,43 @@ inherited_options:
   experimentalcli: false
   kubernetes: false
   swarm: false
+examples: |-
+  ### Get information about a builder instance
+
+  By default, `inspect` shows information about the current builder. Specify the
+  name of the builder to inspect to get information about that builder.
+  The following example shows information about a builder instance named
+  `elated_tesla`:
+
+  ```console
+  $ docker buildx inspect elated_tesla
+
+  Name:   elated_tesla
+  Driver: docker-container
+
+  Nodes:
+  Name:      elated_tesla0
+  Endpoint:  unix:///var/run/docker.sock
+  Status:    running
+  Platforms: linux/amd64
+
+  Name:      elated_tesla1
+  Endpoint:  ssh://ubuntu@1.2.3.4
+  Status:    running
+  Platforms: linux/arm64, linux/arm/v7, linux/arm/v6
+  ```
+
+  ### Ensure that the builder is running before inspecting (--bootstrap) {#bootstrap}
+
+  Use the `--bootstrap` option to ensure that the builder is running before
+  inspecting it. If the driver is `docker-container`, then `--bootstrap` starts
+  the buildkit container and waits until it is operational. Bootstrapping is
+  automatically done during build, and therefore not necessary. The same BuildKit
+  container is used during the lifetime of the associated builder node (as
+  displayed in `buildx ls`).
 deprecated: false
 experimental: false
-experimentalcli: true
+experimentalcli: false
 kubernetes: false
 swarm: false
 

_data/buildx/docker_buildx_install.yaml

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

_data/buildx/docker_buildx_ls.yaml

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

_data/buildx/docker_buildx_prune.yaml

@@ -1,6 +1,6 @@
 command: docker buildx prune
-short: 'Remove build cache '
+short: Remove build cache
-long: 'Remove build cache '
+long: Remove build cache
 usage: docker buildx prune
 pname: docker buildx
 plink: docker_buildx.yaml
@@ -62,7 +62,7 @@ inherited_options:
   swarm: false
 deprecated: false
 experimental: false
-experimentalcli: true
+experimentalcli: false
 kubernetes: false
 swarm: false
 

_data/buildx/docker_buildx_rm.yaml

@@ -1,6 +1,8 @@
 command: docker buildx rm
 short: Remove a builder instance
-long: Remove a builder instance
+long: |-
+  Removes the specified or current builder. It is a no-op attempting to remove the
+  default builder.
 usage: docker buildx rm [NAME]
 pname: docker buildx
 plink: docker_buildx.yaml
@@ -15,7 +17,7 @@ inherited_options:
   swarm: false
 deprecated: false
 experimental: false
-experimentalcli: true
+experimentalcli: false
 kubernetes: false
 swarm: false
 

_data/buildx/docker_buildx_stop.yaml

@@ -1,6 +1,8 @@
 command: docker buildx stop
 short: Stop builder instance
-long: Stop builder instance
+long: |-
+  Stops the specified or current builder. This will not prevent buildx build to
+  restart the builder. The implementation of stop depends on the driver.
 usage: docker buildx stop [NAME]
 pname: docker buildx
 plink: docker_buildx.yaml
@@ -15,7 +17,7 @@ inherited_options:
   swarm: false
 deprecated: false
 experimental: false
-experimentalcli: true
+experimentalcli: false
 kubernetes: false
 swarm: false
 

_data/buildx/docker_buildx_uninstall.yaml

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

_data/buildx/docker_buildx_use.yaml

@@ -1,6 +1,9 @@
 command: docker buildx use
 short: Set the current builder instance
-long: Set the current builder instance
+long: |-
+  Switches the current builder instance. Build commands invoked after this command
+  will run on a specified builder. Alternatively, a context name can be used to
+  switch to the default builder of that context.
 usage: docker buildx use [OPTIONS] NAME
 pname: docker buildx
 plink: docker_buildx.yaml
@@ -34,7 +37,7 @@ inherited_options:
   swarm: false
 deprecated: false
 experimental: false
-experimentalcli: true
+experimentalcli: false
 kubernetes: false
 swarm: false
 

_data/buildx/docker_buildx_version.yaml

@@ -1,6 +1,6 @@
 command: docker buildx version
-short: 'Show buildx version information '
+short: Show buildx version information
-long: 'Show buildx version information '
+long: Show buildx version information
 usage: docker buildx version
 pname: docker buildx
 plink: docker_buildx.yaml
@@ -13,9 +13,17 @@ inherited_options:
   experimentalcli: false
   kubernetes: false
   swarm: false
+examples: |-
+  ### View version information
+
+
+  ```console
+  $ docker buildx version
+  github.com/docker/buildx v0.5.1-docker 11057da37336192bfc57d81e02359ba7ba848e4a
+  ```
 deprecated: false
 experimental: false
-experimentalcli: true
+experimentalcli: false
 kubernetes: false
 swarm: false
 

_data/toc.yaml

@@ -462,6 +462,8 @@ reference:
           title: docker buildx imagetools inspect
         - path: /engine/reference/commandline/buildx_inspect/
           title: docker buildx inspect
+        - path: /engine/reference/commandline/buildx_install/
+          title: docker buildx install
         - path: /engine/reference/commandline/buildx_ls/
           title: docker buildx ls
         - path: /engine/reference/commandline/buildx_prune/
@@ -470,6 +472,8 @@ reference:
           title: docker buildx rm
         - path: /engine/reference/commandline/buildx_stop/
           title: docker buildx stop
+        - path: /engine/reference/commandline/buildx_uninstall/
+          title: docker buildx uninstall
         - path: /engine/reference/commandline/buildx_use/
           title: docker buildx use
         - path: /engine/reference/commandline/buildx_version/

_includes/cli.md

@@ -124,7 +124,11 @@ For example uses of this command, refer to the [examples section](#examples) bel
   {% assign defaults-to-skip = "[],map[],false,0,0s,default,'',\"\"" | split: ',' %}
   {% capture option-default %}{% if option.default_value %}{% unless defaults-to-skip contains option.default_value or defaults-to-skip == blank %}`{{ option.default_value }}`{% endunless %}{% endif %}{% endcapture %}
   <tr>
-    <td markdown="span">`--{{ option.option }}{% if option.shorthand %} , -{{ option.shorthand }}{% endif %}`</td>
+    {% if option.details_url and option.details_url != '' -%}
+    <td markdown="span">[`--{{ option.option }}`]({{ option.details_url }}){% if option.shorthand %} , [`-{{ option.shorthand }}`]({{ option.details_url }}){% endif %}</td>
+    {%- else -%}
+    <td markdown="span">`--{{ option.option }}`{% if option.shorthand %} , `-{{ option.shorthand }}`{% endif %}</td>
+    {%- endif %}
     <td markdown="span">{{ option-default }}</td>
     <td markdown="span">{% if all-badges != '' %}{{ all-badges | strip }}<br />{% endif %}{{ option.description | strip | escape }}</td>
   </tr>

buildx/working-with-buildx.md

@@ -4,84 +4,150 @@ description: Working with Docker Buildx
 keywords: Docker, buildx, multi-arch
 ---
 
->This is an experimental feature.
->
->{% include experimental.md %}
-
 ## Overview
 
-Docker Buildx is a CLI plugin that extends the docker command with the full support of the features provided by [Moby BuildKit](https://github.com/moby/buildkit) builder toolkit. It provides the same user experience as docker build with many new features like creating scoped builder instances and building against multiple nodes concurrently.
+Docker Buildx is a CLI plugin that extends the docker command with the full
+support of the features provided by [Moby BuildKit](https://github.com/moby/buildkit)
+builder toolkit. It provides the same user experience as docker build with many
+new features like creating scoped builder instances and building against multiple
+nodes concurrently.
 
 ## Install
 
-Docker Buildx is included in Docker 19.03 and is also bundled with the following Docker Desktop releases. Note that you must enable the 'Experimental features' option to use Docker Buildx.
+Docker Buildx is included in Docker Desktop and Docker Linux packages when installed
+using the [DEB or RPM packages](../engine/install/index.md).
 
-- Docker Desktop Enterprise version 2.1.0
+You can also download the latest `buildx` binary from the
-- Docker Desktop Edge version 2.0.4.0 or higher
+[Docker buildx](https://github.com/docker/buildx/) repository on GitHub.
 
-You can also download the latest `buildx` binary from the [Docker buildx](https://github.com/docker/buildx/) repository.
+## Set buildx as the default builder
 
-## Build with `buildx`
+Running the command [`docker buildx install`](../engine/reference/commandline/buildx_install.md)
+sets up docker builder command as an alias to `docker buildx`. This results in
+the ability to have [`docker build`](../engine/reference/commandline/build.md)
+use the current buildx builder.
+
+To remove this alias, run [`docker buildx uninstall`](../engine/reference/commandline/buildx_uninstall.md).
+
+## Build with buildx
 
 To start a new build, run the command `docker buildx build .`
 
-```
+```console
 $ docker buildx build .
 [+] Building 8.4s (23/32)
  => ...
- ```
+```
 
-Buildx builds using the BuildKit engine and does not require `DOCKER_BUILDKIT=1` environment variable to start the builds.
+Buildx builds using the BuildKit engine and does not require `DOCKER_BUILDKIT=1`
+environment variable to start the builds.
 
-The `docker buildx build` command supports features available for `docker build`, including the new features in Docker 19.03 such as outputs configuration, inline build caching, and specifying target platform. In addition, Buildx also supports new features that are not yet available for regular `docker build` like building manifest lists, distributed caching, and exporting build results to OCI image tarballs.
+The `docker buildx build` command supports features available for `docker build`,
+including features such as outputs configuration, inline build caching, and
+specifying target platform. In addition, Buildx also supports new features that
+are not yet available for regular `docker build` like building manifest lists,
+distributed caching, and exporting build results to OCI image tarballs.
 
-You can run Buildx in different configurations that are exposed through a driver concept. Currently, Docker supports a "docker" driver that uses the BuildKit library bundled into the docker daemon binary, and a "docker-container" driver that automatically launches BuildKit inside a Docker container.
+You can run Buildx in different configurations that are exposed through a driver
+concept. Currently, Docker supports a "docker" driver that uses the BuildKit
+library bundled into the Docker daemon binary, and a "docker-container" driver
+that automatically launches BuildKit inside a Docker container.
 
-The user experience of using Buildx is very similar across drivers. However, there are some features that are not currently supported by the "docker" driver, because the BuildKit library which is bundled into docker daemon uses a different storage component. In contrast, all images built with the "docker" driver are automatically added to the "docker images" view by default, whereas when using other drivers, the method for outputting an image needs to be selected with `--output`.
+The user experience of using Buildx is very similar across drivers. However,
+there are some features that are not currently supported by the "docker" driver,
+because the BuildKit library which is bundled into docker daemon uses a different
+storage component. In contrast, all images built with the "docker" driver are
+automatically added to the "docker images" view by default, whereas when using
+other drivers, the method for outputting an image needs to be selected
+with `--output`.
 
 ## Work with builder instances
 
-By default, Buildx uses the "docker" driver if it is supported, providing a user experience very similar to the native docker build. Note that you must use a local shared daemon to build your applications.
+By default, Buildx uses the "docker" driver if it is supported, providing a user
+experience very similar to the native docker build. Note that you must use a local
+shared daemon to build your applications.
 
-Buildx allows you to create new instances of isolated builders. You can use this to get a scoped environment for your CI builds that does not change the state of the shared daemon, or for isolating builds for different projects. You can create a new instance for a set of remote nodes, forming a build farm, and quickly switch between them.
+Buildx allows you to create new instances of isolated builders. You can use this
+to get a scoped environment for your CI builds that does not change the state of
+the shared daemon, or for isolating builds for different projects. You can create
+a new instance for a set of remote nodes, forming a build farm, and quickly
+switch between them.
 
-You can create new instances using the `docker buildx create` command. This creates a new builder instance with a single node based on your current configuration.
+You can create new instances using the [`docker buildx create`](../engine/reference/commandline/buildx_create.md)
+command. This creates a new builder instance with a single node based on your
+current configuration.
 
-To use a remote node you can specify the `DOCKER_HOST` or the remote context name while creating the new builder. After creating a new instance, you can manage its lifecycle using the inspect, stop and rm commands. To list all available builders, use ls. After creating a new builder you can also append new nodes to it.
+To use a remote node you can specify the `DOCKER_HOST` or the remote context name
+while creating the new builder. After creating a new instance, you can manage its
+lifecycle using the [`docker buildx inspect`](../engine/reference/commandline/buildx_inspect.md),
+[`docker buildx stop`](../engine/reference/commandline/buildx_stop.md), and
+[`docker buildx rm`](../engine/reference/commandline/buildx_rm.md) commands.
+To list all available builders, use [`docker buildx ls`](../engine/reference/commandline/buildx_ls.md].
+After creating a new builder you can also append new nodes to it.
 
-To switch between different builders use `docker buildx use <name>`. After running this command, the build commands will automatically use this builder.
+To switch between different builders, use [`docker buildx use <name>`](../engine/reference/commandline/buildx_use.md).
+After running this command, the build commands will automatically use this
+builder.
 
-Docker 19.03 also features a new docker context command that you can use to provide names for remote Docker API endpoints. Buildx integrates with docker context to ensure all the contexts automatically get a default builder instance. You can also set the context name as the target when you  create a new builder instance or when you add a node to it.
+Docker also features a [`docker context`](../engine/reference/commandline/context.md)
+command that you can use to provide names for remote Docker API endpoints. Buildx
+integrates with docker context to ensure all the contexts automatically get a
+default builder instance. You can also set the context name as the target when
+you  create a new builder instance or when you add a node to it.
 
 ## Build multi-platform images
 
-BuildKit is designed to work well for building for multiple platforms and not only for the architecture and operating system that the user invoking the build happens to run.
+BuildKit is designed to work well for building for multiple platforms and not
+only for the architecture and operating system that the user invoking the build
+happens to run.
 
-When you invoke a build, you can set the `--platform` flag to specify the target platform for the build output, (for example, linux/amd64, linux/arm64, darwin/amd64).
+When you invoke a build, you can set the `--platform` flag to specify the target
+platform for the build output, (for example, `linux/amd64`, `linux/arm64`, or
+`darwin/amd64`).
 
-When the current builder instance is backed by the "docker-container" driver, you can specify multiple platforms together. In this case, it builds a manifest list which contains images for all of the specified architectures. When you use this image in `docker run` or `docker service`, Docker picks the correct image based on the node’s platform.
+When the current builder instance is backed by the "docker-container" driver,
+you can specify multiple platforms together. In this case, it builds a manifest
+list which contains images for all specified architectures. When you use this
+image in [`docker run`](../engine/reference/commandline/run.md) or
+[`docker service`](../engine/reference/commandline/service.md), Docker picks
+the correct image based on the node's platform.
 
-You can build multi-platform images using three different strategies that are supported by Buildx and Dockerfiles:
+You can build multi-platform images using three different strategies that are
+supported by Buildx and Dockerfiles:
 
 1. Using the QEMU emulation support in the kernel
 2. Building on multiple native nodes using the same builder instance
 3. Using a stage in Dockerfile to cross-compile to different architectures
 
-QEMU is the easiest way to get started if your node already supports it (for example. if you are using Docker Desktop). It requires no changes to your Dockerfile and BuildKit automatically detects the secondary architectures that are available. When BuildKit needs to run a binary for a different architecture, it automatically loads it through a binary registered in the `binfmt_misc` handler.
+QEMU is the easiest way to get started if your node already supports it (for
+example. if you are using Docker Desktop). It requires no changes to your
+Dockerfile and BuildKit automatically detects the secondary architectures that
+are available. When BuildKit needs to run a binary for a different architecture,
+it automatically loads it through a binary registered in the `binfmt_misc`
+handler.
 
-Using multiple native nodes provide better support for more complicated cases that are not handled by QEMU and generally have better performance. You can add additional nodes to the builder instance using the `--append` flag.
+Using multiple native nodes provide better support for more complicated cases
+that are not handled by QEMU and generally have better performance. You can
+add additional nodes to the builder instance using the `--append` flag.
 
-```bash
+Assuming contexts node-amd64 and node-arm64 exist in `docker context ls`;
-# assuming contexts node-amd64 and node-arm64 exist in "docker context ls"
+
+```console
 $ docker buildx create --use --name mybuild node-amd64
 mybuild
 $ docker buildx create --append --name mybuild node-arm64
 $ docker buildx build --platform linux/amd64,linux/arm64 .
 ```
 
-Finally, depending on your project, the language that you use may have good support for cross-compilation. In that case, multi-stage builds in Dockerfiles can be effectively used to build binaries for the platform specified with `--platform` using the native architecture of the build node. A list of build arguments like `BUILDPLATFORM` and `TARGETPLATFORM` is available automatically inside your Dockerfile and can be leveraged by the processes running as part of your build.
+Finally, depending on your project, the language that you use may have good 
+support for cross-compilation. In that case, multi-stage builds in Dockerfiles
+can be effectively used to build binaries for the platform specified with
+`--platform` using the native architecture of the build node. A list of build
+arguments like `BUILDPLATFORM` and `TARGETPLATFORM` is available automatically
+inside your Dockerfile and can be leveraged by the processes running as part
+of your build.
 
-```
+```dockerfile
 FROM --platform=$BUILDPLATFORM golang:alpine AS build
 ARG TARGETPLATFORM
 ARG BUILDPLATFORM
@@ -92,14 +158,16 @@ COPY --from=build /log /log
 
 ## High-level build options
 
-Buildx also aims to provide support for high-level build concepts that go beyond invoking a single build command.
+Buildx also aims to provide support for high-level build concepts that go beyond
+invoking a single build command.
 
-BuildKit efficiently handles multiple concurrent build requests and deduplicating work. The build commands can be combined with general-purpose command runners (for example, `make`). However, these tools generally invoke builds in sequence and therefore cannot leverage the full potential of BuildKit parallelization, or combine BuildKit’s output for the user. For this use case, we have added a command called `docker buildx bake`.
+BuildKit efficiently handles multiple concurrent build requests and de-duplicating
+work. The build commands can be combined with general-purpose command runners
+(for example, `make`). However, these tools generally invoke builds in sequence
+and therefore cannot leverage the full potential of BuildKit parallelization,
+or combine BuildKit’s output for the user. For this use case, we have added a
+command called [`docker buildx bake`](../engine/reference/commandline/buildx_bake.md).
 
-The `bake` command supports building images from compose files, similar to a compose build, but allowing all the services to be built concurrently as part of a single request.
+The `bake` command supports building images from compose files, similar to 
-
+[`docker-compose build`](../compose/reference/build.md), but allowing all the
-## Set `buildx` as the default builder
+services to be built concurrently as part of a single request.
-
-Running the command `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.
-
-To remove this alias, run `docker buildx uninstall`.

engine/reference/commandline/buildx_install.md

@@ -0,0 +1,13 @@
+---
+datafolder: buildx
+datafile: docker_buildx_install
+title: docker buildx install
+---
+<!--
+This page is automatically generated from Docker's source code. If you want to
+suggest a change to the text that appears here, open a ticket or pull request
+in the source repository on GitHub:
+
+https://github.com/docker/buildx
+-->
+{% include cli.md datafolder=page.datafolder datafile=page.datafile %}

engine/reference/commandline/buildx_uninstall.md

@@ -0,0 +1,13 @@
+---
+datafolder: buildx
+datafile: docker_buildx_uninstall
+title: docker buildx uninstall
+---
+<!--
+This page is automatically generated from Docker's source code. If you want to
+suggest a change to the text that appears here, open a ticket or pull request
+in the source repository on GitHub:
+
+https://github.com/docker/buildx
+-->
+{% include cli.md datafolder=page.datafolder datafile=page.datafile %}