docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

working-with-buildx: wrap, remove experimental, and some updates 

- remove the experimental banner
- moved the "install as default builder section under the install
  section
- wrapped lines to be ~80 chars
- created some links to reference pages

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn 2021-03-26 17:26:47 +01:00
parent 1898b1b09c
commit 19ede730f6
No known key found for this signature in database
GPG Key ID: 76698F39D527CE8C
1 changed files with 109 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

150
buildx/working-with-buildx.md
View File

@ -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
- Docker Desktop Edge version 2.0.4.0 or higher
You can also download the latest `buildx` binary from the
[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.
## Set `buildx` as the default builder
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`.
The `bake` command supports building images from compose files, similar to
[`docker-compose build`](../compose/reference/build.md), but allowing all the
services to be built concurrently as part of a single request.