diff --git a/_config.yml b/_config.yml index 5239a2e033..89944f2540 100644 --- a/_config.yml +++ b/_config.yml @@ -170,6 +170,9 @@ fetch-remote: - dest: "build/bake" src: - "docs/guides/bake/**" + - dest: "build/buildx/drivers" + src: + - "docs/guides/drivers/**" - repo: "https://github.com/distribution/distribution" default_branch: "main" diff --git a/_data/toc.yaml b/_data/toc.yaml index e1ee422098..6ef9a30803 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1400,6 +1400,16 @@ manuals: title: Buildx overview - path: /build/buildx/install/ title: Install Buildx + - sectiontitle: Drivers + section: + - path: /build/buildx/drivers/ + title: Overview + - path: /build/buildx/drivers/docker-container/ + title: Docker container driver + - path: /build/buildx/drivers/kubernetes/ + title: Kubernetes driver + - path: /build/buildx/drivers/remote/ + title: Remote driver - path: /build/buildx/multiple-builders/ title: Using multiple builders - path: /build/buildx/multiplatform-images/ diff --git a/build/buildx/drivers/docker-container.md b/build/buildx/drivers/docker-container.md new file mode 100644 index 0000000000..de11b89f52 --- /dev/null +++ b/build/buildx/drivers/docker-container.md @@ -0,0 +1,7 @@ +--- +title: "Docker container driver" +keywords: build, buildx, driver, builder, docker-container +fetch_remote: + line_start: 2 + line_end: -1 +--- diff --git a/build/buildx/drivers/index.md b/build/buildx/drivers/index.md new file mode 100644 index 0000000000..0be093e099 --- /dev/null +++ b/build/buildx/drivers/index.md @@ -0,0 +1,7 @@ +--- +title: "Buildx drivers overview" +keywords: build, buildx, driver, builder, docker-container, kubernetes, remote +fetch_remote: + line_start: 2 + line_end: -1 +--- diff --git a/build/buildx/drivers/kubernetes.md b/build/buildx/drivers/kubernetes.md new file mode 100644 index 0000000000..d89d6e7ac7 --- /dev/null +++ b/build/buildx/drivers/kubernetes.md @@ -0,0 +1,7 @@ +--- +title: "Kubernetes driver" +keywords: build, buildx, driver, builder, kubernetes +fetch_remote: + line_start: 2 + line_end: -1 +--- diff --git a/build/buildx/drivers/remote.md b/build/buildx/drivers/remote.md new file mode 100644 index 0000000000..e3eb1cdccf --- /dev/null +++ b/build/buildx/drivers/remote.md @@ -0,0 +1,22 @@ +--- +title: "Remote driver" +keywords: build, buildx, driver, builder, remote +fetch_remote: + line_start: 2 + line_end: -1 +--- + +> Beta +> +> Remote driver is currently available as a beta feature. We recommend that you +> do not use this feature in production environments. You can [build Buildx from source](https://github.com/docker/buildx#building){: target="_blank" rel="noopener" class="_"} +> to test the remote driver or use the following command to download and +> install an edge release of Buildx: +> +> ```console +> $ echo "FROM docker/buildx-bin:master" | docker buildx build --platform=local --output . -f - . +> $ mkdir -p ~/.docker/cli-plugins/ +> $ mv buildx ~/.docker/cli-plugins/docker-buildx +> ``` +{: .important} + diff --git a/build/buildx/index.md b/build/buildx/index.md index 775b92a26a..a7fc32357e 100644 --- a/build/buildx/index.md +++ b/build/buildx/index.md @@ -34,19 +34,18 @@ 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. +Buildx is flexible and can be run in different configurations that are exposed +through various "drivers". Each driver defines how and where a build should +run, and have different feature sets. -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`. +We currently support the following drivers: +* The `docker` driver ([reference](/engine/reference/commandline/buildx_create/#driver)) +* The `docker-container` driver ([guide](drivers/docker-container.md), [reference](/engine/reference/commandline/buildx_create/#driver)) +* The `kubernetes` driver ([guide](drivers/kubernetes.md), [reference](/engine/reference/commandline/buildx_create/#driver)) +* The `remote` driver ([guide](drivers/remote.md)) + +For more information on drivers, see the [drivers guide](drivers/index.md). ## High-level build options with Bake diff --git a/build/buildx/install.md b/build/buildx/install.md index b2fe45d0ff..0f33bd4012 100644 --- a/build/buildx/install.md +++ b/build/buildx/install.md @@ -75,4 +75,4 @@ 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). \ No newline at end of file +To remove this alias, run [`docker buildx uninstall`](../../engine/reference/commandline/buildx_uninstall.md). diff --git a/build/buildx/multiplatform-images.md b/build/buildx/multiplatform-images.md index 9f0b3fc87e..21fda31c31 100644 --- a/build/buildx/multiplatform-images.md +++ b/build/buildx/multiplatform-images.md @@ -3,6 +3,7 @@ title: Building multi-platform images description: Different strategies for building multi-platform images keywords: build, buildx, buildkit, 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. @@ -75,4 +76,4 @@ ARG BUILDPLATFORM RUN echo "I am running on $BUILDPLATFORM, building for $TARGETPLATFORM" > /log FROM alpine COPY --from=build /log /log -``` \ No newline at end of file +``` diff --git a/build/buildx/multiple-builders.md b/build/buildx/multiple-builders.md index 4a68cf1555..7aebd879d0 100644 --- a/build/buildx/multiple-builders.md +++ b/build/buildx/multiple-builders.md @@ -3,6 +3,7 @@ title: Using multiple builders description: How to instantiate and work with multiple builders keywords: build, buildx, buildkit, builders, build drivers --- + 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. @@ -33,4 +34,4 @@ Docker also features a [`docker context`](../../engine/reference/commandline/con 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. \ No newline at end of file +you create a new builder instance or when you add a node to it. diff --git a/build/index.md b/build/index.md index 529cd1e406..085349c41f 100644 --- a/build/index.md +++ b/build/index.md @@ -40,18 +40,15 @@ Bundle and package your code to run anywhere, from your local Docker Desktop, to To get started with Build, see the [Hello Build](hellobuild.md) page. * **Choosing a build driver** -Run Buildx with different configurations depending on the scenario you are working on, regardless of whether you are using your local machine or a remote compute cluster, all from the comfort of your local working environment. -Here’s a quick overview of the drivers and the use cases they support: - * `docker`– use the default built-in builder to get started quickly. - * `docker-container` – spin up a dedicated builder in a docker container to unlock more advanced features like advanced caching, and multi-platform images. - - * `kubernetes`– connect to your Kubernetes cluster to unlock more features and to run your builds at scale. - * `remote`– manually manage your own BuildKit builder and connect directly to it. +Run Buildx with different configurations depending on the scenario you are +working on, regardless of whether you are using your local machine or a remote +compute cluster, all from the comfort of your local working environment. +For more information on drivers, see the [drivers guide](buildx/drivers/index.md). * **Optimizing builds with cache management** Improve build performance by using a persistent shared build cache to avoid repeating costly operations such as package installations, downloading files from the internet, or code build steps. -* **Creating build-once, run-anywhere with multi-architecture builds** +* **Creating build-once, run-anywhere with multi-platform builds** Collaborate across platforms with one build artifact. See [Build multi-platform images](buildx/multiplatform-images.md).