The puller --platform flag doesn't support platform variants

[ixdy]

The --platform flag I added to the puller (#113) doesn't seem to work with some of the official images like busybox, since those manifests use platform variants for some architectures:

{
   "schemaVersion": 2,
   "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
   "manifests": [
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 527,
         "digest": "sha256:915f390a8912e16d4beb8689720a17348f3f6d1a7b659697df850ab625ea29d5",
         "platform": {
            "architecture": "amd64",
            "os": "linux"
         }
      },
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 527,
         "digest": "sha256:11a6b4baf996d8e52a332fbe7117aca1aae2b3068c7106f5b1065c16e8660895",
         "platform": {
            "architecture": "arm",
            "os": "linux",
            "variant": "v5"
         }
      },
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 527,
         "digest": "sha256:d4ae670481a474fda03b2e026a111972a5f459b86e0c57af1ec72d6045f57a27",
         "platform": {
            "architecture": "arm",
            "os": "linux",
            "variant": "v6"
         }
      },
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 527,
         "digest": "sha256:8777c62bb60d20e3b98216abe38ea1be721badd997f3840295eccd46f2281a2b",
         "platform": {
            "architecture": "arm",
            "os": "linux",
            "variant": "v7"
         }
      },
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 527,
         "digest": "sha256:adeafb67bdeab6f8ab07a46bc7b789d9ae508aac3b0933fb165e3ceb1f36e3e2",
         "platform": {
            "architecture": "arm64",
            "os": "linux",
            "variant": "v8"
         }
      },
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 527,
         "digest": "sha256:1ce7a47326ea36f5ba9bf7689cb1737cf79aef81577671d9774deb7378694e54",
         "platform": {
            "architecture": "386",
            "os": "linux"
         }
      },
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 528,
         "digest": "sha256:f7d5e9a7fa573052bbce9ad2d59b1c63b848f091a246a8c1e54ccc8178e1b794",
         "platform": {
            "architecture": "ppc64le",
            "os": "linux"
         }
      },
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 528,
         "digest": "sha256:d6d388d3ef21f3a75e49606dc0da5ec92da6f181bea347473b7f01904da09175",
         "platform": {
            "architecture": "s390x",
            "os": "linux"
         }
      }
   ]
}

If you try to pull with --platform=linux/amd, it fails, presumably since the platform doesn't match fully.

$ bazel-bin/puller --name index.docker.io/library/busybox:latest --directory /tmp/busybox --platform=linux/arm
F1119 19:28:06.679466   74570 fast_puller_.py:128] Error pulling and saving image index.docker.io/library/busybox:latest: Could not resolve manifest list to compatible manifest

Docker's cli somehow handles this, apparently downloading the v7 variant, but I don't know how it does that.

I can think of a few ways to address this:

1. Remove --platform, replacing it with --os, --architecture, and --variant. It's most explicit, and perhaps is what I should have done all along, but technically is a breaking change. (I'm not sure if anyone is using --platform yet though, since it's pretty new.)
2. Extend --platform to support variants somehow, either
   a. with an optional /variant suffix (e.g. linux/arm/v7), or
   b. by translating special values like those listed in https://github.com/docker-library/go-dockerlibrary/blob/master/architecture/oci-platform.go, e.g. arm32v7 -> {arm, v7}
3. Emulate whatever the docker cli is doing, though I don't like this one as much, since it doesn't seem to be documented, and I can't figure out how to make it download e.g. the arm v5 variant image.

I feel like the best options are either 1 or 2a. Thoughts?

(Note that the place I intend to use this, bazelbuild/rules_docker#544, already separates out os and architecture, so I'll probably add a third attribute there, variant, or maybe even turn it into a dict.)

cc @KaylaNguyen @nlopezgi

[ixdy]

Looking at the OCI spec (and what is implemented in client/v2_2/docker_image_list_.py) we may also need to support os.features, os.version, and probably features too. (The golang image uses os.version for the windows images, for example.)

I'm not sure what the cleanest way to do this is. I don't think we can really add all of those fields to --platform in a manageable way, though.

[nlopezgi]

@ixdy afaik rules_docker is the main user of this repo, so breaking changes (as long as we follow up with PR in rules_docker) should be fine. My preference is option 1.

[jonjohnsonjr]

@ixdy if you want one flag to fit all of this in, you could change --platform to accept a json blob and just pass that through to resolve, though for interactive use that is probably more cumbersome than --os and --architecture flags (et al).