From 84e00b6e3651fe1960ae76991ca2c1470bd07044 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 6 Dec 2022 10:48:02 -0500 Subject: [PATCH 01/30] Update `stacks` to `targets` in buildpack.toml Signed-off-by: Natalie Arellano --- buildpack.md | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/buildpack.md b/buildpack.md index 9f66c40..e073661 100644 --- a/buildpack.md +++ b/buildpack.md @@ -1059,9 +1059,12 @@ id = "" version = "" optional = false -[[stacks]] -id = "" -mixins = [""] +[[targets]] +os = "" +architecture = "" +variant = "" +distro-name = [""] +distro-version = [""] [metadata] # buildpack-specific data @@ -1102,17 +1105,21 @@ The `[[buildpack.licenses]]` table is optional and MAY contain a list of buildpa *Key: `sbom-formats = [ "" ]`* - MUST be supported SBOM media types as described in [Software-Bill-of-Materials](#software-bill-of-materials). -#### Stacks +#### Targets -A buildpack descriptor may specify `stacks`. +A buildpack descriptor MAY specify `targets`. -Each stack in `stacks` either: -- MUST identify a compatible stack: - - `id` MUST be set to a [valid stack ID](https://github.com/buildpacks/spec/blob/main/platform.md#stack-id). - - `mixins` MAY contain one or more mixin names. -- Or MUST indicate compatibility with any stack: - - `id` MUST be set to the special value `"*"`. - - `mixins` MUST be empty. +Each target in `targets`: +- MUST identify a compatible runtime environment: + - `os` and `architecture` are required and MUST be valid identifiers as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md) + - `variant` is optional and MUST be a valid identifier as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md) + - `distro-name` and `distro-version` are optional and MUST be the OS distribution name and OS distribution version + - For Linux-based images, each field should be the values specified in `/etc/os-release` (`$ID` and `$VERSION_ID`), as the `os.version` field in an image config may contain combined distribution and version information + - For Windows-based images, distribution should be empty; version should be the value of `os.version` in the image config (e.g., `10.0.14393.1066`) + +If the `targets` list is empty, tools reading `buildpack.toml` will assume: + - `os = "linux"` and `arch = "x86_64"` if `./bin/build` is present + - `os = "windows"` and `arch = "x86_64"` if `./bin/build.bat` or `./bin/build.exe` are present #### Order From ae549c2d478ba12cf232bfbdbd7340fbd653148d Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 6 Dec 2022 11:37:07 -0500 Subject: [PATCH 02/30] Update distributions Signed-off-by: Natalie Arellano --- buildpack.md | 36 +++++++++++++++++++++++++++++------- 1 file changed, 29 insertions(+), 7 deletions(-) diff --git a/buildpack.md b/buildpack.md index e073661..ff163b5 100644 --- a/buildpack.md +++ b/buildpack.md @@ -1061,10 +1061,11 @@ optional = false [[targets]] os = "" -architecture = "" +arch = "" variant = "" -distro-name = [""] -distro-version = [""] +[[targets.distributions]] +name = "" +versions = [""] [metadata] # buildpack-specific data @@ -1111,11 +1112,11 @@ A buildpack descriptor MAY specify `targets`. Each target in `targets`: - MUST identify a compatible runtime environment: - - `os` and `architecture` are required and MUST be valid identifiers as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md) + - `os` and `arch` are required and MUST be valid identifiers as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md) - `variant` is optional and MUST be a valid identifier as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md) - - `distro-name` and `distro-version` are optional and MUST be the OS distribution name and OS distribution version - - For Linux-based images, each field should be the values specified in `/etc/os-release` (`$ID` and `$VERSION_ID`), as the `os.version` field in an image config may contain combined distribution and version information - - For Windows-based images, distribution should be empty; version should be the value of `os.version` in the image config (e.g., `10.0.14393.1066`) + - `distributions` are optional and MUST describe the OS distributions supported by the buildpack + - For Linux-based images, `distributions.name` and `distributions.versions` should contain the values specified in `/etc/os-release` (`$ID` and `$VERSION_ID`), as the `os.version` field in an image config may contain combined distribution and version information + - For Windows-based images, `distributions.name` should be empty; `distributions.versions` should contain the value of `os.version` in the image config (e.g., `10.0.14393.1066`) If the `targets` list is empty, tools reading `buildpack.toml` will assume: - `os = "linux"` and `arch = "x86_64"` if `./bin/build` is present @@ -1142,6 +1143,27 @@ Each `key`: ## Deprecations This section describes all the features that are deprecated. +### buildpack.toml (TOML) `stacks` Array + +_Deprecated in Buildpack API 0.10._ + +The `stacks` array is deprecated. + +```toml +[[stacks]] +id = "" +mixins = [""] +``` + +Each stack in `stacks` either: +- MUST identify a compatible stack: + - `id` MUST be set to a [valid stack ID](https://github.com/buildpacks/spec/blob/main/platform.md#stack-id). + - `mixins` MAY contain one or more mixin names. +- Or MUST indicate compatibility with any stack: + - `id` MUST be set to the special value `"*"`. + - `mixins` MUST be empty. + + ### Positional Arguments to `detect` and `build` Executables _Deprecated in Buildpack API 0.8._ From 1231cb21000c97d35f7c5640aadfd85edb1e8b56 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 6 Dec 2022 11:44:33 -0500 Subject: [PATCH 03/30] Rename distributions -> distros for parity with platform Signed-off-by: Natalie Arellano --- buildpack.md | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/buildpack.md b/buildpack.md index ff163b5..53cf33d 100644 --- a/buildpack.md +++ b/buildpack.md @@ -1063,7 +1063,7 @@ optional = false os = "" arch = "" variant = "" -[[targets.distributions]] +[[targets.distros]] name = "" versions = [""] @@ -1114,13 +1114,15 @@ Each target in `targets`: - MUST identify a compatible runtime environment: - `os` and `arch` are required and MUST be valid identifiers as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md) - `variant` is optional and MUST be a valid identifier as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md) - - `distributions` are optional and MUST describe the OS distributions supported by the buildpack - - For Linux-based images, `distributions.name` and `distributions.versions` should contain the values specified in `/etc/os-release` (`$ID` and `$VERSION_ID`), as the `os.version` field in an image config may contain combined distribution and version information - - For Windows-based images, `distributions.name` should be empty; `distributions.versions` should contain the value of `os.version` in the image config (e.g., `10.0.14393.1066`) + - `distros` are optional and MUST describe the OS distributions supported by the buildpack + - For Linux-based images, `distros.name` and `distros.versions` should contain the values specified in `/etc/os-release` (`$ID` and `$VERSION_ID`), as the `os.version` field in an image config may contain combined distribution and version information + - For Windows-based images, `distros.name` should be empty; `distros.versions` should contain the value of `os.version` in the image config (e.g., `10.0.14393.1066`) If the `targets` list is empty, tools reading `buildpack.toml` will assume: - `os = "linux"` and `arch = "x86_64"` if `./bin/build` is present - `os = "windows"` and `arch = "x86_64"` if `./bin/build.bat` or `./bin/build.exe` are present + +Metadata specified in `targets` is validated against the runtime and build-time base images. #### Order @@ -1163,6 +1165,16 @@ Each stack in `stacks` either: - `id` MUST be set to the special value `"*"`. - `mixins` MUST be empty. +Tools reading `buildpack.toml` will translate any section that sets `stacks.id = "io.buildpacks.stacks.bionic` to: + +```toml +[[targets]] +os = "linux" +arch = "x86_64" +[[targets.distros]] +name = "ubuntu" +versions = ["18.04"] +``` ### Positional Arguments to `detect` and `build` Executables @@ -1232,7 +1244,6 @@ When the build is complete, a legacy build BOM describing the build container MA If generated, this legacy build BOM MUST contain all `bom` entries in each `build.toml` at the end of each `/bin/build` execution, in adherence with the process and data format outlined in the [Platform Interface Specification](platform.md) for legacy BOM formats. - ### Build Plan (TOML) `requires.version` Key _Deprecated in Buildpack API 0.3._ From 4165ecbae821e635b2734385c90ead05fab947b7 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 6 Dec 2022 11:56:36 -0500 Subject: [PATCH 04/30] Add target env variables Signed-off-by: Natalie Arellano --- buildpack.md | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/buildpack.md b/buildpack.md index 53cf33d..497d4f1 100644 --- a/buildpack.md +++ b/buildpack.md @@ -760,9 +760,22 @@ The purpose of launch is to modify the running app environment using app-provide ### Provided by the Lifecycle +#### Targets + +The following environment variables MUST be set by the lifecycle during `detect` and `build` phases to describe the target runtime image. + +| Env Variable | Description | +|-----------------------------|--------------------------------------------| +| `CNB_TARGET_ID` | Identifier for the target image (optional) | +| `CNB_TARGET_OS` | Target OS | +| `CNB_TARGET_ARCH` | Target architecture | +| `CNB_TARGET_VARIANT` | Target architecture variant (optional) | +| `CNB_TARGET_DISTRO_NAME` | Target OS distribution name (optional) | +| `CNB_TARGET_DISTRO_VERISON` | Target OS distribution version (optional) | + #### Layer Paths -The following layer path environment variables MUST be set by the lifecycle during the build and launch phases in order to make buildpack dependencies accessible. +The following layer path environment variables MUST be set by the lifecycle during the `build` and `launch` phases in order to make buildpack dependencies accessible. During the build phase, each variable designated for build MUST contain absolute paths of all previous buildpacks’ `//` directories that are designated for build. @@ -787,14 +800,13 @@ In either case, The following additional environment variables MUST NOT be overridden by the lifecycle. -| Env Variable | Description | Detect | Build | Launch -|-----------------|------------------------------------------------|--------|-------|-------- -| `CNB_STACK_ID` | Chosen stack ID | [x] | [x] | -| `BP_*` | User-provided variable for buildpack | [x] | [x] | -| `BPL_*` | User-provided variable for exec.d | | | [x] -| `HOME` | Current user's home directory | [x] | [x] | [x] +| Env Variable | Description | Detect | Build | Launch | +|-----------------|--------------------------------------|--------|-------|--------| +| `BP_*` | User-provided variable for buildpack | [x] | [x] | | +| `BPL_*` | User-provided variable for exec.d | | | [x] | +| `HOME` | Current user's home directory | [x] | [x] | [x] | -During the detection and build phases, the lifecycle MUST provide any user-provided environment variables as files in `/env/` with file names and contents matching the environment variable names and contents. +During the `detect` and `build` phases, the lifecycle MUST provide any user-provided environment variables as files in `/env/` with file names and contents matching the environment variable names and contents. When `clear-env` in `buildpack.toml` is set to `true` for a given buildpack, the lifecycle MUST NOT set user-provided environment variables in the environment of `/bin/detect` or `/bin/build`. From eb6afa242a6b4289c15110f2a9e6fc76a9af050c Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 6 Dec 2022 12:04:48 -0500 Subject: [PATCH 05/30] Remove other references to stacks and mixins Signed-off-by: Natalie Arellano --- buildpack.md | 29 +++++------------------------ 1 file changed, 5 insertions(+), 24 deletions(-) diff --git a/buildpack.md b/buildpack.md index 497d4f1..428026e 100644 --- a/buildpack.md +++ b/buildpack.md @@ -132,10 +132,6 @@ A **layer directory** is a directory created by a component buildpack that conta * a **build layer** contains child directories with paths that are added to the environment (e.g., `PATH`, `LD_LIBRARY_PATH`, etc.) for subsequent buildpacks in the same build Any combination of the three layer types are valid for a particular layer directory. -A **stack** is a contract, implemented by a **build image** and **run image**, that guarantees properties of the **build environment** and **app image**. The provided stack is communicated to component buildpacks through the `CNB_STACK_ID` environment variable, enabling each component buildpack to modify its behavior when executed on different stacks. - -A **mixin** is a named set of additions to a stack that can be used to make additive changes to the contract. Buildpacks can express their required mixins in `buildpack.toml`. - ## Buildpack Interface The following specifies the interface implemented by component buildpacks. @@ -400,21 +396,8 @@ For each trial, The lifecycle MAY execute each `/bin/detect` within a group in parallel. -The lifecycle MUST run `/bin/detect` for all extensions and buildpacks in a group in a container using common stack with a common set of mixins. -The lifecycle MUST fail detection if any of the buildpacks does not list that stack in `buildpack.toml`. -The lifecycle MUST fail detection if any of the buildpacks specifies a mixin associated with that stack in `buildpack.toml` that is not satisfied, see [Mixin Satisfaction](#mixin-satisfaction) below. - -#### Mixin Satisfaction - -A buildpack's mixin requirements must be satisfied by the stack in one of the following scenarios. - -1) the stack provides the mixin `run:` and the buildpack requires `run:` -2) the stack provides the mixin `build:` and the buildpack requires `build:` -3) the stack provides the mixin `` and the buildpack requires `` -4) the stack provides the mixin `` and the buildpack requires `build:` -5) the stack provides the mixin `` and the buildpack requires `run:` -6) the stack provides the mixin `` and the buildpack requires both `run:` and `build:` -7) the stack provides the mixins `build:` and `run:` the buildpack requires `` +The lifecycle MUST run `/bin/detect` for all extensions and buildpacks in a group in a container using a common build environment. +If any buildpack in a group fails to declare a target in `buildpack.toml` matching the build-time and runtime base images, the lifecycle MUST fail detection for the group. #### Order Resolution @@ -687,7 +670,7 @@ The purpose of export is to create a new OCI image using a combination of remote - The `` directories provided to each buildpack during the build phase, - The `` directory processed by the buildpacks during the build phase, - The buildpack IDs associated with the buildpacks used during the build phase, in order of execution, -- A reference to the most recent version of the run image associated with the stack and mixins, +- A reference to the most recent version of the run image, - A reference to the old OCI image processed during the analysis phase, if available, and - A tag for a new OCI image, @@ -814,8 +797,6 @@ When `clear-env` in `buildpack.toml` is not set to `true` for a given buildpack, 1. For layer path environment variables, user-provided values are prepended before any existing values and are delimited by the OS path list separator. 2. For all other environment variables, user-provided values override any existing values. -Buildpacks MAY use the value of `CNB_STACK_ID` to modify their behavior when executed on different stacks. - The environment variable prefix `CNB_` is reserved. It MUST NOT be used for environment variables that are not defined in this specification or approved extensions. @@ -1097,8 +1078,6 @@ Buildpack authors MUST choose a globally unique ID, for example: "io.buildpacks. - Each element MUST increase numerically. - Buildpack authors will define what changes will increment `X`, `Y`, and `Z`. -If an `order` is specified, then `stacks` MUST NOT be specified. - **The buildpack API:** *Key: `api = ""`* @@ -1177,6 +1156,8 @@ Each stack in `stacks` either: - `id` MUST be set to the special value `"*"`. - `mixins` MUST be empty. +If an `order` is specified, then `stacks` MUST NOT be specified. + Tools reading `buildpack.toml` will translate any section that sets `stacks.id = "io.buildpacks.stacks.bionic` to: ```toml From ae5039b232086724ac6103dd40db522b6a00d25c Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 6 Dec 2022 12:07:18 -0500 Subject: [PATCH 06/30] Update TOC Signed-off-by: Natalie Arellano --- buildpack.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/buildpack.md b/buildpack.md index 428026e..d0e6672 100644 --- a/buildpack.md +++ b/buildpack.md @@ -24,7 +24,6 @@ This document specifies the interface between a lifecycle program and one or mor - [Phase #1: Detection](#phase-1-detection) - [Purpose](#purpose) - [Process](#process) - - [Mixin Satisfaction](#mixin-satisfaction) - [Order Resolution](#order-resolution) - [Phase #2: Analysis](#phase-2-analysis) - [Purpose](#purpose-1) @@ -51,6 +50,7 @@ This document specifies the interface between a lifecycle program and one or mor - [Process](#process-5) - [Environment](#environment) - [Provided by the Lifecycle](#provided-by-the-lifecycle) + - [Targets](#targets) - [Layer Paths](#layer-paths) - [Provided by the Platform](#provided-by-the-platform) - [Provided by the Buildpacks](#provided-by-the-buildpacks) @@ -71,10 +71,11 @@ This document specifies the interface between a lifecycle program and one or mor - [Buildpack Plan (TOML)](#buildpack-plan-toml) - [Layer Content Metadata (TOML)](#layer-content-metadata-toml) - [buildpack.toml (TOML)](#buildpacktoml-toml) - - [Stacks](#stacks) + - [Targets](#targets-1) - [Order](#order) - [Exec.d Output (TOML)](#execd-output-toml) - [Deprecations](#deprecations) + - [buildpack.toml (TOML) `stacks` Array](#buildpacktoml-toml-stacks-array) - [Positional Arguments to `detect` and `build` Executables](#positional-arguments-to-detect-and-build-executables) - [launch.toml (TOML) `bom` Array](#launchtoml-toml-bom-array) - [build.toml (TOML) `bom` Array](#buildtoml-toml-bom-array) From f865cb00572c9725648e1c42a023d205e0345fb7 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 6 Dec 2022 12:13:03 -0500 Subject: [PATCH 07/30] Rename distros -> distributions Signed-off-by: Natalie Arellano --- buildpack.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/buildpack.md b/buildpack.md index d0e6672..b4d6324 100644 --- a/buildpack.md +++ b/buildpack.md @@ -1057,7 +1057,7 @@ optional = false os = "" arch = "" variant = "" -[[targets.distros]] +[[targets.distributions]] name = "" versions = [""] @@ -1106,9 +1106,9 @@ Each target in `targets`: - MUST identify a compatible runtime environment: - `os` and `arch` are required and MUST be valid identifiers as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md) - `variant` is optional and MUST be a valid identifier as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md) - - `distros` are optional and MUST describe the OS distributions supported by the buildpack - - For Linux-based images, `distros.name` and `distros.versions` should contain the values specified in `/etc/os-release` (`$ID` and `$VERSION_ID`), as the `os.version` field in an image config may contain combined distribution and version information - - For Windows-based images, `distros.name` should be empty; `distros.versions` should contain the value of `os.version` in the image config (e.g., `10.0.14393.1066`) + - `distributions` are optional and MUST describe the OS distributions supported by the buildpack + - For Linux-based images, `distributions.name` and `distributions.versions` should contain the values specified in `/etc/os-release` (`$ID` and `$VERSION_ID`), as the `os.version` field in an image config may contain combined distribution and version information + - For Windows-based images, `distributions.name` should be empty; `distributions.versions` should contain the value of `os.version` in the image config (e.g., `10.0.14393.1066`) If the `targets` list is empty, tools reading `buildpack.toml` will assume: - `os = "linux"` and `arch = "x86_64"` if `./bin/build` is present @@ -1165,7 +1165,7 @@ Tools reading `buildpack.toml` will translate any section that sets `stacks.id = [[targets]] os = "linux" arch = "x86_64" -[[targets.distros]] +[[targets.distributions]] name = "ubuntu" versions = ["18.04"] ``` From 3e227b5bd44a5bd62d90aaaefe4171257dbcefce Mon Sep 17 00:00:00 2001 From: Aidan Delaney Date: Sat, 4 Feb 2023 07:55:21 +0000 Subject: [PATCH 08/30] Describe Operator provided vars in CNB_BUILD_CONFIG_DIR Describe how CNB_BUILD_CONFIG_DIR variables MUST be provided in the lifecycle execution environment and the suffixes that are allowed. Signed-off-by: Aidan Delaney --- platform.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/platform.md b/platform.md index c183701..88819a1 100644 --- a/platform.md +++ b/platform.md @@ -1020,6 +1020,19 @@ User-provided environment variables MAY be modified by prior buildpacks before t The platform SHOULD NOT set user-provided environment variables directly in the lifecycle execution environment. +The `/env/` directory follows the same convention as [Environment Variable Modification Rules](https://github.com/buildpacks/spec/blob/main/buildpack.md#environment-variable-modification-rules). + +##### Operator-Defined Variables +Operator-provided environment varaiables MUST be supplied by the platform as files in the `CNB_BUILD_CONFIG_DIR` directory. + +Each file SHALL define a single environment variable, where the file name defines the key and the file contents define the value. + +Operator-defined environment variables MAY be modified by subsequent buildpacks before they are provided to a given buildpack. + +The platform MUST set operator-provided environment variables directly in the lifecycle execution environment. + +The `CNB_BUILD_CONFIG_DIR` directory follows the same convention as [Environment Variable Modification Rules](https://github.com/buildpacks/spec/blob/main/buildpack.md#environment-variable-modification-rules). + #### Launch Environment User-provided modifications to the process execution environment SHOULD be set directly in the lifecycle execution environment. From 67b286d0274d5c0d0d8fb1d9827df1ff8dc27d35 Mon Sep 17 00:00:00 2001 From: Aidan Delaney Date: Sat, 4 Feb 2023 07:58:30 +0000 Subject: [PATCH 09/30] Provide changes to buildpack.md only Revert changes to platform.md so that buildpack.md can be merged into appropriate branches. Signed-off-by: Aidan Delaney --- platform.md | 63 +++++++++++++++++++---------------------------------- 1 file changed, 22 insertions(+), 41 deletions(-) diff --git a/platform.md b/platform.md index 88819a1..223a6e9 100644 --- a/platform.md +++ b/platform.md @@ -367,7 +367,6 @@ Usage: [-app ] \ [-analyzed ] \ [-buildpacks ] \ - [-build-config ] [-extensions ] \ [-generated ] \ [-group ] \ @@ -379,21 +378,19 @@ Usage: ``` ##### Inputs -| Input | Environment Variable | Default Value | Description | -|------------------|------------------------|--------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | (**[experimental](#experimental-features)**) Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) | -| `` | `CNB_APP_DIR` | `/workspace` | Path to application directory | -| `` | `CNB_BUILDPACKS_DIR` | `/cnb/buildpacks` | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout)) | -| `` | `CNB_EXTENSIONS_DIR` | `/cnb/extensions` | (**[experimental](#experimental-features)**) Path to image extensions directory (see [Image Extensions Directory Layout](#image-extensions-directory-layout) | -| `` | `CNB_GENERATED_DIR` | `/generated` | (**[experimental](#experimental-features)**) Path to output directory for generated Dockerfiles | -| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to output group definition | -| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | -| `` | `CNB_LOG_LEVEL` | `info` | Log Level | -| `` | `CNB_ORDER_PATH` | `/order.toml` if present, or `/cnb/order.toml` | Path resolution for order definition (see [`order.toml`](#ordertoml-toml)) | -| `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to output resolved build plan | -| `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory | -| `` | `CNB_BUILD_CONFIG_DIR` | `/cnb/build-config` | Path to operator-defined environment variables | - +| Input | Environment Variable | Default Value | Description | +|----------------|----------------------|--------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | (**[experimental](#experimental-features)**) Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) | +| `` | `CNB_APP_DIR` | `/workspace` | Path to application directory | +| `` | `CNB_BUILDPACKS_DIR` | `/cnb/buildpacks` | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout)) | +| `` | `CNB_EXTENSIONS_DIR` | `/cnb/extensions` | (**[experimental](#experimental-features)**) Path to image extensions directory (see [Image Extensions Directory Layout](#image-extensions-directory-layout) | +| `` | `CNB_GENERATED_DIR` | `/generated` | (**[experimental](#experimental-features)**) Path to output directory for generated Dockerfiles | +| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to output group definition | +| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | +| `` | `CNB_LOG_LEVEL` | `info` | Log Level | +| `` | `CNB_ORDER_PATH` | `/order.toml` if present, or `/cnb/order.toml` | Path resolution for order definition (see [`order.toml`](#ordertoml-toml)) | +| `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to output resolved build plan | +| `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory | ##### Outputs | Output | Description | @@ -527,7 +524,6 @@ Usage: | `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to resolved build plan (see [`plan.toml`](#plantoml-toml)) | | `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory | | `` | `CNB_USER_ID` | | UID of the build image `User` | -| `` | `CNB_BUILD_CONFIG_DIR` | `/cnb/build-config` | Path to operator-defined environment variables | ##### Outputs @@ -562,7 +558,6 @@ Usage: /cnb/lifecycle/builder \ [-app ] \ [-buildpacks ] \ - [-build-config ] [-group ] \ [-layers ] \ [-log-level ] \ @@ -571,16 +566,15 @@ Usage: ``` ##### Inputs -| Input | Env | Default Value | Description | -|------------------|------------------------|-----------------------|------------------------------------------------------------------------------------------------| -| `` | `CNB_APP_DIR` | `/workspace` | Path to application directory | -| `` | `CNB_BUILDPACKS_DIR` | `/cnb/buildpacks` | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout)) | -| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to group definition (see [`group.toml`](#grouptoml-toml)) | -| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | -| `` | `CNB_LOG_LEVEL` | `info` | Log Level | -| `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to resolved build plan (see [`plan.toml`](#plantoml-toml)) | -| `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory | -| `` | `CNB_BUILD_CONFIG_DIR` | `/cnb/build-config` | Path to operator-defined environment variables | +| Input | Env | Default Value | Description +|----------------|-----------------------|-----------------------|---------------------- +| `` | `CNB_APP_DIR` | `/workspace` | Path to application directory +| `` | `CNB_BUILDPACKS_DIR` | `/cnb/buildpacks` | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout)) +| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to group definition (see [`group.toml`](#grouptoml-toml)) +| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory +| `` | `CNB_LOG_LEVEL` | `info` | Log Level +| `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to resolved build plan (see [`plan.toml`](#plantoml-toml)) +| `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory ##### Outputs | Output | Description @@ -1020,19 +1014,6 @@ User-provided environment variables MAY be modified by prior buildpacks before t The platform SHOULD NOT set user-provided environment variables directly in the lifecycle execution environment. -The `/env/` directory follows the same convention as [Environment Variable Modification Rules](https://github.com/buildpacks/spec/blob/main/buildpack.md#environment-variable-modification-rules). - -##### Operator-Defined Variables -Operator-provided environment varaiables MUST be supplied by the platform as files in the `CNB_BUILD_CONFIG_DIR` directory. - -Each file SHALL define a single environment variable, where the file name defines the key and the file contents define the value. - -Operator-defined environment variables MAY be modified by subsequent buildpacks before they are provided to a given buildpack. - -The platform MUST set operator-provided environment variables directly in the lifecycle execution environment. - -The `CNB_BUILD_CONFIG_DIR` directory follows the same convention as [Environment Variable Modification Rules](https://github.com/buildpacks/spec/blob/main/buildpack.md#environment-variable-modification-rules). - #### Launch Environment User-provided modifications to the process execution environment SHOULD be set directly in the lifecycle execution environment. From b5e07386d8b7872c4987e6521426fa1f5de388d2 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 7 Feb 2023 13:59:15 -0500 Subject: [PATCH 10/30] Add run image extension to buildpack spec as per RFC 0105 Signed-off-by: Natalie Arellano --- image_extension.md | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/image_extension.md b/image_extension.md index 8b69a36..892cc28 100644 --- a/image_extension.md +++ b/image_extension.md @@ -21,7 +21,7 @@ This document specifies the interface between a lifecycle program and one or mor ## Image Extension API Version -This document accompanies Buildpack API version `0.9`. +This document accompanies Buildpack API version `0.10`. ## Image Extension Interface @@ -97,7 +97,14 @@ Correspondingly, each `/bin/generate` executable: A `run.Dockerfile` - MAY contain a single `FROM` instruction -- MUST NOT contain any other instructions +- MUST NOT contain any other `FROM` instructions +- MAY contain `ADD`, `ARG`, `COPY`, `ENV`, `LABEL`, `RUN`, `SHELL`, `USER`, and `WORKDIR` instructions +- SHOULD NOT contain any other instructions +- SHOULD use the `build_id` build arg to invalidate the cache after a certain layer. When the `$build_id` build arg is referenced in a `RUN` instruction, all subsequent layers will be rebuilt on the next build (as the value will change); the `build_id` build arg SHOULD be defaulted to 0 if used (this ensures portability) +- SHOULD NOT edit ``, ``, or `` directories (see the [Platform Interface Specification](platform.md)) as changes will not be persisted +- SHOULD use the `user_id` and `group_id` build args to reset the image config's `User` field to its original value if any `USER` instructions are employed +- SHOULD set the label `io.buildpacks.rebasable` to `true` to indicate that any new run image layers are safe to rebase on top of new runtime base images + - For the final image to be rebasable, all applied Dockerfiles must set this label to `true` A `build.Dockerfile` @@ -110,7 +117,8 @@ FROM ${base_image} - MAY contain `ADD`, `ARG`, `COPY`, `ENV`, `LABEL`, `RUN`, `SHELL`, `USER`, and `WORKDIR` instructions - SHOULD NOT contain any other instructions - SHOULD use the `build_id` build arg to invalidate the cache after a certain layer. When the `$build_id` build arg is referenced in a `RUN` instruction, all subsequent layers will be rebuilt on the next build (as the value will change); the `build_id` build arg SHOULD be defaulted to 0 if used (this ensures portability) -- SHOULD NOT edit ``, ``, or `` directories (see the [Platform Interface Specification](platform.md)) as changes will not be persisted +- SHOULD NOT edit ``, ``, or `` directories (see the [Platform Interface Specification](platform.md)) as changes will not be persisted +- SHOULD use the `user_id` and `group_id` build args to reset the image config's `User` field to its original value if any `USER` instructions are employed ## Phase: Extension @@ -132,6 +140,9 @@ For each Dockerfile in the group in order, the lifecycle MUST apply the Dockerfi - When there are multiple Dockerfiles, the value MUST be the intermediate image generated from the application of the previous Dockerfile. - A `build_id` build arg - The value MUST be a UUID +- `user_id` and `group_id` build args + - For the first Dockerfile, the values MUST be the original `uid` and `gid` from the `User` field of the config for the original base image. + - When there are multiple Dockerfiles, the values MUST be the `uid` and `gid` from the `User` field of the config for the intermediate image generated from the application of the previous Dockerfile. ## Data Format @@ -167,12 +178,20 @@ The image extension `id`, `version`, `api`, and `licenses` entries MUST follow t [[build.args]] name = "" value = "" + +[[run.args]] +name = "" +value = "" ``` The image extension MAY specify any number of args. -For each arg, the image extension: -- MUST specify a `name` to be the name of a build argument that will be provided to any output build.Dockerfile when extending the build base image. +For each `[[build.args]]`, the image extension: +- MUST specify a `name` to be the name of a build argument that will be provided to any output `build.Dockerfile` when extending the build base image. +- MUST specify a `value` to be the value of the build argument that is provided. + +For each `[[run.args]]`, the image extension: +- MUST specify a `name` to be the name of a build argument that will be provided to any output `run.Dockerfile` when extending the runtime base image. - MUST specify a `value` to be the value of the build argument that is provided. ### Build Plan (TOML) From 1d39e567a95bae5b9a589d9a0bc9fe5d0b3ba260 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 3 Mar 2023 14:19:47 -0500 Subject: [PATCH 11/30] Update buildpack.md Co-authored-by: Terence Lee Signed-off-by: Natalie Arellano --- buildpack.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/buildpack.md b/buildpack.md index b4d6324..d2b1e60 100644 --- a/buildpack.md +++ b/buildpack.md @@ -1111,8 +1111,8 @@ Each target in `targets`: - For Windows-based images, `distributions.name` should be empty; `distributions.versions` should contain the value of `os.version` in the image config (e.g., `10.0.14393.1066`) If the `targets` list is empty, tools reading `buildpack.toml` will assume: - - `os = "linux"` and `arch = "x86_64"` if `./bin/build` is present - - `os = "windows"` and `arch = "x86_64"` if `./bin/build.bat` or `./bin/build.exe` are present + - `os = "linux"` and `arch = "amd64"` if `./bin/build` is present + - `os = "windows"` and `arch = "amd64"` if `./bin/build.bat` or `./bin/build.exe` are present Metadata specified in `targets` is validated against the runtime and build-time base images. From c0cf8526572b3770ce0a77571af9f3377a29ee33 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 3 Mar 2023 14:20:04 -0500 Subject: [PATCH 12/30] Update buildpack.md Co-authored-by: Terence Lee Signed-off-by: Natalie Arellano --- buildpack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buildpack.md b/buildpack.md index d2b1e60..8924517 100644 --- a/buildpack.md +++ b/buildpack.md @@ -1164,7 +1164,7 @@ Tools reading `buildpack.toml` will translate any section that sets `stacks.id = ```toml [[targets]] os = "linux" -arch = "x86_64" +arch = "amd64" [[targets.distributions]] name = "ubuntu" versions = ["18.04"] From c985eeb1706c179304446682a91e41b0c47806d6 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 3 Mar 2023 14:29:14 -0500 Subject: [PATCH 13/30] Clarify matching criteria Signed-off-by: Natalie Arellano --- buildpack.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/buildpack.md b/buildpack.md index 8924517..912bc66 100644 --- a/buildpack.md +++ b/buildpack.md @@ -398,7 +398,7 @@ For each trial, The lifecycle MAY execute each `/bin/detect` within a group in parallel. The lifecycle MUST run `/bin/detect` for all extensions and buildpacks in a group in a container using a common build environment. -If any buildpack in a group fails to declare a target in `buildpack.toml` matching the build-time and runtime base images, the lifecycle MUST fail detection for the group. +If any buildpack in a group fails to declare a target in `buildpack.toml` matching the build-time and runtime base images, the lifecycle MUST fail detection for the group. For matching criteria, see [buildpack.toml](#buildpacktoml-toml). #### Order Resolution @@ -746,7 +746,7 @@ The purpose of launch is to modify the running app environment using app-provide #### Targets -The following environment variables MUST be set by the lifecycle during `detect` and `build` phases to describe the target runtime image. +The following environment variables MUST be set by the lifecycle during the `detect` and `build` phases to describe the target runtime image, if inputs are provided. | Env Variable | Description | |-----------------------------|--------------------------------------------| @@ -1114,6 +1114,10 @@ If the `targets` list is empty, tools reading `buildpack.toml` will assume: - `os = "linux"` and `arch = "amd64"` if `./bin/build` is present - `os = "windows"` and `arch = "amd64"` if `./bin/build.bat` or `./bin/build.exe` are present +Two `[[targets]]` are considered to match when: +* `os` and `arch` match, and +* Optional fields either match exactly, or are left blank by at least one target (blank values are wildcard matches) + Metadata specified in `targets` is validated against the runtime and build-time base images. #### Order From 8652ec5e492998e0233c7778b7217d8433f16663 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 3 Mar 2023 14:31:17 -0500 Subject: [PATCH 14/30] Distribution can have only one version Signed-off-by: Natalie Arellano --- buildpack.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/buildpack.md b/buildpack.md index 912bc66..1e342ab 100644 --- a/buildpack.md +++ b/buildpack.md @@ -1059,7 +1059,7 @@ arch = "" variant = "" [[targets.distributions]] name = "" -versions = [""] +version = "" [metadata] # buildpack-specific data @@ -1171,7 +1171,7 @@ os = "linux" arch = "amd64" [[targets.distributions]] name = "ubuntu" -versions = ["18.04"] +version = "18.04" ``` ### Positional Arguments to `detect` and `build` Executables From 7bec2312dc357fce38dff7ebb9555a047c03b774 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 3 Mar 2023 14:33:51 -0500 Subject: [PATCH 15/30] Update buildpack.md Signed-off-by: Natalie Arellano --- buildpack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buildpack.md b/buildpack.md index e114c16..2f73e06 100644 --- a/buildpack.md +++ b/buildpack.md @@ -1166,7 +1166,7 @@ Each stack in `stacks` either: If an `order` is specified, then `stacks` MUST NOT be specified. -Tools reading `buildpack.toml` will translate any section that sets `stacks.id = "io.buildpacks.stacks.bionic` to: +Tools reading `buildpack.toml` will translate any section that sets `stacks.id = "io.buildpacks.stacks.bionic"` to: ```toml [[targets]] From 77ab37b499334acdfcf1d9442cb1f503b0d49785 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 20 Mar 2023 16:56:17 -0400 Subject: [PATCH 16/30] Update buildpack.md Signed-off-by: Natalie Arellano --- buildpack.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/buildpack.md b/buildpack.md index 2f73e06..553ce2a 100644 --- a/buildpack.md +++ b/buildpack.md @@ -1177,6 +1177,8 @@ name = "ubuntu" version = "18.04" ``` +Furthermore, any buildpack that contains `[[stacks]]` with `id = "*"` will match any target. + ### Positional Arguments to `detect` and `build` Executables _Deprecated in Buildpack API 0.8._ From 00cecc280fb8bebca82e65cd6ab9a0b26371128f Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 5 Jun 2023 13:08:27 -0400 Subject: [PATCH 17/30] Apply suggestions from code review Signed-off-by: Natalie Arellano --- buildpack.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/buildpack.md b/buildpack.md index 553ce2a..727e6d1 100644 --- a/buildpack.md +++ b/buildpack.md @@ -1114,8 +1114,8 @@ Each target in `targets`: - For Windows-based images, `distributions.name` should be empty; `distributions.versions` should contain the value of `os.version` in the image config (e.g., `10.0.14393.1066`) If the `targets` list is empty, tools reading `buildpack.toml` will assume: - - `os = "linux"` and `arch = "amd64"` if `./bin/build` is present - - `os = "windows"` and `arch = "amd64"` if `./bin/build.bat` or `./bin/build.exe` are present + - `os = "linux"` and `arch = ` if `./bin/build` is present + - `os = "windows"` and `arch = ` if `./bin/build.bat` or `./bin/build.exe` are present Two `[[targets]]` are considered to match when: * `os` and `arch` match, and From 058949f58c2f9145afac7c1998d693587eebdbdc Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 5 Jun 2023 13:13:48 -0400 Subject: [PATCH 18/30] Extensions specify targets Signed-off-by: Natalie Arellano --- buildpack.md | 3 ++- image_extension.md | 10 ++++++++++ 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/buildpack.md b/buildpack.md index 727e6d1..ba3cf89 100644 --- a/buildpack.md +++ b/buildpack.md @@ -1116,10 +1116,11 @@ Each target in `targets`: If the `targets` list is empty, tools reading `buildpack.toml` will assume: - `os = "linux"` and `arch = ` if `./bin/build` is present - `os = "windows"` and `arch = ` if `./bin/build.bat` or `./bin/build.exe` are present + - `os = ` and `arch = ` for extensions Two `[[targets]]` are considered to match when: * `os` and `arch` match, and -* Optional fields either match exactly, or are left blank by at least one target (blank values are wildcard matches) +* Optional fields either match exactly, or are left blank by at least one target (blank values match any other value) Metadata specified in `targets` is validated against the runtime and build-time base images. diff --git a/image_extension.md b/image_extension.md index 892cc28..3dd13f0 100644 --- a/image_extension.md +++ b/image_extension.md @@ -166,12 +166,22 @@ keywords = [ "" ] [[extension.licenses]] type = "" uri = "" + +[[targets]] +os = "" +arch = "" +variant = "" +[[targets.distributions]] +name = "" +version = "" ``` Image extension authors MUST choose a globally unique ID, for example: "io.buildpacks.apt". The image extension `id`, `version`, `api`, and `licenses` entries MUST follow the requirements defined in the [Buildpack Interface Specification](buildpack.md). +An extension descriptor MAY specify `targets` following the requirements defined in the [Buildpack Interface Specification](buildpack.md). + ### extend-config.toml (TOML) ```toml From 9587e8cd4b65e3aee9a0ac6a4ae2eae5c327f024 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 6 Jun 2023 11:05:26 -0400 Subject: [PATCH 19/30] Apply suggestions from code review Signed-off-by: Natalie Arellano --- buildpack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buildpack.md b/buildpack.md index ba3cf89..5e119c0 100644 --- a/buildpack.md +++ b/buildpack.md @@ -1103,7 +1103,7 @@ The `[[buildpack.licenses]]` table is optional and MAY contain a list of buildpa #### Targets -A buildpack descriptor MAY specify `targets`. +A buildpack descriptor SHOULD specify `targets`. Each target in `targets`: - MUST identify a compatible runtime environment: From 5b7eadeb515c0e3ccf99665c8ada83c13b2fe394 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 6 Jun 2023 11:07:30 -0400 Subject: [PATCH 20/30] Clarify target matching Signed-off-by: Natalie Arellano --- buildpack.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/buildpack.md b/buildpack.md index 5e119c0..321e6de 100644 --- a/buildpack.md +++ b/buildpack.md @@ -1118,11 +1118,10 @@ If the `targets` list is empty, tools reading `buildpack.toml` will assume: - `os = "windows"` and `arch = ` if `./bin/build.bat` or `./bin/build.exe` are present - `os = ` and `arch = ` for extensions -Two `[[targets]]` are considered to match when: -* `os` and `arch` match, and -* Optional fields either match exactly, or are left blank by at least one target (blank values match any other value) - -Metadata specified in `targets` is validated against the runtime and build-time base images. +Metadata specified in `[[targets]]` is validated against the runtime and build-time base images. +* A buildpack target satisfies a base image target when: + * `os` and `arch` match, and + * Optional fields either match exactly, or are left blank by at least one target (blank values match any other value) #### Order From a05c4410f03eaa2dca4ea639422824c6fdb77be8 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 13 Jun 2023 13:24:27 -0400 Subject: [PATCH 21/30] Apply suggestions from code review Signed-off-by: Natalie Arellano --- buildpack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buildpack.md b/buildpack.md index 321e6de..b7fe79f 100644 --- a/buildpack.md +++ b/buildpack.md @@ -756,7 +756,7 @@ The following environment variables MUST be set by the lifecycle during the `det | `CNB_TARGET_ID` | Identifier for the target image (optional) | | `CNB_TARGET_OS` | Target OS | | `CNB_TARGET_ARCH` | Target architecture | -| `CNB_TARGET_VARIANT` | Target architecture variant (optional) | +| `CNB_TARGET_ARCH_VARIANT` | Target architecture variant (optional) | | `CNB_TARGET_DISTRO_NAME` | Target OS distribution name (optional) | | `CNB_TARGET_DISTRO_VERISON` | Target OS distribution version (optional) | From db802b26451b1d8945861fca49716fc8e71912d4 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Wed, 12 Jul 2023 17:33:00 -0400 Subject: [PATCH 22/30] Apply suggestions from code review Co-authored-by: Sambhav Kothari Signed-off-by: Natalie Arellano --- buildpack.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/buildpack.md b/buildpack.md index b7fe79f..29c2979 100644 --- a/buildpack.md +++ b/buildpack.md @@ -1110,8 +1110,8 @@ Each target in `targets`: - `os` and `arch` are required and MUST be valid identifiers as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md) - `variant` is optional and MUST be a valid identifier as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md) - `distributions` are optional and MUST describe the OS distributions supported by the buildpack - - For Linux-based images, `distributions.name` and `distributions.versions` should contain the values specified in `/etc/os-release` (`$ID` and `$VERSION_ID`), as the `os.version` field in an image config may contain combined distribution and version information - - For Windows-based images, `distributions.name` should be empty; `distributions.versions` should contain the value of `os.version` in the image config (e.g., `10.0.14393.1066`) + - For Linux-based images, `distributions.name` and `distributions.versions` SHOULD contain the values specified in `/etc/os-release` (`$ID` and `$VERSION_ID`), as the `os.version` field in an image config may contain combined distribution and version information + - For Windows-based images, `distributions.name` SHOULD be empty; `distributions.versions` SHOULD contain the value of `os.version` in the image config (e.g., `10.0.14393.1066`) If the `targets` list is empty, tools reading `buildpack.toml` will assume: - `os = "linux"` and `arch = ` if `./bin/build` is present From 7fd95e8a14a15600adfa743a03272ead2b7c5856 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Wed, 12 Jul 2023 17:37:35 -0400 Subject: [PATCH 23/30] Update buildpack.md Signed-off-by: Natalie Arellano --- buildpack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buildpack.md b/buildpack.md index 29c2979..c253bfb 100644 --- a/buildpack.md +++ b/buildpack.md @@ -401,7 +401,7 @@ For each trial, The lifecycle MAY execute each `/bin/detect` within a group in parallel. The lifecycle MUST run `/bin/detect` for all extensions and buildpacks in a group in a container using a common build environment. -If any buildpack in a group fails to declare a target in `buildpack.toml` matching the build-time and runtime base images, the lifecycle MUST fail detection for the group. For matching criteria, see [buildpack.toml](#buildpacktoml-toml). +If any non-optional buildpack in a group fails to declare a target in `buildpack.toml` matching the build-time and runtime base images, and in the case that no targets are declared and the [inferred target](#targets-1) does not match, the lifecycle MUST fail detection for the group. For matching criteria, see [buildpack.toml](#buildpacktoml-toml). #### Order Resolution From bf7d412cdbedd271d03b0901cf9ff208d063e59b Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Thu, 13 Jul 2023 11:33:59 -0400 Subject: [PATCH 24/30] Fix modification of platform.md in this branch Signed-off-by: Natalie Arellano --- platform.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/platform.md b/platform.md index 53a5872..f5de11d 100644 --- a/platform.md +++ b/platform.md @@ -367,6 +367,7 @@ Usage: [-app ] \ [-analyzed ] \ [-buildpacks ] \ + [-build-config ] \ [-extensions ] \ [-generated ] \ [-group ] \ @@ -393,6 +394,7 @@ Usage: | `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to output resolved build plan | | `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory | + ##### Outputs | Output | Description | |----------------------------------------------------------|-----------------------------------------------------------------------------------------------| @@ -561,6 +563,7 @@ Usage: /cnb/lifecycle/builder \ [-app ] \ [-buildpacks ] \ + [-build-config ] \ [-group ] \ [-layers ] \ [-log-level ] \ From cbf43c72574eef1bab0df037d4c995f0b4d9a949 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Thu, 13 Jul 2023 11:49:46 -0400 Subject: [PATCH 25/30] Revert "Merge branch 'main' into buildpack/0.10" This reverts commit 26f60e3a20048d93c649d4910f928a120fc8c8d3, reversing changes made to e16c633fd07e39f85dba9dbdf9f4bf96f8d5e5e8. --- README.md | 2 +- buildpack.md | 25 +++---- platform.md | 182 ++++++++++++++++++++++----------------------------- 3 files changed, 92 insertions(+), 117 deletions(-) diff --git a/README.md b/README.md index df2f7ce..48d6060 100644 --- a/README.md +++ b/README.md @@ -52,4 +52,4 @@ These documents currently specify: - Buildpack API: `0.9` - Distribution API: `0.3` -- Platform API: `0.11` +- Platform API: `0.10` diff --git a/buildpack.md b/buildpack.md index 598754d..c253bfb 100644 --- a/buildpack.md +++ b/buildpack.md @@ -161,14 +161,14 @@ The lifecycle MAY return an error to the platform if two or more buildpacks with Executable: `/bin/detect`, Working Dir: `` -| Input | Attributes | Description | -|--------------------------|------------|-----------------------------------------------| -| `$0` | | Absolute path of `/bin/detect` executable | -| `$CNB_BUILD_PLAN_PATH` | E | Absolute path of the build plan | -| `$CNB_BUILDPACK_DIR` | ER | Absolute path of the buildpack root directory | -| `$CNB_PLATFORM_DIR` | AR | Absolute path of the platform directory | -| `$CNB_PLATFORM_DIR/env/` | AR | User-provided environment variables for build | -| `$CNB_PLATFORM_DIR/#` | AR | Platform-specific extensions | +| Input | Attributes | Description | +|--------------------------|------------|---------------------------------------------------| +| `$0` | | Absolute path of `/bin/detect` executable | +| `$CNB_BUILD_PLAN_PATH` | E | Absolute path of the build plan | +| `$CNB_BUILDPACK_DIR` | ER | Absolute path of the buildpack root directory | +| `$CNB_PLATFORM_DIR` | AR | Absolute path of the platform directory | +| `$CNB_PLATFORM_DIR/env/` | AR | User-provided environment variables for build | +| `$CNB_PLATFORM_DIR/#` | AR | Platform-specific extensions | | Output | Description | |------------------------|---------------------------------------------| @@ -369,10 +369,13 @@ For each image extension ("extension") or component buildpack ("buildpack") in e The selected group MUST be filtered to only include extensions and buildpacks with exit status zero. The order of the extensions and buildpacks in the group MUST otherwise be preserved. +For each `/bin/detect` executable in each extension or buildpack, the lifecycle: + +- MUST configure the environment as described in the [Environment](#environment) section. + The `/bin/detect` executable in each extension or buildpack, when executed: - MAY read the app directory. -- MAY read the detect environment as described in the [Environment](#environment) section. - MAY emit error, warning, or debug messages to `stderr`. - MAY augment the Build Plan by writing TOML to ``. - MUST set an exit status code as described in the [Buildpack Interface](#buildpack-interface) section. @@ -779,7 +782,6 @@ In either case, | `CPATH` | `/include` | header files | [x] | | | `PKG_CONFIG_PATH` | `/pkgconfig` | pc files | [x] | | - ### Provided by the Platform The following additional environment variables MUST NOT be overridden by the lifecycle. @@ -790,7 +792,8 @@ The following additional environment variables MUST NOT be overridden by the lif | `BPL_*` | User-provided variable for exec.d | | | [x] | | `HOME` | Current user's home directory | [x] | [x] | [x] | -During the detection and build phases, the lifecycle MUST provide any user-provided environment variables as files in `/env/` with file names and contents matching the environment variable names and contents. +During the detection and build phases, the lifecycle MUST provide as environment variables any user-provided files in `/env/` with environment variable names and contents matching the file names and contents. +During the detection and build phases, the lifecycle MUST provide as environment variables any operator-provided files in `/env` with environment variable names and contents matching the file names and contents. This applies for all values of `clear-env` or if `clear-env` is undefined in `buildpack.toml`. When `clear-env` in `buildpack.toml` is set to `true` for a given buildpack, the lifecycle MUST NOT set user-provided environment variables in the environment of `/bin/detect` or `/bin/build`. diff --git a/platform.md b/platform.md index f5de11d..c725e50 100644 --- a/platform.md +++ b/platform.md @@ -93,7 +93,7 @@ Examples of a platform might include: ## Platform API Version -This document specifies Platform API version `0.11`. +This document specifies Platform API version `0.10`. Platform API versions: - MUST be in form `.` or ``, where `` is equivalent to `.0` @@ -128,7 +128,7 @@ A **launcher layer** refers to a layer in the app OCI image containing the **lau The **launcher** refers to a lifecycle executable packaged in the **app image** for the purpose of executing processes at runtime. -An **image extension** refers to software compliant with the [Image Extension Interface Specification](image_extension.md). Image extensions participate in detection and execute before the buildpack build process. +An **image extension** refers to software compliant with the [Image Extension Interface Specification](image-extension.md). Image extensions participate in detection and execute before the buildpack build process. #### Additional Terminology An **image reference** refers to either a **tag reference** or **digest reference**. @@ -379,20 +379,19 @@ Usage: ``` ##### Inputs -| Input | Environment Variable | Default Value | Description | -|------------------|------------------------|--------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | (**[experimental](#experimental-features)**) Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) | -| `` | `CNB_APP_DIR` | `/workspace` | Path to application directory | -| `` | `CNB_BUILD_CONFIG_DIR` | `/cnb/build-config` | Path to build config directory | -| `` | `CNB_BUILDPACKS_DIR` | `/cnb/buildpacks` | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout)) | -| `` | `CNB_EXTENSIONS_DIR` | `/cnb/extensions` | (**[experimental](#experimental-features)**) Path to image extensions directory (see [Image Extensions Directory Layout](#image-extensions-directory-layout) | -| `` | `CNB_GENERATED_DIR` | `/generated` | (**[experimental](#experimental-features)**) Path to output directory for generated Dockerfiles | -| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to output group definition | -| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | -| `` | `CNB_LOG_LEVEL` | `info` | Log Level | -| `` | `CNB_ORDER_PATH` | `/order.toml` if present, or `/cnb/order.toml` | Path resolution for order definition (see [`order.toml`](#ordertoml-toml)) | -| `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to output resolved build plan | -| `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory | +| Input | Environment Variable | Default Value | Description | +|----------------|----------------------|--------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | (**[experimental](#experimental-features)**) Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) | +| `` | `CNB_APP_DIR` | `/workspace` | Path to application directory | +| `` | `CNB_BUILDPACKS_DIR` | `/cnb/buildpacks` | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout)) | +| `` | `CNB_EXTENSIONS_DIR` | `/cnb/extensions` | (**[experimental](#experimental-features)**) Path to image extensions directory (see [Image Extensions Directory Layout](#image-extensions-directory-layout) | +| `` | `CNB_GENERATED_DIR` | `/generated` | (**[experimental](#experimental-features)**) Path to output directory for generated Dockerfiles | +| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to output group definition | +| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | +| `` | `CNB_LOG_LEVEL` | `info` | Log Level | +| `` | `CNB_ORDER_PATH` | `/order.toml` if present, or `/cnb/order.toml` | Path resolution for order definition (see [`order.toml`](#ordertoml-toml)) | +| `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to output resolved build plan | +| `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory | ##### Outputs @@ -449,19 +448,19 @@ Usage: ``` ##### Inputs -| Input | Environment Variable | Default Value | Description | -|-----------------|----------------------|--------------------------|---------------------------------------------------------------------------------------------------| -| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) | -| `` | `CNB_BUILD_IMAGE` | | Reference to the current build image in an OCI registry (if used `` must be provided) | -| `` | `CNB_CACHE_DIR` | | Path to a cache directory | -| `` | `CNB_CACHE_IMAGE` | | Reference to a cache image in an OCI registry | -| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` | -| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to group definition (see [`group.toml`](#grouptoml-toml)) | -| `` | | | Kaniko directory (must be `/kaniko`) | -| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | -| `` | `CNB_LOG_LEVEL` | `info` | Log Level | -| `` | `CNB_USER_ID` | | UID of the build image `User` | -| `` | `CNB_SKIP_LAYERS` | `false` | Do not perform [layer restoration](#layer-restoration) | +| Input | Environment Variable | Default Value | Description | +|-----------------|----------------------|--------------------------|-----------------------------------------------------------------------------| +| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) | +| `` | `CNB_BUILD_IMAGE` | | Reference to the current build image in an OCI registry (if used `` must be provided) | +| `` | `CNB_CACHE_DIR` | | Path to a cache directory | +| `` | `CNB_CACHE_IMAGE` | | Reference to a cache image in an OCI registry | +| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` | +| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to group definition (see [`group.toml`](#grouptoml-toml)) | +| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | +| `` | `CNB_LOG_LEVEL` | `info` | Log Level | +| `` | `CNB_USER_ID` | | UID of the build image `User` | +| `` | `CNB_SKIP_LAYERS` | `false` | Do not perform [layer restoration](#layer-restoration) | +|``| | | Kaniko directory (must be `/kaniko`) | ##### Outputs | Output | Description | @@ -473,16 +472,16 @@ Usage: | `//.toml` | Files containing the layer content metadata of each analyzed layer (see data format in [Buildpack Interface Specification](buildpack.md)) | | `//.sbom.` | Files containing the Software Bill of Materials for each analyzed layer (see [Buildpack Interface Specification](buildpack.md)) | | `///*`. | Restored layer contents | -| `/cache` | Kaniko cache contents | +| `/cache` | Kaniko cache contents | -| Exit Code | Result | -|-----------------|---------------------------------------| -| `0` | Success | -| `11` | Platform API incompatibility error | -| `12` | Buildpack API incompatibility error | -| `1-10`, `13-19` | Generic lifecycle errors | -| `40-49` | Restoration-specific lifecycle errors | +| Exit Code | Result| +|-----------------|-------| +| `0` | Success +| `11` | Platform API incompatibility error +| `12` | Buildpack API incompatibility error +| `1-10`, `13-19` | Generic lifecycle errors +| `40-49` | Restoration-specific lifecycle errors - For each buildpack in ``, if persistent metadata for that buildpack exists in the analysis metadata, lifecycle MUST write a toml representation of the persistent metadata to `//store.toml` - **If** `` is `true` the lifecycle MUST NOT perform layer restoration. @@ -517,13 +516,11 @@ Usage: |----------------------|------------------------|--------------------------|-------------------------------------------------------------------------------------------------| | `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | Path to analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) | | `` | `CNB_APP_DIR` | `/workspace` | Path to application directory | -| `` | `CNB_BUILD_CONFIG_DIR` | `/cnb/build-config` | Path to build config directory | | `` | `CNB_BUILDPACKS_DIR` | `/cnb/buildpacks` | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout)) | | `` | `CNB_GENERATED_DIR` | `/generated` | (**[experimental](#experimental-features)**) Path to directory containing generated Dockerfiles | | `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` | | `` | `CNB_GROUP_PATH` | `/group.toml` | Path to group definition (see [`group.toml`](#grouptoml-toml)) | | `` | `CNB_KANIKO_CACHE_TTL` | 2 weeks | Kaniko cache TTL | -| `` | | | Kaniko directory (must be `/kaniko`) | | `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | | `` | `CNB_LOG_LEVEL` | `info` | Log Level | | `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to resolved build plan (see [`plan.toml`](#plantoml-toml)) | @@ -534,11 +531,11 @@ Usage: In addition to the outputs enumerated below, outputs produced by `extender` include those produced by `builder` - as the lifecycle will run the `build` phase after extending the build image. When using the `extender` platforms MUST skip the `builder` and proceed to the `exporter`. -| Output | Description | -|----------------------|----------------------------------------| -| [exit status] | (see Exit Code table below for values) | -| `/dev/stdout` | Logs (info) | -| `/dev/stderr` | Logs (warnings, errors) | +| Output | Description | +|-----------------|----------------------------------------| +| [exit status] | (see Exit Code table below for values) | +| `/dev/stdout` | Logs (info) | +| `/dev/stderr` | Logs (warnings, errors) | | `/cache` | Kaniko cache contents | | Exit Code | Result | @@ -572,16 +569,15 @@ Usage: ``` ##### Inputs -| Input | Env | Default Value | Description | -|------------------|------------------------|-----------------------|------------------------------------------------------------------------------------------------| -| `` | `CNB_APP_DIR` | `/workspace` | Path to application directory | -| `` | `CNB_BUILD_CONFIG_DIR` | `/cnb/build-config` | Path to build config directory | -| `` | `CNB_BUILDPACKS_DIR` | `/cnb/buildpacks` | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout)) | -| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to group definition (see [`group.toml`](#grouptoml-toml)) | -| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | -| `` | `CNB_LOG_LEVEL` | `info` | Log Level | -| `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to resolved build plan (see [`plan.toml`](#plantoml-toml)) | -| `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory | +| Input | Env | Default Value | Description +|----------------|-----------------------|-----------------------|---------------------- +| `` | `CNB_APP_DIR` | `/workspace` | Path to application directory +| `` | `CNB_BUILDPACKS_DIR` | `/cnb/buildpacks` | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout)) +| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to group definition (see [`group.toml`](#grouptoml-toml)) +| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory +| `` | `CNB_LOG_LEVEL` | `info` | Log Level +| `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to resolved build plan (see [`plan.toml`](#plantoml-toml)) +| `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory ##### Outputs | Output | Description @@ -621,7 +617,6 @@ Usage: [-group ] \ [-launch-cache ] \ [-launcher ] \ - [-launcher-sbom ] \ [-layers ] \ [-log-level ] \ [-process-type ] \ @@ -633,28 +628,27 @@ Usage: ``` ##### Inputs -| Input | Environment Variable | Default Value | Description | -|---------------------------------|-----------------------------|----------------------------------|--------------------------------------------------------------------------------------------| -| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | Path to analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) | -| `` | `CNB_APP_DIR` | `/workspace` | Path to application directory | -| `` | `CNB_CACHE_DIR` | | Path to a cache directory | -| `` | `CNB_CACHE_IMAGE` | | Reference to a cache image in an OCI registry | -| `` | `CNB_USE_DAEMON` | `false` | Export image to docker daemon | -| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` | -| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to group file (see [`group.toml`](#grouptoml-toml)) | -| `` | | | Tag reference to which the app image will be written | -| `` | `CNB_LAUNCH_CACHE_DIR` | | Path to a cache directory containing launch layers | -| `` | | `/cnb/lifecycle/launcher` | Path to the `launcher` executable | -| `` | | `/cnb/lifecycle` | Path to directory containing SBOM files describing the `launcher` executable | -| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layer directory | -| `` | `CNB_LOG_LEVEL` | `info` | Log Level | -| `` | `CNB_PROCESS_TYPE` | | Default process type to set in the exported image | -| `` | `CNB_PROJECT_METADATA_PATH` | `/project-metadata.toml` | Path to a project metadata file (see [`project-metadata.toml`](#project-metadatatoml-toml) | -| `` | `CNB_REPORT_PATH` | `/report.toml` | Path to report (see [`report.toml`](#reporttoml-toml) | -| `` | `CNB_STACK_PATH` | `/cnb/stack.toml` | Path to stack file (see [`stack.toml`](#stacktoml-toml) | -| `` | `CNB_USER_ID` | | UID of the build image `User` | -| `/config/metadata.toml` | | | Build metadata (see [`metadata.toml`](#metadatatoml-toml) | -| | `SOURCE_DATE_EPOCH` | | Timestamp for `created` time in app image config | +| Input | Environment Variable | Default Value | Description +|---------------------|----------------------------|---------------------|--------------------------------------- +| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | Path to analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) +| `` | `CNB_APP_DIR` | `/workspace` | Path to application directory +| `` | `CNB_CACHE_DIR` | | Path to a cache directory +| `` | `CNB_CACHE_IMAGE` | | Reference to a cache image in an OCI registry +| `` | `CNB_USE_DAEMON` | `false` | Export image to docker daemon +| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` +| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to group file (see [`group.toml`](#grouptoml-toml)) +| `` | | | Tag reference to which the app image will be written +| `` | `CNB_LAUNCH_CACHE_DIR` | | Path to a cache directory containing launch layers +| `` | | `/cnb/lifecycle/launcher` | Path to the `launcher` executable +| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layer directory +| `` | `CNB_LOG_LEVEL` | `info` | Log Level +| `` | `CNB_PROCESS_TYPE` | | Default process type to set in the exported image +| ``| `CNB_PROJECT_METADATA_PATH`| `/project-metadata.toml` | Path to a project metadata file (see [`project-metadata.toml`](#project-metadatatoml-toml) +| `` | `CNB_REPORT_PATH` | `/report.toml` | Path to report (see [`report.toml`](#reporttoml-toml) +| `` | `CNB_STACK_PATH` | `/cnb/stack.toml` | Path to stack file (see [`stack.toml`](#stacktoml-toml) +| `` | `CNB_USER_ID` | | UID of the build image `User` +| `/config/metadata.toml` | | | Build metadata (see [`metadata.toml`](#metadatatoml-toml) +| | `SOURCE_DATE_EPOCH` | | Timestamp for `created` time in app image config | - At least one `` must be provided - Each `` MUST be a valid tag reference @@ -683,11 +677,10 @@ Usage: - All run-image layers SHALL be preserved - All run-image config values SHALL be preserved unless this conflicts with another requirement - MUST contain all buildpack-provided launch layers as determined by the [Buildpack Interface Specfication](buildpack.md) - - MUST contain a layer containing all Software Bill of Materials (SBOM) files for `launch` as determined by the [Buildpack Interface Specfication](buildpack.md) if they are present + - MUST contain a layer containing all buildpack-provided Software Bill of Materials (SBOM) files for `launch` as determined by the [Buildpack Interface Specfication](buildpack.md) if they are present - `/sbom/launch//sbom.` MUST contain the buildpack-provided `launch` SBOM - `/sbom/launch///sbom.` MUST contain the buildpack-provided layer SBOM if `` is a `launch` layer - - `/sbom/launch/sbom.legacy.json` MAY contain the legacy buildpack-provided non-standard Bill of Materials for `launch` (where [supported](buildpack.md)) - - `/sbom/launch/buildpacksio_lifecycle/launcher/sbom.` MUST contain the CNB-provided launcher SBOM if present in the `/cnb/lifecycle` directory + - `/sbom/launch/sbom.legacy.json` MAY contain the legacy non-standard Bill of Materials for `launch` (where [supported](buildpack.md)) - MUST contain one or more app layers as determined by the [Buildpack Interface Specfication](buildpack.md) - MUST contain one or more launcher layers that include: - A file with the contents of the `` file at path `/cnb/lifecycle/launcher` @@ -717,11 +710,10 @@ Usage: - The lifecycle SHALL write a [report](#reporttoml-toml) to `` describing the exported app image - The `` directory: - - MUST include all Software Bill of Materials (SBOM) files for `build` as determined by the [Buildpack Interface Specfication](buildpack.md) if they are present + - MUST include all buildpack-provided Software Bill of Materials (SBOM) files for `build` as determined by the [Buildpack Interface Specfication](buildpack.md) if they are present - `/sbom/build//sbom.` MUST contain the buildpack-provided `build` SBOM - `/sbom/build///sbom.` MUST contain the buildpack-provided layer SBOM if `` is not a `launch` layer. - - `/sbom/build/sbom.legacy.json` MAY contain the legacy buildpack-provided non-standard Bill of Materials for `build` (where [supported](buildpack.md)) - - `/sbom/build/buildpacksio_lifecycle/sbom.` MUST contain the CNB-provided lifecycle SBOM if present in the `/cnb/lifecycle` directory + - `/sbom/build/sbom.legacy.json` MAY contain the legacy non-standard Bill of Materials for `build` (where [supported](buildpack.md)) - *If* a cache is provided the lifecycle: - SHALL write the contents of all cached layers and any provided layer-associated SBOM files to the cache - SHALL record the diffID and layer content metadata of all cached layers in the cache @@ -790,7 +782,6 @@ Usage: [-daemon] \ # sets [-gid ] \ [-log-level ] \ - [-previous-image ] \ [-report ] \ [-run-image | -image ] \ # -image is Deprecated [-uid ] \ @@ -804,7 +795,6 @@ Usage: | `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` | `` | | | App image to rebase | `` | `CNB_LOG_LEVEL` | `info` | Log Level -| `` | | derived from `` | Previous image reference | `` | `CNB_REPORT_PATH` | `/report.toml` | Path to report (see [`report.toml`](#reporttoml-toml) | `` | `CNB_RUN_IMAGE` | derived from `` | Run image reference | `` | `CNB_USER_ID` | | UID of the build image `User` @@ -812,8 +802,6 @@ Usage: - At least one `` must be provided - Each `` MUST be a valid tag reference - **If** `` is `false` and more than one `` is provided they MUST refer to the same registry -- **If** `` is provided by the platform, the value will be used as the app image to rebase. `` must NOT be modified unless specified again in ``. -- **Else** `` value will derived from the first ``. - **If** `` is not provided by the platform the value will be [resolved](#run-image-resolution) from the contents of the `stack` key in the `io.buildpacks.lifecycle.metdata` label on ``. ##### Outputs @@ -1029,19 +1017,6 @@ User-provided environment variables MAY be modified by prior buildpacks before t The platform SHOULD NOT set user-provided environment variables directly in the lifecycle execution environment. -The `/env/` directory follows the same convention as [Environment Variable Modification Rules](https://github.com/buildpacks/spec/blob/main/buildpack.md#environment-variable-modification-rules). - -##### Operator-Defined Variables -Operator-provided environment varaiables MUST be supplied by the platform as files in the `/env/` directory. - -Each file SHALL define a single environment variable, where the file name defines the key and the file contents define the value. - -Operator-defined environment variables MAY be modified by subsequent buildpacks before they are provided to a given buildpack. - -The platform SHOULD NOT set operator-provided environment variables directly in the lifecycle execution environment. - -The `/env/` directory follows the [Environment Variable Modification Rules](https://github.com/buildpacks/spec/blob/main/buildpack.md#environment-variable-modification-rules) outlined in the [Buildpack Interface Specification](buildpack.md), except for the modification behavior when no period-delimited suffix is provided; when no suffix is provided, the behavior is `default`. - #### Launch Environment User-provided modifications to the process execution environment SHOULD be set directly in the lifecycle execution environment. @@ -1259,23 +1234,20 @@ Where: ], "direct": false, "working-dir": "", - "buildpackID": "" } ], "buildpacks": [ { "id": "", "version": "", - "homepage": "", - "api": "" + "homepage": "" } ], "extensions": [ { "id": "", "version": "", - "homepage": "", - "api": "" + "homepage": "" } ], "launcher": { From 4704d14a6622b2b606fbf79d8a97d636024db2b8 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Thu, 13 Jul 2023 11:50:56 -0400 Subject: [PATCH 26/30] Really fix modification of platform.md in this branch Signed-off-by: Natalie Arellano --- README.md | 2 +- platform.md | 182 ++++++++++++++++++++++++++++++---------------------- 2 files changed, 106 insertions(+), 78 deletions(-) diff --git a/README.md b/README.md index 48d6060..df2f7ce 100644 --- a/README.md +++ b/README.md @@ -52,4 +52,4 @@ These documents currently specify: - Buildpack API: `0.9` - Distribution API: `0.3` -- Platform API: `0.10` +- Platform API: `0.11` diff --git a/platform.md b/platform.md index c725e50..f5de11d 100644 --- a/platform.md +++ b/platform.md @@ -93,7 +93,7 @@ Examples of a platform might include: ## Platform API Version -This document specifies Platform API version `0.10`. +This document specifies Platform API version `0.11`. Platform API versions: - MUST be in form `.` or ``, where `` is equivalent to `.0` @@ -128,7 +128,7 @@ A **launcher layer** refers to a layer in the app OCI image containing the **lau The **launcher** refers to a lifecycle executable packaged in the **app image** for the purpose of executing processes at runtime. -An **image extension** refers to software compliant with the [Image Extension Interface Specification](image-extension.md). Image extensions participate in detection and execute before the buildpack build process. +An **image extension** refers to software compliant with the [Image Extension Interface Specification](image_extension.md). Image extensions participate in detection and execute before the buildpack build process. #### Additional Terminology An **image reference** refers to either a **tag reference** or **digest reference**. @@ -379,19 +379,20 @@ Usage: ``` ##### Inputs -| Input | Environment Variable | Default Value | Description | -|----------------|----------------------|--------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | (**[experimental](#experimental-features)**) Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) | -| `` | `CNB_APP_DIR` | `/workspace` | Path to application directory | -| `` | `CNB_BUILDPACKS_DIR` | `/cnb/buildpacks` | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout)) | -| `` | `CNB_EXTENSIONS_DIR` | `/cnb/extensions` | (**[experimental](#experimental-features)**) Path to image extensions directory (see [Image Extensions Directory Layout](#image-extensions-directory-layout) | -| `` | `CNB_GENERATED_DIR` | `/generated` | (**[experimental](#experimental-features)**) Path to output directory for generated Dockerfiles | -| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to output group definition | -| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | -| `` | `CNB_LOG_LEVEL` | `info` | Log Level | -| `` | `CNB_ORDER_PATH` | `/order.toml` if present, or `/cnb/order.toml` | Path resolution for order definition (see [`order.toml`](#ordertoml-toml)) | -| `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to output resolved build plan | -| `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory | +| Input | Environment Variable | Default Value | Description | +|------------------|------------------------|--------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | (**[experimental](#experimental-features)**) Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) | +| `` | `CNB_APP_DIR` | `/workspace` | Path to application directory | +| `` | `CNB_BUILD_CONFIG_DIR` | `/cnb/build-config` | Path to build config directory | +| `` | `CNB_BUILDPACKS_DIR` | `/cnb/buildpacks` | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout)) | +| `` | `CNB_EXTENSIONS_DIR` | `/cnb/extensions` | (**[experimental](#experimental-features)**) Path to image extensions directory (see [Image Extensions Directory Layout](#image-extensions-directory-layout) | +| `` | `CNB_GENERATED_DIR` | `/generated` | (**[experimental](#experimental-features)**) Path to output directory for generated Dockerfiles | +| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to output group definition | +| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | +| `` | `CNB_LOG_LEVEL` | `info` | Log Level | +| `` | `CNB_ORDER_PATH` | `/order.toml` if present, or `/cnb/order.toml` | Path resolution for order definition (see [`order.toml`](#ordertoml-toml)) | +| `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to output resolved build plan | +| `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory | ##### Outputs @@ -448,19 +449,19 @@ Usage: ``` ##### Inputs -| Input | Environment Variable | Default Value | Description | -|-----------------|----------------------|--------------------------|-----------------------------------------------------------------------------| -| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) | -| `` | `CNB_BUILD_IMAGE` | | Reference to the current build image in an OCI registry (if used `` must be provided) | -| `` | `CNB_CACHE_DIR` | | Path to a cache directory | -| `` | `CNB_CACHE_IMAGE` | | Reference to a cache image in an OCI registry | -| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` | -| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to group definition (see [`group.toml`](#grouptoml-toml)) | -| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | -| `` | `CNB_LOG_LEVEL` | `info` | Log Level | -| `` | `CNB_USER_ID` | | UID of the build image `User` | -| `` | `CNB_SKIP_LAYERS` | `false` | Do not perform [layer restoration](#layer-restoration) | -|``| | | Kaniko directory (must be `/kaniko`) | +| Input | Environment Variable | Default Value | Description | +|-----------------|----------------------|--------------------------|---------------------------------------------------------------------------------------------------| +| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) | +| `` | `CNB_BUILD_IMAGE` | | Reference to the current build image in an OCI registry (if used `` must be provided) | +| `` | `CNB_CACHE_DIR` | | Path to a cache directory | +| `` | `CNB_CACHE_IMAGE` | | Reference to a cache image in an OCI registry | +| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` | +| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to group definition (see [`group.toml`](#grouptoml-toml)) | +| `` | | | Kaniko directory (must be `/kaniko`) | +| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | +| `` | `CNB_LOG_LEVEL` | `info` | Log Level | +| `` | `CNB_USER_ID` | | UID of the build image `User` | +| `` | `CNB_SKIP_LAYERS` | `false` | Do not perform [layer restoration](#layer-restoration) | ##### Outputs | Output | Description | @@ -472,16 +473,16 @@ Usage: | `//.toml` | Files containing the layer content metadata of each analyzed layer (see data format in [Buildpack Interface Specification](buildpack.md)) | | `//.sbom.` | Files containing the Software Bill of Materials for each analyzed layer (see [Buildpack Interface Specification](buildpack.md)) | | `///*`. | Restored layer contents | -| `/cache` | Kaniko cache contents | +| `/cache` | Kaniko cache contents | -| Exit Code | Result| -|-----------------|-------| -| `0` | Success -| `11` | Platform API incompatibility error -| `12` | Buildpack API incompatibility error -| `1-10`, `13-19` | Generic lifecycle errors -| `40-49` | Restoration-specific lifecycle errors +| Exit Code | Result | +|-----------------|---------------------------------------| +| `0` | Success | +| `11` | Platform API incompatibility error | +| `12` | Buildpack API incompatibility error | +| `1-10`, `13-19` | Generic lifecycle errors | +| `40-49` | Restoration-specific lifecycle errors | - For each buildpack in ``, if persistent metadata for that buildpack exists in the analysis metadata, lifecycle MUST write a toml representation of the persistent metadata to `//store.toml` - **If** `` is `true` the lifecycle MUST NOT perform layer restoration. @@ -516,11 +517,13 @@ Usage: |----------------------|------------------------|--------------------------|-------------------------------------------------------------------------------------------------| | `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | Path to analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) | | `` | `CNB_APP_DIR` | `/workspace` | Path to application directory | +| `` | `CNB_BUILD_CONFIG_DIR` | `/cnb/build-config` | Path to build config directory | | `` | `CNB_BUILDPACKS_DIR` | `/cnb/buildpacks` | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout)) | | `` | `CNB_GENERATED_DIR` | `/generated` | (**[experimental](#experimental-features)**) Path to directory containing generated Dockerfiles | | `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` | | `` | `CNB_GROUP_PATH` | `/group.toml` | Path to group definition (see [`group.toml`](#grouptoml-toml)) | | `` | `CNB_KANIKO_CACHE_TTL` | 2 weeks | Kaniko cache TTL | +| `` | | | Kaniko directory (must be `/kaniko`) | | `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | | `` | `CNB_LOG_LEVEL` | `info` | Log Level | | `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to resolved build plan (see [`plan.toml`](#plantoml-toml)) | @@ -531,11 +534,11 @@ Usage: In addition to the outputs enumerated below, outputs produced by `extender` include those produced by `builder` - as the lifecycle will run the `build` phase after extending the build image. When using the `extender` platforms MUST skip the `builder` and proceed to the `exporter`. -| Output | Description | -|-----------------|----------------------------------------| -| [exit status] | (see Exit Code table below for values) | -| `/dev/stdout` | Logs (info) | -| `/dev/stderr` | Logs (warnings, errors) | +| Output | Description | +|----------------------|----------------------------------------| +| [exit status] | (see Exit Code table below for values) | +| `/dev/stdout` | Logs (info) | +| `/dev/stderr` | Logs (warnings, errors) | | `/cache` | Kaniko cache contents | | Exit Code | Result | @@ -569,15 +572,16 @@ Usage: ``` ##### Inputs -| Input | Env | Default Value | Description -|----------------|-----------------------|-----------------------|---------------------- -| `` | `CNB_APP_DIR` | `/workspace` | Path to application directory -| `` | `CNB_BUILDPACKS_DIR` | `/cnb/buildpacks` | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout)) -| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to group definition (see [`group.toml`](#grouptoml-toml)) -| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory -| `` | `CNB_LOG_LEVEL` | `info` | Log Level -| `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to resolved build plan (see [`plan.toml`](#plantoml-toml)) -| `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory +| Input | Env | Default Value | Description | +|------------------|------------------------|-----------------------|------------------------------------------------------------------------------------------------| +| `` | `CNB_APP_DIR` | `/workspace` | Path to application directory | +| `` | `CNB_BUILD_CONFIG_DIR` | `/cnb/build-config` | Path to build config directory | +| `` | `CNB_BUILDPACKS_DIR` | `/cnb/buildpacks` | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout)) | +| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to group definition (see [`group.toml`](#grouptoml-toml)) | +| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | +| `` | `CNB_LOG_LEVEL` | `info` | Log Level | +| `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to resolved build plan (see [`plan.toml`](#plantoml-toml)) | +| `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory | ##### Outputs | Output | Description @@ -617,6 +621,7 @@ Usage: [-group ] \ [-launch-cache ] \ [-launcher ] \ + [-launcher-sbom ] \ [-layers ] \ [-log-level ] \ [-process-type ] \ @@ -628,27 +633,28 @@ Usage: ``` ##### Inputs -| Input | Environment Variable | Default Value | Description -|---------------------|----------------------------|---------------------|--------------------------------------- -| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | Path to analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) -| `` | `CNB_APP_DIR` | `/workspace` | Path to application directory -| `` | `CNB_CACHE_DIR` | | Path to a cache directory -| `` | `CNB_CACHE_IMAGE` | | Reference to a cache image in an OCI registry -| `` | `CNB_USE_DAEMON` | `false` | Export image to docker daemon -| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` -| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to group file (see [`group.toml`](#grouptoml-toml)) -| `` | | | Tag reference to which the app image will be written -| `` | `CNB_LAUNCH_CACHE_DIR` | | Path to a cache directory containing launch layers -| `` | | `/cnb/lifecycle/launcher` | Path to the `launcher` executable -| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layer directory -| `` | `CNB_LOG_LEVEL` | `info` | Log Level -| `` | `CNB_PROCESS_TYPE` | | Default process type to set in the exported image -| ``| `CNB_PROJECT_METADATA_PATH`| `/project-metadata.toml` | Path to a project metadata file (see [`project-metadata.toml`](#project-metadatatoml-toml) -| `` | `CNB_REPORT_PATH` | `/report.toml` | Path to report (see [`report.toml`](#reporttoml-toml) -| `` | `CNB_STACK_PATH` | `/cnb/stack.toml` | Path to stack file (see [`stack.toml`](#stacktoml-toml) -| `` | `CNB_USER_ID` | | UID of the build image `User` -| `/config/metadata.toml` | | | Build metadata (see [`metadata.toml`](#metadatatoml-toml) -| | `SOURCE_DATE_EPOCH` | | Timestamp for `created` time in app image config | +| Input | Environment Variable | Default Value | Description | +|---------------------------------|-----------------------------|----------------------------------|--------------------------------------------------------------------------------------------| +| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | Path to analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) | +| `` | `CNB_APP_DIR` | `/workspace` | Path to application directory | +| `` | `CNB_CACHE_DIR` | | Path to a cache directory | +| `` | `CNB_CACHE_IMAGE` | | Reference to a cache image in an OCI registry | +| `` | `CNB_USE_DAEMON` | `false` | Export image to docker daemon | +| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` | +| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to group file (see [`group.toml`](#grouptoml-toml)) | +| `` | | | Tag reference to which the app image will be written | +| `` | `CNB_LAUNCH_CACHE_DIR` | | Path to a cache directory containing launch layers | +| `` | | `/cnb/lifecycle/launcher` | Path to the `launcher` executable | +| `` | | `/cnb/lifecycle` | Path to directory containing SBOM files describing the `launcher` executable | +| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layer directory | +| `` | `CNB_LOG_LEVEL` | `info` | Log Level | +| `` | `CNB_PROCESS_TYPE` | | Default process type to set in the exported image | +| `` | `CNB_PROJECT_METADATA_PATH` | `/project-metadata.toml` | Path to a project metadata file (see [`project-metadata.toml`](#project-metadatatoml-toml) | +| `` | `CNB_REPORT_PATH` | `/report.toml` | Path to report (see [`report.toml`](#reporttoml-toml) | +| `` | `CNB_STACK_PATH` | `/cnb/stack.toml` | Path to stack file (see [`stack.toml`](#stacktoml-toml) | +| `` | `CNB_USER_ID` | | UID of the build image `User` | +| `/config/metadata.toml` | | | Build metadata (see [`metadata.toml`](#metadatatoml-toml) | +| | `SOURCE_DATE_EPOCH` | | Timestamp for `created` time in app image config | - At least one `` must be provided - Each `` MUST be a valid tag reference @@ -677,10 +683,11 @@ Usage: - All run-image layers SHALL be preserved - All run-image config values SHALL be preserved unless this conflicts with another requirement - MUST contain all buildpack-provided launch layers as determined by the [Buildpack Interface Specfication](buildpack.md) - - MUST contain a layer containing all buildpack-provided Software Bill of Materials (SBOM) files for `launch` as determined by the [Buildpack Interface Specfication](buildpack.md) if they are present + - MUST contain a layer containing all Software Bill of Materials (SBOM) files for `launch` as determined by the [Buildpack Interface Specfication](buildpack.md) if they are present - `/sbom/launch//sbom.` MUST contain the buildpack-provided `launch` SBOM - `/sbom/launch///sbom.` MUST contain the buildpack-provided layer SBOM if `` is a `launch` layer - - `/sbom/launch/sbom.legacy.json` MAY contain the legacy non-standard Bill of Materials for `launch` (where [supported](buildpack.md)) + - `/sbom/launch/sbom.legacy.json` MAY contain the legacy buildpack-provided non-standard Bill of Materials for `launch` (where [supported](buildpack.md)) + - `/sbom/launch/buildpacksio_lifecycle/launcher/sbom.` MUST contain the CNB-provided launcher SBOM if present in the `/cnb/lifecycle` directory - MUST contain one or more app layers as determined by the [Buildpack Interface Specfication](buildpack.md) - MUST contain one or more launcher layers that include: - A file with the contents of the `` file at path `/cnb/lifecycle/launcher` @@ -710,10 +717,11 @@ Usage: - The lifecycle SHALL write a [report](#reporttoml-toml) to `` describing the exported app image - The `` directory: - - MUST include all buildpack-provided Software Bill of Materials (SBOM) files for `build` as determined by the [Buildpack Interface Specfication](buildpack.md) if they are present + - MUST include all Software Bill of Materials (SBOM) files for `build` as determined by the [Buildpack Interface Specfication](buildpack.md) if they are present - `/sbom/build//sbom.` MUST contain the buildpack-provided `build` SBOM - `/sbom/build///sbom.` MUST contain the buildpack-provided layer SBOM if `` is not a `launch` layer. - - `/sbom/build/sbom.legacy.json` MAY contain the legacy non-standard Bill of Materials for `build` (where [supported](buildpack.md)) + - `/sbom/build/sbom.legacy.json` MAY contain the legacy buildpack-provided non-standard Bill of Materials for `build` (where [supported](buildpack.md)) + - `/sbom/build/buildpacksio_lifecycle/sbom.` MUST contain the CNB-provided lifecycle SBOM if present in the `/cnb/lifecycle` directory - *If* a cache is provided the lifecycle: - SHALL write the contents of all cached layers and any provided layer-associated SBOM files to the cache - SHALL record the diffID and layer content metadata of all cached layers in the cache @@ -782,6 +790,7 @@ Usage: [-daemon] \ # sets [-gid ] \ [-log-level ] \ + [-previous-image ] \ [-report ] \ [-run-image | -image ] \ # -image is Deprecated [-uid ] \ @@ -795,6 +804,7 @@ Usage: | `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` | `` | | | App image to rebase | `` | `CNB_LOG_LEVEL` | `info` | Log Level +| `` | | derived from `` | Previous image reference | `` | `CNB_REPORT_PATH` | `/report.toml` | Path to report (see [`report.toml`](#reporttoml-toml) | `` | `CNB_RUN_IMAGE` | derived from `` | Run image reference | `` | `CNB_USER_ID` | | UID of the build image `User` @@ -802,6 +812,8 @@ Usage: - At least one `` must be provided - Each `` MUST be a valid tag reference - **If** `` is `false` and more than one `` is provided they MUST refer to the same registry +- **If** `` is provided by the platform, the value will be used as the app image to rebase. `` must NOT be modified unless specified again in ``. +- **Else** `` value will derived from the first ``. - **If** `` is not provided by the platform the value will be [resolved](#run-image-resolution) from the contents of the `stack` key in the `io.buildpacks.lifecycle.metdata` label on ``. ##### Outputs @@ -1017,6 +1029,19 @@ User-provided environment variables MAY be modified by prior buildpacks before t The platform SHOULD NOT set user-provided environment variables directly in the lifecycle execution environment. +The `/env/` directory follows the same convention as [Environment Variable Modification Rules](https://github.com/buildpacks/spec/blob/main/buildpack.md#environment-variable-modification-rules). + +##### Operator-Defined Variables +Operator-provided environment varaiables MUST be supplied by the platform as files in the `/env/` directory. + +Each file SHALL define a single environment variable, where the file name defines the key and the file contents define the value. + +Operator-defined environment variables MAY be modified by subsequent buildpacks before they are provided to a given buildpack. + +The platform SHOULD NOT set operator-provided environment variables directly in the lifecycle execution environment. + +The `/env/` directory follows the [Environment Variable Modification Rules](https://github.com/buildpacks/spec/blob/main/buildpack.md#environment-variable-modification-rules) outlined in the [Buildpack Interface Specification](buildpack.md), except for the modification behavior when no period-delimited suffix is provided; when no suffix is provided, the behavior is `default`. + #### Launch Environment User-provided modifications to the process execution environment SHOULD be set directly in the lifecycle execution environment. @@ -1234,20 +1259,23 @@ Where: ], "direct": false, "working-dir": "", + "buildpackID": "" } ], "buildpacks": [ { "id": "", "version": "", - "homepage": "" + "homepage": "", + "api": "" } ], "extensions": [ { "id": "", "version": "", - "homepage": "" + "homepage": "", + "api": "" } ], "launcher": { From c0e281280b0a78e70033e5f4dd67d00164b0f921 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Thu, 13 Jul 2023 11:56:25 -0400 Subject: [PATCH 27/30] Specify the correct Buildpack API version Signed-off-by: Natalie Arellano --- README.md | 2 +- buildpack.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index df2f7ce..01446eb 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,6 @@ When the specification refers to a path in the context of an OCI layer tar (e.g. These documents currently specify: -- Buildpack API: `0.9` +- Buildpack API: `0.10` - Distribution API: `0.3` - Platform API: `0.11` diff --git a/buildpack.md b/buildpack.md index c253bfb..4333a1a 100644 --- a/buildpack.md +++ b/buildpack.md @@ -82,7 +82,7 @@ This document specifies the interface between a lifecycle program and one or mor - [Build Plan (TOML) `requires.version` Key](#build-plan-toml-requiresversion-key) ## Buildpack API Version -This document specifies Buildpack API version `0.9` +This document specifies Buildpack API version `0.10` Buildpack API versions: - MUST be in form `.` or ``, where `` is equivalent to `.0` From 053e59acf4e8887d089dbcf73d2005bdf167be5d Mon Sep 17 00:00:00 2001 From: Ozzy Osborne Date: Mon, 17 Jul 2023 15:23:28 -0400 Subject: [PATCH 28/30] allow metadata for extension.toml Signed-off-by: Ozzy Osborne --- image_extension.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/image_extension.md b/image_extension.md index 8b69a36..48bd94d 100644 --- a/image_extension.md +++ b/image_extension.md @@ -155,6 +155,9 @@ keywords = [ "" ] [[extension.licenses]] type = "" uri = "" + +[metadata] +# extension-specific data ``` Image extension authors MUST choose a globally unique ID, for example: "io.buildpacks.apt". From 92146ab4f91bbcfd2c92c9130b891bfb66530fcb Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 28 Jul 2023 10:03:59 -0400 Subject: [PATCH 29/30] Clarify target requirements and matching logic Signed-off-by: Natalie Arellano --- buildpack.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/buildpack.md b/buildpack.md index 4333a1a..f392b3a 100644 --- a/buildpack.md +++ b/buildpack.md @@ -756,7 +756,7 @@ The following environment variables MUST be set by the lifecycle during the `det | `CNB_TARGET_ID` | Identifier for the target image (optional) | | `CNB_TARGET_OS` | Target OS | | `CNB_TARGET_ARCH` | Target architecture | -| `CNB_TARGET_ARCH_VARIANT` | Target architecture variant (optional) | +| `CNB_TARGET_ARCH_VARIANT` | Target architecture variant (optional) | | `CNB_TARGET_DISTRO_NAME` | Target OS distribution name (optional) | | `CNB_TARGET_DISTRO_VERISON` | Target OS distribution version (optional) | @@ -1107,21 +1107,18 @@ A buildpack descriptor SHOULD specify `targets`. Each target in `targets`: - MUST identify a compatible runtime environment: - - `os` and `arch` are required and MUST be valid identifiers as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md) - - `variant` is optional and MUST be a valid identifier as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md) - - `distributions` are optional and MUST describe the OS distributions supported by the buildpack + - `os`, `arch`, and `variant` if provided MUST be valid identifiers as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md) + - `distributions` if provided MUST describe the OS distributions supported by the buildpack - For Linux-based images, `distributions.name` and `distributions.versions` SHOULD contain the values specified in `/etc/os-release` (`$ID` and `$VERSION_ID`), as the `os.version` field in an image config may contain combined distribution and version information - For Windows-based images, `distributions.name` SHOULD be empty; `distributions.versions` SHOULD contain the value of `os.version` in the image config (e.g., `10.0.14393.1066`) + - Any field not provided will be interpreted as `` If the `targets` list is empty, tools reading `buildpack.toml` will assume: - `os = "linux"` and `arch = ` if `./bin/build` is present - `os = "windows"` and `arch = ` if `./bin/build.bat` or `./bin/build.exe` are present - - `os = ` and `arch = ` for extensions Metadata specified in `[[targets]]` is validated against the runtime and build-time base images. -* A buildpack target satisfies a base image target when: - * `os` and `arch` match, and - * Optional fields either match exactly, or are left blank by at least one target (blank values match any other value) +* A buildpack target satisfies a base image target when `os`, `arch`, and `variant` match and at least one distribution in `distributions` (if provided) matches #### Order From a1512afa2094c09165b212f002e964ced4452bf9 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 28 Jul 2023 10:09:53 -0400 Subject: [PATCH 30/30] Rename distributions -> distros to match platform spec Signed-off-by: Natalie Arellano --- buildpack.md | 12 ++++++------ image_extension.md | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/buildpack.md b/buildpack.md index f392b3a..cd92a35 100644 --- a/buildpack.md +++ b/buildpack.md @@ -1060,7 +1060,7 @@ optional = false os = "" arch = "" variant = "" -[[targets.distributions]] +[[targets.distros]] name = "" version = "" @@ -1108,9 +1108,9 @@ A buildpack descriptor SHOULD specify `targets`. Each target in `targets`: - MUST identify a compatible runtime environment: - `os`, `arch`, and `variant` if provided MUST be valid identifiers as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md) - - `distributions` if provided MUST describe the OS distributions supported by the buildpack - - For Linux-based images, `distributions.name` and `distributions.versions` SHOULD contain the values specified in `/etc/os-release` (`$ID` and `$VERSION_ID`), as the `os.version` field in an image config may contain combined distribution and version information - - For Windows-based images, `distributions.name` SHOULD be empty; `distributions.versions` SHOULD contain the value of `os.version` in the image config (e.g., `10.0.14393.1066`) + - `distros` if provided MUST describe the OS distributions supported by the buildpack + - For Linux-based images, `distros.name` and `distros.versions` SHOULD contain the values specified in `/etc/os-release` (`$ID` and `$VERSION_ID`), as the `os.version` field in an image config may contain combined distribution and version information + - For Windows-based images, `distros.name` SHOULD be empty; `distros.versions` SHOULD contain the value of `os.version` in the image config (e.g., `10.0.14393.1066`) - Any field not provided will be interpreted as `` If the `targets` list is empty, tools reading `buildpack.toml` will assume: @@ -1118,7 +1118,7 @@ If the `targets` list is empty, tools reading `buildpack.toml` will assume: - `os = "windows"` and `arch = ` if `./bin/build.bat` or `./bin/build.exe` are present Metadata specified in `[[targets]]` is validated against the runtime and build-time base images. -* A buildpack target satisfies a base image target when `os`, `arch`, and `variant` match and at least one distribution in `distributions` (if provided) matches +* A buildpack target satisfies a base image target when `os`, `arch`, and `variant` match and at least one distribution in `distros` (if provided) matches #### Order @@ -1169,7 +1169,7 @@ Tools reading `buildpack.toml` will translate any section that sets `stacks.id = [[targets]] os = "linux" arch = "amd64" -[[targets.distributions]] +[[targets.distros]] name = "ubuntu" version = "18.04" ``` diff --git a/image_extension.md b/image_extension.md index 3dd13f0..7784075 100644 --- a/image_extension.md +++ b/image_extension.md @@ -171,7 +171,7 @@ uri = "" os = "" arch = "" variant = "" -[[targets.distributions]] +[[targets.distros]] name = "" version = "" ```