Support referencing base images from a manifest list

[briandealwis]

Follow-on to #1547 (and #1360), users should be able to identify a platform for base image from a manifest list. Manifest lists are a mechanism for aggregating and serving platform-specific images from a registry. The list specifies manifests with a set of annotations for os, architecture, os.version, os.features, variant (cpu), and features (cpu).

There's a nice article describing use of manifest lists. The Docker CLI support an experimental --platform argument for specifying os/arch/variant combinations.

A related question is support for creating and pushing manifest lists — including perhaps being able to reference images built by jib within the reactor.

• when fixing this bug, remember to remove/update the FAQ entry

[chanseokoh]

There's something I am still not getting it. For example, openjdk:latest or openjdk:11 seems like a manifest list, and we know Jib has been working well. But #1360 suggests, perhaps when reference through a digest, using a manifest list doesn't work. Hence the questions to clear:

1. Is it certain that openjdk:11 is a manifest list? (Probably.) If so, how has Jib been able to cope with a manifest list? Or, is the registry that returns amd/linux by default in this situation?
2. But pulling a manifest list by a digest doesn't work. Is it the use of a digest that makes this difference? That is, unlike using a tag, a registry doesn't assume amd/linux by default?

[briandealwis]

Jib doesn't use manifest lists: to do so requires that we request application/vnd.docker.distribution.manifest.list.v2, but we don't. A manifest list is just a map of platforms to a sha1, which is why referencing a specific digest works.

openjdk does provide a manifest list:

$ docker manifest inspect openjdk
{
   "schemaVersion": 2,
   "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
   "manifests": [
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 2208,
         "digest": "sha256:08620da8ca7a66f433de9bf14bdcdd390292436f049a7a407a49eabad67d0827",
         "platform": {
            "architecture": "amd64",
            "os": "linux"
         }
      },
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 2207,
         "digest": "sha256:c5830875c4e5341dbc70996f33a58f7eed38f9d68d084c2ca183326fd14d14a7",
         "platform": {
            "architecture": "arm",
            "os": "linux",
            "variant": "v5"
         }
      },
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 2207,
         "digest": "sha256:79a149aef2e344ad38924e0999442a62ed93f8cab9eb35c39ae4414899bfccd9",
         "platform": {
...

# Inspect manifest for ARM image
$ docker manifest inspect openjdk@sha256:c5830875c4e5341dbc70996f33a58f7eed38f9d68d084c2ca183326fd14d14a7
{
	"schemaVersion": 2,
	"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
	"config": {
		"mediaType": "application/vnd.docker.container.image.v1+json",
		"size": 5597,
		"digest": "sha256:ae097c632fbe620b26d0df6fd32a831d98e90666f3a88feb69ba8011cd235928"
	},
	"layers": [
		{
			"mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
			"size": 44029811,
			"digest": "sha256:35963a726ee5d52a496a31b3c1f6accaf90ad61bf0e1e0bd8aad2cf66ab8cdb3"
		},
...
	]
}

And I can confirm that building against openjdk@sha256:c5830875c4e5341dbc70996f33a58f7eed38f9d68d084c2ca183326fd14d14a7 succeeds and is arm/linux.

[chanseokoh]

I know pulling a manifest (not manifest list) by a digest works, but rather, my question was more about the following:

But pulling a manifest list by a digest doesn't work. Is it the use of a digest that makes this difference? That is, unlike using a tag, a registry doesn't assume amd/linux by default?

That is, pulling a manifest list by a tag has been working, but pulling the very same manifest list by a digest doesn't work. And I think I now know why. Based on this comment, I guess it is the intention that a digest for a manifest list (e.g., the reference in #1360) won't work in the same way as it does when using a tag (e.g., openjdk:latest).

[briandealwis]

Bumping to P1 as it's actually not that easy to find the right digest for a manifest-list.

[briandealwis]

NB: OCI supports a similar concept called an image index.

[loosebazooka]

Okay started on this: tracking progress here:

• add support for v2.2 manifest list add v2.2 manifest list template #1805
• and more!

[chanseokoh]

Newer Jib versions now have an incubating feature to select a base image matching a user-configured platform from a manifest list. For usage, refer to the FAQ "How do I specify a platform in the manifest list (or OCI index) of a base image?".

As an incubating feature, there are limitations. For example, pushing a manifest list (in other words, selecting multiple base images) is not supported and being tracked by #2523.

Closing.