Setting OCI base image annotations

[imjasonh]

The OCI spec recently added specification for two new standard annotations, to facilitate pointing to a base image:

• org.opencontainers.image.base.digest Digest of the image this image is based on (string)
  • This SHOULD be the immediate image sharing zero-indexed layers with the image, such as from a Dockerfile FROM statement.
  • This SHOULD NOT reference any other images used to generate the contents of the image (e.g., multi-stage Dockerfile builds).
• org.opencontainers.image.base.name Image reference of the image this image is based on (string)
  • This SHOULD be image references in the format defined by distribution/distribution.
  • This SHOULD be a fully qualified reference name, without any assumed default registry. (e.g., registry.example.com/my-org/my-image:tag instead of my-org/my-image:tag).
  • This SHOULD be the immediate image sharing zero-indexed layers with the image, such as from a Dockerfile FROM statement.
  • This SHOULD NOT reference any other images used to generate the contents of the image (e.g., multi-stage Dockerfile builds).
  • If the image.base.name annotation is specified, the image.base.digest annotation SHOULD be the digest of the manifest referenced by the image.ref.name annotation.

More details and motivation here: https://articles.imjasonh.com/oci-base-image-annotations

This was based in part on work done by buildpacks, specifically the run-image.topLayer label, described here.

The hope is that, by standardizing how to communicate base image information, build tools like buildpacks and generalized rebase tooling consuming the data can interoperate.

I'd like to discuss and propose having the buildpacks spec recommend that implementations set these annotations, in addition to the existing base lifecycle.metadata labels already specified, and for the reference implementation in lifecycle to set it as well.

AFAIK this shouldn't require fundamentally new work, since implementations already need to be able to set the runImage.topLayer and runImage.reference -- this would just be a slightly different phrasing of that information, in a slightly different place, and codified as a recommendation in the spec.

[imjasonh]

Talked about this at office hours today.

The feedback seemed largely positive, but since pack defaults to writing images to the daemon (where annotations are lost), and having divergent behavior between pack build [to daemon] and pack build --publish [to registry] isn't great, it sounds like this might be blocked on larger architectural changes to make daemon-publishing not the default behavior.

Those changes will help with some other things too, and I think there's general agreement it's the right direction to go anyway, so let's let this proposal further motivate that architectural change, and when it's done, we'll be unblocked to set these annotations.

@sclevine also mentioned that buildpacks' topLayer scheme was specifically necessary to be able to rebase images where the old base image is no longer available in the registry (e.g., it was GCed since it no longer has a tag pointing at it). This is a totally reasonable use case, and something we might only be able to solve by proposing some topLayer-equivalent annotation to OCI.

(@ekcasey @sclevine please let me know if I'm mischaracterizing or missing details)