diff --git a/README.md b/README.md index 0f8189f1..319c7689 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ Key features: - [Using a custom registry configuration](docs/guides/custom-registry-config.md) - [OpenTelemetry support](docs/guides/opentelemetry.md) - [Registry mirror](docs/guides/registry-mirror.md) - - [Remote builder](docs/guides/remote-builder.md) + - [Drivers](docs/guides/drivers/index.md) - [Resource limiting](docs/guides/resource-limiting.md) - [Reference](docs/reference/buildx.md) - [`buildx bake`](docs/reference/buildx_bake.md) @@ -185,27 +185,17 @@ 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. -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](docs/reference/buildx_create.md#docker-driver) that uses - the BuildKit library bundled into the Docker daemon binary, -- a [`docker-container` driver](docs/reference/buildx_create.md#docker-container-driver) - that automatically launches BuildKit inside a Docker container, -- a [`kubernetes` driver](docs/reference/buildx_create.md#kubernetes-driver) to - spin up pods with defined BuildKit container image to build your images. -- a [`remote` driver](docs/reference/buildx_create.md#remote-driver) to - connect to manually provisioned and managed buildkitd instances. - -We plan to add more drivers in the future. - -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`. +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. + +We currently support the following drivers: +- The `docker` driver ([reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver)) +- The `docker-container` driver ([guide](./docker-container.md), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver)) +- The `kubernetes` driver ([guide](./kubernetes.md), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver)) +- The `remote` driver ([guide](./remote.md)) + +For more information on drivers, see the [drivers guide](docs/guides/drivers/index.md). ## Working with builder instances diff --git a/docs/guides/drivers/index.md b/docs/guides/drivers/index.md new file mode 100644 index 00000000..898b6946 --- /dev/null +++ b/docs/guides/drivers/index.md @@ -0,0 +1,41 @@ +# Buildx drivers overview + +The buildx client connects out to the BuildKit backend to execute builds - +Buildx drivers allow fine-grained control over management of the backend, and +supports several different options for where and how BuildKit should run. + +Currently, we support the following drivers: + +- The `docker` driver, that uses the BuildKit library bundled into the Docker + daemon. + ([reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver)) +- The `docker-container` driver, that launches a dedicated BuildKit container + using Docker, for access to advanced features. + ([guide](./docker-container.md), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver)) +- The `kubernetes` driver, that launches dedicated BuildKit pods in a + remote Kubernetes cluster, for scalable builds. + ([guide](./kubernetes.md), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver)) +- The `remote` driver, that allows directly connecting to a manually managed + BuildKit daemon, for more custom setups. + ([guide](./remote.md)) + + + +To create a new builder that uses one of the above drivers, you can use the +[`docker buildx create`](https://docs.docker.com/engine/reference/commandline/buildx_create/) command: + +```console +$ docker buildx create --name= --driver= --driver-opt= +``` + +The build experience is very similar across drivers, however, there are some +features that are not evenly supported across the board, notably, the `docker` +driver does not include support for certain output/caching types. + +| Feature | `docker` | `docker-container` | `kubernetes` | `remote` | +| :---------------------------- | :-------------: | :----------------: | :----------: | :--------------------: | +| **Automatic `--load`** | ✅ | ❌ | ❌ | ❌ | +| **Cache export** | ❔ (inline only) | ✅ | ✅ | ✅ | +| **Docker/OCI tarball output** | ❌ | ✅ | ✅ | ✅ | +| **Multi-arch images** | ❌ | ✅ | ✅ | ✅ | +| **BuildKit configuration** | ❌ | ✅ | ✅ | ❔ (managed externally) | diff --git a/docs/guides/kubernetes-builder.md b/docs/guides/drivers/kubernetes.md similarity index 99% rename from docs/guides/kubernetes-builder.md rename to docs/guides/drivers/kubernetes.md index aa856be2..240256fb 100644 --- a/docs/guides/kubernetes-builder.md +++ b/docs/guides/drivers/kubernetes.md @@ -1,4 +1,4 @@ -# Kubernetes builder +# Kubernetes driver The buildx kubernetes driver allows connecting your local development or ci environments to your kubernetes cluster to allow access to more powerful diff --git a/docs/guides/remote-builder.md b/docs/guides/drivers/remote.md similarity index 99% rename from docs/guides/remote-builder.md rename to docs/guides/drivers/remote.md index 7caf5825..5e61245b 100644 --- a/docs/guides/remote-builder.md +++ b/docs/guides/drivers/remote.md @@ -1,4 +1,4 @@ -# Remote builder +# Remote driver The buildx remote driver allows for more complex custom build workloads that allow users to connect to external buildkit instances. This is useful for