API: deprecate VirtualSize field for /images/json and /images/{id}/json

thaJeztah · thaJeztah · commit 1261fe69a358 · 2023-04-18T14:46:11.000+02:00
In versions of Docker before v1.10, this field was calculated from
the image itself and all of its parent images. Images are now stored
self-contained, and no longer use a parent-chain, making this field
an equivalent of the Size field.

Signed-off-by: Sebastiaan van Stijn &lt;github@gone.nl&gt;
diff --git a/api/server/router/image/image_routes.go b/api/server/router/image/image_routes.go
@@ -299,7 +299,7 @@ func (ir *imageRouter) toImageInspect(img *image.Image) (*types.ImageInspect, er
 		Os:              img.OperatingSystem(),
 		OsVersion:       img.OSVersion,
 		Size:            img.Details.Size,
-		VirtualSize:     img.Details.Size, // TODO: field unused, deprecate
+		VirtualSize:     img.Details.Size, //nolint:staticcheck // ignore SA1019: field is deprecated, but still set on API < v1.44.
 		GraphDriver: types.GraphDriverData{
 			Name: img.Details.Driver,
 			Data: img.Details.Metadata,
diff --git a/api/swagger.yaml b/api/swagger.yaml
@@ -1746,15 +1746,14 @@ definitions:
           Total size of the image including all layers it is composed of.
 
           In versions of Docker before v1.10, this field was calculated from
-          the image itself and all of its parent images. Docker v1.10 and up
-          store images self-contained, and no longer use a parent-chain, making
-          this field an equivalent of the Size field.
+          the image itself and all of its parent images. Images are now stored
+          self-contained, and no longer use a parent-chain, making this field
+          an equivalent of the Size field.
 
-          This field is kept for backward compatibility, but may be removed in
-          a future version of the API.
+          > **Deprecated**: this field is kept for backward compatibility, but
+          > will be removed in API v1.44.
         type: "integer"
         format: "int64"
-        x-nullable: false
         example: 1239828
       GraphDriver:
         $ref: "#/definitions/GraphDriverData"
@@ -1802,7 +1801,6 @@ definitions:
       - Created
       - Size
       - SharedSize
-      - VirtualSize
       - Labels
       - Containers
     properties:
@@ -1888,19 +1886,17 @@ definitions:
         x-nullable: false
         example: 1239828
       VirtualSize:
-        description: |
+        description: |-
           Total size of the image including all layers it is composed of.
 
           In versions of Docker before v1.10, this field was calculated from
-          the image itself and all of its parent images. Docker v1.10 and up
-          store images self-contained, and no longer use a parent-chain, making
-          this field an equivalent of the Size field.
+          the image itself and all of its parent images. Images are now stored
+          self-contained, and no longer use a parent-chain, making this field
+          an equivalent of the Size field.
 
-          This field is kept for backward compatibility, but may be removed in
-          a future version of the API.
+          Deprecated: this field is kept for backward compatibility, and will be removed in API v1.44.
         type: "integer"
         format: "int64"
-        x-nullable: false
         example: 172064416
       Labels:
         description: "User-defined key/value metadata."
diff --git a/api/types/image_summary.go b/api/types/image_summary.go
@@ -85,13 +85,10 @@ type ImageSummary struct {
 	// Total size of the image including all layers it is composed of.
 	//
 	// In versions of Docker before v1.10, this field was calculated from
-	// the image itself and all of its parent images. Docker v1.10 and up
-	// store images self-contained, and no longer use a parent-chain, making
-	// this field an equivalent of the Size field.
+	// the image itself and all of its parent images. Images are now stored
+	// self-contained, and no longer use a parent-chain, making this field
+	// an equivalent of the Size field.
 	//
-	// This field is kept for backward compatibility, but may be removed in
-	// a future version of the API.
-	//
-	// Required: true
-	VirtualSize int64 `json:"VirtualSize"`
+	// Deprecated: this field is kept for backward compatibility, and will be removed in API v1.44.
+	VirtualSize int64 `json:"VirtualSize,omitempty"`
 }
diff --git a/api/types/types.go b/api/types/types.go
@@ -123,9 +123,8 @@ type ImageInspect struct {
 	// store images self-contained, and no longer use a parent-chain, making
 	// this field an equivalent of the Size field.
 	//
-	// This field is kept for backward compatibility, but may be removed in
-	// a future version of the API.
-	VirtualSize int64 // TODO(thaJeztah): deprecate this field
+	// Deprecated: Unused in API 1.43 and up, but kept for backward compatibility with older API versions.
+	VirtualSize int64 `json:"VirtualSize,omitempty"`
 
 	// GraphDriver holds information about the storage driver used to store the
 	// container's and image's filesystem.
diff --git a/daemon/containerd/image_list.go b/daemon/containerd/image_list.go
@@ -250,7 +250,7 @@ func (i *ImageService) singlePlatformImage(ctx context.Context, contentStore con
 		RepoDigests: repoDigests,
 		RepoTags:    repoTags,
 		Size:        totalSize,
-		VirtualSize: totalSize,
+		VirtualSize: totalSize, //nolint:staticcheck // ignore SA1019: field is deprecated, but still set on API < v1.44.
 		// -1 indicates that the value has not been set (avoids ambiguity
 		// between 0 (default) and "not set". We cannot use a pointer (nil)
 		// for this, as the JSON representation uses "omitempty", which would
diff --git a/daemon/images/image_list.go b/daemon/images/image_list.go
@@ -261,7 +261,7 @@ func newImageSummary(image *image.Image, size int64) *types.ImageSummary {
 		ID:          image.ID().String(),
 		Created:     image.Created.Unix(),
 		Size:        size,
-		VirtualSize: size,
+		VirtualSize: size, //nolint:staticcheck // ignore SA1019: field is deprecated, but still set on API < v1.44.
 		// -1 indicates that the value has not been set (avoids ambiguity
 		// between 0 (default) and "not set". We cannot use a pointer (nil)
 		// for this, as the JSON representation uses "omitempty", which would
diff --git a/docs/api/version-history.md b/docs/api/version-history.md
@@ -23,6 +23,9 @@ keywords: "API, Docker, rcli, REST, documentation"
 * `GET /images/json` no longer includes hardcoded `<none>:<none>` and
   `<none>@<none>` in `RepoTags` and`RepoDigests` for untagged images.
   In such cases, empty arrays will be produced instead.
+* The `VirtualSize` field in the `GET /images/{name}/json` and `GET /images//json`
+  responses is deprecated and will no longer be included in API v1.44. Use the
+  `Size` field instead, which contains the same information.
 * `GET /info` now includes `no-new-privileges` in the `SecurityOptions` string
   list when this option is enabled globally. This change is not versioned, and
   affects all API versions if the daemon has this patch.
diff --git a/integration/system/disk_usage_test.go b/integration/system/disk_usage_test.go
@@ -61,7 +61,7 @@ func TestDiskUsage(t *testing.T) {
 							ID:          du.Images[0].ID,
 							RepoTags:    []string{"busybox:latest"},
 							Size:        du.LayersSize,
-							VirtualSize: du.LayersSize,
+							VirtualSize: du.LayersSize, //nolint:staticcheck // ignore SA1019: field is deprecated, but still set on API < v1.44.
 						},
 					},
 					Containers: []*types.Container{},
