Add annotations support to OCI outputter

[chrisdostert]

The OCI image spec allows specifying annotations on index entries.

I would like the ability to include annotations in my oci image output argument as in --output type=oci,dest=/image.tar,annotations=org.opencontainers.image.ref.name=latest and have it add these annotations.

see also #1218 for related

[developer-guy]

kindly ping @tonistiigi, I can take care of this one, would you mind assigning it to me?

[tonistiigi]

One thing you need to think about is if these annotations are in the descriptors of image index(used for multi-platform builds) or in the image manifest. I'm not sure if even the spec authors had any idea what is correct there.

[tonistiigi]

Some more specific steps for this:

Annotations should be settable by both client and a frontend. Client uses the output options that end up in https://github.com/moby/buildkit/blob/v0.10.3/client/solve.go#L49 and are passed to exporter in https://github.com/moby/buildkit/blob/v0.10.3/exporter/containerimage/export.go#L85 . Instead of using CSV inside CSV I think we can just let user define all annotations with unique key. -o annotation.<key>=value .

In addition to that they should be settable by the frontend. Frontend would write a record ref.annotation.<key>=value in https://pkg.go.dev/github.com/moby/buildkit@v0.10.3/frontend/gateway/client#Result.AddMeta that will end up in exporter at https://github.com/moby/buildkit/blob/v0.10.3/exporter/containerimage/export.go#L259 src.Metadata. We may want to set some annotations automatically in Dockerfile frontend for certain configurations but that can be a later PR as well.

If the image is multi-arch then all subimages get the annotation.

To set annotation to a specific subimage inside multi-arch manifest the key would be ref-<refid>.annotation.key=value. This RefID is the key in https://pkg.go.dev/github.com/moby/buildkit@v0.10.3/frontend/gateway/client#Result.AddRef and shows what reference is being addressed. Atm this is usually the platform value, eg. linux/amd64.

Still not clear to me if all annotations should go to the descriptors in the manifest list(index) or some go to individual manifest. If we want to make this distinction I think we need to support both annotation and descriptor-annotation scheme (or manifest-annotation and annotation). What about the main index manifest itself or the extra index in OCI export layout. Do these also need annotations? Hard to find any live images that use this thing and spec doesn't seem to define anything about it. They have just added "Annotations" field to all possible structures.

@jedevc

[crazy-max]

We may want to set some annotations automatically in Dockerfile frontend for certain configurations but that can be a later PR as well.

I think we could set some annotations automatically if a Git context is being used for example. Pretty much like the metadata-action does: https://github.com/docker/metadata-action/blob/8d56fe93cf3fd680736a906389438c1ed74d75f7/src/meta.ts#L442-L449 (minus the spdx ID, title and desc which is taken from GitHub API).

[jedevc]

@developer-guy are you still interested in this? I'd like to take this one if possible.

[developer-guy]

Please go ahead @jedevc, I'm interested in as well but I'm always open to learn new things from your contributions 🙅‍♂️