Merge pull request #47941 from thaJeztah/api_image_inspect_deprecate_fields

api: deprecate erroneous Config fields in `GET /images/{name}/json` response

api/swagger.yaml

@@ -1368,7 +1368,8 @@ definitions:
 
           <p><br /></p>
 
-          > **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:
 
           <p><br /></p>
 
-          > **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:
 
           <p><br /></p>
 
-          > **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:
 
           <p><br /></p>
 
-          > **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:
 
           <p><br /></p>
 
-          > **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:
 
           <p><br /></p>
 
-          > **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:
 
           <p><br /></p>
 
-          > **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:
 
           <p><br /></p>
 
-          > **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:
 
           <p><br /></p>
 
-          > **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:
 
           <p><br /></p>
 
-          > **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:
 
           <p><br /></p>
 
-          > **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:
 
           <p><br /></p>
 
-          > **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"

docs/api/version-history.md

@@ -31,6 +31,47 @@ keywords: "API, Docker, rcli, REST, documentation"
   OCI Platform type) that allows selecting a specific platform manifest from
   the multi-platform image.
 
+### 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