RFC for OCI Image Annotations on Buildpacks

[candrews]

The buildpack tool should set OCI annotations on the OCI artifacts it produces providing users of these buildpacks with a consistent, standard mechanism for gathering information about the buildpack, including how to find its documentation and what version it is. The annotation values can be gathered from existing data sources (such as buildpack.toml) therefore not requiring any additional effort on the part of users of the buildpack tool.

Originally proposed to Paketo at paketo-buildpacks/rfcs#307 where it was pointed out that this change would best be made in the buildpack tool, see paketo-buildpacks/rfcs#307 (comment)

[buildpack-bot]

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)

[edmorley]

What happens when an app has more than one buildpack? The proposed schema doesn't support more than one entry.

[candrews]

The RFC is for the buildpacks themselves - not for the apps built by the buildpacks.

For example, it would apply to the Paketo Java buildpack, gcr.io/paketo-buildpacks/java, not to the application it builds.

[edmorley]

Ah ok. I think the RFC wording might need adjusting to make that clearer.

For example here:

The buildpack tool should set OCI annotations on the OCI artifacts it produces

"buildpack tool" isn't a phrase that's really used by this project, and read to me as meaning "the buildpack".

So it then read as:

"The buildpack should set OCI annotations on the OCI artifacts it produces"

...and the only OCI artifacts created when the buildpack runs is the app OCI image.

It sounds like what you're really proposing is a change to the buildpack distribution specification:
https://github.com/buildpacks/spec/blob/main/distribution.md

[edmorley]

It sounds like what you're really proposing is a change to the buildpack distribution specification:

Combined with proposing that the Pack CLI implement these changes, so that when a buildpack maintainer runs pack buildpack package to package their buildpack into the OCI image form of distribution it has the proposed labels set.

[candrews]

Instead of:

The buildpack tool should set...

I've updated the RFC to say:

pack buildpack package should set

Does that eliminate the confusion?

It sounds like what you're really proposing is a change to the buildpack distribution specification:
https://github.com/buildpacks/spec/blob/main/distribution.md

I believe so - is there something I should do in this RFC to indicate as much?

[edmorley]

Does that eliminate the confusion?

Yeah that does thank you.

I believe so - is there something I should do in this RFC to indicate as much?

So I think this comes down to whether this RFC is proposing only a change to the Pack CLI's own implementation, or a change to the specification which then the Pack CLI (plus any other implementations) would implement. If the latter, than the spec change could be described under the "spec change" section of the RFC template.

[candrews]

I've updated this MR to indicate that the Distribution spec would also be updated.

[natalieparellano]

Awesome to see this! I believe this supersedes #196

Edit: I am wrong, this is about buildpacks themselves, not the artifacts they produce!

[shresthaujjwal]

Thanks for opening this RFC. May I recommend extending this RFC not just to buildpack but also to builders?

[candrews]

Thanks for opening this RFC. May I recommend extending this RFC not just to buildpack but also to builders?

That sounds like a good idea to me!

[jkutner]

git commit ref

Should this be the Git commit sha instead of the ref?

[candrews]

You are correct - that should be the sha, not the commit ref.