From af0cdc36c7fd07f61717f1226ff0bfb6fc810347 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 10 Jun 2024 09:36:48 +0200 Subject: [PATCH] api: deprecate erroneous Config fields in `GET /images/{name}/json` response The `Config` field returned by this endpoint (used for "image inspect") returns additional fields that are not part of the image's configuration and not part of the [Docker Image Spec] and the [OCI Image Spec]. These additional fields are included in the response, due to an implementation detail, where the [api/types.ImageInspec] type used for the response is using the [container.Config] type. The [container.Config] type is a superset of the image config, and while the image's Config is used as a _template_ for containers created from the image, the additional fields are set at runtime (from options passed when creating the container) and not taken from the image Config. These fields are never set (and always return the default value for the type), but are not omitted in the response when left empty. As these fields were not intended to be part of the image configuration response, they are deprecated, and will be removed from the API. The following fields are currently included in the API response, but are not part of the underlying image's Config, and deprecated: - `Hostname` - `Domainname` - `AttachStdin` - `AttachStdout` - `AttachStderr` - `Tty` - `OpenStdin` - `StdinOnce` - `Image` - `NetworkDisabled` (already omitted unless set) - `MacAddress` (already omitted unless set) - `StopTimeout` (already omitted unless set) [Docker image spec]: https://github.com/moby/docker-image-spec/blob/v1.3.1/specs-go/v1/image.go#L19-L32 [OCI Image Spec]: https://github.com/opencontainers/image-spec/blob/v1.1.0/specs-go/v1/config.go#L24-L62 [api/types.ImageInspec]: https://github.com/moby/moby/blob/v26.1.4/api/types/types.go#L87-L104 [container.Config]: https://github.com/moby/moby/blob/v26.1.4/api/types/container/config.go#L47-L82 Signed-off-by: Sebastiaan van Stijn --- api/swagger.yaml | 37 ++++++++++++++++++++++----------- docs/api/version-history.md | 41 +++++++++++++++++++++++++++++++++++++ 2 files changed, 66 insertions(+), 12 deletions(-) diff --git a/api/swagger.yaml b/api/swagger.yaml index d845b1d737..56457afc4e 100644 --- a/api/swagger.yaml +++ b/api/swagger.yaml @@ -1368,7 +1368,8 @@ definitions:


- > **Note**: this field is always empty and must not be used. + > **Deprecated**: this field is not part of the image specification and is + > always empty. It must not be used, and will be removed in API v1.47. type: "string" example: "" Domainname: @@ -1377,7 +1378,8 @@ definitions:


- > **Note**: this field is always empty and must not be used. + > **Deprecated**: this field is not part of the image specification and is + > always empty. It must not be used, and will be removed in API v1.47. type: "string" example: "" User: @@ -1390,7 +1392,8 @@ definitions:


- > **Note**: this field is always false and must not be used. + > **Deprecated**: this field is not part of the image specification and is + > always false. It must not be used, and will be removed in API v1.47. type: "boolean" default: false example: false @@ -1400,7 +1403,8 @@ definitions:


- > **Note**: this field is always false and must not be used. + > **Deprecated**: this field is not part of the image specification and is + > always false. It must not be used, and will be removed in API v1.47. type: "boolean" default: false example: false @@ -1410,7 +1414,8 @@ definitions:


- > **Note**: this field is always false and must not be used. + > **Deprecated**: this field is not part of the image specification and is + > always false. It must not be used, and will be removed in API v1.47. type: "boolean" default: false example: false @@ -1436,7 +1441,8 @@ definitions:


- > **Note**: this field is always false and must not be used. + > **Deprecated**: this field is not part of the image specification and is + > always false. It must not be used, and will be removed in API v1.47. type: "boolean" default: false example: false @@ -1446,7 +1452,8 @@ definitions:


- > **Note**: this field is always false and must not be used. + > **Deprecated**: this field is not part of the image specification and is + > always false. It must not be used, and will be removed in API v1.47. type: "boolean" default: false example: false @@ -1456,7 +1463,8 @@ definitions:


- > **Note**: this field is always false and must not be used. + > **Deprecated**: this field is not part of the image specification and is + > always false. It must not be used, and will be removed in API v1.47. type: "boolean" default: false example: false @@ -1492,7 +1500,8 @@ definitions:


- > **Note**: this field is always empty and must not be used. + > **Deprecated**: this field is not part of the image specification and is + > always empty. It must not be used, and will be removed in API v1.47. type: "string" default: "" example: "" @@ -1530,7 +1539,8 @@ definitions:


- > **Note**: this field is always omitted and must not be used. + > **Deprecated**: this field is not part of the image specification and is + > always omitted. It must not be used, and will be removed in API v1.47. type: "boolean" default: false example: false @@ -1541,7 +1551,8 @@ definitions:


- > **Deprecated**: this field is deprecated in API v1.44 and up. It is always omitted. + > **Deprecated**: this field is not part of the image specification and is + > always omitted. It must not be used, and will be removed in API v1.47. type: "string" default: "" example: "" @@ -1574,7 +1585,8 @@ definitions:


- > **Note**: this field is always omitted and must not be used. + > **Deprecated**: this field is not part of the image specification and is + > always omitted. It must not be used, and will be removed in API v1.47. type: "integer" default: 10 x-nullable: true @@ -2115,6 +2127,7 @@ definitions: format: "dateTime" example: "2022-02-28T14:40:02.623929178Z" x-nullable: true + ImageSummary: type: "object" x-go-name: "Summary" diff --git a/docs/api/version-history.md b/docs/api/version-history.md index b9edc5a5e3..456855f467 100644 --- a/docs/api/version-history.md +++ b/docs/api/version-history.md @@ -29,6 +29,47 @@ keywords: "API, Docker, rcli, REST, documentation" * `GET /containers/json` now returns the annotations of containers. +### Deprecated Config fields in `GET /images/{name}/json` response + +The `Config` field returned by this endpoint (used for "image inspect") returns +additional fields that are not part of the image's configuration and not part of +the [Docker Image Spec] and the [OCI Image Spec]. + +These additional fields are included in the response, due to an +implementation detail, where the [api/types.ImageInspec] type used +for the response is using the [container.Config] type. + +The [container.Config] type is a superset of the image config, and while the +image's Config is used as a _template_ for containers created from the image, +the additional fields are set at runtime (from options passed when creating +the container) and not taken from the image Config. + +These fields are never set (and always return the default value for the type), +but are not omitted in the response when left empty. As these fields were not +intended to be part of the image configuration response, they are deprecated, +and will be removed from the API. + +The following fields are currently included in the API response, but +are not part of the underlying image's Config, and deprecated: + +- `Hostname` +- `Domainname` +- `AttachStdin` +- `AttachStdout` +- `AttachStderr` +- `Tty` +- `OpenStdin` +- `StdinOnce` +- `Image` +- `NetworkDisabled` (already omitted unless set) +- `MacAddress` (already omitted unless set) +- `StopTimeout` (already omitted unless set) + +[Docker image spec]: https://github.com/moby/docker-image-spec/blob/v1.3.1/specs-go/v1/image.go#L19-L32 +[OCI Image Spec]: https://github.com/opencontainers/image-spec/blob/v1.1.0/specs-go/v1/config.go#L24-L62 +[api/types.ImageInspec]: https://github.com/moby/moby/blob/v26.1.4/api/types/types.go#L87-L104 +[container.Config]: https://github.com/moby/moby/blob/v26.1.4/api/types/container/config.go#L47-L82 + ## v1.45 API changes [Docker Engine API v1.45](https://docs.docker.com/engine/api/v1.45/) documentation