From 7dc794a22741840df53b28b3062b3f86d76419ba Mon Sep 17 00:00:00 2001 From: Craig Andrews Date: Wed, 26 Jun 2024 16:06:14 -0400 Subject: [PATCH 1/8] RFC for OCI Image Annotations on Buildpacks Signed-off-by: Craig Andrews --- text/0000-oci-image-annotations.md | 116 +++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 text/0000-oci-image-annotations.md diff --git a/text/0000-oci-image-annotations.md b/text/0000-oci-image-annotations.md new file mode 100644 index 000000000..00ca7089c --- /dev/null +++ b/text/0000-oci-image-annotations.md @@ -0,0 +1,116 @@ +# Meta +[meta]: #meta +- Name: OCI Image Annotations on Buildpacks +- Start Date: 2024-06-26 +- Author(s): @candrews +- Status: Draft +- 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` +- `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. + +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 `buildpack` tool would be modified to set the annotations. + +# 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 + + \ No newline at end of file From 04e957ea7054f5f4b404040085b5cf9a3fdc0710 Mon Sep 17 00:00:00 2001 From: Craig Andrews Date: Thu, 11 Jul 2024 15:48:05 -0400 Subject: [PATCH 2/8] Note that buildpacks without these annotation would still be valid Co-authored-by: Joe Kutner Signed-off-by: Craig Andrews --- text/0000-oci-image-annotations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-oci-image-annotations.md b/text/0000-oci-image-annotations.md index 00ca7089c..d0d39efb1 100644 --- a/text/0000-oci-image-annotations.md +++ b/text/0000-oci-image-annotations.md @@ -66,7 +66,7 @@ The following example values are from [Paketo Buildpack for Java 13.0.1](https:/ # Migration [migration]: #migration -The `buildpack` tool would be modified to set the annotations. +The `buildpack` 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 consider to be valid in accordance with the distribution specification. # Drawbacks [drawbacks]: #drawbacks From dca1e5e4bd2c90ab5bcd68a892cfaa8cf5fc4a8c Mon Sep 17 00:00:00 2001 From: Craig Andrews Date: Fri, 12 Jul 2024 11:33:52 -0400 Subject: [PATCH 3/8] Don't require VCS info, as that info isn't always available Co-authored-by: Joe Kutner Signed-off-by: Craig Andrews --- text/0000-oci-image-annotations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0000-oci-image-annotations.md b/text/0000-oci-image-annotations.md index d0d39efb1..ae8edc642 100644 --- a/text/0000-oci-image-annotations.md +++ b/text/0000-oci-image-annotations.md @@ -33,8 +33,8 @@ The outcome will be that users and tools will be able to gather more information `pack buildpack package` should set the following OCI annotations on the images it produces: -- `org.opencontainers.image.source` -- `org.opencontainers.image.revision` +- `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) From 1ac82955b7c8265503f70609d7e248e67c79dc9f Mon Sep 17 00:00:00 2001 From: Craig Andrews Date: Fri, 12 Jul 2024 11:37:08 -0400 Subject: [PATCH 4/8] `org.opencontainers.image.revision` should be the hash, not the ref Signed-off-by: Craig Andrews --- text/0000-oci-image-annotations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-oci-image-annotations.md b/text/0000-oci-image-annotations.md index ae8edc642..a77b0a3ea 100644 --- a/text/0000-oci-image-annotations.md +++ b/text/0000-oci-image-annotations.md @@ -45,7 +45,7 @@ The target personas as buildpack users, platform operators, and platform impleme # 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. +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 hash. The other annotation values come from `buildpack.toml` mapped to OCI annotations as follows: From d2b2b1a9b196a9e5963454f20a3948e6d8ef7207 Mon Sep 17 00:00:00 2001 From: Craig Andrews Date: Thu, 18 Jul 2024 13:21:57 -0400 Subject: [PATCH 5/8] Consistently use the term `pack` tool instead of `buildpack` tool Signed-off-by: Craig Andrews --- text/0000-oci-image-annotations.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/text/0000-oci-image-annotations.md b/text/0000-oci-image-annotations.md index a77b0a3ea..a711cb45c 100644 --- a/text/0000-oci-image-annotations.md +++ b/text/0000-oci-image-annotations.md @@ -12,7 +12,7 @@ # 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. +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 @@ -45,7 +45,7 @@ The target personas as buildpack users, platform operators, and platform impleme # 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 hash. +When building 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: @@ -66,7 +66,7 @@ The following example values are from [Paketo Buildpack for Java 13.0.1](https:/ # Migration [migration]: #migration -The `buildpack` 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 consider to be valid in accordance with the distribution specification. +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 consider to be valid in accordance with the distribution specification. # Drawbacks [drawbacks]: #drawbacks From 438fddec807e2dac65b1f910852eac9a5886f8fe Mon Sep 17 00:00:00 2001 From: Craig Andrews Date: Thu, 18 Jul 2024 13:24:45 -0400 Subject: [PATCH 6/8] Fix incorrect tense of "consider" Co-authored-by: Josh W Lewis Signed-off-by: Craig Andrews --- text/0000-oci-image-annotations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-oci-image-annotations.md b/text/0000-oci-image-annotations.md index a711cb45c..4e1d0642f 100644 --- a/text/0000-oci-image-annotations.md +++ b/text/0000-oci-image-annotations.md @@ -66,7 +66,7 @@ The following example values are from [Paketo Buildpack for Java 13.0.1](https:/ # 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 consider to be valid in accordance with the distribution specification. +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 From cc8e2f4532999664f9f5b2404371c2e4e268fbee Mon Sep 17 00:00:00 2001 From: Craig Andrews Date: Thu, 18 Jul 2024 13:25:21 -0400 Subject: [PATCH 7/8] Use the term "packaging" as that's the term used by the tool Co-authored-by: Josh W Lewis Signed-off-by: Craig Andrews --- text/0000-oci-image-annotations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-oci-image-annotations.md b/text/0000-oci-image-annotations.md index 4e1d0642f..678d5d30e 100644 --- a/text/0000-oci-image-annotations.md +++ b/text/0000-oci-image-annotations.md @@ -45,7 +45,7 @@ The target personas as buildpack users, platform operators, and platform impleme # How it Works [how-it-works]: #how-it-works -When building 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. +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: From 4c05331f64d4bbc77d50371bc491be5459aa3677 Mon Sep 17 00:00:00 2001 From: Joe Kutner Date: Thu, 8 Aug 2024 10:16:44 -0500 Subject: [PATCH 8/8] RFC 0130 [#314] Signed-off-by: Joe Kutner --- ...i-image-annotations.md => 0130-oci-image-annotations.md} | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) rename text/{0000-oci-image-annotations.md => 0130-oci-image-annotations.md} (97%) diff --git a/text/0000-oci-image-annotations.md b/text/0130-oci-image-annotations.md similarity index 97% rename from text/0000-oci-image-annotations.md rename to text/0130-oci-image-annotations.md index 678d5d30e..0e5e8f3c1 100644 --- a/text/0000-oci-image-annotations.md +++ b/text/0130-oci-image-annotations.md @@ -3,10 +3,10 @@ - Name: OCI Image Annotations on Buildpacks - Start Date: 2024-06-26 - Author(s): @candrews -- Status: Draft -- RFC Pull Request: (leave blank) +- Status: Approved +- RFC Pull Request: [rfcs#314](https://github.com/buildpacks/rfcs/pull/314) - CNB Pull Request: (leave blank) -- CNB Issue: (leave blank) +- CNB Issue: https://github.com/buildpacks/rfcs/issues/318 - Supersedes: (put "N/A" unless this replaces an existing RFC, then link to that RFC) # Summary