Docker CLI plugin for extended build capabilities with BuildKit
Go to file
Tonis Tiigi c46407b2d3
docs: reference docs updates
Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2021-03-25 00:44:17 +01:00
.github ci: enable building darwin/arm64 in CI 2021-02-04 19:00:41 -08:00
bake bake: allow variables to reference each other 2021-03-07 21:27:30 -08:00
build don't require entitlement for network none 2021-02-04 22:45:20 -08:00
cmd/buildx vendor: update buildkit with typed errors support 2020-09-13 21:28:20 -07:00
commands imagetools inspect: don't discard errors from PrintManifestList 2021-03-24 15:54:32 +01:00
docs docs: reference docs updates 2021-03-25 00:44:17 +01:00
driver set DefaultRootlessImage to "moby/buildkit:buildx-stable-1-rootless" 2020-12-16 17:35:38 +09:00
hack update lint to go1.16/golangci 2021-02-16 23:43:06 -08:00
store Allow users to have separate store paths 2020-09-10 17:14:41 +01:00
util Add quiet mode to progress printer 2021-03-09 17:12:46 -03:00
vendor vendor: update buildkit to 8effd45b 2021-03-22 15:54:07 -07:00
version rename to docker/buildx 2019-04-24 20:02:20 -07:00
.dockerignore hack: add cross target 2019-03-22 18:05:05 -07:00
.gitignore GitHub Actions for test 2020-12-05 04:18:28 +01:00
.golangci.yml update lint to go1.16/golangci 2021-02-16 23:43:06 -08:00
.mailmap Add maintainers and authors 2019-05-24 17:33:28 -07:00
.yamllint.yml Refactor validate for GitHub Actions 2020-11-30 08:14:28 +01:00
AUTHORS Add maintainers and authors 2019-05-24 17:33:28 -07:00
Dockerfile Dockerfile: update to go1.16 2021-02-16 23:42:59 -08:00
LICENSE Add LICENSE file 2019-05-24 17:35:34 -07:00
MAINTAINERS add akihiro and crazy-max to maintainers 2021-02-10 09:18:05 -08:00
Makefile avoid cp in install target 2021-02-04 13:29:16 -08:00
README.md docs: split reference docs to separate files 2021-03-25 00:37:53 +01:00
codecov.yml GitHub Actions for test 2020-12-05 04:18:28 +01:00
go.mod vendor: update buildkit to 8effd45b 2021-03-22 15:54:07 -07:00
go.sum vendor: update buildkit to 8effd45b 2021-03-22 15:54:07 -07:00

README.md

buildx

PkgGoDev Build Status Go Report Card codecov

buildx is a Docker CLI plugin for extended build capabilities with BuildKit.

Key features:

  • Familiar UI from docker build
  • Full BuildKit capabilities with container driver
  • Multiple builder instance support
  • Multi-node builds for cross-platform images
  • Compose build support
  • WIP: High-level build constructs (bake)
  • In-container driver support (both Docker and Kubernetes)

Table of Contents

Installing

Using buildx as a docker CLI plugin requires using Docker 19.03. A limited set of functionality works with older versions of Docker when invoking the binary directly.

Docker CE

buildx comes bundled with Docker CE starting with 19.03, but requires experimental mode to be enabled on the Docker CLI. To enable it, "experimental": "enabled" can be added to the CLI configuration file ~/.docker/config.json. An alternative is to set the DOCKER_CLI_EXPERIMENTAL=enabled environment variable.

Binary release

Download the latest binary release from https://github.com/docker/buildx/releases/latest and copy it to ~/.docker/cli-plugins folder with name docker-buildx.

Change the permission to execute:

chmod a+x ~/.docker/cli-plugins/docker-buildx

Building

with Docker 18.09+

$ git clone git://github.com/docker/buildx && cd buildx
$ make install

with buildx or Docker 19.03

$ export DOCKER_BUILDKIT=1
$ docker build --platform=local -o . git://github.com/docker/buildx
$ mkdir -p ~/.docker/cli-plugins
$ mv buildx ~/.docker/cli-plugins/docker-buildx

Getting started

Building with buildx

Buildx is a Docker CLI plugin that extends the docker build command with the full support of the features provided by 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.

After installation, buildx can be accessed through the docker buildx command with Docker 19.03. docker buildx build is the command for starting a new build. With Docker versions older than 19.03 buildx binary can be called directly to access the docker buildx subcommands.

$ docker buildx build .
[+] Building 8.4s (23/32)
 => ...

Buildx will always build using the BuildKit engine and does not require DOCKER_BUILDKIT=1 environment variable for starting builds.

