build: add build architecture

Signed-off-by: David Karlsson <david.karlsson@docker.com>

_data/toc.yaml

@@ -1623,8 +1623,8 @@ manuals:
   section:
     - path: /build/
       title: Overview
-    - path: /build/install-buildx/
+    - path: /build/architecture/
-      title: Install Buildx
+      title: Architecture
     - sectiontitle: Building images
       section:
         - path: /build/building/packaging/

_redirects.yml

@@ -92,7 +92,7 @@
   - /go/attack-surface/
 "/build/buildkit/#getting-started":
   - /go/buildkit/
-"/build/install-buildx/":
+"/build/architecture/#install-buildx":
   # Instructions on installing Buildx. Redirect used in Docker CLI.
   - /go/buildx/
 "/engine/reference/commandline/compose_build/":

build/architecture.md

@@ -0,0 +1,101 @@
+---
+title: Docker Build architecture
+description: Learn about Docker Build and its components.
+keywords: build, buildkit, buildx, architecture
+---
+
+Docker Build implements a client-server architecture, where:
+
+- Buildx is the client and the user interface for running and managing builds
+- BuildKit is the server, or builder, that handles the build execution.
+
+![Build high-level architecture](./images/build-high-level-arch.png)
+
+As of Docker Engine 23.0 and Docker Desktop 4.19, Buildx is the default build
+client.
+
+## Buildx
+
+Buildx is a CLI tool that provides a user interface for working with builds.
+Buildx is a drop-in replacement for the legacy build client used in earlier
+versions of Docker Engine and Docker Desktop. In newer versions of Docker
+Desktop and Docker Engine, you're using Buildx by default when you invoke the
+`docker build` command. In earlier versions, to build using Buildx you would
+use the `docker buildx build` command.
+
+Buildx is more than just an updated `build` command. It also contains utilities
+for creating and managing [builders](#builders).
+
+### Install Buildx
+
+Docker Buildx is installed by default with Docker Desktop. Docker Engine
+version 23.0 and later requires that you install Buildx from a separate
+package. Buildx is included in the Docker Engine installation instructions, see
+[Install Docker Engine](../engine/install/index.md).
+
+You can also build the CLI plugin from source, or grab a binary from the GitHub
+repository and install it manually. See
+[docker/buildx README](https://github.com/docker/buildx#manual-download){: target="blank" rel="noopener"}
+for more information
+
+## Builders
+
+"Builder" is a term used to describe an instance of a BuildKit backend.
+
+A builder may run on the same system as the Buildx client, or it may run
+remotely, on a different system. You can run it as a single node, or as a cluster
+of nodes. Builder nodes may be containers, virtual machines, or physical machines.
+
+How and where you run your builders depends on your use case. Buildx implements
+a concept of [build drivers](./drivers/index.md) to refer to different types of
+builder configurations. Buildx supports the following drivers:
+
+- `docker`: uses the BuildKit library bundled into the Docker daemon.
+- `docker-container`: creates a dedicated BuildKit container using Docker.
+- `kubernetes`: creates BuildKit pods in a Kubernetes cluster.
+- `remote`: connects directly to a manually managed BuildKit daemon.
+
+You can create, append, and connect to builders and nodes using the
+[`docker buildx create` command](../engine/reference/commandline/buildx_create.md).
+
+## BuildKit
+
+BuildKit, or `buildkitd`, is the daemon process that executes the build
+workloads.
+
+A build execution starts with the invocation of a `docker build` command.
+Buildx interprets your build command and sends a build request to the BuildKit
+backend. The build request includes:
+
+- The Dockerfile
+- Build arguments
+- Export options
+- Caching options
+
+BuildKit resolves the build instruction and executes the build steps.
+For the duration of the build, Buildx monitors the build status and prints
+the progress to the terminal.
+
+If the build requires resources from the client, such as local files or build
+secrets, BuildKit requests the resources that it needs from Buildx.
+
+This is one way in which BuildKit is more efficient compared to the legacy
+builder it replaces. BuildKit only requests the resources that the build needs,
+when they're needed. The legacy builder, in comparison, always takes a copy of
+the local filesystem.
+
+Examples of resources that BuildKit can request from Buildx include:
+
+- Local filesystem build contexts
+- Build secrets
+- SSH sockets
+- Registry authentication tokens
+
+For more information about BuildKit, see [BuildKit](buildkit/index.md).
+
+## Example build sequence
+
+The following diagram shows an example build sequence involving Buildx and
+BuildKit.
+
+![Buildx and BuildKit sequence diagram](./images/build-execution.png)

build/buildkit/index.md

@@ -91,7 +91,7 @@ $ DOCKER_BUILDKIT=1 docker build .
 
 > **Note**
 >
-> [Buildx](../install-buildx.md) always uses BuildKit.
+> [Buildx](../architecture.md#buildx) always uses BuildKit.
 
 To use Docker BuildKit by default, edit the Docker daemon configuration in
 `/etc/docker/daemon.json` as follows, and restart the daemon.

build/guide/multi-platform.md

@@ -40,8 +40,7 @@ Buildx comes pre-bundled with Docker Desktop, and you can invoke this build
 client using the `docker buildx` command. No need for any additional setup. If
 you installed Docker Engine manually, you may need to install the Buildx plugin
 separately. See
-[Install Docker Buildx](https://docs.docker.com/build/buildx/install/) for
+[Install Docker Engine](../../engine/install/index.md) for instructions.
-instructions.
 
 Verify that the Buildx client is installed on your system, and that you’re able
 to run it:

build/index.md

@@ -3,7 +3,6 @@ title: Overview of Docker Build
 description: Introduction and overview of Docker Build
 keywords: build, buildx, buildkit
 redirect_from:
-  - /build/buildx/
   - /buildx/working-with-buildx/
   - /develop/develop-images/build_enhancements/
 ---
@@ -13,29 +12,7 @@ creating an image you are using Docker Build. Build is a key part of your
 software development life cycle allowing you to package and bundle your code and
 ship it anywhere.
 
-The Docker Engine uses a client-server architecture and is composed of multiple components
+Docker Build is more than a command for building images, and it's not only about
-and tools. The most common method of executing a build is by issuing a
-[`docker build` command](../engine/reference/commandline/build.md). The CLI
-sends the request to Docker Engine which, in turn, executes your build.
-
-There are now two components in Engine that can be used to build an image.
-Starting with the [18.09 release](../engine/release-notes/18.09.md#18090),
-Engine is shipped with Moby [BuildKit](buildkit/index.md), the new component for
-executing your builds by default.
-
-The new client [Docker Buildx](https://github.com/docker/buildx){:target="blank" rel="noopener" class=""}
-is a CLI plugin that extends the `docker` command with the full support of the
-features provided by [BuildKit](buildkit/index.md) builder toolkit.
-[`docker buildx build` command](../engine/reference/commandline/buildx_build.md)
-provides the same user experience as `docker build` with many new features like
-creating scoped [builder instances](drivers/index.md), building against
-multiple nodes concurrently, outputs configuration, inline
-[build caching](cache/index.md), and specifying target platform. In
-addition, Buildx also supports new features that aren't yet available for
-regular `docker build` like building manifest lists, distributed caching, and
-exporting build results to OCI image tarballs.
-
-Docker Build is more than a simple build command, and it's not only about
 packaging your code. It's a whole ecosystem of tools and features that support
 not only common workflow tasks but also provides support for more complex and
 advanced scenarios.
@@ -83,6 +60,32 @@ advanced scenarios.
     </div>
   </div>
   <div class="row">
+    <div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
+      <div class="component">
+        <div class="component-icon">
+          <a href="/build/architecture/">
+           <img src="/assets/images/explore.svg" alt="Compass" width="70px" height="70px">
+          </a>
+        </div>
+        <h2><a href="/build/architecture/">Architecture</a></h2>
+        <p>
+          Learn the Docker Build components.
+        </p>
+      </div>
+    </div>
+    <div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
+      <div class="component">
+        <div class="component-icon">
+          <a href="/build/buildkit/">
+           <img src="/assets/images/build-configure-buildkit.svg" alt="Hammer and screwdriver" width="70px" height="70px">
+          </a>
+        </div>
+        <h2><a href="/build/buildkit/">BuildKit</a></h2>
+        <p>
+          Explore BuildKit, the open source builder engine.
+        </p>
+      </div>
+    </div>
     <div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
       <div class="component">
         <div class="component-icon">
@@ -96,6 +99,8 @@ advanced scenarios.
         </p>
       </div>
     </div>
+  </div>
+  <div class="row">
     <div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
       <div class="component">
         <div class="component-icon">
@@ -122,8 +127,6 @@ advanced scenarios.
         </p>
       </div>
     </div>
-  </div>
-  <div class="row">
     <div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
       <div class="component">
         <div class="component-icon">
@@ -137,45 +140,5 @@ advanced scenarios.
         </p>
       </div>
     </div>
-    <div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
-      <div class="component">
-        <div class="component-icon">
-          <a href="/build/ci/">
-           <img src="/assets/images/build-ci.svg" alt="Infinity loop" width="70px" height="70px">
-          </a>
-        </div>
-        <h2><a href="/build/ci/">Continuous integration</a></h2>
-        <p>
-          Learn how to use Docker in your continuous integration pipelines.
-        </p>
-      </div>
-    </div>
-    <div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
-      <div class="component">
-        <div class="component-icon">
-          <a href="/build/dockerfile/frontend/">
-           <img src="/assets/images/build-frontends.svg" alt="Pen writing on a document" width="70px" height="70px">
-          </a>
-        </div>
-        <h2><a href="/build/dockerfile/frontend/">Dockerfile frontend</a></h2>
-        <p>
-          Learn about the Dockerfile frontend for BuildKit.
-        </p>
-      </div>
-    </div>
-    <div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
-      <div class="component">
-        <div class="component-icon">
-          <a href="/build/buildkit/configure/">
-           <img src="/assets/images/build-configure-buildkit.svg" alt="Hammer and screwdriver" width="70px" height="70px">
-          </a>
-        </div>
-        <h2><a href="/build/buildkit/configure/">Configure BuildKit</a></h2>
-        <p>
-          Take a deep dive into the internals of BuildKit to get the most out of
-          your builds.
-        </p>
-      </div>
-    </div>
   </div>
 </div>

build/install-buildx.md

@@ -1,85 +0,0 @@
----
-title: Install Docker Buildx
-description: How to install Docker Buildx
-keywords: build, buildx, buildkit
-redirect_from:
-  - /build/buildx/install/
----
-
-This page describes how to install Buildx, the CLI plugin for managing Docker builds.
-
-Buildx requires Docker Engine version 19.03 or later.
-
-## Docker Desktop
-
-Docker Buildx is included by default in Docker Desktop.
-
-## Docker Engine via package manager
-
-Docker Linux packages also include Docker Buildx when installed using the
-`.deb` or `.rpm` packages.
-
-## Install using a Dockerfile
-
-Here is how to install and use Buildx inside a Dockerfile through the
-[`docker/buildx-bin`](https://hub.docker.com/r/docker/buildx-bin){:target="blank" rel="noopener" class=""}
-image:
-
-```dockerfile
-# syntax=docker/dockerfile:1
-FROM docker
-COPY --from=docker/buildx-bin:latest /buildx /usr/libexec/docker/cli-plugins/docker-buildx
-RUN docker buildx version
-```
-
-## Download manually
-
-> **Important**
->
-> This section is for unattended installation of the Buildx component. These
-> instructions are mostly suitable for testing purposes. We do not recommend
-> installing Buildx using manual download in production environments as they
-> will not be updated automatically with security updates.
->
-> On Windows, macOS, and Linux workstations we recommend that you install
-> Docker Desktop instead. For Linux servers, we recommend that you follow the
-> instructions specific for your distribution.
-{: .important}
-
-You can also download the latest binary from the [releases page on GitHub](https://github.com/docker/buildx/releases/latest){:target="blank" rel="noopener" class="_"}.
-
-Rename the relevant binary and copy it to the destination matching your OS:
-
-| OS       | Binary name          | Destination folder                         |
-|----------|----------------------|--------------------------------------------|
-| Linux    | `docker-buildx`      | `$HOME/.docker/cli-plugins`                |
-| macOS    | `docker-buildx`      | `$HOME/.docker/cli-plugins`                |
-| Windows  | `docker-buildx.exe`  | `%USERPROFILE%\.docker\cli-plugins`        |
-
-Or copy it into one of these folders for installing it system-wide.
-
-On Unix environments:
-
-* `/usr/local/lib/docker/cli-plugins` OR `/usr/local/libexec/docker/cli-plugins`
-* `/usr/lib/docker/cli-plugins` OR `/usr/libexec/docker/cli-plugins`
-
-On Windows:
-
-* `C:\ProgramData\Docker\cli-plugins`
-* `C:\Program Files\Docker\cli-plugins`
-
-> **Note**
->
-> On Unix environments, it may also be necessary to make it executable with `chmod +x`:
-> ```shell
-> $ chmod +x ~/.docker/cli-plugins/docker-buildx
-> ```
-
-## Set Buildx as the default builder
-
-Running the command [`docker buildx install`](../engine/reference/commandline/buildx_install.md)
-sets up the `docker build` 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).

desktop/containerd/index.md

@@ -171,7 +171,7 @@ Inspecting the tag on Docker Hub shows that the image is available for multiple
     > `Multiple platforms feature is currently not supported for docker driver. Please switch to a different driver`.
     >
     > Install a newer version of Buildx following the instructions on
-    > [how to manually download Buildx](../../build/install-buildx/#download-manually).
+    > [how to manually download Buildx](../../build/architecture.md#install-buildx).
 
 - In Docker Desktop 4.12.0, the containerd image store feature is incompatible
   with the Kubernetes cluster support. Turn off the containerd image store