Thoughts on Support Platform Selection on Copy Func

[lizMSFT]

This page is about Platform Selection Behavior for docker pull <image> --platform <platform> command.

I'm trying to list some Platform Selection workflows for docker pull command. Then we can somehow follow these scenarios while working on ORAS platform selection feature.
Related task: #210

Sample manifest list

Artifact reference: zoeycr0707.azurecr.io/hello-world:multi
Manifest:

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
  "manifests": [
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "size": 525,
      "digest": "sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4",
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "size": 525,
      "digest": "sha256:432f982638b3aefab73cc58ab28f5c16e96fdb504e8c134fc58dff4bae8bf338",
      "platform": {
        "architecture": "arm64",
        "os": "linux",
        "variant": "v8"
      }
    },
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "size": 525,
      "digest": "sha256:7b8b7289d0536a08eabdf71c20246e23f7116641db7e1d278592236ea4dcb30c",
      "platform": {
        "architecture": "arm",
        "os": "linux",
        "variant": "v5"
      }
    },
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "size": 525,
      "digest": "sha256:f130bd2d67e6e9280ac6d0a6c83857bfaf70234e8ef4236876eccfbd30973b1c",
      "platform": {
        "architecture": "arm",
        "os": "linux",
        "variant": "v7"
      }
    },
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "size": 525,
      "digest": "sha256:b836bb24a270b9cc935962d8228517fde0f16990e88893d935efcb1b14c0017a",
      "platform": {
        "architecture": "ppc64le",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "size": 525,
      "digest": "sha256:c7b6944911848ce39b44ed660d95fb54d69bbd531de724c7ce6fc9f743c0b861",
      "platform": {
        "architecture": "s390x",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "size": 1125,
      "digest": "sha256:9ec668ee97c20731eb4f4f55f6248ac6b83a0d2e1add2110e6b5d62191f66dd7",
      "platform": {
        "architecture": "amd64",
        "os": "windows",
        "os.version": "10.0.20348.768"
      }
    }
  ]
}

Case 1

docker pull zoeycr0707.azurecr.io/hello-world:multi --platform linux

pulled image platform:

    ...
    "Architecture": "amd64",
    "Os": "linux",
    ...

Note: pulled the default linux platform image

Case 2

docker pull zoeycr0707.azurecr.io/hello-world:multi --platform windows

output:

    multi: Pulling from hello-world
    image operating system "windows" cannot be used on this platform

Note: not able to pull image with different operating system

Case 3

docker pull zoeycr0707.azurecr.io/hello-world:multi --platform linux/amd64

pulled image platform:

    ...
    "Architecture": "amd64",
    "Os": "linux",
    ...

Case 4

docker pull zoeycr0707.azurecr.io/hello-world:multi --platform linux/amd

output:

    multi: Pulling from hello-world
    no matching manifest for linux/amd in the manifest list entries

Note: not able to pull image without matching manifest architecture

Case 5

docker pull zoeycr0707.azurecr.io/hello-world:multi --platform linux/arm

pulled image platform:

    ...
    "Architecture": "arm",
    "Variant": "v7",
    "Os": "linux",
    ...

Note: pull the image with the greater variant

Case 6

docker pull zoeycr0707.azurecr.io/hello-world:multi --platform linux/arm/v6

pulled image platform:

    ...
    "Architecture": "arm",
    "Variant": "v5",
    "Os": "linux",
    ...

Note: pull the image with previous variant

Case 7

docker pull zoeycr0707.azurecr.io/hello-world:multi --platform linux/arm/v5

pulled image platform:

    ...
    "Architecture": "arm",
    "Variant": "v5",
    "Os": "linux",
    ...

Case 8

docker pull zoeycr0707.azurecr.io/hello-world:multi --platform linux/arm/xxx

pulled image platform:

    ...
    "Architecture": "arm",
    "Variant": "v5",
    "Os": "linux",
    ...

Note: pull the image with previous variant

Case 9

docker pull zoeycr0707.azurecr.io/hello-world:multi --platform linux/arm64/v1

output:

    multi: Pulling from hello-world
    no matching manifest for linux/arm64/v1 in the manifest list entries

Note: not able to pull image without matching manifest variant

Case 10

docker pull zoeycr0707.azurecr.io/hello-world:multi --platform linux/arm64

pulled image platform:

    ...
    "Architecture": "arm64",
    "Variant": "v8",
    "Os": "linux",
    ...

Case 11

docker pull zoeycr0707.azurecr.io/hello-world:multi --platform linuxxx

output:

    Error response from daemon: "linuxxx": unknown operating system or architecture: invalid argument

Case 12

docker pull zoeycr0707.azurecr.io/hello-world:multi --platform

output:

    flag needs an argument: --platform

Case 13

docker pull zoeycr0707.azurecr.io/hello-world:multi

pulled image platform:

    ...
    "Architecture": "amd64",
    "Os": "linux",
    ...

[Wwwsylvia]

Thanks for the summary!

[m5i-work]

Per Platform in image spec, an OS may have different version and features, should we cover them as well?

[lizMSFT]

Good catch, we might need to discuss with PM to clarify the workflows first.

[FeynmanZhou]

Hi @lizMSFT ,

To confirm the platform object, I think we need to be aligned with the OCI Image Index Specification. It has given a specific recommendation for each property.

[lizMSFT]

Discussion summary:

1. We will be aligned with the OCI Image Index Specification
   architecture and os are required
   os.version and variant are optional
   os.features and features are also optional, will discuss this later when implementing oras cli (including input format)

2. We will follow the rules that if multiple manifests match a client or runtime's requirements, the first matching entry SHOULD be used
   e.g.,
   Manifest list:

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
  "manifests": [
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "size": 525,
      "digest": "sha256:7b8b7289d0536a08eabdf71c20246e23f7116641db7e1d278592236ea4dcb30c",
      "platform": {
        "architecture": "arm",
        "os": "linux",
        "variant": "v5"
      }
    },
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "size": 525,
      "digest": "sha256:f130bd2d67e6e9280ac6d0a6c83857bfaf70234e8ef4236876eccfbd30973b1c",
      "platform": {
        "architecture": "arm",
        "os": "linux",
        "variant": "v7"
      }
    }
  ]
}

Input: oras pull zoeycr0707.azurecr.io/hello-world:multi --platform linux/arm
Pulled image platform should be:

    ...
    "Architecture": "arm",
    "Variant": "v5",
    "Os": "linux",
    ...

3. The returned manifest must exactly match the provided platform fields.

4. Platform comparison is case sensitive (in oras-go)

5. We will allow users to pull image with different operating system (oras-cli behavior)