From 1261fe69a3586bb102182aa885197822419c768c Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 17 Apr 2023 13:15:57 +0200 Subject: [PATCH] API: deprecate VirtualSize field for /images/json and /images/{id}/json 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 --- api/server/router/image/image_routes.go | 2 +- api/swagger.yaml | 24 ++++++++++-------------- api/types/image_summary.go | 13 +++++-------- api/types/types.go | 5 ++--- daemon/containerd/image_list.go | 2 +- daemon/images/image_list.go | 2 +- docs/api/version-history.md | 3 +++ integration/system/disk_usage_test.go | 2 +- 8 files changed, 24 insertions(+), 29 deletions(-) diff --git a/api/server/router/image/image_routes.go b/api/server/router/image/image_routes.go index a0e609c427..1500f0e876 100644 --- 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 index aea7521786..84a98d042e 100644 --- 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 index 90b983a25c..0f6f144840 100644 --- 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 index 0d25ea4c45..b413e02000 100644 --- 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 index 1b3f6ffb89..2f49ffabe4 100644 --- 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 index e940813c87..1c3331c8b7 100644 --- 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 index c48697245e..530040cdce 100644 --- 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 `:` and `@` 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 index a7bc863429..17d3b2c318 100644 --- 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{},