Merge pull request #16036 from crazy-max/buildkit-configure

build: builkit configure

_config.yml

@@ -51,6 +51,7 @@ compose_file_v2: "2.4"
 machine_version: "0.16.0"
 distribution_version: "2.7"
 compose_switch_version: "1.0.4"
+buildkit_version: "0.10.5"
 
 # Options for displaying minimum API version requirements in the reference pages.
 #
@@ -217,3 +218,6 @@ fetch-remote:
       - dest: "engine/reference/builder.md"
         src:
           - "frontend/dockerfile/docs/reference.md"
+      - dest: "build/buildkit/toml-configuration.md"
+        src:
+          - "docs/buildkitd.toml.md"

_data/toc.yaml

@@ -1559,12 +1559,18 @@ manuals:
               title: Build contexts and linking targets
             - path: /build/customize/bake/compose-file/
               title: Building from Compose file
+        - path: /build/customize/color-output-controls/
+          title: Color output controls
     - sectiontitle: BuildKit
       section:
         - path: /build/buildkit/
           title: Overview
         - path: /build/buildkit/dockerfile-frontend/
           title: Custom Dockerfile syntax
+        - path: /build/buildkit/configure/
+          title: Configure
+        - path: /build/buildkit/toml-configuration/
+          title: TOML configuration
     - sectiontitle: Buildx
       section:
         - path: /build/buildx/install/

build/buildkit/configure.md

