build: extending buildkit section

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

_data/toc.yaml

@@ -1541,6 +1541,12 @@ manuals:
               title: Build contexts and linking targets
             - path: /build/customize/bake/compose-file/
               title: Building from Compose file
+    - sectiontitle: Extending BuildKit
+      section:
+        - path: /build/extend/
+          title: Overview
+        - path: /build/extend/dockerfile-frontend/
+          title: Custom Dockerfile syntax
     - sectiontitle: Buildx
       section:
         - path: /build/buildx/install/

build/extend/dockerfile-frontend.md

@@ -0,0 +1,99 @@
+---
+title: Custom Dockerfile syntax
+keywords: build, buildkit, dockerfile, frontend
+---
+
+## Dockerfile frontend
+
+BuildKit supports loading frontends dynamically from container images. To use
+an external Dockerfile frontend, the first line of your [Dockerfile](../../engine/reference/builder.md)
+needs to set the [`syntax` directive](../../engine/reference/builder.md#syntax)
+pointing to the specific image you want to use:
+
+```dockerfile
+# syntax=[remote image reference]
+```
+
+For example:
+
+```dockerfile
+# syntax=docker/dockerfile:1
+# syntax=docker.io/docker/dockerfile:1
+# syntax=example.com/user/repo:tag@sha256:abcdef...
+```
+
+This defines the location of the Dockerfile syntax that is used to build the
+Dockerfile. The BuildKit backend allows to seamlessly use external
+implementations that are distributed as Docker images and execute inside a
+container sandbox environment.
+
+Custom Dockerfile implementations allows you to:
+
+- Automatically get bugfixes without updating the Docker daemon
+- Make sure all users are using the same implementation to build your Dockerfile
+- Use the latest features without updating the Docker daemon
+- Try out new features or third-party features before they are integrated in the Docker daemon
+- Use [alternative build definitions, or create your own](https://github.com/moby/buildkit#exploring-llb){:target="_blank" rel="noopener" class="_"}
+
+> **Note**
+> 
+> BuildKit also ships with Dockerfile frontend builtin, but it is recommended
+> to use an external image to make sure that all users use the same version on
+> the builder and to pick up bugfixes automatically without waiting for a new
+> version of BuildKit or Docker engine.
+
+## Official releases
+
+Docker distributes official versions of the images that can be used for building
+Dockerfiles under `docker/dockerfile` repository on Docker Hub. There are two
+channels where new images are released: `stable` and `labs`.
+
+Stable channel follows [semantic versioning](https://semver.org){:target="_blank" rel="noopener" class="_"}.
+For example:
+
+- `docker/dockerfile:1` - kept updated with the latest `1.x.x` minor _and_ patch
+  release.
+- `docker/dockerfile:1.2` -  kept updated with the latest `1.2.x` patch release,
+  and stops receiving updates once version `1.3.0` is released.
+- `docker/dockerfile:1.2.1` - immutable: never updated.
+
+We recommend using `docker/dockerfile:1`, which always points to the latest
+stable release of the version 1 syntax, and receives both "minor" and "patch"
+updates for the version 1 release cycle. BuildKit automatically checks for
+updates of the syntax when performing a build, making sure you are using the
+most current version.
+
+If a specific version is used, such as `1.2` or `1.2.1`, the Dockerfile needs
+to be updated manually to continue receiving bugfixes and new features. Old
+versions of the Dockerfile remain compatible with the new versions of the
+builder.
+
+### labs channel
+
+The "labs" channel provides early access to Dockerfile features that are not yet
+available in the stable channel. Labs channel images are released in conjunction
+with the stable releases, and follow the same versioning with the `-labs` suffix,
+for example:
+
+- `docker/dockerfile:labs` - latest release on labs channel.
+- `docker/dockerfile:1-labs` - same as `dockerfile:1` in the stable channel,
+  with labs features enabled.
+- `docker/dockerfile:1.2-labs` -  same as `dockerfile:1.2` in the stable
+  channel, with labs features enabled.
+- `docker/dockerfile:1.2.1-labs` - immutable: never updated. Same as
+  `dockerfile:1.2.1` in the stable channel, with labs features enabled.
+
+Choose a channel that best fits your needs; if you want to benefit from
+new features, use the labs channel. Images in the labs channel provide a superset
+of the features in the stable channel; note that `stable` features in the labs
+channel images follow [semantic versioning](https://semver.org){:target="_blank" rel="noopener" class="_"},
+but "labs" features do not, and newer releases may not be backwards compatible,
+so it is recommended to use an immutable full version variant.
+
+## Other resources
+
+For documentation on "labs" features, master builds, and nightly feature
+releases, refer to the description in [the BuildKit source repository on GitHub](https://github.com/moby/buildkit/blob/master/README.md){:target="_blank" rel="noopener" class="_"}.
+For a full list of available images, visit the [`docker/dockerfile` repository on Docker Hub](https://hub.docker.com/r/docker/dockerfile){:target="_blank" rel="noopener" class="_"},
+and the [`docker/dockerfile-upstream` repository on Docker Hub](https://hub.docker.com/r/docker/dockerfile-upstream){:target="_blank" rel="noopener" class="_"}
+for development builds.

build/extend/index.md

@@ -0,0 +1,64 @@
+---
+title: Extending BuildKit
+description: Introduction and overview of BuildKit
+keywords: build, buildkit
+---
+
+## Overview
+
+[BuildKit](https://github.com/moby/buildkit){:target="_blank" rel="noopener" class="_"}
+is the backend evolution from the Legacy Builder, it comes with new and much
+improved functionality that can be powerful tools for improving your builds'
+performance or reusability of your Dockerfiles, and it also introduces
+support for complex scenarios:
+
+- Detect and skip executing unused build stages
+- Parallelize building independent build stages
+- Incrementally transfer only the changed files in your build context between builds
+- Detect and skip transferring unused files in your build context
+- Use [Dockerfile frontend](dockerfile-frontend.md) implementations with many new features
+- Avoid side effects with rest of the API (intermediate images and containers)
+- Prioritize your build cache for automatic pruning
+
+Apart from many new features, the main areas BuildKit improves on the current
+experience are performance, storage management, and extensibility. From the
+performance side, a significant update is a new fully concurrent build graph
+solver. It can run build steps in parallel when possible and optimize out
+commands that don't have an impact on the final result. We have also optimized
+the access to the local source files. By tracking only the updates made to these
+files between repeated build invocations, there is no need to wait for local
+files to be read or uploaded before the work can begin.
+
+## LLB
+
+At the core of BuildKit is a new low-level build definition format called [LLB](https://github.com/moby/buildkit#exploring-llb){:target="_blank" rel="noopener" class="_"}
+(low-level builder). This is an intermediate binary format that end users are
+not exposed to but allows to easily build on top of BuildKit. LLB defines a
+content-addressable dependency graph that can be used to put together very
+complex build definitions. It also supports features not exposed in Dockerfiles,
+like direct data mounting and nested invocation.
+
+![Directed acyclic graph (DAG)](../images/buildkit-dag.svg){:class="invertible" style="width:80%"}
+
+Everything about execution and caching of your builds is defined only in LLB.
+The caching model is entirely rewritten compared to the current Dockerfile
+builder. Instead of doing heuristics to compare images, it can directly track
+the checksums of build graphs and content mounted to specific operations. This
+makes it much faster, more precise and portable. The build cache can even be
+exported to a registry, where it can be pulled on-demand by subsequent
+invocations on any host.
+
+LLB can be generated directly using a [golang client package](https://pkg.go.dev/github.com/moby/buildkit/client/llb)
+that allows defining the relationships between your build operations using Go
+language primitives. This gives you full power to run anything you can imagine,
+but will probably not be how most people will define their builds. Instead, we
+expect most users to use a frontend component or LLB nested invocation to run
+some prepared combination of build steps.
+
+A frontend is a component that takes a human-readable
+build format and converts it to LLB so BuildKit can execute it. Frontends can
+be distributed as images, and the user can target a specific version of a
+frontend that is guaranteed to work for the features used by their definition.
+
+For example, to build a [Dockerfile](../../engine/reference/builder.md) with
+BuildKit, you would [use an external Dockerfile frontend](dockerfile-frontend.md).