Add OCI recommended annotations #196

sambhav · 2021-12-03T19:07:16Z

Signed-off-by: Sambhav Kothari [email protected]

buildpack-bot · 2021-12-03T19:07:32Z

Maintainers,

As you review this RFC please queue up issues to be created using the following commands:

/queue-issue <repo> "<title>" [labels]...
/unqueue-issue <uid>

Issues

(none)

imjasonh · 2021-12-05T13:37:05Z

There's an important distinction between labels and annotations. OCI recommends these annotations, but AIUI images in the daemon can't (currently?) be annotated, only labeled.

Talking to @ekcasey about this a few months ago it sounded like buildpacks would have to become more remote-image-centric in order to propagate annotations through the build. Or maybe the annotations only if the build is doing --push?

That being said I'm +1 on the change, and I'd love to help however I can.

sambhav · 2021-12-05T14:06:58Z

There's an important distinction between labels and annotations. OCI recommends these annotations, but AIUI images in the daemon can't (currently?) be annotated, only labeled.

Talking to @ekcasey about this a few months ago it sounded like buildpacks would have to become more remote-image-centric in order to propagate annotations through the build. Or maybe the annotations only if the build is doing --push?

That being said I'm +1 on the change, and I'd love to help however I can.

@imjasonh all your help is appreciated! I think I got a bit confused with the b/w compatibility clause at https://github.com/opencontainers/image-spec/blob/main/annotations.md#back-compatibility-with-label-schema

but reading it more closely it looks like it recommends not just changing the domain but also moving from labels to annotations. Happy to update the rfc to use annotations and making it conditional on registry pushes directly.

That being said, we have recently been facing more and more restrictions because of the daemon use case. Especially with things like cosign/sboms etc. I have been thinking about writing an RFC about deprecating the daemon flag and instead moving to OCI layout and registry. I could really use some help there if you are interested in the RFC. Your experience/knowledge with GGCR and OCI would be really helpful! Some more details at #197 (comment)

Signed-off-by: Sambhav Kothari <[email protected]>

sambhav · 2021-12-07T11:25:35Z

@imjasonh - updated to annotations conditional on the registry.

imjasonh · 2021-12-07T15:30:21Z

@imjasonh - updated to annotations conditional on the registry.

Thanks, this looks great to me. 👍

imjasonh · 2021-12-08T17:49:53Z

text/0000-annotations.md

+- `org.opencontainers.image.authors`: Authors of hte image. Sourced from `source.metadata.authors`.
+- `org.opencontainers.image.version`: Authors of hte image. Sourced from `source.metadata.version`.


Suggested change

- `org.opencontainers.image.authors`: Authors of hte image. Sourced from `source.metadata.authors`.

- `org.opencontainers.image.version`: Authors of hte image. Sourced from `source.metadata.version`.

- `org.opencontainers.image.authors`: Authors of the image. Sourced from `source.metadata.authors`.

- `org.opencontainers.image.version`: Version of the image. Sourced from `source.metadata.version`.

imjasonh · 2021-12-08T17:50:51Z

text/0000-annotations.md

+Optionally adds the following annotations where applicable when lifecycle is used to publish images directly to the registry - 
+
+- `org.opencontainers.image.base.name`: Run image tag name. Currently stored in `io.buildpacks.lifecycle.metadata.run-image.reference`
+- `org.opencontainers.image.base.digest`: Run image digest. Currently stored in `io.buildpacks.lifecycle.metadata.run-image.reference`


Does the run-image.reference data include both the mutable tag reference and the immutable digest?

Based on the spec this would be the immutable digest:

A digest reference to a manifest stored in an OCI image registry

hone

This looks good to me.

natalieparellano · 2022-01-03T20:05:08Z

text/0000-annotations.md

+
+Optionally adds the following annotations where applicable when lifecycle is used to publish images directly to the registry - 
+
+- `org.opencontainers.image.base.name`: Run image tag name. Currently stored in `io.buildpacks.lifecycle.metadata.run-image.reference`


I think this is actually io.buildpacks.lifecycle.metadata.stack.runImage.image

natalieparellano · 2022-01-03T20:06:23Z

text/0000-annotations.md

