Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

RFC for OCI Image Annotations on Buildpacks #314

Merged
merged 7 commits into from
Aug 8, 2024
Merged

RFC for OCI Image Annotations on Buildpacks #314

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
7dc794a
RFC for OCI Image Annotations on Buildpacks
candrews Jun 26, 2024
04e957e
Note that buildpacks without these annotation would still be valid
candrews Jul 11, 2024
dca1e5e
Don't require VCS info, as that info isn't always available
candrews Jul 12, 2024
1ac8295
`org.opencontainers.image.revision` should be the hash, not the ref
candrews Jul 12, 2024
d2b2b1a
Consistently use the term `pack` tool instead of `buildpack` tool
candrews Jul 18, 2024
438fdde
Fix incorrect tense of "consider"
candrews Jul 18, 2024
cc8e2f4
Use the term "packaging" as that's the term used by the tool
candrews Jul 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 116 additions & 0 deletions text/0000-oci-image-annotations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
# Meta
[meta]: #meta
- Name: OCI Image Annotations on Buildpacks
- Start Date: 2024-06-26
- Author(s): @candrews
- Status: Draft <!-- Acceptable values: Draft, Approved, On Hold, Superseded -->
- RFC Pull Request: (leave blank)
- CNB Pull Request: (leave blank)
- CNB Issue: (leave blank)
- Supersedes: (put "N/A" unless this replaces an existing RFC, then link to that RFC)

# Summary
[summary]: #summary

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.

# Definitions
[definitions]: #definitions

[Buildpacks](https://buildpacks.io/docs/for-app-developers/concepts/buildpack/) are [OCI images](https://github.com/opencontainers/image-spec/blob/v1.1.0/README.md). [Annotations](https://github.com/opencontainers/image-spec/blob/v1.1.0/annotations.md) are optional properties that can be applies to image manifests and descriptions providing mechanism to communicate metadata. The [Pre-Defined Annotation Keys](https://github.com/opencontainers/image-spec/blob/v1.1.0/annotations.md#pre-defined-annotation-keys) are a standardized set of annotations that can be used to convey metadata in a consistent way between image authors and users.

# Motivation
[motivation]: #motivation

Knowing the origin and other metadata for a buildpack (which is an OCI image) is very helpful. Some examples of such use cases include finding release notes, user manuals, bug reporting procedures, and license information. Currently, it can be difficult to find the source control repository of a buildpack as that information is not available in a standard way.

The OCI Image Format Specification's Pre-Defined Annotation Keys provide a standardized way to discover additional information about an OCI image. Because these annotations are standardized and widely used, tools have come to use them. For example, [Snyk](https://snyk.io/blog/how-and-when-to-use-docker-labels-oci-container-annotations/) and [Renovate](https://github.com/renovatebot/renovate/blob/34.115.1/lib/modules/datasource/docker/readme.md) use these annotations.

The outcome will be that users and tools will be able to gather more information about buildpacks, facilitating use cases such as gathering releases notes and finding documentation.

# What it is
[what-it-is]: #what-it-is

`pack buildpack package` should set the following OCI annotations on the images it produces:

- `org.opencontainers.image.source`
- `org.opencontainers.image.revision`
candrews marked this conversation as resolved.
Show resolved Hide resolved
- `org.opencontainers.image.title`
- `org.opencontainers.image.version`
- `org.opencontainers.image.url` (when possible)
- `org.opencontainers.image.description` (when possible)

The target personas as buildpack users, platform operators, and platform implementers. Any of those groups will be able to more easily understand the origin (source), version, and other information about the buildpack. This information can then be used manually or with the aid of tools to get release notes which aid these personas in making informed decisions.

# How it Works
[how-it-works]: #how-it-works

When building the buildpack, the `buildpack` tool can get the values for the `org.opencontainers.image.source` and `org.opencontainers.image.revision` annotations from git. `org.opencontainers.image.source` is derived from the git origin and `org.opencontainers.image.revision` is the git commit ref.
jkutner marked this conversation as resolved.
Show resolved Hide resolved

The other annotation values come from `buildpack.toml` mapped to OCI annotations as follows:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@candrews candrews Jun 26, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm still seeing a lot of references to: "buildpack tool". Can we ensure this RFC is consistent in its terminology?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've updated all occurrences of "buildpack tool" to be "pack tool" for consistency


- `name` -> `org.opencontainers.image.title`
- `version` -> `org.opencontainers.image.version`
- `homepage` (optional) -> `org.opencontainers.image.url`
- `description` (optional) -> `org.opencontainers.image.description`

The following example values are from [Paketo Buildpack for Java 13.0.1](https://github.com/paketo-buildpacks/java/releases/tag/v13.0.1):

- `org.opencontainers.image.source`: https://github.com/paketo-buildpacks/java
- `org.opencontainers.image.revision`: 09747b1df0a56aea74ce9b01af89df6feb1fc50a
- `org.opencontainers.image.title`: Paketo Buildpack for Java
- `org.opencontainers.image.version`: 13.0.1
- `org.opencontainers.image.url`: https://paketo.io/docs/howto/java
- `org.opencontainers.image.description`: A Cloud Native Buildpack with an order definition suitable for Java applications

# Migration
[migration]: #migration

The `buildpack` tool would be modified to set the annotations.
candrews marked this conversation as resolved.
Show resolved Hide resolved

# Drawbacks
[drawbacks]: #drawbacks

N/A

# Alternatives
[alternatives]: #alternatives

Instead of standardizing the use of these annotations across all buildpacks, each buildpack could add the annotations individually. However, that approach has significant consistency and maintainability concerns. Standardizing the annotations and implementing them consistently across all buildpacks minimizes risk and maximizes utility. If this approach is not done, users will continue to be unable to use tools to gather buildpack information, and gathering that information manually will continue to be difficult or impossible.

# Prior Art
[prior-art]: #prior-art

Many images are setting OCI image annotations with adoption continually on the rise.

# Unresolved Questions
[unresolved-questions]: #unresolved-questions

N/A

# Spec. Changes (OPTIONAL)
[spec-changes]: #spec-changes

The [distribution spec](https://github.com/buildpacks/spec/blob/main/distribution.md) would be updated to document the OCI image annotations as covered in ["How it Works"](#how-it-works).


# History
[history]: #history

<!--
## Amended
### Meta
[meta-1]: #meta-1
- Name: (fill in the amendment name: Variable Rename)
- Start Date: (fill in today's date: YYYY-MM-DD)
- Author(s): (Github usernames)
- Amendment Pull Request: (leave blank)

### Summary

A brief description of the changes.

### Motivation

Why was this amendment necessary?
--->
Loading