api: set default "Builder-Version" to "2" (BuildKit) on Linux

Starting with the 22.06 release, buildx is the default client for
docker build, which uses BuildKit as builder.

This patch changes the default builder version as advertised by
the daemon to "2" (BuildKit), so that pre-22.06 CLIs with BuildKit
support (but no buildx installed) also default to using BuildKit
when interacting with a 22.06 (or up) daemon.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

api/server/router/build/build.go

@@ -1,6 +1,8 @@
 package build // import "github.com/docker/docker/api/server/router/build"
 
 import (
+	"runtime"
+
 	"github.com/docker/docker/api/server/router"
 	"github.com/docker/docker/api/types"
 )
@@ -37,17 +39,24 @@ func (r *buildRouter) initRoutes() {
 	}
 }
 
-// BuilderVersion derives the default docker builder version from the config
-// Note: it is valid to have BuilderVersion unset which means it is up to the
-// client to choose which builder to use.
+// BuilderVersion derives the default docker builder version from the config.
+//
+// The default on Linux is version "2" (BuildKit), but the daemon can be
+// configured to recommend version "1" (classic Builder). Windows does not
+// yet support BuildKit for native Windows images, and uses "1" (classic builder)
+// as a default.
+//
+// This value is only a recommendation as advertised by the daemon, and it is
+// up to the client to choose which builder to use.
 func BuilderVersion(features map[string]bool) types.BuilderVersion {
-	var bv types.BuilderVersion
-	if v, ok := features["buildkit"]; ok {
-		if v {
-			bv = types.BuilderBuildKit
-		} else {
-			bv = types.BuilderV1
-		}
+	// TODO(thaJeztah) move the default to daemon/config
+	if runtime.GOOS == "windows" {
+		return types.BuilderV1
+	}
+
+	bv := types.BuilderBuildKit
+	if v, ok := features["buildkit"]; ok && !v {
+		bv = types.BuilderV1
 	}
 	return bv
 }

api/swagger.yaml

@@ -8718,7 +8718,17 @@ paths:
               description: "Max API Version the server supports"
             Builder-Version:
               type: "string"
-              description: "Default version of docker image builder"
+              description: |
+                Default version of docker image builder
+
+                The default on Linux is version "2" (BuildKit), but the daemon
+                can be configured to recommend version "1" (classic Builder).
+                Windows does not yet support BuildKit for native Windows images,
+                and uses "1" (classic builder) as a default.
+
+                This value is a recommendation as advertised by the daemon, and
+                it is up to the client to choose which builder to use.
+              default: "2"
             Docker-Experimental:
               type: "boolean"
               description: "If the server is running with experimental mode enabled"

docs/api/version-history.md

@@ -53,6 +53,18 @@ keywords: "API, Docker, rcli, REST, documentation"
   if they are not set.
 * `GET /info` now omits the `KernelMemory` and `KernelMemoryTCP` if they are not
   supported by the host or host's configuration (if cgroups v2 are in use).
+* `GET /_ping` and `HEAD /_ping` now return `Builder-Version` by default.
+  This header contains the default builder to use, and is a recommendation as
+  advertised by the daemon. However, it is up to the client to choose which builder
+  to use.
+
+  The default value on Linux is version "2" (BuildKit), but the daemon can be
+  configured to recommend version "1" (classic Builder). Windows does not yet
+  support BuildKit for native Windows images, and uses "1" (classic builder) as
+  a default.
+
+  This change is not versioned, and affects all API versions if the daemon has
+  this patch. 
 * `GET /_ping` and `HEAD /_ping` now return a `Swarm` header, which allows a
   client to detect if Swarm is enabled on the daemon, without having to call
   additional endpoints.

integration/system/ping_test.go

@@ -3,9 +3,13 @@ package system // import "github.com/docker/docker/integration/system"
 import (
 	"context"
 	"net/http"
+	"os"
+	"path/filepath"
+	"runtime"
 	"strings"
 	"testing"
 
+	"github.com/docker/docker/api/types"
 	"github.com/docker/docker/api/types/swarm"
 	"github.com/docker/docker/api/types/versions"
 	"github.com/docker/docker/testutil/daemon"
@@ -93,6 +97,42 @@ func TestPingSwarmHeader(t *testing.T) {
 	})
 }
 
+func TestPingBuilderHeader(t *testing.T) {
+	skip.If(t, testEnv.IsRemoteDaemon)
+
+	defer setupTest(t)()
+	d := daemon.New(t)
+
+	t.Run("default config", func(t *testing.T) {
+		d.Start(t)
+		defer d.Stop(t)
+
+		var expected = string(types.BuilderBuildKit)
+		if runtime.GOOS == "windows" {
+			expected = string(types.BuilderV1)
+		}
+
+		res, _, err := request.Head("/_ping", request.Host(d.Sock()))
+		assert.NilError(t, err)
+		assert.Equal(t, res.StatusCode, http.StatusOK)
+		assert.Equal(t, hdr(res, "Builder-Version"), expected)
+	})
+
+	t.Run("buildkit disabled", func(t *testing.T) {
+		cfg := filepath.Join(d.RootDir(), "daemon.json")
+		err := os.WriteFile(cfg, []byte(`{"features": { "buildkit": false }}`), 0644)
+		assert.NilError(t, err)
+		d.Start(t, "--config-file", cfg)
+		defer d.Stop(t)
+
+		var expected = string(types.BuilderV1)
+		res, _, err := request.Head("/_ping", request.Host(d.Sock()))
+		assert.NilError(t, err)
+		assert.Equal(t, res.StatusCode, http.StatusOK)
+		assert.Equal(t, hdr(res, "Builder-Version"), expected)
+	})
+}
+
 func hdr(res *http.Response, name string) string {
 	val, ok := res.Header[http.CanonicalHeaderKey(name)]
 	if !ok || len(val) == 0 {