Skip to content

Commit 1261fe6

Browse files
committed
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 <github@gone.nl>
1 parent 20a1d23 commit 1261fe6

File tree

8 files changed

+24
-29
lines changed

8 files changed

+24
-29
lines changed

api/server/router/image/image_routes.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -299,7 +299,7 @@ func (ir *imageRouter) toImageInspect(img *image.Image) (*types.ImageInspect, er
299299
Os: img.OperatingSystem(),
300300
OsVersion: img.OSVersion,
301301
Size: img.Details.Size,
302-
VirtualSize: img.Details.Size, // TODO: field unused, deprecate
302+
VirtualSize: img.Details.Size, //nolint:staticcheck // ignore SA1019: field is deprecated, but still set on API < v1.44.
303303
GraphDriver: types.GraphDriverData{
304304
Name: img.Details.Driver,
305305
Data: img.Details.Metadata,

api/swagger.yaml

Lines changed: 10 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1746,15 +1746,14 @@ definitions:
17461746
Total size of the image including all layers it is composed of.
17471747
17481748
In versions of Docker before v1.10, this field was calculated from
1749-
the image itself and all of its parent images. Docker v1.10 and up
1750-
store images self-contained, and no longer use a parent-chain, making
1751-
this field an equivalent of the Size field.
1749+
the image itself and all of its parent images. Images are now stored
1750+
self-contained, and no longer use a parent-chain, making this field
1751+
an equivalent of the Size field.
17521752
1753-
This field is kept for backward compatibility, but may be removed in
1754-
a future version of the API.
1753+
> **Deprecated**: this field is kept for backward compatibility, but
1754+
> will be removed in API v1.44.
17551755
type: "integer"
17561756
format: "int64"
1757-
x-nullable: false
17581757
example: 1239828
17591758
GraphDriver:
17601759
$ref: "#/definitions/GraphDriverData"
@@ -1802,7 +1801,6 @@ definitions:
18021801
- Created
18031802
- Size
18041803
- SharedSize
1805-
- VirtualSize
18061804
- Labels
18071805
- Containers
18081806
properties:
@@ -1888,19 +1886,17 @@ definitions:
18881886
x-nullable: false
18891887
example: 1239828
18901888
VirtualSize:
1891-
description: |
1889+
description: |-
18921890
Total size of the image including all layers it is composed of.
18931891
18941892
In versions of Docker before v1.10, this field was calculated from
1895-
the image itself and all of its parent images. Docker v1.10 and up
1896-
store images self-contained, and no longer use a parent-chain, making
1897-
this field an equivalent of the Size field.
1893+
the image itself and all of its parent images. Images are now stored
1894+
self-contained, and no longer use a parent-chain, making this field
1895+
an equivalent of the Size field.
18981896
1899-
This field is kept for backward compatibility, but may be removed in
1900-
a future version of the API.
1897+
Deprecated: this field is kept for backward compatibility, and will be removed in API v1.44.
19011898
type: "integer"
19021899
format: "int64"
1903-
x-nullable: false
19041900
example: 172064416
19051901
Labels:
19061902
description: "User-defined key/value metadata."

api/types/image_summary.go

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -85,13 +85,10 @@ type ImageSummary struct {
8585
// Total size of the image including all layers it is composed of.
8686
//
8787
// In versions of Docker before v1.10, this field was calculated from
88-
// the image itself and all of its parent images. Docker v1.10 and up
89-
// store images self-contained, and no longer use a parent-chain, making
90-
// this field an equivalent of the Size field.
88+
// the image itself and all of its parent images. Images are now stored
89+
// self-contained, and no longer use a parent-chain, making this field
90+
// an equivalent of the Size field.
9191
//
92-
// This field is kept for backward compatibility, but may be removed in
93-
// a future version of the API.
94-
//
95-
// Required: true
96-
VirtualSize int64 `json:"VirtualSize"`
92+
// Deprecated: this field is kept for backward compatibility, and will be removed in API v1.44.
93+
VirtualSize int64 `json:"VirtualSize,omitempty"`
9794
}

api/types/types.go

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -123,9 +123,8 @@ type ImageInspect struct {
123123
// store images self-contained, and no longer use a parent-chain, making
124124
// this field an equivalent of the Size field.
125125
//
126-
// This field is kept for backward compatibility, but may be removed in
127-
// a future version of the API.
128-
VirtualSize int64 // TODO(thaJeztah): deprecate this field
126+
// Deprecated: Unused in API 1.43 and up, but kept for backward compatibility with older API versions.
127+
VirtualSize int64 `json:"VirtualSize,omitempty"`
129128

130129
// GraphDriver holds information about the storage driver used to store the
131130
// container's and image's filesystem.

daemon/containerd/image_list.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -250,7 +250,7 @@ func (i *ImageService) singlePlatformImage(ctx context.Context, contentStore con
250250
RepoDigests: repoDigests,
251251
RepoTags: repoTags,
252252
Size: totalSize,
253-
VirtualSize: totalSize,
253+
VirtualSize: totalSize, //nolint:staticcheck // ignore SA1019: field is deprecated, but still set on API < v1.44.
254254
// -1 indicates that the value has not been set (avoids ambiguity
255255
// between 0 (default) and "not set". We cannot use a pointer (nil)
256256
// for this, as the JSON representation uses "omitempty", which would

daemon/images/image_list.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -261,7 +261,7 @@ func newImageSummary(image *image.Image, size int64) *types.ImageSummary {
261261
ID: image.ID().String(),
262262
Created: image.Created.Unix(),
263263
Size: size,
264-
VirtualSize: size,
264+
VirtualSize: size, //nolint:staticcheck // ignore SA1019: field is deprecated, but still set on API < v1.44.
265265
// -1 indicates that the value has not been set (avoids ambiguity
266266
// between 0 (default) and "not set". We cannot use a pointer (nil)
267267
// for this, as the JSON representation uses "omitempty", which would

docs/api/version-history.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,9 @@ keywords: "API, Docker, rcli, REST, documentation"
2323
* `GET /images/json` no longer includes hardcoded `<none>:<none>` and
2424
`<none>@<none>` in `RepoTags` and`RepoDigests` for untagged images.
2525
In such cases, empty arrays will be produced instead.
26+
* The `VirtualSize` field in the `GET /images/{name}/json` and `GET /images//json`
27+
responses is deprecated and will no longer be included in API v1.44. Use the
28+
`Size` field instead, which contains the same information.
2629
* `GET /info` now includes `no-new-privileges` in the `SecurityOptions` string
2730
list when this option is enabled globally. This change is not versioned, and
2831
affects all API versions if the daemon has this patch.

integration/system/disk_usage_test.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ func TestDiskUsage(t *testing.T) {
6161
ID: du.Images[0].ID,
6262
RepoTags: []string{"busybox:latest"},
6363
Size: du.LayersSize,
64-
VirtualSize: du.LayersSize,
64+
VirtualSize: du.LayersSize, //nolint:staticcheck // ignore SA1019: field is deprecated, but still set on API < v1.44.
6565
},
6666
},
6767
Containers: []*types.Container{},

0 commit comments

Comments
 (0)