-
Notifications
You must be signed in to change notification settings - Fork 71
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.
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
RFC for OCI Image Annotations on Buildpacks #314
Merged
Merged
Changes from all commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
7dc794a
RFC for OCI Image Annotations on Buildpacks
candrews 04e957e
Note that buildpacks without these annotation would still be valid
candrews dca1e5e
Don't require VCS info, as that info isn't always available
candrews 1ac8295
`org.opencontainers.image.revision` should be the hash, not the ref
candrews d2b2b1a
Consistently use the term `pack` tool instead of `buildpack` tool
candrews 438fdde
Fix incorrect tense of "consider"
candrews cc8e2f4
Use the term "packaging" as that's the term used by the tool
candrews File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 `pack` 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 `pack` 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` (when possible) | ||
| - `org.opencontainers.image.revision` (when possible) | ||
| - `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 packaging the buildpack, the `pack` 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 hash. | ||
|
|
||
| The other annotation values come from `buildpack.toml` mapped to OCI annotations as follows: | ||
|
|
||
| - `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 `pack` tool would be modified to set the annotations. Because the tool _should_ set these annotations (not _must_ set), buildpacks created with earlier versions of the tool are still considered to be valid in accordance with the distribution specification. | ||
|
|
||
| # 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? | ||
| ---> | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.There was a problem hiding this comment.
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:
"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
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Combined with proposing that the Pack CLI implement these changes, so that when a buildpack maintainer runs
pack buildpack packageto package their buildpack into the OCI image form of distribution it has the proposed labels set.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Instead of:
I've updated the RFC to say:
Does that eliminate the confusion?
I believe so - is there something I should do in this RFC to indicate as much?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah that does thank you.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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: "
buildpacktool". Can we ensure this RFC is consistent in its terminology?There was a problem hiding this comment.
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 "
buildpacktool" to be "packtool" for consistency