From b79533d2e605e269dcc93d31a35564758a71c986 Mon Sep 17 00:00:00 2001 From: Iain Sproat Date: Thu, 12 Dec 2019 14:04:42 +0000 Subject: [PATCH 1/7] Include buildpack RFC0013 in specification - Add app source metadata format - [RFC0013](https://github.com/buildpack/rfcs/blob/master/text/0013-app-layer-metadata-source.md) [#170205764] Signed-off-by: Shane Huston Signed-off-by: Velda Conaty --- buildpack.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/buildpack.md b/buildpack.md index b9ccf512..7a801488 100644 --- a/buildpack.md +++ b/buildpack.md @@ -522,6 +522,8 @@ Subsequently, - The run image filesystem layers, - The executable component of the lifecycle that implements the launch phase, and - An `ENTRYPOINT` set to that component. +3. The lifecycle MAY add Config labels to the new OCI image, composed of + - A label with the key `"io.buildpacks.app.source"` with a [value describing the source location of the app](#io.buildpacks.app.source-oci-image-label). Finally, any `/` directories specified as `cache = true` in `/.toml` MAY be preserved for the next local build. For any `/.toml` files specifying both `cache = true` and `launch = true`, the lifecycle SHOULD store a checksum of the corresponding `/` directory so that it is associated with the locally cached directory. @@ -991,3 +993,19 @@ The stack ID: A buildpack descriptor that specifies `order` MUST be [resolvable](#order-resolution) into an ordering of buildpacks that implement the [Buildpack Interface](#buildpack-interface). A buildpack reference inside of a `group` MUST contain an `id` and `version`. + +### io.buildpacks.app.source OCI Image label +The value of this label: +- MUST be a string of escaped json complying with [RFC 8259](https://tools.ietf.org/html/rfc8259). +- when unescaped, MUST comply with the following schema: +```json +{ + "$schema": "http://json-schema.org/schema#", + "type": "object", + "properties": { + "type": {"type": "string"}, + "version": {}, + "metadata": {} + } +} +``` \ No newline at end of file From ebbdcbaf4e991051704c17192668340bf1e2a262 Mon Sep 17 00:00:00 2001 From: Shane Huston Date: Thu, 12 Dec 2019 16:34:20 +0000 Subject: [PATCH 2/7] Revert "Include buildpack RFC0013 in specification" * Changes will be moved to the platform specification document This reverts commit 3dc1b445aa5d62081050b2ac48352287c3ef0cd9. Signed-off-by: Velda Conaty --- buildpack.md | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/buildpack.md b/buildpack.md index 7a801488..b9ccf512 100644 --- a/buildpack.md +++ b/buildpack.md @@ -522,8 +522,6 @@ Subsequently, - The run image filesystem layers, - The executable component of the lifecycle that implements the launch phase, and - An `ENTRYPOINT` set to that component. -3. The lifecycle MAY add Config labels to the new OCI image, composed of - - A label with the key `"io.buildpacks.app.source"` with a [value describing the source location of the app](#io.buildpacks.app.source-oci-image-label). Finally, any `/` directories specified as `cache = true` in `/.toml` MAY be preserved for the next local build. For any `/.toml` files specifying both `cache = true` and `launch = true`, the lifecycle SHOULD store a checksum of the corresponding `/` directory so that it is associated with the locally cached directory. @@ -993,19 +991,3 @@ The stack ID: A buildpack descriptor that specifies `order` MUST be [resolvable](#order-resolution) into an ordering of buildpacks that implement the [Buildpack Interface](#buildpack-interface). A buildpack reference inside of a `group` MUST contain an `id` and `version`. - -### io.buildpacks.app.source OCI Image label -The value of this label: -- MUST be a string of escaped json complying with [RFC 8259](https://tools.ietf.org/html/rfc8259). -- when unescaped, MUST comply with the following schema: -```json -{ - "$schema": "http://json-schema.org/schema#", - "type": "object", - "properties": { - "type": {"type": "string"}, - "version": {}, - "metadata": {} - } -} -``` \ No newline at end of file From 257dcca720aa6e953481e11ff11a5f49a63b551c Mon Sep 17 00:00:00 2001 From: Iain Sproat Date: Thu, 12 Dec 2019 16:36:44 +0000 Subject: [PATCH 3/7] RFC0013 moved to platform specification * Moves the specification from Buildpack document to Platform document * Adds a new optional `-platform` flag to the lifecycle builder * Adds a new project.toml input file * Includes source, source.version, and source.metadata properties to project.toml * Provides a new section to specify the Config labels to be added to the OCI image * Includes a data type for the "io.buildpacks.project" Config label. [#170205764] Signed-off-by: Velda Conaty --- platform.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 46 insertions(+), 2 deletions(-) diff --git a/platform.md b/platform.md index 3e995420..806d3bdd 100644 --- a/platform.md +++ b/platform.md @@ -61,7 +61,8 @@ The platform MUST ensure that: - The image config's `Env` field has the environment variable `CNB_GROUP_ID` set to the primary GID of the user specified in the `User` field. - The image config's `Label` field has the label `io.buildpacks.stack.id` set to the stack ID. - The image config's `Label` field has the label `io.buildpacks.stack.mixins` set to a JSON array containing mixin names for each mixin applied to the image. - + + #### Detection phase To initiate the detection phase, the platform MUST invoke the `/cnb/lifecycle/detector` executable with the user and environment defined in the build image config. Invoking this executable with no flags is equivalent to the following invocation including all accepted flags and their default values. @@ -76,11 +77,12 @@ Where: - `-group` MUST specify output to a `group.toml` file path as defined in the [Data Format](#data-format) section. - `-plan` MUST specify output to a Build Plan as defined in the [Buildpack Interface Specification](buildpack.md). +#### Build phase To initiate the build phase, the platform MUST invoke the `/cnb/lifecycle/builder` executable with the user and environment defined in the build image config. Invoking this executable with no flags is equivalent to the following invocation including all accepted flags and their default values. ```bash -/cnb/lifecycle/builder -buildpacks /cnb/by-id -group ./group.toml -plan ./plan.toml +/cnb/lifecycle/builder -buildpacks /cnb/by-id -group ./group.toml -plan ./plan.toml -project ./project.toml ``` Where: @@ -88,6 +90,7 @@ Where: - `-buildpacks` MUST specify input from a buildpacks directory as defined in the [Buildpacks Directory Layout](#buildpacks-directory-layout) section. - `-group` MUST specify input from a `group.toml` file path as defined in the [Data Format](#data-format) section. - `-plan` MUST specify input from a Build Plan as defined in the [Buildpack Interface Specification](buildpack.md). +- `-project` MAY specify input from a `project.toml` file path as defined in the [Data Format](#data-format) section. ### Run Image @@ -122,6 +125,13 @@ The buildpacks directory MUST contain unarchived buildpacks such that: - Each top-level directory is a buildpack ID. - Each second-level directory is a buildpack version. +## OCI Image +The OCI image containing the compiled application is generated by the Build Image during the [Build Phase](#build-phase). + +If the `/cnb/lifecycle/builder` is invoked with the optional `-project` argument, the lifecycle MUST add a `"io.buildpacks.project"` Config label to the new OCI image with a [value as described in the data-format](#io.buildpacks.app.source-oci-image-label) section. + + + ## Security Considerations The platform SHOULD run each phase of the lifecycle in an isolated container to prevent untrusted app and buildpack code from accessing storage credentials needed during the export and analysis phases. @@ -179,3 +189,37 @@ group = [ Where: - Both `id` and `version` MUST be present for each buildpack object in a group. + +### project.toml (TOML) + +```toml +[source] +type = "" + +[source.version] + +[source.metadata] + +``` + +### io.buildpacks.project OCI Image label +The value of this label: +- MUST be a string of escaped json complying with [RFC 8259](https://tools.ietf.org/html/rfc8259). +- when unescaped, MUST comply with the following schema: + +```json +{ + "$schema": "http://json-schema.org/schema#", + "type": "object", + "properties": { + "source: { + "type": "object", + "properties":{ + "type": {"type": "string"}, + "version": {}, + "metadata": {} + } + } + } +} +``` \ No newline at end of file From f826067f0bf4a9f23c26afbaafa0f760de382e8d Mon Sep 17 00:00:00 2001 From: Iain Sproat Date: Thu, 12 Dec 2019 16:41:28 +0000 Subject: [PATCH 4/7] Corrects error in json schema for io.buildpacks.project data type [#170205764] Signed-off-by: Velda Conaty --- platform.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform.md b/platform.md index 806d3bdd..8fff27b9 100644 --- a/platform.md +++ b/platform.md @@ -212,7 +212,7 @@ The value of this label: "$schema": "http://json-schema.org/schema#", "type": "object", "properties": { - "source: { + "source": { "type": "object", "properties":{ "type": {"type": "string"}, From 5f00729281d4d6ea29029e6af65ad97c82c6a058 Mon Sep 17 00:00:00 2001 From: Iain Sproat Date: Fri, 13 Dec 2019 10:37:15 +0000 Subject: [PATCH 5/7] Moved flag from Build phase to Export phase * renamed flag to source-metadata * created an Export Phase section * removed redundant quotation marks from label key * renamed TOML file to source-metadata.toml [#170205764] Signed-off-by: Velda Conaty --- platform.md | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/platform.md b/platform.md index 8fff27b9..3f2d7ea0 100644 --- a/platform.md +++ b/platform.md @@ -82,7 +82,7 @@ To initiate the build phase, the platform MUST invoke the `/cnb/lifecycle/builde Invoking this executable with no flags is equivalent to the following invocation including all accepted flags and their default values. ```bash -/cnb/lifecycle/builder -buildpacks /cnb/by-id -group ./group.toml -plan ./plan.toml -project ./project.toml +/cnb/lifecycle/builder -buildpacks /cnb/by-id -group ./group.toml -plan ./plan.toml ``` Where: @@ -90,7 +90,18 @@ Where: - `-buildpacks` MUST specify input from a buildpacks directory as defined in the [Buildpacks Directory Layout](#buildpacks-directory-layout) section. - `-group` MUST specify input from a `group.toml` file path as defined in the [Data Format](#data-format) section. - `-plan` MUST specify input from a Build Plan as defined in the [Buildpack Interface Specification](buildpack.md). -- `-project` MAY specify input from a `project.toml` file path as defined in the [Data Format](#data-format) section. + +#### Export phase +To initiate the export phase, the platform MUST invoke the `/cnb/lifecycle/exporter` executable with the user and environment defined in the build image config. +Invoking this executable with no flags is equivalent to the following invocation including all accepted flags and their default values. + +```bash +/cnb/lifecycle/exporter -source-metadata ./source-metadata.toml +``` + +Where: + +- `-source-metadata` MAY specify input from a `source-metadata.toml` file path as defined in the [Data Format](#data-format) section. ### Run Image @@ -126,11 +137,9 @@ The buildpacks directory MUST contain unarchived buildpacks such that: - Each second-level directory is a buildpack version. ## OCI Image -The OCI image containing the compiled application is generated by the Build Image during the [Build Phase](#build-phase). - -If the `/cnb/lifecycle/builder` is invoked with the optional `-project` argument, the lifecycle MUST add a `"io.buildpacks.project"` Config label to the new OCI image with a [value as described in the data-format](#io.buildpacks.app.source-oci-image-label) section. - +The OCI image containing the compiled application is generated by the Build Image during the [Export Phase](#export-phase). +If the `/cnb/lifecycle/exporter` is invoked with the optional `-source-metadata` argument, the lifecycle MUST add a `io.buildpacks.project` image config label to the new OCI image with a [value as described in the data-format](#io.buildpacks.app.source-oci-image-label-json) section. ## Security Considerations @@ -190,7 +199,7 @@ Where: - Both `id` and `version` MUST be present for each buildpack object in a group. -### project.toml (TOML) +### source-metadata.toml (TOML) ```toml [source] @@ -202,7 +211,7 @@ type = "" ``` -### io.buildpacks.project OCI Image label +### io.buildpacks.project OCI Image label (JSON) The value of this label: - MUST be a string of escaped json complying with [RFC 8259](https://tools.ietf.org/html/rfc8259). - when unescaped, MUST comply with the following schema: From 334e1c475f7b7346bd7537bb23cb9edc6a8fc3d4 Mon Sep 17 00:00:00 2001 From: Iain Sproat Date: Tue, 17 Dec 2019 15:55:42 +0000 Subject: [PATCH 6/7] RFC0013: renames `source-metadata` to `project-metadata` * follows comments received on PR ** remove whitespace ** add section to Table of Contents ** Renames `source-metadata` to `project-metadata` [#170205764] Signed-off-by: Carlo Colombo Signed-off-by: Velda Conaty --- platform.md | 33 ++++++--------------------------- 1 file changed, 6 insertions(+), 27 deletions(-) diff --git a/platform.md b/platform.md index 3f2d7ea0..0a680048 100644 --- a/platform.md +++ b/platform.md @@ -26,6 +26,7 @@ Examples of a platform might include: 5. [Data Format](#data-format) 1. [order.toml (TOML)](#order.toml-(toml)) 2. [group.toml (TOML)](#group.toml-(toml)) + 3. [project-metadata.toml (TOML)](#project-metadata.toml-(toml)) ## Stacks @@ -62,7 +63,7 @@ The platform MUST ensure that: - The image config's `Label` field has the label `io.buildpacks.stack.id` set to the stack ID. - The image config's `Label` field has the label `io.buildpacks.stack.mixins` set to a JSON array containing mixin names for each mixin applied to the image. - #### Detection phase +#### Detection phase To initiate the detection phase, the platform MUST invoke the `/cnb/lifecycle/detector` executable with the user and environment defined in the build image config. Invoking this executable with no flags is equivalent to the following invocation including all accepted flags and their default values. @@ -96,12 +97,12 @@ To initiate the export phase, the platform MUST invoke the `/cnb/lifecycle/expor Invoking this executable with no flags is equivalent to the following invocation including all accepted flags and their default values. ```bash -/cnb/lifecycle/exporter -source-metadata ./source-metadata.toml +/cnb/lifecycle/exporter -project-metadata ./project-metadata.toml ``` Where: -- `-source-metadata` MAY specify input from a `source-metadata.toml` file path as defined in the [Data Format](#data-format) section. +- `-project-metadata` MAY specify input from a `project-metadata.toml` file path as defined in the [Data Format](#data-format) section. ### Run Image @@ -139,7 +140,7 @@ The buildpacks directory MUST contain unarchived buildpacks such that: ## OCI Image The OCI image containing the compiled application is generated by the Build Image during the [Export Phase](#export-phase). -If the `/cnb/lifecycle/exporter` is invoked with the optional `-source-metadata` argument, the lifecycle MUST add a `io.buildpacks.project` image config label to the new OCI image with a [value as described in the data-format](#io.buildpacks.app.source-oci-image-label-json) section. +If the `/cnb/lifecycle/exporter` is invoked with the optional `-project-metadata` argument, the lifecycle MUST add a `io.buildpacks.project` image config label to the new OCI image. This label value is encoded JSON format of the `project-metadata.toml` contents, as described in the [data-format](#data-format) section. ## Security Considerations @@ -199,7 +200,7 @@ Where: - Both `id` and `version` MUST be present for each buildpack object in a group. -### source-metadata.toml (TOML) +### project-metadata.toml (TOML) ```toml [source] @@ -209,26 +210,4 @@ type = "" [source.metadata] -``` - -### io.buildpacks.project OCI Image label (JSON) -The value of this label: -- MUST be a string of escaped json complying with [RFC 8259](https://tools.ietf.org/html/rfc8259). -- when unescaped, MUST comply with the following schema: - -```json -{ - "$schema": "http://json-schema.org/schema#", - "type": "object", - "properties": { - "source": { - "type": "object", - "properties":{ - "type": {"type": "string"}, - "version": {}, - "metadata": {} - } - } - } -} ``` \ No newline at end of file From 32c757e341424db0325d6ff6c72bb58f459a51bf Mon Sep 17 00:00:00 2001 From: Iain Sproat Date: Thu, 23 Jan 2020 11:20:23 +0000 Subject: [PATCH 7/7] Removes project-metadata flag - Renames OCI image to Exported image [#170205764] Signed-off-by: Velda Conaty --- platform.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/platform.md b/platform.md index 0a680048..25f7ff4f 100644 --- a/platform.md +++ b/platform.md @@ -94,15 +94,9 @@ Where: #### Export phase To initiate the export phase, the platform MUST invoke the `/cnb/lifecycle/exporter` executable with the user and environment defined in the build image config. -Invoking this executable with no flags is equivalent to the following invocation including all accepted flags and their default values. - -```bash -/cnb/lifecycle/exporter -project-metadata ./project-metadata.toml -``` - -Where: -- `-project-metadata` MAY specify input from a `project-metadata.toml` file path as defined in the [Data Format](#data-format) section. +The platform MAY provide a [`project-metadata.toml`](#project-metadata.toml-(toml)) file in the platform directory. +The platform MAY provide a `-platform` flag or `CNB_PLATFORM_DIR` environment variable to specify the path of the platform directory. If not provided, the default is `/platform`. ### Run Image @@ -137,10 +131,10 @@ The buildpacks directory MUST contain unarchived buildpacks such that: - Each top-level directory is a buildpack ID. - Each second-level directory is a buildpack version. -## OCI Image -The OCI image containing the compiled application is generated by the Build Image during the [Export Phase](#export-phase). +## Exported Image +The Exported image containing the compiled application is generated by the Build Image during the [Export Phase](#export-phase). -If the `/cnb/lifecycle/exporter` is invoked with the optional `-project-metadata` argument, the lifecycle MUST add a `io.buildpacks.project` image config label to the new OCI image. This label value is encoded JSON format of the `project-metadata.toml` contents, as described in the [data-format](#data-format) section. +If the `/cnb/lifecycle/exporter` is provided with a `project-metadata.toml` file in the Platform directory, the lifecycle MUST add a `io.buildpacks.project` image config label to the Exported image. This label value is encoded JSON format of the `project-metadata.toml` contents, as described in the [data-format](#data-format) section. ## Security Considerations