Buildx build command supports the features available for docker build including the new features in Docker 19.03 such as outputs configuration, inline build caching or specifying target platform. In addition, buildx supports new features not yet available for regular docker build like building manifest lists, distributed caching, exporting build results to OCI image tarballs etc.

Buildx is supposed to be flexible and can be run in different configurations that are exposed through a driver concept. Currently, we support 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. We plan to add more drivers in the future, for example, one that would allow running buildx inside an (unprivileged) container.

The user experience of using buildx is very similar across drivers, but there are some features that are not currently supported by the "docker" driver, because the BuildKit library bundled into docker daemon currently uses a different storage component. In contrast, all images built with "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.

Working with builder instances

By default, buildx will initially use the "docker" driver if it is supported, providing a very similar user experience to the native docker build. But using a local shared daemon is only one way to build your applications.

Buildx allows you to create new instances of isolated builders. This can be used for getting a scoped environment for your CI builds that does not change the state of the shared daemon or for isolating the 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.

New instances can be created with docker buildx create command. This will create 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 remote context name while creating the new builder. After creating a new instance you can manage its lifecycle with the inspect, stop and rm commands and list all available builders with ls. 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 would automatically keep using this builder.

Docker 19.03 also features a new docker context command that can be used for giving names for remote Docker API endpoints. Buildx integrates with docker context so that all of your contexts automatically get a default builder instance. While creating a new builder instance or when adding a node to it you can also set the context name as the target.

Building 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.

When invoking a build, the --platform flag can be used to specify the target platform for the build output, (e.g. linux/amd64, linux/arm64, darwin/amd64). When the current builder instance is backed by the "docker-container" driver, multiple platforms can be specified together. In this case, a manifest list will be built, containing images for all of the specified architectures. When this image is used in docker run or docker service, Docker will pick the correct image based on the nodes platform.

Multi-platform images can be built by mainly three different strategies that are all supported by buildx and Dockerfiles. You can use the QEMU emulation support in the kernel, build on multiple native nodes using the same builder instance or use a stage in Dockerfile to cross-compile to different architectures.

QEMU is the easiest way to get started if your node already supports it (e.g. if you are using Docker Desktop). It requires no changes to your Dockerfile and BuildKit will automatically detect the secondary architectures that are available. When BuildKit needs to run a binary for a different architecture it will automatically load it through a binary registered in the binfmt_misc handler. For QEMU binaries registered with binfmt_misc on the host OS to work transparently inside containers they must be registered with the fix_binary flag. This requires a kernel >= 4.8 and binfmt-support >= 2.1.7. You can check for proper registration by checking if F is among the flags in /proc/sys/fs/binfmt_misc/qemu-*. While Docker Desktop comes preconfigured with binfmt_misc support for additional platforms, for other installations it likely needs to be installed using tonistiigi/binfmt image.

$ docker run --privileged --rm tonistiigi/binfmt --install all

Using multiple native nodes provides better support for more complicated cases not handled by QEMU and generally have better performance. Additional nodes can be added to the builder instance with --append flag.

# assuming contexts node-amd64 and node-arm64 exist in "docker context ls"
$ 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. List of build arguments like BUILDPLATFORM and TARGETPLATFORM are available automatically inside your Dockerfile and can be leveraged by the processes running as part of your build.

FROM --platform=$BUILDPLATFORM golang:alpine AS build
ARG TARGETPLATFORM
ARG BUILDPLATFORM
RUN echo "I am running on $BUILDPLATFORM, building for $TARGETPLATFORM" > /log
FROM alpine
COPY --from=build /log /log

High-level build options

Buildx also aims to provide support for higher level build concepts that go beyond invoking a single build command. We want to support building all the images in your application together and let the users define project specific reusable build flows that can then be easily invoked by anyone.

BuildKit has great support for efficiently handling multiple concurrent build requests and deduplicating work. While build commands can be combined with general-purpose command runners (eg. make), these tools generally invoke builds in sequence and therefore cant leverage the full potential of BuildKit parallelization or combine BuildKits output for the user. For this use case we have added a command called docker buildx bake.

Currently, the bake command supports building images from compose files, similar to compose build but allowing all the services to be built concurrently as part of a single request.

There is also support for custom build rules from HCL/JSON files allowing better code reuse and different target groups. The design of bake is in very early stages and we are looking for feedback from users.

Setting buildx as default builder in Docker 19.03+

Running docker buildx install sets up docker builder command as an alias to docker buildx. This results in the ability to have docker build use the current buildx builder.

To remove this alias, you can run docker buildx uninstall.

Contributing

Want to contribute to Buildx? Awesome! You can find information about contributing to this project in the CONTRIBUTING.md