diff --git a/_data/toc.yaml b/_data/toc.yaml index c8479960c9..87076ed49b 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1623,8 +1623,8 @@ manuals: section: - path: /build/ title: Overview - - path: /build/install-buildx/ - title: Install Buildx + - path: /build/architecture/ + title: Architecture - sectiontitle: Building images section: - path: /build/building/packaging/ diff --git a/_redirects.yml b/_redirects.yml index a6bd7461e5..9e6f7d51d7 100644 --- a/_redirects.yml +++ b/_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/": diff --git a/build/architecture.md b/build/architecture.md new file mode 100644 index 0000000000..2699e3a881 --- /dev/null +++ b/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) diff --git a/build/buildkit/index.md b/build/buildkit/index.md index 5a75b6a95a..9d484c72a6 100644 --- a/build/buildkit/index.md +++ b/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. diff --git a/build/guide/multi-platform.md b/build/guide/multi-platform.md index 66aff74c05..97cc877ab0 100644 --- a/build/guide/multi-platform.md +++ b/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 -instructions. +[Install Docker Engine](../../engine/install/index.md) for instructions. Verify that the Buildx client is installed on your system, and that you’re able to run it: diff --git a/build/images/build-execution.png b/build/images/build-execution.png new file mode 100644 index 0000000000..5138441af2 Binary files /dev/null and b/build/images/build-execution.png differ diff --git a/build/images/build-high-level-arch.png b/build/images/build-high-level-arch.png new file mode 100644 index 0000000000..9c5c54f1e9 Binary files /dev/null and b/build/images/build-high-level-arch.png differ diff --git a/build/index.md b/build/index.md index 950931f9ca..4f066b7bef 100644 --- a/build/index.md +++ b/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 -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 +Docker Build is more than a command for building images, 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.
+
+
+
+ + Compass + +
+

Architecture

+

+ Learn the Docker Build components. +

+
+
+
+
+
+ + Hammer and screwdriver + +
+

BuildKit

+

+ Explore BuildKit, the open source builder engine. +

+
+
@@ -96,6 +99,8 @@ advanced scenarios.

+
+
@@ -122,8 +127,6 @@ advanced scenarios.

-
-
@@ -137,45 +140,5 @@ advanced scenarios.

-
-
-
- - Infinity loop - -
-

Continuous integration

-

- Learn how to use Docker in your continuous integration pipelines. -

-
-
-
-
-
- - Pen writing on a document - -
-

Dockerfile frontend

-

- Learn about the Dockerfile frontend for BuildKit. -

-
-
-
-
-
- - Hammer and screwdriver - -
-

Configure BuildKit

-

- Take a deep dive into the internals of BuildKit to get the most out of - your builds. -

-
-
diff --git a/build/install-buildx.md b/build/install-buildx.md deleted file mode 100644 index 492ae58ac7..0000000000 --- a/build/install-buildx.md +++ /dev/null @@ -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). diff --git a/desktop/containerd/index.md b/desktop/containerd/index.md index bbb29e7d8c..1b5ca20603 100644 --- a/desktop/containerd/index.md +++ b/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