api/types/image: InspectResponse: deprecate Parent, DockerVersion

The image inspect response has various fields that were deprecated as
part of the legacy builder, or Dockerfile syntax;

- The `Parent` field is only used for the legacy builder, and only set for
  images that are built locally (i.e., not persisted when pulling an image).
- The `DockerVersion` field is only set when building images with the legacy
  builder, and empty in most cases.

This patch deprecates the fields in the `InspectResponse` go struct, as
these fields will no longer be set in future once the legacy builder is
removed (`Parent`, `DockerVersion`). The legacy builder's deprecation in
[cli@4d8e457] / [cli@fd22746] (docker 23.0, API v1.42), however the related
API fields were kept so that information of legacy images would not be
discarded.

The API continues to return these fields if set, allowing the client to
print the fields for informational purposes when printing the raw response,
but these fields should be considered "transitional", and not be depended
on; deprecating the fields helps raise awareness.

[cli@4d8e457]: 4d8e45782b
[cli@fd22746]: fd2274692f

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
(cherry picked from commit bd8a99b400)
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

api/swagger.yaml

@@ -1938,6 +1938,11 @@ definitions:
           Depending on how the image was created, this field may be empty and
           is only set for images that were built/created locally. This field
           is empty if the image was pulled from an image registry.
+
+          > **Deprecated**: This field is only set when using the deprecated
+          > legacy builder. It is included in API responses for informational
+          > purposes, but should not be depended on as it will be omitted
+          > once the legacy builder is removed.
         type: "string"
         x-nullable: false
         example: ""
@@ -1963,6 +1968,11 @@ definitions:
           The version of Docker that was used to build the image.
 
           Depending on how the image was created, this field may be empty.
+
+          > **Deprecated**: This field is only set when using the deprecated
+          > legacy builder. It is included in API responses for informational
+          > purposes, but should not be depended on as it will be omitted
+          > once the legacy builder is removed.
         type: "string"
         x-nullable: false
         example: "27.0.1"

api/types/image/image_inspect.go

@@ -48,6 +48,8 @@ type InspectResponse struct {
 	// Depending on how the image was created, this field may be empty and
 	// is only set for images that were built/created locally. This field
 	// is empty if the image was pulled from an image registry.
+	//
+	// Deprecated: this field is deprecated, and will be removed in the next release.
 	Parent string
 
 	// Comment is an optional message that can be set when committing or
@@ -80,6 +82,8 @@ type InspectResponse struct {
 	// DockerVersion is the version of Docker that was used to build the image.
 	//
 	// Depending on how the image was created, this field may be empty.
+	//
+	// Deprecated: this field is deprecated, and will be removed in the next release.
 	DockerVersion string
 
 	// Author is the name of the author that was specified when committing the

daemon/containerd/image_inspect.go

@@ -90,14 +90,13 @@ func (i *ImageService) ImageInspect(ctx context.Context, refOrID string, opts ba
 	}
 
 	resp := &imagetypes.InspectResponse{
-		ID:            target.Digest.String(),
-		RepoTags:      repoTags,
-		Descriptor:    &target,
-		RepoDigests:   repoDigests,
-		Parent:        parent,
-		DockerVersion: "",
-		Size:          size,
-		Manifests:     manifests,
+		ID:          target.Digest.String(),
+		RepoTags:    repoTags,
+		Descriptor:  &target,
+		RepoDigests: repoDigests,
+		Parent:      parent, //nolint:staticcheck // ignore SA1019: field is deprecated, but still included in response when present.
+		Size:        size,
+		Manifests:   manifests,
 		GraphDriver: storage.DriverData{
 			Name: i.snapshotter,
 			Data: nil,

daemon/images/image_inspect.go

@@ -58,12 +58,12 @@ func (i *ImageService) ImageInspect(ctx context.Context, refOrID string, opts ba
 		ID:              img.ID().String(),
 		RepoTags:        repoTags,
 		RepoDigests:     repoDigests,
-		Parent:          img.Parent.String(),
+		Parent:          img.Parent.String(), //nolint:staticcheck // ignore SA1019: field is deprecated, but still included in response when present (built with legacy builder).
 		Comment:         comment,
 		Created:         created,
 		Container:       img.Container,        //nolint:staticcheck // ignore SA1019: field is deprecated, but still set on API < v1.45.
 		ContainerConfig: &img.ContainerConfig, //nolint:staticcheck // ignore SA1019: field is deprecated, but still set on API < v1.45.
-		DockerVersion:   img.DockerVersion,
+		DockerVersion:   img.DockerVersion,    //nolint:staticcheck // ignore SA1019: field is deprecated, but still included in response when present.
 		Author:          img.Author,
 		Config:          &imgConfig,
 		Architecture:    img.Architecture,

docs/api/v1.51.yaml

@@ -1938,6 +1938,11 @@ definitions:
           Depending on how the image was created, this field may be empty and
           is only set for images that were built/created locally. This field
           is empty if the image was pulled from an image registry.
+
+          > **Deprecated**: This field is only set when using the deprecated
+          > legacy builder. It is included in API responses for informational
+          > purposes, but should not be depended on as it will be omitted
+          > once the legacy builder is removed.
         type: "string"
         x-nullable: false
         example: ""
@@ -1963,6 +1968,11 @@ definitions:
           The version of Docker that was used to build the image.
 
           Depending on how the image was created, this field may be empty.
+
+          > **Deprecated**: This field is only set when using the deprecated
+          > legacy builder. It is included in API responses for informational
+          > purposes, but should not be depended on as it will be omitted
+          > once the legacy builder is removed.
         type: "string"
         x-nullable: false
         example: "27.0.1"

docs/api/version-history.md

@@ -27,6 +27,12 @@ keywords: "API, Docker, rcli, REST, documentation"
   in the next API version.
 * Deprecated: The field `KernelMemoryTCP` as part of `GET /info` is deprecated
   and will be removed in the next API version.
+* Deprecated: the `Parent` and `DockerVersion` fields returned by the
+  `GET /images/{name}/json` endpoint are deprecated. These fields are set by
+  the legacy builder, and are no longer set when using BuildKit. The API
+  continues returning these fields when set for informational purposes, but
+  they should not be depended on as they will be omitted once the legacy builder
+  is removed.
 
 ## v1.50 API changes
 

integration-cli/docker_api_build_test.go

@@ -313,16 +313,16 @@ func (s *DockerAPISuite) TestBuildOnBuildCache(c *testing.T) {
 	assert.Assert(c, is.Len(imageIDs, 2))
 	parentID, childID := imageIDs[0], imageIDs[1]
 
-	client := testEnv.APIClient()
+	apiClient := testEnv.APIClient()
 	ctx := testutil.GetContext(c)
 
 	// check parentID is correct
 	// Parent is graphdriver-only
 	if !testEnv.UsingSnapshotter() {
-		image, err := client.ImageInspect(ctx, childID)
+		image, err := apiClient.ImageInspect(ctx, childID)
 		assert.NilError(c, err)
 
-		assert.Check(c, is.Equal(parentID, image.Parent))
+		assert.Check(c, is.Equal(parentID, image.Parent)) //nolint:staticcheck // ignore SA1019: field is deprecated, but still included in response when present.
 	}
 }