@@ -0,0 +1,179 @@
+---
+title: Configure BuildKit
+description: Learn how to configure BuildKit for your builder.
+keywords: build, buildkit, configuration, buildx, network, cni, registry
+---
+
+If you create a `docker-container` or `kubernetes` builder with Buildx, you can
+apply a custom [BuildKit configuration](toml-configuration.md) by passing the
+[`--config` flag](../../engine/reference/commandline/buildx_create.md#config) to
+the `docker buildx create` command.
+
+## Registry mirror
+
+You can define a registry mirror to use for your builds. Doing so redirects
+BuildKit to pull images from a different hostname. The following steps exemplify
+defining a mirror for `docker.io` (Docker Hub) to `mirror.gcr.io`.
+
+1. Create a TOML at `/etc/buildkitd.toml` with the following content:
+
+   ```toml
+   debug = true
+   [registry."docker.io"]
+     mirrors = ["mirror.gcr.io"]
+   ```
+
+   > **Note**
+   >
+   > `debug = true` turns on debug requests in the BuildKit daemon, which logs a
+   > message that shows when a mirror is being used.
+
+2. Create a `docker-container` builder that uses this BuildKit configuration:
+
+   ```console
+   $ docker buildx create --use --bootstrap \
+     --name mybuilder \
+     --driver docker-container \
+     --config /etc/buildkitd.toml
+   ```
+
+3. Build an image:
+
+   ```console
+   $ docker buildx build --load . -f - <<EOF
+   FROM alpine
+   RUN echo "hello world"
+   EOF
+   ```
+
+The BuildKit logs for this builder now shows that it uses the GCR mirror. You
+can tell by the fact that the response messages include the `x-goog-*` HTTP
+headers.
+
+```console
+$ docker logs buildx_buildkit_mybuilder0
+```
+
+```text
+...
+time="2022-02-06T17:47:48Z" level=debug msg="do request" request.header.accept="application/vnd.docker.container.image.v1+json, */*" request.header.user-agent=containerd/1.5.8+unknown request.method=GET spanID=9460e5b6e64cec91 traceID=b162d3040ddf86d6614e79c66a01a577
+time="2022-02-06T17:47:48Z" level=debug msg="fetch response received" response.header.accept-ranges=bytes response.header.age=1356 response.header.alt-svc="h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000,h3-Q050=\":443\"; ma=2592000,h3-Q046=\":443\"; ma=2592000,h3-Q043=\":443\"; ma=2592000,quic=\":443\"; ma=2592000; v=\"46,43\"" response.header.cache-control="public, max-age=3600" response.header.content-length=1469 response.header.content-type=application/octet-stream response.header.date="Sun, 06 Feb 2022 17:25:17 GMT" response.header.etag="\"774380abda8f4eae9a149e5d5d3efc83\"" response.header.expires="Sun, 06 Feb 2022 18:25:17 GMT" response.header.last-modified="Wed, 24 Nov 2021 21:07:57 GMT" response.header.server=UploadServer response.header.x-goog-generation=1637788077652182 response.header.x-goog-hash="crc32c=V3DSrg==" response.header.x-goog-hash.1="md5=d0OAq9qPTq6aFJ5dXT78gw==" response.header.x-goog-metageneration=1 response.header.x-goog-storage-class=STANDARD response.header.x-goog-stored-content-encoding=identity response.header.x-goog-stored-content-length=1469 response.header.x-guploader-uploadid=ADPycduqQipVAXc3tzXmTzKQ2gTT6CV736B2J628smtD1iDytEyiYCgvvdD8zz9BT1J1sASUq9pW_ctUyC4B-v2jvhIxnZTlKg response.status="200 OK" spanID=9460e5b6e64cec91 traceID=b162d3040ddf86d6614e79c66a01a577
+time="2022-02-06T17:47:48Z" level=debug msg="fetch response received" response.header.accept-ranges=bytes response.header.age=760 response.header.alt-svc="h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000,h3-Q050=\":443\"; ma=2592000,h3-Q046=\":443\"; ma=2592000,h3-Q043=\":443\"; ma=2592000,quic=\":443\"; ma=2592000; v=\"46,43\"" response.header.cache-control="public, max-age=3600" response.header.content-length=1471 response.header.content-type=application/octet-stream response.header.date="Sun, 06 Feb 2022 17:35:13 GMT" response.header.etag="\"35d688bd15327daafcdb4d4395e616a8\"" response.header.expires="Sun, 06 Feb 2022 18:35:13 GMT" response.header.last-modified="Wed, 24 Nov 2021 21:07:12 GMT" response.header.server=UploadServer response.header.x-goog-generation=1637788032100793 response.header.x-goog-hash="crc32c=aWgRjA==" response.header.x-goog-hash.1="md5=NdaIvRUyfar8201DleYWqA==" response.header.x-goog-metageneration=1 response.header.x-goog-storage-class=STANDARD response.header.x-goog-stored-content-encoding=identity response.header.x-goog-stored-content-length=1471 response.header.x-guploader-uploadid=ADPycdtR-gJYwC7yHquIkJWFFG8FovDySvtmRnZBqlO3yVDanBXh_VqKYt400yhuf0XbQ3ZMB9IZV2vlcyHezn_Pu3a1SMMtiw response.status="200 OK" spanID=9460e5b6e64cec91 traceID=b162d3040ddf86d6614e79c66a01a577
+time="2022-02-06T17:47:48Z" level=debug msg=fetch spanID=9460e5b6e64cec91 traceID=b162d3040ddf86d6614e79c66a01a577
+time="2022-02-06T17:47:48Z" level=debug msg=fetch spanID=9460e5b6e64cec91 traceID=b162d3040ddf86d6614e79c66a01a577
+time="2022-02-06T17:47:48Z" level=debug msg=fetch spanID=9460e5b6e64cec91 traceID=b162d3040ddf86d6614e79c66a01a577
+time="2022-02-06T17:47:48Z" level=debug msg=fetch spanID=9460e5b6e64cec91 traceID=b162d3040ddf86d6614e79c66a01a577
+time="2022-02-06T17:47:48Z" level=debug msg="do request" request.header.accept="application/vnd.docker.image.rootfs.diff.tar.gzip, */*" request.header.user-agent=containerd/1.5.8+unknown request.method=GET spanID=9460e5b6e64cec91 traceID=b162d3040ddf86d6614e79c66a01a577
+time="2022-02-06T17:47:48Z" level=debug msg="fetch response received" response.header.accept-ranges=bytes response.header.age=1356 response.header.alt-svc="h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000,h3-Q050=\":443\"; ma=2592000,h3-Q046=\":443\"; ma=2592000,h3-Q043=\":443\"; ma=2592000,quic=\":443\"; ma=2592000; v=\"46,43\"" response.header.cache-control="public, max-age=3600" response.header.content-length=2818413 response.header.content-type=application/octet-stream response.header.date="Sun, 06 Feb 2022 17:25:17 GMT" response.header.etag="\"1d55e7be5a77c4a908ad11bc33ebea1c\"" response.header.expires="Sun, 06 Feb 2022 18:25:17 GMT" response.header.last-modified="Wed, 24 Nov 2021 21:07:06 GMT" response.header.server=UploadServer response.header.x-goog-generation=1637788026431708 response.header.x-goog-hash="crc32c=ZojF+g==" response.header.x-goog-hash.1="md5=HVXnvlp3xKkIrRG8M+vqHA==" response.header.x-goog-metageneration=1 response.header.x-goog-storage-class=STANDARD response.header.x-goog-stored-content-encoding=identity response.header.x-goog-stored-content-length=2818413 response.header.x-guploader-uploadid=ADPycdsebqxiTBJqZ0bv9zBigjFxgQydD2ESZSkKchpE0ILlN9Ibko3C5r4fJTJ4UR9ddp-UBd-2v_4eRpZ8Yo2llW_j4k8WhQ response.status="200 OK" spanID=9460e5b6e64cec91 traceID=b162d3040ddf86d6614e79c66a01a577
+...
+```
+
+## Setting registry certificates
+
+If you specify registry certificates in the BuildKit configuration, the daemon
+copies the files into the container under `/etc/buildkit/certs`. The following
+steps show adding a self-signed registry certificate to the BuildKit
+configuration.
+
+1. Add the following configuration to `/etc/buildkitd.toml`:
+
+   ```toml
+   # /etc/buildkitd.toml
+   debug = true
+   [registry."myregistry.com"]
+     ca=["/etc/certs/myregistry.pem"]
+     [[registry."myregistry.com".keypair]]
+       key="/etc/certs/myregistry_key.pem"
+       cert="/etc/certs/myregistry_cert.pem"
+   ```
+
+   This tells the builder to push images to the `myregistry.com` registry using
+   the certificates in the specified location (`/etc/certs`).
+
+2. Create a `docker-container` builder that uses this configuration:
+
+   ```console
+   $ docker buildx create --use --bootstrap \
+     --name mybuilder \
+     --driver docker-container \
+     --config /etc/buildkitd.toml
+   ```
+
+3. Inspect the builder's configuration file (`/etc/buildkit/buildkitd.toml`), it
+   shows that the certificate configuration is now configured in the builder.
+
+   ```console
+   $ docker exec -it buildx_buildkit_mybuilder0 cat /etc/buildkit/buildkitd.toml
+   ```
+
+   ```toml
+   debug = true
+
+   [registry]
+
+     [registry."myregistry.com"]
+       ca = ["/etc/buildkit/certs/myregistry.com/myregistry.pem"]
+
+       [[registry."myregistry.com".keypair]]
+         cert = "/etc/buildkit/certs/myregistry.com/myregistry_cert.pem"
+         key = "/etc/buildkit/certs/myregistry.com/myregistry_key.pem"
+   ```
+
+4. Verify that the certificates are inside the container:
+
+   ```console
+   $ docker exec -it buildx_buildkit_mybuilder0 ls /etc/buildkit/certs/myregistry.com/
+   myregistry.pem    myregistry_cert.pem   myregistry_key.pem
+   ```
+
+Now you can push to the registry using this builder, and it will authenticate
+using the certificates:
+
+```console
+$ docker buildx build --push --tag myregistry.com/myimage:latest .
+```
+
+## CNI networking
+
+CNI networking for builders can be useful for dealing with network port
+contention during concurrent builds. CNI is
+[not yet](https://github.com/moby/buildkit/issues/28){:target="_blank"
+rel="noopener" class="_"} available in the default BuildKit image. But you can
+create your own image that includes CNI support.
+
+The following Dockerfile example shows a custom BuildKit image with CNI support.
+It uses the
+[CNI config for integration tests](https://github.com/moby/buildkit/blob/master//hack/fixtures/cni.json){:target="_blank"
+rel="noopener" class="_"} in BuildKit as an example. Feel free to include your
+own CNI configuration.
+
+```dockerfile
+ARG BUILDKIT_VERSION=v{{ site.buildkit_version }}
+ARG CNI_VERSION=v1.0.1
+
+FROM --platform=$BUILDPLATFORM alpine AS cni-plugins
+RUN apk add --no-cache curl
+ARG CNI_VERSION
+ARG TARGETOS
+ARG TARGETARCH
+WORKDIR /opt/cni/bin
+RUN curl -Ls https://github.com/containernetworking/plugins/releases/download/$CNI_VERSION/cni-plugins-$TARGETOS-$TARGETARCH-$CNI_VERSION.tgz | tar xzv
+
+FROM moby/buildkit:${BUILDKIT_VERSION}
+ARG BUILDKIT_VERSION
+RUN apk add --no-cache iptables
+COPY --from=cni-plugins /opt/cni/bin /opt/cni/bin
+ADD https://raw.githubusercontent.com/moby/buildkit/${BUILDKIT_VERSION}/hack/fixtures/cni.json /etc/buildkit/cni.json
+```
+
+Now you can build this image, and create a builder instance from it using
+[the `--driver-opt image` option](../../engine/reference/commandline/buildx_create.md#driver-opt):
+
+```console
+$ docker buildx build --tag buildkit-cni:local --load .
+$ docker buildx create --use --bootstrap \
+  --name mybuilder \
+  --driver docker-container \
+  --driver-opt "image=buildkit-cni:local" \
+  --buildkitd-flags "--oci-worker-net=cni"
+```

build/buildkit/toml-configuration.md

@@ -0,0 +1,7 @@
+---
+title: BuildKit TOML configuration
+keywords: build, buildkit, configuration
+fetch_remote:
+  line_start: 2
+  line_end: -1
+---

build/customize/color-output-controls.md

@@ -0,0 +1,24 @@
+---
+title: Color output controls
+description: Learn how to control the color of BuildKit progress output.
+keywords: build, buildx buildkit, color, terminal
+---
+
+BuildKit and Buildx have support for modifying the colors that are used to
+output information to the terminal. You can set the environment variable
+`BUILDKIT_COLORS` to something like `run=123,20,245:error=yellow:cancel=blue:warning=white`
+to set the colors that you would like to use:
+
+![Progress output custom colors](../images/buildkit-progress-colors.png)
+
+Setting `NO_COLOR` to anything will disable any colorized output as recommended
+by [no-color.org](https://no-color.org/){:target="_blank" rel="noopener" class="_"}:
+
+![Progress output no color](../images/buildkit-progress-nocolor.png)
+
+> **Note**
+>
+> Parsing errors will be reported but ignored. This will result in default
+> color values being used where needed.
+
+See also [the list of pre-defined colors](https://github.com/moby/buildkit/blob/master/util/progress/progressui/colors.go){:target="_blank" rel="noopener" class="_"}.

build/index.md

@@ -121,6 +121,7 @@ own to BuildKit using the power of custom frontends.
 
 ### Configure BuildKit
 
-Take a deep dive into the internal BuildKit configuration to get the most out
-of your builds. See also [`buildkitd.toml`](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md),
-the configuration file for `buildkitd`.
+Take a deep dive into the internal [BuildKit configuration](buildkit/toml-configuration.md)
+to get the most out of your builds.
+
+[Configure BuildKit](buildkit/configure.md){: .button .outline-btn }