From f51884e89325bd91ae5d5f48b9f302c616ce8d8a Mon Sep 17 00:00:00 2001 From: David Karlsson Date: Tue, 4 Oct 2022 13:20:14 +0200 Subject: [PATCH] address review comments Signed-off-by: David Karlsson --- docs/guides/drivers/docker-container.md | 17 ++++++----- docs/guides/drivers/index.md | 14 ++++----- docs/guides/drivers/kubernetes.md | 40 ++++++++++++------------- docs/guides/drivers/remote.md | 6 ++-- 4 files changed, 38 insertions(+), 39 deletions(-) diff --git a/docs/guides/drivers/docker-container.md b/docs/guides/drivers/docker-container.md index 6ca9ffa5..24ccd6b1 100644 --- a/docs/guides/drivers/docker-container.md +++ b/docs/guides/drivers/docker-container.md @@ -17,7 +17,10 @@ Run the following command to create a new builder, named `container`, that uses the Docker container driver: ```console -$ docker buildx create --name container --driver docker-container +$ docker buildx create \ + --name container \ + --driver=docker-container \ + --driver-opt=[key=value,...] container ``` @@ -26,13 +29,14 @@ pass to `--driver-opt`: | Parameter | Value | Default | Description | | --------------- | ------ | ---------------- | ------------------------------------------------------------------------------------------ | -| `image` | string | | Sets the image to use for running BuildKit. | -| `network` | string | | Sets the network mode for running the BuildKit container. | -| `cgroup-parent` | string | `/docker/buildx` | Sets the cgroup parent of the BuildKit container if Docker is using the `cgroupfs` driver. | +| `image` | String | | Sets the image to use for running BuildKit. | +| `network` | String | | Sets the network mode for running the BuildKit container. | +| `cgroup-parent` | String | `/docker/buildx` | Sets the cgroup parent of the BuildKit container if Docker is using the `cgroupfs` driver. | ## Usage -When you run a build, Buildx pulls the specified `image` (by default, [`moby/buildkit`](https://hub.docker.com/r/moby/buildkit)) +When you run a build, Buildx pulls the specified `image` (by default, +[`moby/buildkit`](https://hub.docker.com/r/moby/buildkit)) [Docker Hub](https://hub.docker.com/u/moby/buildkit). When the container has started, Buildx submits the build submitted to the containerized build server. @@ -99,6 +103,3 @@ $ docker buildx build . \ For more information on the Docker container driver, see the [buildx reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver). - -If want to explore builders running on a remote server, see the -[Kubernetes driver](./kubernetes.md) and the [Remote driver](./remote.md). diff --git a/docs/guides/drivers/index.md b/docs/guides/drivers/index.md index f36d1ce6..62b2f635 100644 --- a/docs/guides/drivers/index.md +++ b/docs/guides/drivers/index.md @@ -12,19 +12,17 @@ Buildx supports the following drivers: Different drivers support different use cases. The default `docker` driver prioritizes simplicity and ease of use. It has limited support for advanced features like caching and output formats, and isn't configurable. Other drivers -provide more flexibility and are better at handling advanced scenarios. The -`kubernetes` and `remote` drivers specifically aim to enable remote builders. +provide more flexibility and are better at handling advanced scenarios. The following table outlines some of the differences between drivers. | Feature | `docker` | `docker-container` | `kubernetes` | `remote` | | :--------------------------- | :---------: | :----------------: | :----------: | :----------------: | -| **Automatically load image** | Yes | No | No | No | -| **Cache export** | Inline only | Yes | Yes | Yes | -| **Remote builders** | No | No | Yes | Yes | -| **Tarball output** | No | Yes | Yes | Yes | -| **Multi-arch images** | No | Yes | Yes | Yes | -| **BuildKit configuration** | No | Yes | Yes | Managed externally | +| **Automatically load image** | ✅ | | | | +| **Cache export** | Inline only | ✅ | ✅ | ✅ | +| **Tarball output** | | ✅ | ✅ | ✅ | +| **Multi-arch images** | | ✅ | ✅ | ✅ | +| **BuildKit configuration** | | ✅ | ✅ | Managed externally | ## List available builders diff --git a/docs/guides/drivers/kubernetes.md b/docs/guides/drivers/kubernetes.md index d871a212..a1f187fd 100644 --- a/docs/guides/drivers/kubernetes.md +++ b/docs/guides/drivers/kubernetes.md @@ -20,21 +20,21 @@ $ docker buildx create \ The following table describes the available driver-specific options that you can pass to `--driver-opt`: -| Parameter | Value | Default | Description | -| ----------------- | ---------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| `image` | String | | Sets the image to use for running BuildKit. | -| `namespace` | String | Namespace in current Kubernetes context | Sets the Kubernetes namespace. | -| `replicas` | Integer | 1 | Sets the number of Pod replicas to create. See [scaling BuildKit][1] | -| `requests.cpu` | CPU units | | Sets the request CPU value specified in units of Kubernetes CPU. For example `requests.cpu=100m` or `requests.cpu=2` | -| `requests.memory` | Memory size | | Sets the request memory value specified in bytes or with a valid suffix. For example `requests.memory=500Mi` or `requests.memory=4G` | -| `limits.cpu` | CPU units | | Sets the limit CPU value specified in units of Kubernetes CPU. For example `requests.cpu=100m` or `requests.cpu=2` | -| `limits.memory` | Memory size | | Sets the limit memory value specified in bytes or with a valid suffix. For example `requests.memory=500Mi` or `requests.memory=4G` | -| `nodeselector` | CSV string | | Sets the pod's `nodeSelector` label(s). See [node assignment][2]. | -| `tolerations` | CSV string | | Configures the pod's taint toleration. See [node assignment][2]. | -| `rootless` | `true\|false` | `false` | Run the container as a non-root user. See [rootless mode][3]. | -| `loadbalance` | `sticky\|random` | `sticky` | Load-balancing strategy. If set to `sticky`, the pod is chosen using the hash of the context path. | -| `qemu.install` | `true\|false` | | Install QEMU emulation for multi platforms support. See [QEMU][4]. | -| `qemu.image` | String | `tonistiigi/binfmt:latest` | Sets the QEMU emulation image. See [QEMU][4]. | +| Parameter | Value | Default | Description | +| ----------------- | ----------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| `image` | String | | Sets the image to use for running BuildKit. | +| `namespace` | String | Namespace in current Kubernetes context | Sets the Kubernetes namespace. | +| `replicas` | Integer | 1 | Sets the number of Pod replicas to create. See [scaling BuildKit][1] | +| `requests.cpu` | CPU units | | Sets the request CPU value specified in units of Kubernetes CPU. For example `requests.cpu=100m` or `requests.cpu=2` | +| `requests.memory` | Memory size | | Sets the request memory value specified in bytes or with a valid suffix. For example `requests.memory=500Mi` or `requests.memory=4G` | +| `limits.cpu` | CPU units | | Sets the limit CPU value specified in units of Kubernetes CPU. For example `requests.cpu=100m` or `requests.cpu=2` | +| `limits.memory` | Memory size | | Sets the limit memory value specified in bytes or with a valid suffix. For example `requests.memory=500Mi` or `requests.memory=4G` | +| `nodeselector` | CSV string | | Sets the pod's `nodeSelector` label(s). See [node assignment][2]. | +| `tolerations` | CSV string | | Configures the pod's taint toleration. See [node assignment][2]. | +| `rootless` | `true`,`false` | `false` | Run the container as a non-root user. See [rootless mode][3]. | +| `loadbalance` | `sticky`,`random` | `sticky` | Load-balancing strategy. If set to `sticky`, the pod is chosen using the hash of the context path. | +| `qemu.install` | `true`,`false` | | Install QEMU emulation for multi platforms support. See [QEMU][4]. | +| `qemu.image` | String | `tonistiigi/binfmt:latest` | Sets the QEMU emulation image. See [QEMU][4]. | [1]: #scaling-buildkit [2]: #node-assignment @@ -107,16 +107,16 @@ the same values as the Kubernetes manifest. Each `tolerations` entry specifies a taint key and the value, operator, or effect. For example: `"tolerations=key=foo,value=bar;key=foo2,operator=exists;key=foo3,effect=NoSchedule"` -The syntax for these parameters is slightly different compared to other driver -options. You must wrap both `nodeSelector` and `tolerations` in double quotes. -For example: +Due to quoting rules for shell commands, you must wrap the `nodeselector` and +`tolerations` parameters in single quotes. You can even wrap all of +`--driver-opt` in single quotes, for example: ```console $ docker buildx create \ --bootstrap \ --name=kube \ --driver=kubernetes \ - --driver-opt="nodeselector=label=value","tolerations=key=key1,value=value1" + '--driver-opt="nodeselector=label1=value1,label2=value2","tolerations=key=key1,value=value1"' ``` ## Multi-platform builds @@ -238,7 +238,7 @@ This will create your pods without `securityContext.privileged`. Requires Kubernetes version 1.19 or later. Using Ubuntu as the host kernel is recommended. -## Guide: Creating a Buildx builder in Kubernetes +## Example: Creating a Buildx builder in Kubernetes This guide shows you how to: diff --git a/docs/guides/drivers/remote.md b/docs/guides/drivers/remote.md index e96a0ce4..06a24059 100644 --- a/docs/guides/drivers/remote.md +++ b/docs/guides/drivers/remote.md @@ -24,7 +24,7 @@ pass to `--driver-opt`: | `cacert` | String | | Sets the TLS certificate authority used for validation. | | `servername` | String | Endpoint hostname. | Sets the TLS server name used in requests. | -## Guide: Remote BuildKit over Unix sockets +## Example: Remote BuildKit over Unix sockets This guide shows you how to create a setup with a BuildKit daemon listening on a Unix socket, and have Buildx connect through it. @@ -81,7 +81,7 @@ $ docker buildx build . --builder=remote-unix -t test --load Remember that you need to use the `--load` flag if you want to load the build result into the Docker daemon. -## Guide: Remote BuildKit in Docker container +## Example: Remote BuildKit in Docker container This guide will show you how to create setup similar to the `docker-container` driver, by manually booting a BuildKit Docker container and connecting to it @@ -136,7 +136,7 @@ but this is for illustration purposes.) docker-container://remote-container ``` -## Guide: Remote BuildKit in Kubernetes +## Example: Remote BuildKit in Kubernetes This guide will show you how to create a setup similar to the `kubernetes` driver by manually creating a BuildKit `Deployment`. While the `kubernetes`