Merge pull request #43890 from thaJeztah/22.06_backport_api_fix_missing_platform

[22.06 backport] api: swagger: add missing "platform" query-arg on create

api/swagger.yaml

@@ -6251,6 +6251,28 @@ paths:
             `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.
           type: "string"
           pattern: "^/?[a-zA-Z0-9][a-zA-Z0-9_.-]+$"
+        - name: "platform"
+          in: "query"
+          description: |
+            Platform in the format `os[/arch[/variant]]` used for image lookup.
+
+            When specified, the daemon checks if the requested image is present
+            in the local image cache with the given OS and Architecture, and
+            otherwise returns a `404` status.
+
+            If the option is not set, the host's native OS and Architecture are
+            used to look up the image in the image cache. However, if no platform
+            is passed and the given image does exist in the local image cache,
+            but its OS or architecture does not match, the container is created
+            with the available image, and a warning is added to the `Warnings`
+            field in the response, for example;
+
+                WARNING: The requested image's platform (linux/arm64/v8) does not
+                         match the detected host platform (linux/amd64) and no
+                         specific platform was requested
+
+          type: "string"
+          default: ""
         - name: "body"
           in: "body"
           description: "Container to create"

docs/api/v1.41.yaml

@@ -5990,6 +5990,28 @@ paths:
             `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.
           type: "string"
           pattern: "^/?[a-zA-Z0-9][a-zA-Z0-9_.-]+$"
+        - name: "platform"
+          in: "query"
+          description: |
+            Platform in the format `os[/arch[/variant]]` used for image lookup.
+
+            When specified, the daemon checks if the requested image is present
+            in the local image cache with the given OS and Architecture, and
+            otherwise returns a `404` status.
+
+            If the option is not set, the host's native OS and Architecture are
+            used to look up the image in the image cache. However, if no platform
+            is passed and the given image does exist in the local image cache,
+            but its OS or architecture does not match, the container is created
+            with the available image, and a warning is added to the `Warnings`
+            field in the response, for example;
+
+                WARNING: The requested image's platform (linux/arm64/v8) does not
+                         match the detected host platform (linux/amd64) and no
+                         specific platform was requested
+
+          type: "string"
+          default: ""
         - name: "body"
           in: "body"
           description: "Container to create"

docs/api/v1.42.yaml

@@ -6251,6 +6251,28 @@ paths:
             `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.
           type: "string"
           pattern: "^/?[a-zA-Z0-9][a-zA-Z0-9_.-]+$"
+        - name: "platform"
+          in: "query"
+          description: |
+            Platform in the format `os[/arch[/variant]]` used for image lookup.
+
+            When specified, the daemon checks if the requested image is present
+            in the local image cache with the given OS and Architecture, and
+            otherwise returns a `404` status.
+
+            If the option is not set, the host's native OS and Architecture are
+            used to look up the image in the image cache. However, if no platform
+            is passed and the given image does exist in the local image cache,
+            but its OS or architecture does not match, the container is created
+            with the available image, and a warning is added to the `Warnings`
+            field in the response, for example;
+
+                WARNING: The requested image's platform (linux/arm64/v8) does not
+                         match the detected host platform (linux/amd64) and no
+                         specific platform was requested
+
+          type: "string"
+          default: ""
         - name: "body"
           in: "body"
           description: "Container to create"

docs/api/version-history.md

@@ -140,6 +140,22 @@ keywords: "API, Docker, rcli, REST, documentation"
   to limit the maximum number of PIDs.
 * `GET /tasks` now  returns `Pids` in `TaskTemplate.Resources.Limits`.
 * `GET /tasks/{id}` now  returns `Pids` in `TaskTemplate.Resources.Limits`.
+* `POST /containers/create` now accepts a `platform` query parameter in the format
+  `os[/arch[/variant]]`.
+
+  When set, the daemon checks if the requested image is present in the local image
+  cache with the given OS and Architecture, and otherwise returns a `404` status.
+
+  If the option is _not_ set, the host's native OS and Architecture are used to
+  look up the image in the image cache. However, if no platform is passed and the
+  given image _does_ exist in the local image cache, but its OS or architecture
+  do not match, the container is created with the available image, and a warning
+  is added to the `Warnings` field in the response, for example;
+
+      WARNING: The requested image's platform (linux/arm64/v8) does not
+               match the detected host platform (linux/amd64) and no
+               specific platform was requested
+
 * `POST /containers/create` on Linux now accepts the `HostConfig.CgroupnsMode` property.
   Set the property to `host` to create the container in the daemon's cgroup namespace, or
   `private` to create the container in its own private cgroup namespace.  The per-daemon