Merge pull request #17053 from dvdksn/build/update-default-builder-note

build: clarify that buildkit is default in Docker Engine v23

build/buildkit/index.md

@@ -7,16 +7,20 @@ keywords: build, buildkit
 ## Overview
 
 [BuildKit](https://github.com/moby/buildkit){:target="blank" rel="noopener" class=""}
-is an improved backend to replace the legacy builder. It comes with new and much
-improved functionality for improving your builds' performance and the
-reusability of your Dockerfiles. It also introduces support for handling more
-complex scenarios:
+is an improved backend to replace the legacy builder. BuildKit is the default builder
+for users on Docker Desktop, and Docker Engine as of version 23.0.
+
+BuildKit provides new functionality and improves your builds' performance.
+It also introduces support for handling more complex scenarios:
 
 - Detect and skip executing unused build stages
 - Parallelize building independent build stages
-- Incrementally transfer only the changed files in your [build context](../building/context.md) between builds
-- Detect and skip transferring unused files in your [build context](../building/context.md)
-- Use [Dockerfile frontend](dockerfile-frontend.md) implementations with many new features
+- Incrementally transfer only the changed files in your
+  [build context](../building/context.md) between builds
+- Detect and skip transferring unused files in your
+  [build context](../building/context.md)
+- 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
 
@@ -31,14 +35,16 @@ files to be read or uploaded before the work can begin.
 
 ## LLB
 
-At the core of BuildKit is a [Low-Level Build (LLB)](https://github.com/moby/buildkit#exploring-llb){:target="blank" rel="noopener" class=""}
-definition format. LLB is an intermediate binary format that allows developers
-to extend 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.
+At the core of BuildKit is a
+[Low-Level Build (LLB)](https://github.com/moby/buildkit#exploring-llb){:target="blank"
+rel="noopener" class=""} definition format. LLB is an intermediate binary format
+that allows developers to extend 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:60%"}
+![Directed acyclic graph (DAG)](../images/buildkit-dag.svg){:class="invertible"
+style="width:60%"}
 
 Everything about execution and caching of your builds is defined in LLB. The
 caching model is entirely rewritten compared to the legacy builder. Rather than
@@ -47,12 +53,13 @@ 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){:target="blank" rel="noopener" class=""}
-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,
-most users would use a frontend component, or LLB nested invocation, to run
-a prepared set of build steps.
+LLB can be generated directly using a
+[golang client package](https://pkg.go.dev/github.com/moby/buildkit/client/llb){:target="blank"
+rel="noopener" class=""} 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, most users would use a frontend component, or LLB nested
+invocation, to run a prepared set of build steps.
 
 ## Frontend
 
@@ -62,14 +69,18 @@ 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).
+BuildKit, you would
+[use an external Dockerfile frontend](dockerfile-frontend.md).
 
 ## Getting started
 
-BuildKit is enabled by default for all users on [Docker Desktop](../../desktop/index.md).
-If you have installed Docker Desktop, you don't have to manually enable
-BuildKit. If you are running Docker on Linux, you can enable BuildKit either by
-using an environment variable or by making BuildKit the default setting.
+BuildKit is the default builder for users on Docker Desktop and Docker Engine
+v23.0 and later.
+
+If you have installed Docker Desktop, you don't need to enable BuildKit. If you
+are running a version of Docker Engine version earlier than 23.0, you can enable
+BuildKit either by setting an environment variable, or by making BuildKit the
+default setting in the daemon configuration.
 
 To set the BuildKit environment variable when running the `docker build`
 command, run:
@@ -78,27 +89,28 @@ command, run:
 $ DOCKER_BUILDKIT=1 docker build .
 ```
 
->**Note**
+> **Note**
 >
-> Buildx always enables BuildKit.
+> [Buildx](../install-buildx.md) always uses BuildKit.
 
-To enable docker BuildKit by default, set daemon configuration in `/etc/docker/daemon.json`
-feature to `true` and restart the daemon. If the `daemon.json` file doesn't
-exist, create new file called `daemon.json` and then add the following to the
-file.
+To use Docker BuildKit by default, edit the Docker daemon configuration in
+`/etc/docker/daemon.json` as follows, and restart the daemon.
 
 ```json
 {
   "features": {
-    "buildkit" : true
+    "buildkit": true
   }
 }
 ```
 
-And restart the Docker daemon.
+If the `/etc/docker/daemon.json` file doesn't exist, create new file called
+`daemon.json` and then add the following to the file. And restart the Docker
+daemon.
 
 > **Warning**
 >
 > BuildKit only supports building Linux containers. Windows support is tracked
-> in [`moby/buildkit#616`](https://github.com/moby/buildkit/issues/616){:target="blank" rel="noopener" class=""}
+> in
+> [`moby/buildkit#616`](https://github.com/moby/buildkit/issues/616){:target="blank" rel="noopener" class=""}
 {: .warning}