diff --git a/README.md b/README.md index 1680a6eb..885f6956 100644 --- a/README.md +++ b/README.md @@ -184,14 +184,18 @@ 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 and a -[`kubernetes` driver](docs/reference/buildx_create.md#kubernetes-driver) to -spin up pods with defined BuildKit container image to build your images. We -plan to add more drivers in the future. +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, diff --git a/docs/generate.go b/docs/generate.go index dee56cc7..f48a3cc2 100644 --- a/docs/generate.go +++ b/docs/generate.go @@ -16,6 +16,7 @@ import ( _ "github.com/docker/buildx/driver/docker" _ "github.com/docker/buildx/driver/docker-container" _ "github.com/docker/buildx/driver/kubernetes" + _ "github.com/docker/buildx/driver/remote" ) const defaultSourcePath = "docs/reference/" diff --git a/docs/reference/buildx_create.md b/docs/reference/buildx_create.md index bd9ea1c4..a30adb48 100644 --- a/docs/reference/buildx_create.md +++ b/docs/reference/buildx_create.md @@ -15,7 +15,7 @@ Create a new builder instance | `--bootstrap` | | | Boot builder after creation | | [`--buildkitd-flags`](#buildkitd-flags) | `string` | | Flags for buildkitd daemon | | [`--config`](#config) | `string` | | BuildKit config file | -| [`--driver`](#driver) | `string` | | Driver to use (available: `docker`, `docker-container`, `kubernetes`) | +| [`--driver`](#driver) | `string` | | Driver to use (available: `docker`, `docker-container`, `kubernetes`, `remote`) | | [`--driver-opt`](#driver-opt) | `stringArray` | | Options for the driver | | [`--leave`](#leave) | | | Remove a node from builder instead of changing it | | [`--name`](#name) | `string` | | Builder instance name | @@ -118,36 +118,59 @@ Unlike `docker` driver, built images will not automatically appear in `docker images` and [`build --load`](buildx_build.md#load) needs to be used to achieve that. +#### `remote` driver + +Uses a remote instance of buildkitd over an arbitrary connection. With this +driver, you manually create and manage instances of buildkit yourself, and +configure buildx to point at it. + +Unlike `docker` driver, built images will not automatically appear in +`docker images` and [`build --load`](buildx_build.md#load) needs to be used +to achieve that. + ### Set additional driver-specific options (--driver-opt) ``` --driver-opt OPTIONS ``` -Passes additional driver-specific options. Details for each driver: +Passes additional driver-specific options. -- `docker` - No driver options -- `docker-container` - - `image=IMAGE` - Sets the container image to be used for running buildkit. - - `network=NETMODE` - Sets the network mode for running the buildkit container. - - `cgroup-parent=CGROUP` - Sets the cgroup parent of the buildkit container if docker is using the "cgroupfs" driver. Defaults to `/docker/buildx`. -- `kubernetes` - - `image=IMAGE` - Sets the container image to be used for running buildkit. - - `namespace=NS` - Sets the Kubernetes namespace. Defaults to the current namespace. - - `replicas=N` - Sets the number of `Pod` replicas. Defaults to 1. - - `requests.cpu` - Sets the request CPU value specified in units of Kubernetes CPU. Example `requests.cpu=100m`, `requests.cpu=2` - - `requests.memory` - Sets the request memory value specified in bytes or with a valid suffix. Example `requests.memory=500Mi`, `requests.memory=4G` - - `limits.cpu` - Sets the limit CPU value specified in units of Kubernetes CPU. Example `limits.cpu=100m`, `limits.cpu=2` - - `limits.memory` - Sets the limit memory value specified in bytes or with a valid suffix. Example `limits.memory=500Mi`, `limits.memory=4G` - - `"nodeselector=label1=value1,label2=value2"` - Sets the kv of `Pod` nodeSelector. No Defaults. Example `nodeselector=kubernetes.io/arch=arm64` - - `"tolerations=key=foo,value=bar;key=foo2,operator=exists;key=foo3,effect=NoSchedule"` - Sets the `Pod` tolerations. Accepts the same values as the kube manifest tolerations. Key-value pairs are separated by `,`, tolerations are separated by `;`. No Defaults. Example `tolerations=operator=exists` - - `rootless=(true|false)` - Run the container as a non-root user without `securityContext.privileged`. Needs Kubernetes 1.19 or later. [Using Ubuntu host kernel is recommended](https://github.com/moby/buildkit/blob/master/docs/rootless.md). Defaults to false. - - `loadbalance=(sticky|random)` - Load-balancing strategy. If set to "sticky", the pod is chosen using the hash of the context path. Defaults to "sticky" - - `qemu.install=(true|false)` - Install QEMU emulation for multi platforms support. - - `qemu.image=IMAGE` - Sets the QEMU emulation image. Defaults to `tonistiigi/binfmt:latest` +Note: When using quoted values for example for the `nodeselector` or +`tolerations` options, ensure that quotes are escaped correctly for your shell. -Note: When using quoted values for example for the `nodeselector` or `tolerations` options, ensure that quotes are escaped -correctly for your shell. +#### `docker` driver + +No driver options. + +#### `docker-container` driver + +- `image=IMAGE` - Sets the container image to be used for running buildkit. +- `network=NETMODE` - Sets the network mode for running the buildkit container. +- `cgroup-parent=CGROUP` - Sets the cgroup parent of the buildkit container if docker is using the "cgroupfs" driver. Defaults to `/docker/buildx`. + +#### `kubernetes` driver + +- `image=IMAGE` - Sets the container image to be used for running buildkit. +- `namespace=NS` - Sets the Kubernetes namespace. Defaults to the current namespace. +- `replicas=N` - Sets the number of `Pod` replicas. Defaults to 1. +- `requests.cpu` - Sets the request CPU value specified in units of Kubernetes CPU. Example `requests.cpu=100m`, `requests.cpu=2` +- `requests.memory` - Sets the request memory value specified in bytes or with a valid suffix. Example `requests.memory=500Mi`, `requests.memory=4G` +- `limits.cpu` - Sets the limit CPU value specified in units of Kubernetes CPU. Example `limits.cpu=100m`, `limits.cpu=2` +- `limits.memory` - Sets the limit memory value specified in bytes or with a valid suffix. Example `limits.memory=500Mi`, `limits.memory=4G` +- `"nodeselector=label1=value1,label2=value2"` - Sets the kv of `Pod` nodeSelector. No Defaults. Example `nodeselector=kubernetes.io/arch=arm64` +- `"tolerations=key=foo,value=bar;key=foo2,operator=exists;key=foo3,effect=NoSchedule"` - Sets the `Pod` tolerations. Accepts the same values as the kube manifest tolera>tions. Key-value pairs are separated by `,`, tolerations are separated by `;`. No Defaults. Example `tolerations=operator=exists` +- `rootless=(true|false)` - Run the container as a non-root user without `securityContext.privileged`. Needs Kubernetes 1.19 or later. [Using Ubuntu host kernel is recommended](https://github.com/moby/buildkit/blob/master/docs/rootless.md). Defaults to false. +- `loadbalance=(sticky|random)` - Load-balancing strategy. If set to "sticky", the pod is chosen using the hash of the context path. Defaults to "sticky" +- `qemu.install=(true|false)` - Install QEMU emulation for multi platforms support. +- `qemu.image=IMAGE` - Sets the QEMU emulation image. Defaults to `tonistiigi/binfmt:latest` + +#### `remote` driver + +- `key=KEY` - Sets the TLS client key. +- `cert=CERT` - Sets the TLS client certificate to present to buildkitd. +- `cacert=CACERT` - Sets the TLS certificate authority used for validation. +- `servername=SERVER` - Sets the TLS server name to be used in requests (defaults to the endpoint hostname). ### Remove a node from a builder (--leave)