From 0122f574201dc1fd287f39d61d6a741dff98c559 Mon Sep 17 00:00:00 2001 From: Kashyap Vedurmudi Date: Tue, 12 May 2020 17:21:22 -0500 Subject: [PATCH 1/4] Add RFC for Stack metadata Signed-off-by: Kashyap Vedurmudi --- text/0000-stack-metadata.md | 95 +++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 text/0000-stack-metadata.md diff --git a/text/0000-stack-metadata.md b/text/0000-stack-metadata.md new file mode 100644 index 000000000..885de52dc --- /dev/null +++ b/text/0000-stack-metadata.md @@ -0,0 +1,95 @@ +# Meta +[meta]: #meta +- Name: Additional Stack Metadata +- Start Date: 2020-05-12 +- Author(s): kvedurmu +- RFC Pull Request: (leave blank) +- CNB Pull Request: (leave blank) +- CNB Issue: (leave blank) +- Supersedes: N/A + +# Summary +[summary]: #summary + +We currently expose the Stack ID and Mixins via Labels on the build/run images. It would be great if we could leverage Labels to allow stack authors to specify additional image metadata (e.g OS Distro, Maintainer, Stack Version, etc.). The purpose of this RFC is to enumerate on additional metadata we want to expose in our stack images and standardize on these labels. + +# Motivation +[motivation]: #motivation + +- Why should we do this? +Exposing additional metadata in stack images will make it easier for end users to debug stack related issues. Also, by exposing this metadata, CNB platforms such as kpack can leverage this information to improve their UX. +- What is the expected outcome? +We converge on metadata we want to expose in stack images via labels, and all stack authors eventually support these. + +# What it is +[what-it-is]: #what-it-is + +This provides a high level overview of the feature. + +- Define the target persona: stack author +- Explaining the feature largely in terms of examples. +The following labels will be added to stack images: +`io.buildpacks.stack.maintainer`: Name of Stack Maintainer +`io.buildpacks.stack.url`: URL for the stack (i.e repo link) +`io.buildpacks.stack.distro.name`: Name of OS Distribution +`io.buildpacks.stack.distro.version`: Version of OS Distribution +`io.buildpacks.stack.release`: Release Number +`io.buildpacks.stack.release_date`: Release date of image +`io.buildpacks.stack.description`: Description + + +# How it Works +[how-it-works]: #how-it-works + +This is the technical portion of the RFC, where you explain the design in sufficient detail. +All labels listed above will be added as `Labels` in the stack's Dockerfile. + +Example Dockerfile: +``` +ARG cnb_uid=1000 +ARG cnb_gid=1000 +ARG stack_id="io.buildpacks.stacks.bionic" +ENV CNB_USER_ID=${cnb_uid} +ENV CNB_GROUP_ID=${cnb_gid} +ENV CNB_STACK_ID=${stack_id} +USER ${cnb_uid}:${cnb_gid} +LABEL io.buildpacks.stack.id=${stack_id} +LABEL io.buildpacks.stack.mixins="[\"ca-certificates\"............]" +LABEL io.buildpacks.stack.maintainer="Paketo Buildpacks" +LABEL io.buildpacks.stack.url="https://github.com/paketo-buildpacks/stacks/" +LABEL io.buildpacks.stack.distro.name="ubuntu" +LABEL io.buildpacks.stack.distro.version="18.04" +LABEL io.buildpacks.stack.release="25" +LABEL io.buildpacks.stack.release_date="2020-05-12T05:17:02.390472" +LABEL io.buildpacks.stack.description="Paketo Buildpacks base stack build image" +``` + +# Drawbacks +[drawbacks]: #drawbacks + +This could make image rebasing slightly more complicated as labels like stack version will need to be updated. + +# Alternatives +[alternatives]: #alternatives + +- What other designs have been considered? +It could be more consistent to have a single metadata label (io.buildpacks.stack.metadata) that is structured JSON, but a JSON object would be hard to create in a Dockerfile. +- Why is this proposal the best? +It is the simplest way to expose image metadata to users and follows existing conventions with label naming. +- What is the impact of not doing this? +Stack authors will define their own custom labels to surface the metadata above. By standardizing on the names and purpose of each of these labels, we make it easier for CNB platforms to consume this metadata. + +# Prior Art +[prior-art]: #prior-art + +- Upstream OS distros have an existing pattern of doing this. (e.g `registry.access.redhat.com/ubi8/ubi`) +- Buildpack Homepage field - https://github.com/buildpacks/rfcs/blob/master/text/0030-links-for-buildpacks.md + +# Unresolved Questions +[unresolved-questions]: #unresolved-questions + +- Any additional labels that we'd want to expose? + +# Spec. Changes (OPTIONAL) +[spec-changes]: #spec-changes +None. From 9c25aeeec2b054f7e98f297a6d6544c1e1aa9814 Mon Sep 17 00:00:00 2001 From: Kashyap Vedurmudi <37810054+kvedurmu@users.noreply.github.com> Date: Thu, 14 May 2020 13:59:25 -0500 Subject: [PATCH 2/4] Update 0000-stack-metadata.md Signed-off-by: Kashyap Vedurmudi --- text/0000-stack-metadata.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/text/0000-stack-metadata.md b/text/0000-stack-metadata.md index 885de52dc..c81d79ba3 100644 --- a/text/0000-stack-metadata.md +++ b/text/0000-stack-metadata.md @@ -30,10 +30,10 @@ This provides a high level overview of the feature. - Explaining the feature largely in terms of examples. The following labels will be added to stack images: `io.buildpacks.stack.maintainer`: Name of Stack Maintainer -`io.buildpacks.stack.url`: URL for the stack (i.e repo link) +`io.buildpacks.stack.homepage`: URL for the stack (i.e repo link) `io.buildpacks.stack.distro.name`: Name of OS Distribution `io.buildpacks.stack.distro.version`: Version of OS Distribution -`io.buildpacks.stack.release`: Release Number +`io.buildpacks.stack.version`: Release Number `io.buildpacks.stack.release_date`: Release date of image `io.buildpacks.stack.description`: Description @@ -56,10 +56,10 @@ USER ${cnb_uid}:${cnb_gid} LABEL io.buildpacks.stack.id=${stack_id} LABEL io.buildpacks.stack.mixins="[\"ca-certificates\"............]" LABEL io.buildpacks.stack.maintainer="Paketo Buildpacks" -LABEL io.buildpacks.stack.url="https://github.com/paketo-buildpacks/stacks/" +LABEL io.buildpacks.stack.homepage="https://github.com/paketo-buildpacks/stacks/" LABEL io.buildpacks.stack.distro.name="ubuntu" LABEL io.buildpacks.stack.distro.version="18.04" -LABEL io.buildpacks.stack.release="25" +LABEL io.buildpacks.stack.version="25" LABEL io.buildpacks.stack.release_date="2020-05-12T05:17:02.390472" LABEL io.buildpacks.stack.description="Paketo Buildpacks base stack build image" ``` From 8468dd822708c86953c3cec77906a1fcf5e7509e Mon Sep 17 00:00:00 2001 From: Kashyap Vedurmudi Date: Thu, 18 Jun 2020 16:54:09 -0500 Subject: [PATCH 3/4] Updates RFC to add examples Signed-off-by: Kashyap Vedurmudi --- text/0000-stack-metadata.md | 51 ++++++++++++++++++++++++++++++++++--- 1 file changed, 47 insertions(+), 4 deletions(-) diff --git a/text/0000-stack-metadata.md b/text/0000-stack-metadata.md index c81d79ba3..296320976 100644 --- a/text/0000-stack-metadata.md +++ b/text/0000-stack-metadata.md @@ -21,6 +21,44 @@ Exposing additional metadata in stack images will make it easier for end users t - What is the expected outcome? We converge on metadata we want to expose in stack images via labels, and all stack authors eventually support these. +Here's the current output of the `pack inspect-image` command on a sample app: +``` +Inspecting image: go-mod-simple-app +................... +LOCAL: + +Stack: io.buildpacks.stacks.bionic + +Base Image: + Reference: 610caf01e85e5da52c6a99b42fed80858c153de6d25b120940266846bec0872a + Top Layer: sha256:b6aadae5b30af0345f0ab82add7ed5b951d78230e86693c08f5c1ae8470a0ffb + +Run Images: + gcr.io/paketo-buildpacks/run:base-cnb +................... +``` + +By adding the proposed metadata, `pack inspect-image` output of this app could eventually look like: +``` +Inspecting image: go-mod-simple-app +................... +LOCAL: + +Stack: io.buildpacks.stacks.bionic +Stack Metadata: + Maintainer: "Paketo Buildpacks" + Homepage: "https://github.com/paketo-buildpacks/stacks" + OS Distro: "unbuntu 18.04" + +Base Image: + Reference: 610caf01e85e5da52c6a99b42fed80858c153de6d25b120940266846bec0872a + Top Layer: sha256:b6aadae5b30af0345f0ab82add7ed5b951d78230e86693c08f5c1ae8470a0ffb + +Run Images: + gcr.io/paketo-buildpacks/run:base-cnb +................... +``` + # What it is [what-it-is]: #what-it-is @@ -28,14 +66,15 @@ This provides a high level overview of the feature. - Define the target persona: stack author - Explaining the feature largely in terms of examples. -The following labels will be added to stack images: +The following labels can **optionally** be added by stack maintainers to stack images: `io.buildpacks.stack.maintainer`: Name of Stack Maintainer `io.buildpacks.stack.homepage`: URL for the stack (i.e repo link) `io.buildpacks.stack.distro.name`: Name of OS Distribution `io.buildpacks.stack.distro.version`: Version of OS Distribution -`io.buildpacks.stack.version`: Release Number -`io.buildpacks.stack.release_date`: Release date of image +`io.buildpacks.stack.version`: Release Number +`io.buildpacks.stack.release_date`: Release date of image `io.buildpacks.stack.description`: Description +`io.buildpacks.stack.metadata`: Generic stack metadata # How it Works @@ -62,6 +101,7 @@ LABEL io.buildpacks.stack.distro.version="18.04" LABEL io.buildpacks.stack.version="25" LABEL io.buildpacks.stack.release_date="2020-05-12T05:17:02.390472" LABEL io.buildpacks.stack.description="Paketo Buildpacks base stack build image" +LABEL io.buildpacks.stack.metadata="Some optionally defined metadata" ``` # Drawbacks @@ -92,4 +132,7 @@ Stack authors will define their own custom labels to surface the metadata above. # Spec. Changes (OPTIONAL) [spec-changes]: #spec-changes -None. + +The platform spec should be updated to indicate that these keys can **optionally** be added on the build/run stack image. + +PR - https://github.com/buildpacks/spec/pull/89 From 58c1c57d36776e6f71220cbacf47902356a056aa Mon Sep 17 00:00:00 2001 From: Kashyap Vedurmudi <37810054+kvedurmu@users.noreply.github.com> Date: Wed, 8 Jul 2020 16:18:03 -0500 Subject: [PATCH 4/4] Update text/0000-stack-metadata.md Co-authored-by: Terence Lee Signed-off-by: Kashyap Vedurmudi --- text/0000-stack-metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-stack-metadata.md b/text/0000-stack-metadata.md index 296320976..6c2debca9 100644 --- a/text/0000-stack-metadata.md +++ b/text/0000-stack-metadata.md @@ -103,7 +103,7 @@ LABEL io.buildpacks.stack.release_date="2020-05-12T05:17:02.390472" LABEL io.buildpacks.stack.description="Paketo Buildpacks base stack build image" LABEL io.buildpacks.stack.metadata="Some optionally defined metadata" ``` - +During rebase, the `rebaser` will copy the `io.buildpacks.stack.*` labels from the new run image to the app image. # Drawbacks [drawbacks]: #drawbacks