+Optionally adds the following annotations where applicable when lifecycle is used to publish images directly to the registry - 
+
+- `org.opencontainers.image.base.name`: Run image tag name. Currently stored in `io.buildpacks.lifecycle.metadata.run-image.reference`
+- `org.opencontainers.image.base.digest`: Run image digest. Currently stored in `io.buildpacks.lifecycle.metadata.run-image.reference`


Suggested change

- `org.opencontainers.image.base.digest`: Run image digest. Currently stored in `io.buildpacks.lifecycle.metadata.run-image.reference`

- `org.opencontainers.image.base.digest`: Run image digest. Currently stored in `io.buildpacks.lifecycle.metadata.runImage.reference`

hone · 2022-01-12T19:45:02Z

@sclevine @jkutner @ekcasey ready for review please 🙏

ekcasey

I am of the opinion that we should table this and come back to it after implementing a proposal to fix the only source of complexity here and remove lifecycle->daemon support.

ekcasey · 2022-01-14T19:45:07Z

text/0000-annotations.md

+# Drawbacks
+[drawbacks]: #drawbacks
+
+In case of the daemon mode, the annotations cannot be applied and will be ignored.


Up until this point we have endeavored to make the output image identical regardless of export target (registry vs daemon). I am leary of introducing behavior differences between the daemon and remote cases. IMO it would be much better to remove the daemon as an export target first before continuing with this RFC.

I would agree if the registry and daemon cases were identical to begin with but they are already not. Things like io.buildpacks.lifecycle.metadata.runImage.reference change depending on whether it's built for daemon or registry. The same inputs for an image don't survive round-tripping because of that and the difference in compression of layers. In other words, lifecycle -> daemon -> registry != lifecycle -> registry. IMO, it doesn't sound reasonable to block this feature on the eventual hope that we'll get rid of the daemon. At the end of the day, the core concern (discrepancy) will always exist but be pushed onto the platform.

IMO, it doesn't sound reasonable to block this feature on the eventual hope that we'll get rid of the daemon.

In order to get rid of the daemon instead of merely hoping it goes away I think we need to hold the line somewhere and actually prioritize getting rid of it. Adding remote-only features seems like the right place to draw the line to me.

Yes there is a path forward without removing the daemon first, but it is uglier and requires more compromises in the lifecycle and imgutil and caveats in our docs and specs. Instead we could invest in removing the daemon and clean up some of the uglier parts of the project.

ekcasey · 2022-01-14T19:51:02Z

text/0000-annotations.md

+- `org.opencontainers.image.base.name`: Run image tag name. Currently stored in `io.buildpacks.lifecycle.metadata.run-image.reference`
+- `org.opencontainers.image.base.digest`: Run image digest. Currently stored in `io.buildpacks.lifecycle.metadata.run-image.reference`
+
+The platform may also provide appropriate keys inside `project-metadata.toml` to the lifecycle so that it exports the appropriate annotations listed below.


In the ideal world I think these project metadata annotation would be better contributed by a buildpack vs by the lifecycle for the following reasons:

Buildpack contributed behavior more easily upgradable accross a variable of platforms

Keeping the surface area of the platform API as small as possible makes the spec and the conditional logic in lifecycle less complicated, thus making our lives easier and enabling us to actually make progress shipping things.

The way I imagine it:

step 1 remove daemon

step 2 allow buildpacks to contribute aribtrary annotations

step 3 provide a (utility?) buildpack that contributes these annotations based off the values in project.toml

That ordering makes sense to me. Is there a rough plan/timeline for step 1?

It ties into this RFC issue: #197

@jjbustamante is on it!

Based on my comment here, I'm back to say that I don't think step 1 is necessary.

steps 2 and 3 can be an alternative approach to this RFC without step 1. I'd love to see it comparatively in the Alternatives section.

#196 (comment)

ekcasey · 2022-02-04T20:17:41Z

@samj1912 I am convinced that we can approve a version of this without blocking on the daemon removal. However I still feel pretty strongly that we shouldn't make the lifecycle aware of these specific annotations, but should instead:

Provide a mechanism whereby a buildpack can set abitrary annotations
Implementing this as a utility buildpack

Are you open to revising this RFC to make it address buildpack-provided annotations instead of addressing OCI specified annotations specifically?

sambhav requested a review from a team as a code owner December 3, 2021 19:07

sambhav added the team/implementation label Dec 3, 2021

github-actions bot assigned sclevine Dec 3, 2021

Add OCI recommended labels

ffa7354

Signed-off-by: Sambhav Kothari <[email protected]>

sambhav force-pushed the annotations branch from c67190e to ffa7354 Compare December 7, 2021 11:25

sambhav changed the title ~~Add OCI recommended labels~~ Add OCI recommended annotations Dec 7, 2021

imjasonh reviewed Dec 8, 2021

View reviewed changes

hone requested review from hone, jkutner and nebhale December 8, 2021 19:42

imjasonh mentioned this pull request Dec 14, 2021

Support OCI labels ko-build/ko#538

Closed

hone approved these changes Dec 15, 2021

View reviewed changes

hone requested a review from sclevine December 15, 2021 17:31

natalieparellano reviewed Jan 3, 2022

View reviewed changes

natalieparellano approved these changes Jan 3, 2022

View reviewed changes

nebhale approved these changes Jan 6, 2022

View reviewed changes

hone requested a review from ekcasey January 12, 2022 19:44

ekcasey requested changes Jan 14, 2022

View reviewed changes

ekcasey mentioned this pull request Jan 14, 2022

Add RFC for cosign integration #195

Open

jkutner approved these changes Jan 19, 2022

View reviewed changes

jromero approved these changes Jan 20, 2022

View reviewed changes

sambhav marked this pull request as draft February 16, 2022 19:27

jjbustamante mentioned this pull request Aug 18, 2023

Set org.opencontainers.image.source From project.source-url buildpacks/pack#1049

Open

natalieparellano mentioned this pull request Jun 27, 2024

RFC for OCI Image Annotations on Buildpacks #314

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add OCI recommended annotations #196

Add OCI recommended annotations #196

sambhav commented Dec 3, 2021 •

edited

Loading

buildpack-bot commented Dec 3, 2021

imjasonh commented Dec 5, 2021

sambhav commented Dec 5, 2021 •

edited

Loading

sambhav commented Dec 7, 2021

imjasonh commented Dec 7, 2021

imjasonh Dec 8, 2021

imjasonh Dec 8, 2021

jromero Jan 20, 2022

hone left a comment

natalieparellano Jan 3, 2022 •

edited

Loading

natalieparellano Jan 3, 2022

hone commented Jan 12, 2022

ekcasey left a comment

ekcasey Jan 14, 2022

jromero Jan 20, 2022 •

edited

Loading

ekcasey Jan 20, 2022

ekcasey Jan 14, 2022

imjasonh Jan 14, 2022

jromero Jan 20, 2022

jromero Jan 20, 2022 •

edited

Loading

ekcasey Jan 20, 2022

ekcasey commented Feb 4, 2022

		- `org.opencontainers.image.authors`: Authors of hte image. Sourced from `source.metadata.authors`.
		- `org.opencontainers.image.version`: Authors of hte image. Sourced from `source.metadata.version`.


		Optionally adds the following annotations where applicable when lifecycle is used to publish images directly to the registry -

		- `org.opencontainers.image.base.name`: Run image tag name. Currently stored in `io.buildpacks.lifecycle.metadata.run-image.reference`

	- `org.opencontainers.image.base.digest`: Run image digest. Currently stored in `io.buildpacks.lifecycle.metadata.run-image.reference`
	- `org.opencontainers.image.base.digest`: Run image digest. Currently stored in `io.buildpacks.lifecycle.metadata.runImage.reference`

Add OCI recommended annotations #196

Are you sure you want to change the base?

Add OCI recommended annotations #196

Conversation

sambhav commented Dec 3, 2021 • edited Loading

buildpack-bot commented Dec 3, 2021

Issues

imjasonh commented Dec 5, 2021

sambhav commented Dec 5, 2021 • edited Loading

sambhav commented Dec 7, 2021

imjasonh commented Dec 7, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hone left a comment

Choose a reason for hiding this comment

natalieparellano Jan 3, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hone commented Jan 12, 2022

ekcasey left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jromero Jan 20, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jromero Jan 20, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ekcasey commented Feb 4, 2022

sambhav commented Dec 3, 2021 •

edited

Loading

sambhav commented Dec 5, 2021 •

edited

Loading

natalieparellano Jan 3, 2022 •

edited

Loading

jromero Jan 20, 2022 •

edited

Loading

jromero Jan 20, 2022 •

edited

Loading