From d38828abcddcb8f5d967bbe0de52012f878b6ea0 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Thu, 1 Dec 2022 09:58:28 -0500 Subject: [PATCH 01/67] Removed stack and mixin from terminology, updated stack section Signed-off-by: Natalie Arellano --- platform.md | 102 ++++++++++++++++++---------------------------------- 1 file changed, 35 insertions(+), 67 deletions(-) diff --git a/platform.md b/platform.md index 223a6e9..91f2d55 100644 --- a/platform.md +++ b/platform.md @@ -104,16 +104,10 @@ Platform API versions: #### CNB Terminology A **buildpack** refers to software compliant with the [Buildpack Interface Specification](buildpack.md). -A **stack** is a contract, implemented by a **build image** and **run image**, that guarantees properties of the **build environment** and **app image**. - -A **stack ID** uniquely identifies a particular **stack**. - A **build image** is an OCI image that provides the base of the **build environment**. A **run image** is an OCI image that provides the base from which **app images** are built. -A **mixin** is a named set of additions to a stack that can be used to make additive changes to the contract. - The **build environment** refers to the containerized environment in which the lifecycle executes buildpacks. An **app image** refers to an OCI image generated by the lifecycle by extending the **run image** with any or all of the following: **app layers**, **launch layers**, **launcher layers**, image configuration. @@ -146,94 +140,68 @@ The following is a non-exhaustive list of terms defined in the [OCI Distribution * **registry** - https://github.com/opencontainers/distribution-spec/blob/main/spec.md#definitions -## Stacks +### Build Image -A typical stack might specify: +A typical build image might specify: * The OS distro in the build environment. * OS packages installed in the build environment. * Trusted CA certificates in the build environment. -* The OS distro or distroless OS in the launch environment. -* OS packages installed in the launch environment. -* Trusted CA certificates in the launch environment. -* The default user and the build and launch environments. - -Stack authors SHOULD define the contract such that any stack images CVEs can be addressed with security patches without violating the [compatibility guarantees](#compatibility-guarantees). - -### Stack ID - -Stack authors MUST choose a globally unique ID, for example: "io.buildpacks.mystack". - -The stack ID: -- MUST NOT be identical to any other stack ID when using a case-insensitive comparison. -- MUST only contain numbers, letters, and the characters `.`, `/`, and `-`. -- SHOULD use reverse domain name notation to avoid name collisions. - -### Build Image +* The default user in the build environment. The platform MUST ensure that: - The image config's `User` field is set to a non-root user with a writable home directory. -- The image config's `Env` field has the environment variable `CNB_STACK_ID` set to the stack ID. - The image config's `Env` field has the environment variable `CNB_USER_ID` set to the user [†](README.md#operating-system-conventions)UID/[‡](README.md#operating-system-conventions)SID of the user specified in the `User` field. - The image config's `Env` field has the environment variable `CNB_GROUP_ID` set to the primary group [†](README.md#operating-system-conventions)GID/[‡](README.md#operating-system-conventions)SID of the user specified in the `User` field. - The image config's `Env` field has the environment variable `PATH` set to a valid set of paths or explicitly set to empty (`PATH=`). -- The image config's `Label` field has the label `io.buildpacks.stack.id` set to the stack ID. -- The image config's `Label` field has the label `io.buildpacks.stack.mixins` set to a JSON array containing mixin names for each mixin applied to the image. +- The image config's `os` and `architecture` fields are set to valid identifiers as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md). The platform SHOULD ensure that: -- The image config's `Label` field has the label `io.buildpacks.stack.maintainer` set to the name of the stack maintainer. -- The image config's `Label` field has the label `io.buildpacks.stack.homepage` set to the homepage of the stack. -- The image config's `Label` field has the label `io.buildpacks.stack.distro.name` set to the name of the stack's OS distro. -- The image config's `Label` field has the label `io.buildpacks.stack.distro.version` set to the version of the stack's OS distro. -- The image config's `Label` field has the label `io.buildpacks.stack.released` set to the release date of the stack. -- The image config's `Label` field has the label `io.buildpacks.stack.description` set to the description of the stack. -- The image config's `Label` field has the label `io.buildpacks.stack.metadata` set to additional metadata related to the stack. +- The image config's `variant` field is set to a valid identifier as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md). +- The image config's `Label` field has the label `io.buildpacks.distribution.name` set to the OS distribution and the label `io.buildpacks.distribution.version` set to the 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, and `version` should be the value of `os.version` in the image config (e.g., `10.0.14393.1066`). +- The image config's `Label` field has the label `io.buildpacks.base.maintainer` set to the name of the image maintainer. +- The image config's `Label` field has the label `io.buildpacks.base.homepage` set to the homepage of the image. +- The image config's `Label` field has the label `io.buildpacks.base.released` set to the release date of the image. +- The image config's `Label` field has the label `io.buildpacks.base.description` set to the description of the image. +- The image config's `Label` field has the label `io.buildpacks.base.metadata` set to additional metadata related to the image. ### Run Image +A typical run image might specify: +* The OS distro or distroless OS in the launch environment. +* OS packages installed in the launch environment. +* Trusted CA certificates in the launch environment. +* The default user in the run environment. + +Run image authors SHOULD define the contract such that any CVEs can be addressed with security patches without violating the [compatibility guarantees](#compatibility-guarantees). + The platform MUST ensure that: -- The image config's `Label` field has the label `io.buildpacks.stack.id` set to the stack ID. -- The image config's `Label` field has the label `io.buildpacks.stack.mixins` set to a JSON array containing mixin names for each mixin applied to the image. - The image config's `Env` field has the environment variable `PATH` set to a valid set of paths or explicitly set to empty (`PATH=`). +- The image config's `os` and `architecture` fields are set to valid identifiers as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md). The platform SHOULD ensure that: - The image config's `User` field is set to a user with a **DIFFERENT** user [†](README.md#operating-system-conventions)UID/[‡](README.md#operating-system-conventions)SID as the build image. -- The image config's `Label` field has the label `io.buildpacks.stack.maintainer` set to the name of the stack maintainer. -- The image config's `Label` field has the label `io.buildpacks.stack.homepage` set to the homepage of the stack. -- The image config's `Label` field has the label `io.buildpacks.stack.distro.name` set to the name of the stack's OS distro. -- The image config's `Label` field has the label `io.buildpacks.stack.distro.version` set to the version of the stack's OS distro. -- The image config's `Label` field has the label `io.buildpacks.stack.released` set to the release date of the stack. -- The image config's `Label` field has the label `io.buildpacks.stack.description` set to the description of the stack. -- The image config's `Label` field has the label `io.buildpacks.stack.metadata` set to additional metadata related to the stack. - -### Mixins - -A mixin name MUST only be defined by the author of its corresponding stack. -A mixin name MUST always be used to specify the same set of changes. -A mixin name MUST only contain a `:` character as part of an optional stage specifier. - -A mixin prefixed with the `build:` stage specifier only affects the build image and does not need to be specified on the run image. -A mixin prefixed with the `run:` stage specifier only affects the run image and does not need to be specified on the build image. -A mixin WITHOUT a `build:` or `run:` prefix affects both the build and the run images. - -A platform MAY support any number of mixins for a given stack in order to support application code or buildpacks that require those mixins. - -Changes introduced by mixins SHOULD be restricted to the addition of operating system software packages that are regularly patched with strictly backwards-compatible security fixes. -However, mixins MAY consist of any changes that follow the [Compatibility Guarantees](#compatibility-guarantees). +- The image config's `Label` field has the label `io.buildpacks.id` set to the target ID (e.g., "minimal") of the image. +- The image config's `variant` field is set to a valid identifier as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md). +- The image config's `Label` field has the label `io.buildpacks.distribution.name` set to the OS distribution and the label `io.buildpacks.distribution.version` set to the 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`). +- The image config's `Label` field has the label `io.buildpacks.base.maintainer` set to the name of the image maintainer. +- The image config's `Label` field has the label `io.buildpacks.base.homepage` set to the homepage of the image. +- The image config's `Label` field has the label `io.buildpacks.base.released` set to the release date of the image. +- The image config's `Label` field has the label `io.buildpacks.base.description` set to the description of the image. +- The image config's `Label` field has the label `io.buildpacks.base.metadata` set to additional metadata related to the image. ### Compatibility Guarantees -Stack image authors SHOULD ensure that build image versions maintain [ABI-compatibility](https://en.wikipedia.org/wiki/Application_binary_interface) with previous versions, although violating this requirement will not change the behavior of previously built images containing app and launch layers. - -Stack image authors MUST ensure that new run image versions maintain [ABI-compatibility](https://en.wikipedia.org/wiki/Application_binary_interface) with previous versions. -Stack image authors MUST ensure that app and launch layers do not change behavior when the run image layers are upgraded to newer versions, unless those behavior changes are intended to fix security vulnerabilities. - -Mixin authors MUST ensure that mixins do not affect the [ABI-compatibility](https://en.wikipedia.org/wiki/Application_binary_interface) of any object code compiled to run on the base stack images without mixins. - -During build, platforms MUST use the same set of mixins for the run image as were used in the build image (excluding mixins that have a stage specifier). +- Base image authors SHOULD ensure that build image versions maintain [ABI-compatibility](https://en.wikipedia.org/wiki/Application_binary_interface) with previous versions, although violating this requirement will not change the behavior of previously built images containing app and launch layers. +- Base image authors MUST ensure that new run image versions maintain [ABI-compatibility](https://en.wikipedia.org/wiki/Application_binary_interface) with previous versions. +- Base image authors MUST ensure that app and launch layers do not change behavior when the run image layers are upgraded to newer versions, unless those behavior changes are intended to fix security vulnerabilities. ## Lifecycle Interface From a2d3554db403c36249ae3b9ac216b7be85629178 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 5 Dec 2022 16:09:42 -0500 Subject: [PATCH 02/67] Update analyzer Signed-off-by: Natalie Arellano --- platform.md | 100 ++++++++++++++++++++++++++++++++-------------------- 1 file changed, 61 insertions(+), 39 deletions(-) diff --git a/platform.md b/platform.md index 91f2d55..27391ac 100644 --- a/platform.md +++ b/platform.md @@ -154,14 +154,9 @@ The platform MUST ensure that: - The image config's `Env` field has the environment variable `CNB_USER_ID` set to the user [†](README.md#operating-system-conventions)UID/[‡](README.md#operating-system-conventions)SID of the user specified in the `User` field. - The image config's `Env` field has the environment variable `CNB_GROUP_ID` set to the primary group [†](README.md#operating-system-conventions)GID/[‡](README.md#operating-system-conventions)SID of the user specified in the `User` field. - The image config's `Env` field has the environment variable `PATH` set to a valid set of paths or explicitly set to empty (`PATH=`). -- The image config's `os` and `architecture` fields are set to valid identifiers as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md). The platform SHOULD ensure that: -- The image config's `variant` field is set to a valid identifier as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md). -- The image config's `Label` field has the label `io.buildpacks.distribution.name` set to the OS distribution and the label `io.buildpacks.distribution.version` set to the 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, and `version` should be the value of `os.version` in the image config (e.g., `10.0.14393.1066`). - The image config's `Label` field has the label `io.buildpacks.base.maintainer` set to the name of the image maintainer. - The image config's `Label` field has the label `io.buildpacks.base.homepage` set to the homepage of the image. - The image config's `Label` field has the label `io.buildpacks.base.released` set to the release date of the image. @@ -181,22 +176,31 @@ Run image authors SHOULD define the contract such that any CVEs can be addressed The platform MUST ensure that: - The image config's `Env` field has the environment variable `PATH` set to a valid set of paths or explicitly set to empty (`PATH=`). -- The image config's `os` and `architecture` fields are set to valid identifiers as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md). The platform SHOULD ensure that: - The image config's `User` field is set to a user with a **DIFFERENT** user [†](README.md#operating-system-conventions)UID/[‡](README.md#operating-system-conventions)SID as the build image. - The image config's `Label` field has the label `io.buildpacks.id` set to the target ID (e.g., "minimal") of the image. -- The image config's `variant` field is set to a valid identifier as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md). -- The image config's `Label` field has the label `io.buildpacks.distribution.name` set to the OS distribution and the label `io.buildpacks.distribution.version` set to the 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`). - The image config's `Label` field has the label `io.buildpacks.base.maintainer` set to the name of the image maintainer. - The image config's `Label` field has the label `io.buildpacks.base.homepage` set to the homepage of the image. - The image config's `Label` field has the label `io.buildpacks.base.released` set to the release date of the image. - The image config's `Label` field has the label `io.buildpacks.base.description` set to the description of the image. - The image config's `Label` field has the label `io.buildpacks.base.metadata` set to additional metadata related to the image. +#### Platform Data + +For both build images and run images, the platform MUST ensure that: + +- The image config's `os` and `architecture` fields are set to valid identifiers as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md). +- The build image config and the run image config both specify the same `os`, `architecture`, `variant` (if specified), `io.buildpacks.distribution.name` (if specified), and `io.buildpacks.distribution.version` (if specified). + +The platform SHOULD ensure that: + +- The image config's `variant` field is set to a valid identifier as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md). +- The image config's `Label` field has the label `io.buildpacks.distribution.name` set to the OS distribution and the label `io.buildpacks.distribution.version` set to the 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`). + ### Compatibility Guarantees - Base image authors SHOULD ensure that build image versions maintain [ABI-compatibility](https://en.wikipedia.org/wiki/Application_binary_interface) with previous versions, although violating this requirement will not change the behavior of previously built images containing app and launch layers. @@ -237,7 +241,7 @@ or by executing `/cnb/lifecycle/creator`. > The meaning of any particular instance of the word **build** must be assessed in context #### Rebase -When an updated run image with the same stack ID is available, an updated app image SHOULD be generated from the existing app image config by replacing the run image layers in the existing app image with the layers from the new run image. +When an updated run image is available, an updated app image SHOULD be generated from the existing app image config by replacing the run image layers in the existing app image with the layers from the new run image. This is referred to as rebasing the app, launch, and launcher layers onto the new run image layers. When layers are rebased, any app image metadata referencing to the original run image MUST be updated to reference to the new run image. This entire operation is referred to as rebasing the app image. @@ -426,7 +430,7 @@ Usage: | `` | `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`) | +| `` | | | Kaniko directory (must be `/kaniko`) | ##### Outputs | Output | Description | @@ -745,6 +749,7 @@ Usage: ``` /cnb/lifecycle/rebaser \ [-daemon] \ # sets + [-force] \ [-gid ] \ [-log-level ] \ [-report ] \ @@ -754,20 +759,27 @@ Usage: ``` ##### Inputs -| Input | Environment Variable | Default Value | Description -|---------------------|-----------------------|------------------------|--------------------------------------- -| `` | `CNB_USE_DAEMON` | `false` | Export image to docker daemon -| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` -| `` | | | App image to rebase -| `` | `CNB_LOG_LEVEL` | `info` | Log Level -| `` | `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` +| Input | Environment Variable | Default Value | Description | +|---------------|----------------------|------------------------|----------------------------------------------------------| +| `` | `CNB_USE_DAEMON` | `false` | Export image to docker daemon | +| `` | `CNB_FORCE_REBASE` | `false` | Allow mismatched metadata between new and old run images | +| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` | +| `` | | | App image to rebase | +| `` | `CNB_LOG_LEVEL` | `info` | Log Level | +| `` | `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` | - 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 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 ``. +- **If** `` is `false` and more than one `` is provided, the images MUST refer to the same registry +- **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 `` +- **If** `` is true the following values in the output `` config MUST be derived from the new ``, or else they MUST match the old run image if `` is false: + - `os` + - `architecture` + - `variant` (if specified) + - `io.buildpacks.distribution.name` (if specified) + - `io.buildpacks.distribution.version` (if specified) ##### Outputs | Output | Description @@ -955,22 +967,24 @@ A more thorough explanation is provided in the [Buildpack Interface Specificatio ### Environment #### Buildpack Environment -##### Stack-Provided Variables -The following variables SHOULD be set in the lifecycle execution environment and SHALL be directly inherited by the buildpack without modification: -| Env Variable | Description -|-----------------|-------------------------------------- -| `CNB_STACK_ID` | Chosen stack ID -| `HOME` | Current user's home directory +##### Base Image-Provided Variables + +The following variables SHOULD be set in the lifecycle execution environment and SHALL be directly inherited by the +buildpack without modification: + +| Env Variable | Description | +|-----------------------------|--------------------------------| +| `HOME` | Current user's home directory | The following variables SHOULD be set in the lifecycle execution environment and MAY be modified by prior buildpacks before they are provided to a given buildpack: -| Env Variable | Layer Path | Contents -|-------------------|--------------|------------------ -| `PATH` | `/bin` | binaries -| `LD_LIBRARY_PATH` | `/lib` | shared libraries -| `LIBRARY_PATH` | `/lib` | static libraries -| `CPATH` | `/include` | header files -| `PKG_CONFIG_PATH` | `/pkgconfig` | pc files +| Env Variable | Layer Path | Contents | +|-------------------|--------------|------------------| +| `PATH` | `/bin` | binaries | +| `LD_LIBRARY_PATH` | `/lib` | shared libraries | +| `LIBRARY_PATH` | `/lib` | static libraries | +| `CPATH` | `/include` | header files | +| `PKG_CONFIG_PATH` | `/pkgconfig` | pc files | The platform SHOULD NOT assume any other stack-provided environment variables are inherited by the buildpack. @@ -985,7 +999,7 @@ The platform SHOULD NOT set user-provided environment variables directly in the #### Launch Environment User-provided modifications to the process execution environment SHOULD be set directly in the lifecycle execution environment. -The process SHALL inherit both stack-provided and user-provided variables from the lifecycle execution environment with the following exceptions: +The process SHALL inherit both base-image-provided and user-provided variables from the lifecycle execution environment with the following exceptions: * `CNB_APP_DIR`, `CNB_LAYERS_DIR` and `CNB_PROCESS_TYPE` SHALL NOT be set in the process execution environment. * `/cnb/process` SHALL be removed from the beginning of `PATH`. * The lifecycle SHALL apply buildpack-provided modifications to the environment as outlined in the [Buildpack Interface Specification](buildpack.md). @@ -1030,15 +1044,23 @@ For more information on build reproducibility see [https://reproducible-builds.o [run-image] reference = "" + target-id = "" + [platform] + os = "" + arch = "" + variant = "" + distro-name = "" [build-image] reference = "" ``` Where: -- `previous-image.reference` MUST be either a digest reference to an image in an OCI registry or the ID of an image in a docker daemon +- `image.reference` MUST be either a digest reference to an image in an OCI registry or the ID of an image in a docker daemon +- `image.metadata` MUST be the TOML representation of the layer [metadata label](#iobuildpackslifecyclemetadata-json) - `run-image.reference` MUST be either a digest reference to an image in an OCI registry or the ID of an image in a docker daemon -- `previous-image.metadata` MUST be the TOML representation of the layer [metadata label](#iobuildpackslifecyclemetadata-json) +- `run-image.target-id` is optional and MUST be the value of the label `io.buildpacks.id` +- `run-image.platform` contains the [platform data](#TODO) for the image #### `group.toml` (TOML) From 4531d8cf44f1e69ade030124a516367773963037 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 5 Dec 2022 16:11:56 -0500 Subject: [PATCH 03/67] Format TOC, fix TODO Signed-off-by: Natalie Arellano --- platform.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/platform.md b/platform.md index 27391ac..29e0629 100644 --- a/platform.md +++ b/platform.md @@ -19,11 +19,9 @@ Examples of a platform might include: - [Terminology](#terminology) - [CNB Terminology](#cnb-terminology) - [Additional Terminology](#additional-terminology) - - [Stacks](#stacks) - - [Stack ID](#stack-id) - [Build Image](#build-image) - [Run Image](#run-image) - - [Mixins](#mixins) + - [Platform Data](#platform-data) - [Compatibility Guarantees](#compatibility-guarantees) - [Lifecycle Interface](#lifecycle-interface) - [Platform API Compatibility](#platform-api-compatibility) @@ -59,6 +57,7 @@ Examples of a platform might include: - [Outputs](#outputs-7) - [`launcher`](#launcher) - [Inputs](#inputs-8) + - [Execution](#execution) - [Outputs](#outputs-8) - [Run Image Resolution](#run-image-resolution) - [Registry Authentication](#registry-authentication) @@ -71,7 +70,7 @@ Examples of a platform might include: - [Additional Guidance](#additional-guidance) - [Environment](#environment) - [Buildpack Environment](#buildpack-environment) - - [Stack-Provided Variables](#stack-provided-variables) + - [Base Image-Provided Variables](#base-image-provided-variables) - [User-Provided Variables](#user-provided-variables) - [Launch Environment](#launch-environment) - [Caching](#caching) @@ -1060,7 +1059,7 @@ Where: - `image.metadata` MUST be the TOML representation of the layer [metadata label](#iobuildpackslifecyclemetadata-json) - `run-image.reference` MUST be either a digest reference to an image in an OCI registry or the ID of an image in a docker daemon - `run-image.target-id` is optional and MUST be the value of the label `io.buildpacks.id` -- `run-image.platform` contains the [platform data](#TODO) for the image +- `run-image.platform` contains the [platform data](#platform-data) for the image #### `group.toml` (TOML) From 58904f26920277e2fa19b01fd513670afcfca519 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 5 Dec 2022 16:18:38 -0500 Subject: [PATCH 04/67] Add derive missing values for known stack ID Signed-off-by: Natalie Arellano --- platform.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/platform.md b/platform.md index 29e0629..73996c7 100644 --- a/platform.md +++ b/platform.md @@ -1046,9 +1046,10 @@ For more information on build reproducibility see [https://reproducible-builds.o target-id = "" [platform] os = "" - arch = "" + architecture = "" variant = "" distro-name = "" + distro-version = "" [build-image] reference = "" @@ -1060,6 +1061,11 @@ Where: - `run-image.reference` MUST be either a digest reference to an image in an OCI registry or the ID of an image in a docker daemon - `run-image.target-id` is optional and MUST be the value of the label `io.buildpacks.id` - `run-image.platform` contains the [platform data](#platform-data) for the image + - If platform data is missing but the image contains the label `io.buildpacks.stack.id` with value `io.buildpacks.stacks.bionic`, the lifecycle SHALL assume the following values: + - `run-image.platform.os = "linux"` + - `run-image.platform.architecture = "x86_64"` + - `run-image.platform.distro-name = "ubuntu"` + - `run-image.platform.distro-version = "18.04"` #### `group.toml` (TOML) From 3140c7db6d2a39c1c7924b727f53fd3216db0ad2 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 5 Dec 2022 16:21:11 -0500 Subject: [PATCH 05/67] Add guidance around SBOM and rebase Signed-off-by: Natalie Arellano --- platform.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/platform.md b/platform.md index 73996c7..f492aa6 100644 --- a/platform.md +++ b/platform.md @@ -249,6 +249,10 @@ Rebasing allows for fast runtime OS-level dependency updates for app images with To rebase an app image a platform MUST execute the `/cnb/lifecycle/rebaser` or perform an equivalent operation. +If an SBOM is available, platforms MAY: +- Warn when a rebase operation would add OS packages. +- Fail if a rebase operation would remove OS packages. + #### Launch `/cnb/lifecycle/launcher` is responsible for launching user and buildpack provided processes in the correct execution environment. `/cnb/lifecycle/launcher`, or a symlink to it (see [exporter outputs](#outputs-4)), SHALL be the `ENTRYPOINT` for all app images. From f31e623e17e55278704ca0275440256072391dcf Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 5 Dec 2022 16:32:53 -0500 Subject: [PATCH 06/67] Fix nesting Signed-off-by: Natalie Arellano --- platform.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/platform.md b/platform.md index f492aa6..45606bc 100644 --- a/platform.md +++ b/platform.md @@ -21,7 +21,7 @@ Examples of a platform might include: - [Additional Terminology](#additional-terminology) - [Build Image](#build-image) - [Run Image](#run-image) - - [Platform Data](#platform-data) + - [Platform Data](#platform-data) - [Compatibility Guarantees](#compatibility-guarantees) - [Lifecycle Interface](#lifecycle-interface) - [Platform API Compatibility](#platform-api-compatibility) @@ -186,7 +186,7 @@ The platform SHOULD ensure that: - The image config's `Label` field has the label `io.buildpacks.base.description` set to the description of the image. - The image config's `Label` field has the label `io.buildpacks.base.metadata` set to additional metadata related to the image. -#### Platform Data +### Platform Data For both build images and run images, the platform MUST ensure that: From c58ae52a92272a73dd81079d43495b2ca32491c2 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 5 Dec 2022 16:35:55 -0500 Subject: [PATCH 07/67] Remove language about a "contract" Signed-off-by: Natalie Arellano --- platform.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/platform.md b/platform.md index 45606bc..fe8058b 100644 --- a/platform.md +++ b/platform.md @@ -170,8 +170,6 @@ A typical run image might specify: * Trusted CA certificates in the launch environment. * The default user in the run environment. -Run image authors SHOULD define the contract such that any CVEs can be addressed with security patches without violating the [compatibility guarantees](#compatibility-guarantees). - The platform MUST ensure that: - The image config's `Env` field has the environment variable `PATH` set to a valid set of paths or explicitly set to empty (`PATH=`). From cac2d6e009d5719dba2ca25ca6bbfb4cf1cbfbdb Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 5 Dec 2022 16:55:23 -0500 Subject: [PATCH 08/67] Describe how analyzed is used by the detector Signed-off-by: Natalie Arellano --- platform.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/platform.md b/platform.md index fe8058b..c4a6d2b 100644 --- a/platform.md +++ b/platform.md @@ -337,8 +337,8 @@ The platform MUST execute `detector` in the **build environment** Usage: ``` /cnb/lifecycle/detector \ - [-app ] \ [-analyzed ] \ + [-app ] \ [-buildpacks ] \ [-extensions ] \ [-generated ] \ @@ -353,7 +353,7 @@ 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_ANALYZED_PATH` | `/analyzed.toml` | 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) | @@ -393,6 +393,7 @@ Usage: The lifecycle: - SHALL detect a single group from `` and write it to `` using the [detection process](buildpack.md#phase-1-detection) outlined in the Buildpack Interface Specification - SHALL write the resolved build plan from the detected group to `` +- SHALL provide `run-image.platform` data in `` to buildpacks according to the process outlined in the [Buildpack Interface Specification](buildpack.md). When image extensions are present in the order (**[experimental](#experimental-features)**), the lifecycle: - SHALL execute all image extensions in the order defined in `` according to the process outlined in the [Buildpack Interface Specification](buildpack.md). From d6141f2f8c632bba353c394aa74f0d2aa741a572 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 6 Dec 2022 10:26:49 -0500 Subject: [PATCH 09/67] Remove other references to stack Signed-off-by: Natalie Arellano --- platform.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/platform.md b/platform.md index c4a6d2b..41d0321 100644 --- a/platform.md +++ b/platform.md @@ -806,7 +806,7 @@ Usage: - The value of `io.buildpacks.lifecycle.metadata` SHALL be modified as follows - `run-image.reference` SHALL uniquely identify `` - `run-image.top-layer` SHALL be set to the uncompressed digest of the top layer in `` - - The value of `io.buildpacks.stack.*` labels SHALL be modified to that of the new `run-image` + - The value of `io.buildpacks.base.*` labels SHALL be modified to that of the new `run-image` - To ensure [build reproducibility](#build-reproducibility), the lifecycle: - SHOULD set the `created` time in image config to a constant @@ -914,7 +914,7 @@ The launcher: ### Run Image Resolution -Given stack metadata containing `run-image.image` and a set of `run-image.mirrors`. The `` for a given `` shall be resolved as follows: +Given [stack](#stacktoml-toml) metadata containing `run-image.image` and a set of `run-image.mirrors`. The `` for a given `` shall be resolved as follows: - **If** any of `run-image.image` or `run-image.mirrors` has a registry matching that of ``, this value will become the `` - **If** none of `run-image.image` or `run-image.mirrors` has a registry matching that of ``, `` will become the `` @@ -988,7 +988,7 @@ The following variables SHOULD be set in the lifecycle execution environment and | `CPATH` | `/include` | header files | | `PKG_CONFIG_PATH` | `/pkgconfig` | pc files | -The platform SHOULD NOT assume any other stack-provided environment variables are inherited by the buildpack. +The platform SHOULD NOT assume any other base-image-provided environment variables are inherited by the buildpack. ##### User-Provided Variables User-provided environment variables MUST be supplied by the platform as files in the `/env/` directory. From 10293e9549c1857d9894c664ccd6a588cdd0300d Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 6 Dec 2022 10:29:38 -0500 Subject: [PATCH 10/67] Rename platform -> target Signed-off-by: Natalie Arellano --- platform.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/platform.md b/platform.md index 41d0321..87a3cef 100644 --- a/platform.md +++ b/platform.md @@ -21,7 +21,7 @@ Examples of a platform might include: - [Additional Terminology](#additional-terminology) - [Build Image](#build-image) - [Run Image](#run-image) - - [Platform Data](#platform-data) + - [Target Data](#target-data) - [Compatibility Guarantees](#compatibility-guarantees) - [Lifecycle Interface](#lifecycle-interface) - [Platform API Compatibility](#platform-api-compatibility) @@ -184,7 +184,7 @@ The platform SHOULD ensure that: - The image config's `Label` field has the label `io.buildpacks.base.description` set to the description of the image. - The image config's `Label` field has the label `io.buildpacks.base.metadata` set to additional metadata related to the image. -### Platform Data +### Target Data For both build images and run images, the platform MUST ensure that: @@ -1047,7 +1047,7 @@ For more information on build reproducibility see [https://reproducible-builds.o [run-image] reference = "" target-id = "" - [platform] + [target] os = "" architecture = "" variant = "" @@ -1063,8 +1063,8 @@ Where: - `image.metadata` MUST be the TOML representation of the layer [metadata label](#iobuildpackslifecyclemetadata-json) - `run-image.reference` MUST be either a digest reference to an image in an OCI registry or the ID of an image in a docker daemon - `run-image.target-id` is optional and MUST be the value of the label `io.buildpacks.id` -- `run-image.platform` contains the [platform data](#platform-data) for the image - - If platform data is missing but the image contains the label `io.buildpacks.stack.id` with value `io.buildpacks.stacks.bionic`, the lifecycle SHALL assume the following values: +- `run-image.platform` contains the [target data](#target-data) for the image + - If target data is missing but the image contains the label `io.buildpacks.stack.id` with value `io.buildpacks.stacks.bionic`, the lifecycle SHALL assume the following values: - `run-image.platform.os = "linux"` - `run-image.platform.architecture = "x86_64"` - `run-image.platform.distro-name = "ubuntu"` From ec8769e0b392fa20d2bee03281e4a26a74976b3d Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 6 Dec 2022 10:43:26 -0500 Subject: [PATCH 11/67] Small syntax change Signed-off-by: Natalie Arellano --- platform.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform.md b/platform.md index 87a3cef..6c3d178 100644 --- a/platform.md +++ b/platform.md @@ -196,7 +196,7 @@ The platform SHOULD ensure that: - The image config's `variant` field is set to a valid identifier as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md). - The image config's `Label` field has the label `io.buildpacks.distribution.name` set to the OS distribution and the label `io.buildpacks.distribution.version` set to the 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`). + - 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`). ### Compatibility Guarantees From 0373ea9f2a1bb94d072807eac5286eb1d48cade9 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 6 Dec 2022 10:49:48 -0500 Subject: [PATCH 12/67] Rename architecture -> arch to match buildpack spec Signed-off-by: Natalie Arellano --- platform.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/platform.md b/platform.md index 6c3d178..ac304e5 100644 --- a/platform.md +++ b/platform.md @@ -1049,7 +1049,7 @@ For more information on build reproducibility see [https://reproducible-builds.o target-id = "" [target] os = "" - architecture = "" + arch = "" variant = "" distro-name = "" distro-version = "" @@ -1065,10 +1065,10 @@ Where: - `run-image.target-id` is optional and MUST be the value of the label `io.buildpacks.id` - `run-image.platform` contains the [target data](#target-data) for the image - If target data is missing but the image contains the label `io.buildpacks.stack.id` with value `io.buildpacks.stacks.bionic`, the lifecycle SHALL assume the following values: - - `run-image.platform.os = "linux"` - - `run-image.platform.architecture = "x86_64"` - - `run-image.platform.distro-name = "ubuntu"` - - `run-image.platform.distro-version = "18.04"` + - `run-image.target.os = "linux"` + - `run-image.target.arch = "x86_64"` + - `run-image.target.distro-name = "ubuntu"` + - `run-image.target.distro-version = "18.04"` #### `group.toml` (TOML) From 941516ee286b7fb8387054f7a8de7bd4068cb167 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 6 Dec 2022 11:38:39 -0500 Subject: [PATCH 13/67] Wording Signed-off-by: Natalie Arellano --- platform.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/platform.md b/platform.md index ac304e5..eeffac4 100644 --- a/platform.md +++ b/platform.md @@ -195,8 +195,8 @@ The platform SHOULD ensure that: - The image config's `variant` field is set to a valid identifier as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md). - The image config's `Label` field has the label `io.buildpacks.distribution.name` set to the OS distribution and the label `io.buildpacks.distribution.version` set to the 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`). + - For Linux-based images, each label 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, `io.buildpacks.distribution.name` should be empty; `io.buildpacks.distribution.version` should contain the value of `os.version` in the image config (e.g., `10.0.14393.1066`). ### Compatibility Guarantees From b3c883b24148d275bfa18917f0c3e4d2868d3e80 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 6 Dec 2022 12:14:59 -0500 Subject: [PATCH 14/67] Rename distro -> distribution and update schema of analyzed.toml to match buildpack spec Signed-off-by: Natalie Arellano --- platform.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/platform.md b/platform.md index eeffac4..0ef65ae 100644 --- a/platform.md +++ b/platform.md @@ -1048,11 +1048,12 @@ For more information on build reproducibility see [https://reproducible-builds.o reference = "" target-id = "" [target] - os = "" - arch = "" - variant = "" - distro-name = "" - distro-version = "" + os = "" + arch = "" + variant = "" + [target.distribution] + name = "" + version = "" [build-image] reference = "" @@ -1067,8 +1068,8 @@ Where: - If target data is missing but the image contains the label `io.buildpacks.stack.id` with value `io.buildpacks.stacks.bionic`, the lifecycle SHALL assume the following values: - `run-image.target.os = "linux"` - `run-image.target.arch = "x86_64"` - - `run-image.target.distro-name = "ubuntu"` - - `run-image.target.distro-version = "18.04"` + - `run-image.target.distribution.name = "ubuntu"` + - `run-image.target.distribution.version = "18.04"` #### `group.toml` (TOML) From 64d392cc342674ec74b71d98f65ec0769864779b Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 6 Dec 2022 12:18:00 -0500 Subject: [PATCH 15/67] More rename platform -> target Signed-off-by: Natalie Arellano --- platform.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/platform.md b/platform.md index 0ef65ae..82451e6 100644 --- a/platform.md +++ b/platform.md @@ -393,7 +393,7 @@ Usage: The lifecycle: - SHALL detect a single group from `` and write it to `` using the [detection process](buildpack.md#phase-1-detection) outlined in the Buildpack Interface Specification - SHALL write the resolved build plan from the detected group to `` -- SHALL provide `run-image.platform` data in `` to buildpacks according to the process outlined in the [Buildpack Interface Specification](buildpack.md). +- SHALL provide `run-image.target` data in `` to buildpacks according to the process outlined in the [Buildpack Interface Specification](buildpack.md). When image extensions are present in the order (**[experimental](#experimental-features)**), the lifecycle: - SHALL execute all image extensions in the order defined in `` according to the process outlined in the [Buildpack Interface Specification](buildpack.md). @@ -1064,7 +1064,7 @@ Where: - `image.metadata` MUST be the TOML representation of the layer [metadata label](#iobuildpackslifecyclemetadata-json) - `run-image.reference` MUST be either a digest reference to an image in an OCI registry or the ID of an image in a docker daemon - `run-image.target-id` is optional and MUST be the value of the label `io.buildpacks.id` -- `run-image.platform` contains the [target data](#target-data) for the image +- `run-image.target` contains the [target data](#target-data) for the image - If target data is missing but the image contains the label `io.buildpacks.stack.id` with value `io.buildpacks.stacks.bionic`, the lifecycle SHALL assume the following values: - `run-image.target.os = "linux"` - `run-image.target.arch = "x86_64"` From 156a8124db2c9d085b104cc417ea4a5c3b204ca9 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Thu, 2 Feb 2023 16:55:15 -0500 Subject: [PATCH 16/67] Add run image extension to platform spec as per RFC 0105 Signed-off-by: Natalie Arellano --- platform.md | 300 +++++++++++++++++++++++++++++++++++----------------- 1 file changed, 201 insertions(+), 99 deletions(-) diff --git a/platform.md b/platform.md index 82451e6..e573ebf 100644 --- a/platform.md +++ b/platform.md @@ -101,6 +101,7 @@ Platform API versions: ## Terminology #### CNB Terminology + A **buildpack** refers to software compliant with the [Buildpack Interface Specification](buildpack.md). A **build image** is an OCI image that provides the base of the **build environment**. @@ -124,6 +125,7 @@ The **launcher** refers to a lifecycle executable packaged in the **app image** 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**. A **tag reference** refers to an identifier of form `/:` which locates an image manifest in an [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec/blob/master/spec.md) compliant registry. @@ -183,6 +185,7 @@ The platform SHOULD ensure that: - The image config's `Label` field has the label `io.buildpacks.base.released` set to the release date of the image. - The image config's `Label` field has the label `io.buildpacks.base.description` set to the description of the image. - The image config's `Label` field has the label `io.buildpacks.base.metadata` set to additional metadata related to the image. +- The image config's `Label` field has the label `io.buildpacks.rebasable` set to `true` to indicate that new run image versions maintain [ABI-compatibility](https://en.wikipedia.org/wiki/Application_binary_interface) with previous versions (see [Compatibility Guarantees](#compatibility-guarantees)). ### Target Data @@ -217,33 +220,39 @@ If `CNB_PLATFORM_API` is set in the lifecycle's execution environment, the lifec ### Operations #### Build + A single app image build* consists of the following phases: 1. Analysis -1. Detection -1. Cache Restoration -1. Build* -1. Export +2. Detection +3. Cache Restoration +4. (Optional and Experimental) Base Image Extension +5. Build* +6. Export A platform MUST execute these phases either by invoking the following phase-specific lifecycle binaries in order: 1. `/cnb/lifecycle/analyzer` -1. `/cnb/lifecycle/detector` -1. `/cnb/lifecycle/restorer` -1. `/cnb/lifecycle/builder` -1. `/cnb/lifecycle/exporter` +2. `/cnb/lifecycle/detector` +3. `/cnb/lifecycle/restorer` +4. (Optional and Experimental) `/cnb/lifecycle/extender` +5. `/cnb/lifecycle/builder` +6. `/cnb/lifecycle/exporter` + +or by executing `/cnb/lifecycle/creator`**. -or by executing `/cnb/lifecycle/creator`. +> \* **Build** is an overloaded term that refers to both a single phase and the operation comprised of the above phases. +> The meaning of any particular instance of the word **build** must be assessed in context. -> \* **build** is an overloaded term that refers to both a single phase and the operation comprised of the above phases. -> The meaning of any particular instance of the word **build** must be assessed in context +> **Does not perform image extension. #### Rebase + When an updated run image is available, an updated app image SHOULD be generated from the existing app image config by replacing the run image layers in the existing app image with the layers from the new run image. This is referred to as rebasing the app, launch, and launcher layers onto the new run image layers. When layers are rebased, any app image metadata referencing to the original run image MUST be updated to reference to the new run image. This entire operation is referred to as rebasing the app image. -Rebasing allows for fast runtime OS-level dependency updates for app images without requiring a rebuild. A rebase requires minimal data transfer when the app and run images are colocated on an OCI registry that supports [Cross Repository Blob Mounts](https://docs.docker.com/registry/spec/api/#cross-repository-blob-mount). +Rebasing allows for fast runtime OS-level dependency updates for app images without requiring a rebuild. A rebase requires minimal data transfer when the app and run images are co-located on an OCI registry that supports [Cross Repository Blob Mounts](https://docs.docker.com/registry/spec/api/#cross-repository-blob-mount). To rebase an app image a platform MUST execute the `/cnb/lifecycle/rebaser` or perform an equivalent operation. @@ -252,7 +261,8 @@ If an SBOM is available, platforms MAY: - Fail if a rebase operation would remove OS packages. #### Launch -`/cnb/lifecycle/launcher` is responsible for launching user and buildpack provided processes in the correct execution environment. + +`/cnb/lifecycle/launcher` is responsible for launching user- and buildpack-provided processes in the correct execution environment. `/cnb/lifecycle/launcher`, or a symlink to it (see [exporter outputs](#outputs-4)), SHALL be the `ENTRYPOINT` for all app images. ### Usage @@ -284,6 +294,7 @@ Usage: ``` ##### Inputs + | Input | Environment Variable | Default Value | Description |-------------------|-----------------------|--------------------------|---------------------- | `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) @@ -316,6 +327,7 @@ Usage: - `run-image` MUST describe the `` ##### Outputs + | Output | Description |--------------------|---------------------------------------------- | [exit status] | (see Exit Code table below for values) @@ -332,6 +344,7 @@ Usage: | `30-39` | Analysis-specific lifecycle errors #### `detector` + The platform MUST execute `detector` in the **build environment** Usage: @@ -351,21 +364,24 @@ Usage: ``` ##### Inputs -| Input | Environment Variable | Default Value | Description | -|----------------|----------------------|--------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | 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` | 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 | +> ^Only needed when using image extensions ##### Outputs + | Output | Description | |----------------------------------------------------------|-----------------------------------------------------------------------------------------------| | [exit status] | (see Exit Code table below for values) | @@ -395,15 +411,25 @@ The lifecycle: - SHALL write the resolved build plan from the detected group to `` - SHALL provide `run-image.target` data in `` to buildpacks according to the process outlined in the [Buildpack Interface Specification](buildpack.md). -When image extensions are present in the order (**[experimental](#experimental-features)**), the lifecycle: +When image extensions are present in the order (optional and **[experimental](#experimental-features)**), the lifecycle: - SHALL execute all image extensions in the order defined in `` according to the process outlined in the [Buildpack Interface Specification](buildpack.md). +- SHALL filter the build plan with dependencies provided by image extensions. - SHALL copy any generated run.Dockerfiles to `/run//Dockerfile`. - SHALL copy any generated build.Dockerfiles to `/build//Dockerfile`. - SHALL copy any generated `` files to `/build//`. -- SHALL replace the `run-image` reference in `` with the selected run image reference. The selected run image reference SHALL be the base image referenced in the Dockerfile output by the last image extension in the group. -- SHALL filter the build plan with dependencies provided by image extensions. +- SHALL replace `run-image` in `` with the selected run image. To select the run image, the lifecycle SHALL inspect each `run.Dockerfile` output by image extensions, in the order defined in ``: + - **If** all `run.Dockerfile`s declare `FROM ${base_image}`, the selected run image SHALL be the original run image in ``, with `extend = true` + - **Else** the selected run image SHALL be the last image referenced in the `FROM` statement of the last `run.Dockerfile` not to declare `FROM ${base_image}` + - `run-image.image` SHALL be the name of the selected run image + - `run-image.reference` and `run-image.target` SHALL be cleared (as they may no longer be accurate) + - All preceding `run.Dockerfile`s SHALL be renamed `run.Dockerfile.ignore` + - **If** there are no `run.Dockerfile`s following the Dockerfile with the selected run image: + - `run-image.extend` SHALL be `false` + - **Else** + - `run-image.extend` SHALL be `true` #### `restorer` + Usage: ``` /cnb/lifecycle/restorer \ @@ -411,6 +437,7 @@ Usage: [-build-image ] \ [-cache-dir ] \ [-cache-image ] \ + [-generated ] \ [-gid ] \ [-group ] \ [-layers ] \ @@ -420,21 +447,28 @@ 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_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_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`) | + +> ^ Only needed when using image extensions + +> \* Only needed when using image extensions to extend the build image ##### Outputs + | Output | Description | |---------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------| | [exit status] | (see Exit Code table below for values) | @@ -444,7 +478,7 @@ 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| @@ -458,24 +492,35 @@ Usage: - 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. - **Else** the lifecycle MUST perform [layer restoration](#layer-restoration) for any app image layers or cached layers created by any buildpack present in the provided ``. -- When the provided `` contains image extensions (**[experimental](#experimental-features)**), the lifecycle: +- When `/build` contains Dockerfiles (optional and **[experimental](#experimental-features)**), the lifecycle: - MUST record the digest reference to the provided `` in `` - MUST copy the OCI manifest and config file for `` to `/cache` +- When `/run` contains Dockerfiles, the lifecycle: + - MUST resolve `run-image.reference` to a digest in `` if not present + - MUST populate `run-image.target` data in `` if not present + - **If** `` has `run-image.extend = true`, the lifecycle: + - MUST download from the registry and save in OCI layout format the `run-image` in `` to `/cache` ##### Layer Restoration + lifeycle MUST use the provided `cache-dir` or `cache-image` to retrieve cache contents. The [rules](https://github.com/buildpacks/spec/blob/main/buildpack.md#layer-types) for restoration MUST be followed when determining how and when to store cache layers. -#### `extender` (**[experimental](#experimental-features)**) +#### `extender` (optional and **[experimental](#experimental-features)**) + +If using `extender`, the platform MUST execute `extender` in either or both of: the **build environment**, the **run environment** + Usage: ``` /cnb/lifecycle/extender \ [-analyzed ] \ [-app ] \ [-buildpacks ] \ + [-extended ] \ [-generated ] \ [-gid ] \ [-group ] \ [-kaniko-cache-ttl ] \ + [-kind ] \ [-layers ] \ [-log-level ] \ [-plan ] \ @@ -484,30 +529,40 @@ Usage: ``` ##### Inputs + | Input | Env | 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_BUILDPACKS_DIR` | `/cnb/buildpacks` | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout)) | +| ``* | `CNB_BUILDPACKS_DIR` | `/cnb/buildpacks` | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout)) | +| ``** | `CNB_EXTENDED_DIR` | `/extended` | Path to output directory for extended run image layers | | `` | `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_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 | +| `` | `CNB_EXTEND_KIND` | `build` | Type of image to extend (valid values: `build`, `run`) | | `` | `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_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_USER_ID` | | UID of the build image `User` | + +> \* Only needed when extending the build image + +> ** Only needed when extending the run image ##### Outputs -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`. +When extending the build image: + +- 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. +- 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 | @@ -518,13 +573,20 @@ In addition to the outputs enumerated below, outputs produced by `extender` incl | `1-10`, `13-19` | Generic lifecycle errors | | `100-109` | Extension-specific lifecycle errors | -- For each extension in ``, if a Dockerfile exists in `/build/`, the lifecycle: - - MUST apply the Dockerfile to the build environment according to the process outlined in the [Image Extension Specification](image-extension.md). -- The extended image MUST be an extension of the `build-image` in [`analyzed.toml`](#analyzedtoml-toml) -- After all Dockerfiles are applied, the lifecycle: - - MUST proceed with the `build` phase using the provided `` and `` +- For each extension in `` in order, if a Dockerfile exists in `//`, the lifecycle: + - SHALL apply the Dockerfile to the environment according to the process outlined in the [Image Extension Specification](image-extension.md). +- The extended image MUST be an extension of: + - The `build-image` in `` when `` is `build`, or + - The `run-image` in `` when `` is `run` +- When extending the build image, after all `build.Dockefile`s are applied, the lifecycle: + - SHALL proceed with the `build` phase using the provided `` and `` +- When extending the run image, after all `run.Dockefile`s are applied, the lifecycle: + - **If** any `run.Dockerfile` set the label `io.buildpacks.rebasable` to `false` or left the label unset: + - SHALL set the label `io.buildpacks.rebasable` to `false` on the extended run image + - SHALL copy the manifest and config for the extended run image, along with any new layers, to `` #### `builder` + The platform MUST execute `builder` in the **build environment** Usage: @@ -540,6 +602,7 @@ Usage: ``` ##### Inputs + | Input | Env | Default Value | Description |----------------|-----------------------|-----------------------|---------------------- | `` | `CNB_APP_DIR` | `/workspace` | Path to application directory @@ -551,6 +614,7 @@ Usage: | `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory ##### Outputs + | Output | Description |--------------------------------------------|---------------------------------------------- | [exit status] | (see Exit Code table below for values) @@ -576,6 +640,7 @@ Usage: - The lifecycle SHALL treat `web` processes defined by buildpacks implementing Buildpack API < 0.6 as `default = true`. #### `exporter` + Usage: ``` /cnb/lifecycle/exporter \ @@ -584,6 +649,7 @@ Usage: [-cache-dir ] \ [-cache-image ] \ [-daemon] \ # sets + [-extended ] \ [-gid ] \ [-group ] \ [-launch-cache ] \ @@ -599,27 +665,31 @@ 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_EXTENDED_DIR` | `/extended` | Path to directory containing extended run image layers | +| `` | `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 | + +> ** Only needed when extending the run image - At least one `` must be provided - Each `` MUST be a valid tag reference @@ -627,6 +697,7 @@ Usage: - The `` will be read from [`analyzed.toml`](#analyzedtoml-toml) ##### Outputs + | Output | Description |--------------------|---------------------------------------------- | `[exit status]` | Success (0), or error (1+) @@ -644,9 +715,12 @@ Usage: - The lifecycle SHALL write the same app image to each `` tag - The app image: - - MUST be an extension of the `run-image` in [`analyzed.toml`](#analyzedtoml-toml) - - All run-image layers SHALL be preserved - - All run-image config values SHALL be preserved unless this conflicts with another requirement + - **If** image extensions were used to extend the `run-image` in [`analyzed.toml`](#analyzedtoml-toml): + - MUST be based on the image in `` + - **Else**: + - MUST be based on the `run-image` in [`analyzed.toml`](#analyzedtoml-toml) + - All base image layers and any extension layers SHALL be preserved + - All base 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 - `/sbom/launch//sbom.` MUST contain the buildpack-provided `launch` SBOM @@ -672,8 +746,15 @@ Usage: - MUST have the working directory set to the value of ``. - MUST contain the following labels - `io.buildpacks.lifecycle.metadata`: see [lifecycle metadata label](#iobuildpackslifecyclemetadata-json) + - **If** `run-image.image` in `` does not match `run-image.image` in ``: + - `stack.runImage.image` SHALL be the value from `` + - `stack.runImage.mirrors` SHALL be omitted - `io.buildpacks.project.metadata`: the value of which SHALL be the json representation `` - `io.buildpacks.build.metadata`: see [build metadata](#iobuildpacksbuildmetadata-json) + - **If** image extensions were used to extend the run image and `/` has the label `io.buildpacks.rebasable` set to `true`: + - `io.buildpacks.rebasable` SHALL be `true` + - **Else** + - `io.buildpacks.rebasable` SHALL be `false` - To ensure [build reproducibility](#build-reproducibility), the lifecycle: - SHOULD set the modification time of all files in newly created layers to a constant value - SHOULD set the `created` time in image config to `SOURCE_DATE_EPOCH`, or to a constant value if not defined @@ -690,6 +771,7 @@ Usage: - SHALL record the diffID and layer content metadata of all cached layers in the cache #### `creator` + The platform MUST execute `creator` in the **build environment** Usage: @@ -720,6 +802,7 @@ Usage: ``` ##### Inputs + Running `creator` SHALL be equivalent to running `detector`, `analyzer`, `restorer`, `builder` and `exporter` in order with identical inputs where they are accepted, with the following exceptions. | Input | Environment Variable| Default Value| Description @@ -732,6 +815,7 @@ Running `creator` SHALL be equivalent to running `detector`, `analyzer`, `restor - **If** the platform provides one or more `` inputs they SHALL be treated as additional `` inputs to the `exporter` ##### Outputs + Outputs produced by `creator` are identical to those produced by `exporter`, with the following additional expanded set of error codes. | Exit Code | Result| @@ -747,6 +831,7 @@ Outputs produced by `creator` are identical to those produced by `exporter`, wit | `60-69`| Export-specific lifecycle errors #### `rebaser` + Usage: ``` /cnb/lifecycle/rebaser \ @@ -761,22 +846,24 @@ Usage: ``` ##### Inputs -| Input | Environment Variable | Default Value | Description | -|---------------|----------------------|------------------------|----------------------------------------------------------| -| `` | `CNB_USE_DAEMON` | `false` | Export image to docker daemon | -| `` | `CNB_FORCE_REBASE` | `false` | Allow mismatched metadata between new and old run images | -| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` | -| `` | | | App image to rebase | -| `` | `CNB_LOG_LEVEL` | `info` | Log Level | -| `` | `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` | + +| Input | Environment Variable | Default Value | Description | +|---------------|----------------------|------------------------|-------------------------------------------------------| +| `` | `CNB_USE_DAEMON` | `false` | Export image to docker daemon | +| `` | `CNB_FORCE_REBASE` | `false` | Allow unsafe rebase | +| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` | +| `` | | | App image to rebase | +| `` | `CNB_LOG_LEVEL` | `info` | Log Level | +| `` | `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` | - At least one `` must be provided +- **If** `` has `io.buildpacks.rebasable` set to `false`, the lifecycle SHALL fail unless `` is `true` - Each `` MUST be a valid tag reference - **If** `` is `false` and more than one `` is provided, the images MUST refer to the same registry - **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 `` -- **If** `` is true the following values in the output `` config MUST be derived from the new ``, or else they MUST match the old run image if `` is false: +- **If** `` is `true` the following values in the output `` config MUST be derived from the new ``, or else they MUST match the old run image if `` is `false`: - `os` - `architecture` - `variant` (if specified) @@ -784,6 +871,7 @@ Usage: - `io.buildpacks.distribution.version` (if specified) ##### Outputs + | Output | Description |--------------------|---------------------------------------------- | [exit status] | (see Exit Code table below for values) @@ -809,10 +897,10 @@ Usage: - The value of `io.buildpacks.base.*` labels SHALL be modified to that of the new `run-image` - To ensure [build reproducibility](#build-reproducibility), the lifecycle: - SHOULD set the `created` time in image config to a constant - - The lifecycle SHALL write a [report](#reporttoml-toml) to `` describing the rebased app image #### `launcher` + Usage: ``` /cnb/process/ [...] @@ -820,6 +908,7 @@ Usage: /cnb/lifecycle/launcher [--] [ ...] ``` ##### Inputs + | Input | Environment Variable | Default Value | Description | |------------------------------------|----------------------|---------------|-----------------------------------------------------------| | `` | `CNB_APP_DIR` | `/workspace` | Path to application directory | @@ -897,6 +986,7 @@ Given the start command and execution strategy, [‡](README.md#windows-only)When executing a process with Command Prompt, the launcher SHOULD start a new process with the same security context, terminal, working directory, STDIN/STDOUT/STDERR handles and environment variables as the Command Prompt process. ##### Outputs + If the launcher errors before executing the process it will have one of the following error codes: | Exit Code | Result | @@ -968,7 +1058,9 @@ A more thorough explanation is provided in the [Buildpack Interface Specificatio ## Additional Guidance ### Environment + #### Buildpack Environment + ##### Base Image-Provided Variables The following variables SHOULD be set in the lifecycle execution environment and SHALL be directly inherited by the @@ -991,6 +1083,7 @@ The following variables SHOULD be set in the lifecycle execution environment and The platform SHOULD NOT assume any other base-image-provided environment variables are inherited by the buildpack. ##### User-Provided Variables + User-provided environment variables 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. @@ -999,6 +1092,7 @@ 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. #### Launch Environment + User-provided modifications to the process execution environment SHOULD be set directly in the lifecycle execution environment. The process SHALL inherit both base-image-provided and user-provided variables from the lifecycle execution environment with the following exceptions: @@ -1013,6 +1107,7 @@ Whenever possible, the platform SHOULD provide the same cache to each rebuild of Cache locality and availability MAY vary between platforms. ### Build Reproducibility + When given identical inputs all build and rebase operations: - SHOULD produce app images with identical imageIDs - **If** exporting directly to a registry @@ -1045,7 +1140,9 @@ For more information on build reproducibility see [https://reproducible-builds.o # layer metadata [run-image] + image = "" reference = "" + extend = false target-id = "" [target] os = "" @@ -1143,6 +1240,7 @@ Where: - The value of `optional` MUST default to `false` if not specified. #### `plan.toml` (TOML) + ```toml [[entries]] @@ -1160,7 +1258,7 @@ Where: - `entries` MAY be empty - Each entry: - MUST contain at least one buildpack or image extension in `providers` - - If the provider is an image extension (**[experimental](#experimental-features)**), `extension` MUST be `true`; the value of `extension` MUST default to `false` if not specified + - If the provider is an image extension (optional and **[experimental](#experimental-features)**), `extension` MUST be `true`; the value of `extension` MUST default to `false` if not specified - MUST contain at least one dependency requirement in `requires` - MUST exclusively contain dependency requirements with the same `` @@ -1184,6 +1282,7 @@ Where: - `metadata` MAY contain additional arbitrary data about the provided source #### `report.toml` (TOML) + ```toml [image] tags = [""] @@ -1204,7 +1303,7 @@ Where: ```toml [run-image] image = "" - mirrors = ["", ""] + mirrors = ["", ""] ``` Where: @@ -1301,11 +1400,13 @@ Where: }, "stack": { "runImage": { - "image": "cnbs/sample-stack-run:bionic" + "image": "cnbs/sample-stack-run:bionic", + "mirrors": = ["", ""] } } } ``` + Where: - `app` MUST contain one entry per app slice layer where - `sha` MUST contain the digest of the uncompressed layer @@ -1341,4 +1442,5 @@ Where: } } ``` + This label MUST contain the JSON representation of [`project-metadata.toml`](#project-metadatatoml-toml) From ef56944eb55afd3c984a8211a53f3b3ea6373045 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Thu, 2 Feb 2023 17:32:09 -0500 Subject: [PATCH 17/67] Rename stack.toml to run.toml and validate run image selection against run.toml Signed-off-by: Natalie Arellano --- platform.md | 96 ++++++++++++++++++++++++++--------------------------- 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/platform.md b/platform.md index e573ebf..af27de6 100644 --- a/platform.md +++ b/platform.md @@ -84,7 +84,7 @@ Examples of a platform might include: - [`plan.toml` (TOML)](#plantoml-toml) - [`project-metadata.toml` (TOML)](#project-metadatatoml-toml) - [`report.toml` (TOML)](#reporttoml-toml) - - [`stack.toml` (TOML)](#stacktoml-toml) + - [`run.toml` (TOML)](#runtoml-toml) - [Labels](#labels) - [`io.buildpacks.build.metadata` (JSON)](#iobuildpacksbuildmetadata-json) - [`io.buildpacks.lifecycle.metadata` (JSON)](#iobuildpackslifecyclemetadata-json) @@ -285,9 +285,9 @@ Usage: [-layers ] \ [-log-level ] \ [-previous-image ] \ + [-run ] \ [-run-image ] \ [-skip-layers ] \ - [-stack ] \ [-tag ...] \ [-uid ] \ @@ -295,22 +295,22 @@ Usage: ##### Inputs -| Input | Environment Variable | Default Value | Description -|-------------------|-----------------------|--------------------------|---------------------- -| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) -| `` | `CNB_CACHE_IMAGE` | | Reference to a cache image in an OCI registry -| `` | `CNB_USE_DAEMON` | `false` | Analyze image from docker daemon -| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` -| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory -| `` | | | Tag reference to which the app image will be written -| `` | `CNB_LAUNCH_CACHE_DIR`| | Path to a cache directory containing launch layers -| `` | `CNB_LOG_LEVEL` | `info` | Log Level -| ``| `CNB_PREVIOUS_IMAGE` | `` | Image reference to be analyzed (usually the result of the previous build) -| `` | `CNB_RUN_IMAGE` | resolved from `` | Run image reference -| `` | `CNB_SKIP_LAYERS` | `false` | Do not restore SBOM layer from previous image -| `` | `CNB_STACK_PATH` | `/cnb/stack.toml` | Path to stack file (see [`stack.toml`](#stacktoml-toml)) -| `...` | | | Additional tag to apply to exported image -| `` | `CNB_USER_ID` | | UID of the build image `User` +| Input | Environment Variable | Default Value | Description | +|--------------------|------------------------|--------------------------|-----------------------------------------------------------------------------| +| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) | +| `` | `CNB_CACHE_IMAGE` | | Reference to a cache image in an OCI registry | +| `` | `CNB_USE_DAEMON` | `false` | Analyze image from docker daemon | +| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` | +| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | +| `` | | | Tag reference to which the app image will be written | +| `` | `CNB_LAUNCH_CACHE_DIR` | | Path to a cache directory containing launch layers | +| `` | `CNB_LOG_LEVEL` | `info` | Log Level | +| `` | `CNB_PREVIOUS_IMAGE` | `` | Image reference to be analyzed (usually the result of the previous build) | +| `` | `CNB_RUN_PATH` | `/cnb/run.toml` | Path to run file (see [`run.toml`](#runtoml-toml)) | +| `` | `CNB_RUN_IMAGE` | resolved from `` | Run image reference | +| `` | `CNB_SKIP_LAYERS` | `false` | Do not restore SBOM layer from previous image | +| `...` | | | Additional tag to apply to exported image | +| `` | `CNB_USER_ID` | | UID of the build image `User` | -`` MUST be a valid image reference - **If** the platform provides one or more `` inputs, each `` MUST be a valid image reference. @@ -318,7 +318,7 @@ Usage: - **If** `` is `false`, ``, if provided, MUST be a valid image reference. - **If** `` is `true`, ``, if provided, MUST be either a valid image reference or an imageID. - **If** `` is `true` the lifecycle MUST NOT restore the SBOM layer (if any) from the previous image. -- **If** `` is not provided by the platform the lifecycle MUST [resolve](#run-image-resolution) the run image from the contents of `stack` or fail if `stack` does not contain a valid run image. +- **If** `` is not provided by the platform the lifecycle MUST [resolve](#run-image-resolution) the run image from the contents of `run` or fail if `run` does not contain a valid run image. - The lifecycle MUST accept valid references to non-existent ``, ``, and `` without error. - The lifecycle MUST ensure registry write access to ``, `` and any provided ``s. - The lifecycle MUST ensure registry read access to ``, ``, and ``. @@ -360,7 +360,8 @@ Usage: [-log-level ] \ [-order ] \ [-plan ] \ - [-platform ] + [-platform ] \ + [-run ] ``` ##### Inputs @@ -378,6 +379,7 @@ Usage: | `` | `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_RUN_PATH` | `/cnb/run.toml` | Path to run file (see [`run.toml`](#runtoml-toml)) | > ^Only needed when using image extensions ##### Outputs @@ -427,6 +429,7 @@ When image extensions are present in the order (optional and **[experimental](#e - `run-image.extend` SHALL be `false` - **Else** - `run-image.extend` SHALL be `true` +- SHALL fail if the selected run image is not found in `` #### `restorer` @@ -659,7 +662,7 @@ Usage: [-process-type ] \ [-project-metadata ] \ [-report ] \ - [-stack ] \ + [-run ] \ [-uid ] \ [...] ``` @@ -684,7 +687,7 @@ Usage: | `` | `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_RUN_PATH` | `/cnb/run.toml` | Path to run file (see [`run.toml`](#runtoml-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 | @@ -746,10 +749,7 @@ Usage: - MUST have the working directory set to the value of ``. - MUST contain the following labels - `io.buildpacks.lifecycle.metadata`: see [lifecycle metadata label](#iobuildpackslifecyclemetadata-json) - - **If** `run-image.image` in `` does not match `run-image.image` in ``: - - `stack.runImage.image` SHALL be the value from `` - - `stack.runImage.mirrors` SHALL be omitted - - `io.buildpacks.project.metadata`: the value of which SHALL be the json representation `` + - `io.buildpacks.project.metadata`: the value of which SHALL be the json representation of `` - `io.buildpacks.build.metadata`: see [build metadata](#iobuildpacksbuildmetadata-json) - **If** image extensions were used to extend the run image and `/` has the label `io.buildpacks.rebasable` set to `true`: - `io.buildpacks.rebasable` SHALL be `true` @@ -793,9 +793,9 @@ Usage: [-process-type ] \ [-project-metadata ] \ [-report ] \ + [-run ] \ [-run-image ] \ [-skip-restore ] \ - [-stack ] \ [-tag ...] \ [-uid ] \ @@ -862,7 +862,7 @@ Usage: - **If** `` has `io.buildpacks.rebasable` set to `false`, the lifecycle SHALL fail unless `` is `true` - Each `` MUST be a valid tag reference - **If** `` is `false` and more than one `` is provided, the images MUST refer to the same registry -- **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 `` +- **If** `` is not provided by the platform, the value will be [resolved](#run-image-resolution) from the contents of the `runImage` key in the `io.buildpacks.lifecycle.metdata` label on `` - **If** `` is `true` the following values in the output `` config MUST be derived from the new ``, or else they MUST match the old run image if `` is `false`: - `os` - `architecture` @@ -1004,9 +1004,12 @@ The launcher: ### Run Image Resolution -Given [stack](#stacktoml-toml) metadata containing `run-image.image` and a set of `run-image.mirrors`. The `` for a given `` shall be resolved as follows: -- **If** any of `run-image.image` or `run-image.mirrors` has a registry matching that of ``, this value will become the `` -- **If** none of `run-image.image` or `run-image.mirrors` has a registry matching that of ``, `` will become the `` +Given [run](#runtoml-toml) metadata, the `` for a given `` shall be resolved as follows: +- From the matching `[[image]]`: + - **If** the tag reference for the run image is known (e.g., from a `-run-image` argument), the `[[image]]` with matching `image` + - **Else** the first `[[image]]` +- **If** any of `[image.image]` or `[image.mirrors]` has a registry matching that of ``, this value will become the `` +- **If** none of `[image.image]` or `[image.mirrors]` has a registry matching that of ``, `[image.image]` will become the `` ### Registry Authentication @@ -1298,21 +1301,21 @@ Where: - **If** the app image was exported to a docker daemon - `imageID` MUST contain the imageID -#### `stack.toml` (TOML) +#### `run.toml` (TOML) ```toml -[run-image] +[[image]] image = "" mirrors = ["", ""] ``` Where: -- `run-image.image` MAY be a reference to a run image in an OCI registry -- `run-image.mirrors` MUST NOT be present if `run-image.image` is not present -- `run-image.mirrors` MAY contain one or more tag references to run images in OCI registries -- All `run-image.mirrors`: - - SHOULD reference an image with ID identical to that of `run-image.image` -- `run-image.image` and `run-image.mirrors.[]` SHOULD each refer to a unique registry +- `image.image` MAY be a tag reference to a run image in an OCI registry +- `image.mirrors` MUST NOT be present if `image.image` is not present +- `image.mirrors` MAY contain one or more tag references to run images in OCI registries +- All `image.mirrors`: + - SHOULD reference an image with ID identical to that of `image.image` +- `image.image` and `image.mirrors.[]` SHOULD each refer to a unique registry ### Labels @@ -1395,14 +1398,10 @@ Where: } ], "runImage": { + "image": "cnbs/sample-stack-run:bionic", + "mirrors": = ["", ""], "topLayer": "", "reference": "" - }, - "stack": { - "runImage": { - "image": "cnbs/sample-stack-run:bionic", - "mirrors": = ["", ""] - } } } ``` @@ -1421,11 +1420,12 @@ Where: - The key MUST be the name of the layer - The value MUST contain JSON representation of the `layer.toml` with an additional `sha` key, containing the digest of the uncompressed layer - The value MUST contain an additional `sha` key, containing the digest of the uncompressed layer -- `run-image.topLayer` must contain the uncompressed digest of the top layer of the run-image -- `run-image.reference` MUST uniquely identify the run image. It MAY contain one of the following +- `runImage.image` MUST be a tag reference to the run-image +- `runImage.mirrors` MUST be selected from `run.toml` +- `runImage.topLayer` MUST contain the uncompressed digest of the top layer of the run-image +- `runImage.reference` MUST uniquely identify the run image. It MAY contain one of the following - An image ID (the digest of the uncompressed config blob) - A digest reference to a manifest stored in an OCI registry -- `stack` MUST contain the json representation of `stack.toml` #### `io.buildpacks.project.metadata` (JSON) From 796133ad329c3cdbb30b8b1f6cec434eba20557c Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Thu, 2 Feb 2023 18:06:27 -0500 Subject: [PATCH 18/67] Apply suggestions from code review Signed-off-by: Natalie Arellano --- platform.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/platform.md b/platform.md index 82451e6..ae0dea2 100644 --- a/platform.md +++ b/platform.md @@ -806,7 +806,7 @@ Usage: - The value of `io.buildpacks.lifecycle.metadata` SHALL be modified as follows - `run-image.reference` SHALL uniquely identify `` - `run-image.top-layer` SHALL be set to the uncompressed digest of the top layer in `` - - The value of `io.buildpacks.base.*` labels SHALL be modified to that of the new `run-image` + - The value of `io.buildpacks.base.*` labels (and any `io.buildpacks.stack.*` labels, if present) SHALL be modified to that of the new `run-image` - To ensure [build reproducibility](#build-reproducibility), the lifecycle: - SHOULD set the `created` time in image config to a constant @@ -1046,8 +1046,8 @@ For more information on build reproducibility see [https://reproducible-builds.o [run-image] reference = "" - target-id = "" [target] + id = "" os = "" arch = "" variant = "" @@ -1063,7 +1063,7 @@ Where: - `image.reference` MUST be either a digest reference to an image in an OCI registry or the ID of an image in a docker daemon - `image.metadata` MUST be the TOML representation of the layer [metadata label](#iobuildpackslifecyclemetadata-json) - `run-image.reference` MUST be either a digest reference to an image in an OCI registry or the ID of an image in a docker daemon -- `run-image.target-id` is optional and MUST be the value of the label `io.buildpacks.id` +- `run-image.target.id` is optional and MUST be the value of the label `io.buildpacks.id` - `run-image.target` contains the [target data](#target-data) for the image - If target data is missing but the image contains the label `io.buildpacks.stack.id` with value `io.buildpacks.stacks.bionic`, the lifecycle SHALL assume the following values: - `run-image.target.os = "linux"` From 9828bf3cb46695aea3911ca37d0bb0a009517607 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Wed, 8 Feb 2023 16:38:40 -0500 Subject: [PATCH 19/67] Apply suggestions from code review Co-authored-by: Joe Kutner Signed-off-by: Natalie Arellano --- platform.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/platform.md b/platform.md index af27de6..77966f6 100644 --- a/platform.md +++ b/platform.md @@ -234,7 +234,7 @@ A platform MUST execute these phases either by invoking the following phase-spec 1. `/cnb/lifecycle/analyzer` 2. `/cnb/lifecycle/detector` 3. `/cnb/lifecycle/restorer` -4. (Optional and Experimental) `/cnb/lifecycle/extender` +4. `/cnb/lifecycle/extender` (Optional and [Experimental](#experimental-features)) 5. `/cnb/lifecycle/builder` 6. `/cnb/lifecycle/exporter` @@ -859,7 +859,7 @@ Usage: | `` | `CNB_USER_ID` | | UID of the build image `User` | - At least one `` must be provided -- **If** `` has `io.buildpacks.rebasable` set to `false`, the lifecycle SHALL fail unless `` is `true` +- **If** `` has the label `io.buildpacks.rebasable` set to `false`, the lifecycle SHALL fail unless `` is `true` - Each `` MUST be a valid tag reference - **If** `` is `false` and more than one `` is provided, the images MUST refer to the same registry - **If** `` is not provided by the platform, the value will be [resolved](#run-image-resolution) from the contents of the `runImage` key in the `io.buildpacks.lifecycle.metdata` label on `` From 4480ba799723495e096795ecf7edc91ccf8492e2 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Thu, 2 Feb 2023 17:32:09 -0500 Subject: [PATCH 20/67] Rename stack.toml to run.toml and validate run image selection against run.toml Signed-off-by: Natalie Arellano --- platform.md | 131 +++++++++++++++++++++++++++------------------------- 1 file changed, 67 insertions(+), 64 deletions(-) diff --git a/platform.md b/platform.md index ae0dea2..afa5344 100644 --- a/platform.md +++ b/platform.md @@ -84,7 +84,7 @@ Examples of a platform might include: - [`plan.toml` (TOML)](#plantoml-toml) - [`project-metadata.toml` (TOML)](#project-metadatatoml-toml) - [`report.toml` (TOML)](#reporttoml-toml) - - [`stack.toml` (TOML)](#stacktoml-toml) + - [`run.toml` (TOML)](#runtoml-toml) - [Labels](#labels) - [`io.buildpacks.build.metadata` (JSON)](#iobuildpacksbuildmetadata-json) - [`io.buildpacks.lifecycle.metadata` (JSON)](#iobuildpackslifecyclemetadata-json) @@ -275,31 +275,31 @@ Usage: [-layers ] \ [-log-level ] \ [-previous-image ] \ + [-run ] \ [-run-image ] \ [-skip-layers ] \ - [-stack ] \ [-tag ...] \ [-uid ] \ ``` ##### Inputs -| Input | Environment Variable | Default Value | Description -|-------------------|-----------------------|--------------------------|---------------------- -| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) -| `` | `CNB_CACHE_IMAGE` | | Reference to a cache image in an OCI registry -| `` | `CNB_USE_DAEMON` | `false` | Analyze image from docker daemon -| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` -| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory -| `` | | | Tag reference to which the app image will be written -| `` | `CNB_LAUNCH_CACHE_DIR`| | Path to a cache directory containing launch layers -| `` | `CNB_LOG_LEVEL` | `info` | Log Level -| ``| `CNB_PREVIOUS_IMAGE` | `` | Image reference to be analyzed (usually the result of the previous build) -| `` | `CNB_RUN_IMAGE` | resolved from `` | Run image reference -| `` | `CNB_SKIP_LAYERS` | `false` | Do not restore SBOM layer from previous image -| `` | `CNB_STACK_PATH` | `/cnb/stack.toml` | Path to stack file (see [`stack.toml`](#stacktoml-toml)) -| `...` | | | Additional tag to apply to exported image -| `` | `CNB_USER_ID` | | UID of the build image `User` +| Input | Environment Variable | Default Value | Description | +|--------------------|------------------------|--------------------------|-----------------------------------------------------------------------------| +| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) | +| `` | `CNB_CACHE_IMAGE` | | Reference to a cache image in an OCI registry | +| `` | `CNB_USE_DAEMON` | `false` | Analyze image from docker daemon | +| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` | +| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | +| `` | | | Tag reference to which the app image will be written | +| `` | `CNB_LAUNCH_CACHE_DIR` | | Path to a cache directory containing launch layers | +| `` | `CNB_LOG_LEVEL` | `info` | Log Level | +| `` | `CNB_PREVIOUS_IMAGE` | `` | Image reference to be analyzed (usually the result of the previous build) | +| `` | `CNB_RUN_PATH` | `/cnb/run.toml` | Path to run file (see [`run.toml`](#runtoml-toml)) | +| `` | `CNB_RUN_IMAGE` | resolved from `` | Run image reference | +| `` | `CNB_SKIP_LAYERS` | `false` | Do not restore SBOM layer from previous image | +| `...` | | | Additional tag to apply to exported image | +| `` | `CNB_USER_ID` | | UID of the build image `User` | -`` MUST be a valid image reference - **If** the platform provides one or more `` inputs, each `` MUST be a valid image reference. @@ -307,7 +307,7 @@ Usage: - **If** `` is `false`, ``, if provided, MUST be a valid image reference. - **If** `` is `true`, ``, if provided, MUST be either a valid image reference or an imageID. - **If** `` is `true` the lifecycle MUST NOT restore the SBOM layer (if any) from the previous image. -- **If** `` is not provided by the platform the lifecycle MUST [resolve](#run-image-resolution) the run image from the contents of `stack` or fail if `stack` does not contain a valid run image. +- **If** `` is not provided by the platform the lifecycle MUST [resolve](#run-image-resolution) the run image from the contents of `run` or fail if `run` does not contain a valid run image. - The lifecycle MUST accept valid references to non-existent ``, ``, and `` without error. - The lifecycle MUST ensure registry write access to ``, `` and any provided ``s. - The lifecycle MUST ensure registry read access to ``, ``, and ``. @@ -347,7 +347,8 @@ Usage: [-log-level ] \ [-order ] \ [-plan ] \ - [-platform ] + [-platform ] \ + [-run ] ``` ##### Inputs @@ -364,6 +365,7 @@ Usage: | `` | `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_RUN_PATH` | `/cnb/run.toml` | Path to run file (see [`run.toml`](#runtoml-toml)) | ##### Outputs | Output | Description | @@ -593,33 +595,33 @@ Usage: [-process-type ] \ [-project-metadata ] \ [-report ] \ - [-stack ] \ + [-run ] \ [-uid ] \ [...] ``` ##### 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_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_RUN_PATH` | `/cnb/run.toml` | Path to run file (see [`run.toml`](#runtoml-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 @@ -711,9 +713,9 @@ Usage: [-process-type ] \ [-project-metadata ] \ [-report ] \ + [-run ] \ [-run-image ] \ [-skip-restore ] \ - [-stack ] \ [-tag ...] \ [-uid ] \ @@ -775,8 +777,8 @@ Usage: - At least one `` must be provided - Each `` MUST be a valid tag reference - **If** `` is `false` and more than one `` is provided, the images MUST refer to the same registry -- **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 `` -- **If** `` is true the following values in the output `` config MUST be derived from the new ``, or else they MUST match the old run image if `` is false: +- **If** `` is not provided by the platform, the value will be [resolved](#run-image-resolution) from the contents of the `runImage` key in the `io.buildpacks.lifecycle.metdata` label on `` +- **If** `` is `true` the following values in the output `` config MUST be derived from the new ``, or else they MUST match the old run image if `` is `false`: - `os` - `architecture` - `variant` (if specified) @@ -914,9 +916,12 @@ The launcher: ### Run Image Resolution -Given [stack](#stacktoml-toml) metadata containing `run-image.image` and a set of `run-image.mirrors`. The `` for a given `` shall be resolved as follows: -- **If** any of `run-image.image` or `run-image.mirrors` has a registry matching that of ``, this value will become the `` -- **If** none of `run-image.image` or `run-image.mirrors` has a registry matching that of ``, `` will become the `` +Given [run](#runtoml-toml) metadata, the `` for a given `` shall be resolved as follows: +- From the matching `[[image]]`: + - **If** the tag reference for the run image is known (e.g., from a `-run-image` argument), the `[[image]]` with matching `image` + - **Else** the first `[[image]]` +- **If** any of `[image.image]` or `[image.mirrors]` has a registry matching that of ``, this value will become the `` +- **If** none of `[image.image]` or `[image.mirrors]` has a registry matching that of ``, `[image.image]` will become the `` ### Registry Authentication @@ -1199,21 +1204,21 @@ Where: - **If** the app image was exported to a docker daemon - `imageID` MUST contain the imageID -#### `stack.toml` (TOML) +#### `run.toml` (TOML) ```toml -[run-image] +[[image]] image = "" mirrors = ["", ""] ``` Where: -- `run-image.image` MAY be a reference to a run image in an OCI registry -- `run-image.mirrors` MUST NOT be present if `run-image.image` is not present -- `run-image.mirrors` MAY contain one or more tag references to run images in OCI registries -- All `run-image.mirrors`: - - SHOULD reference an image with ID identical to that of `run-image.image` -- `run-image.image` and `run-image.mirrors.[]` SHOULD each refer to a unique registry +- `image.image` MAY be a tag reference to a run image in an OCI registry +- `image.mirrors` MUST NOT be present if `image.image` is not present +- `image.mirrors` MAY contain one or more tag references to run images in OCI registries +- All `image.mirrors`: + - SHOULD reference an image with ID identical to that of `image.image` +- `image.image` and `image.mirrors.[]` SHOULD each refer to a unique registry ### Labels @@ -1296,13 +1301,10 @@ Where: } ], "runImage": { + "image": "cnbs/sample-stack-run:bionic", + "mirrors": = ["", ""], "topLayer": "", "reference": "" - }, - "stack": { - "runImage": { - "image": "cnbs/sample-stack-run:bionic" - } } } ``` @@ -1320,11 +1322,12 @@ Where: - The key MUST be the name of the layer - The value MUST contain JSON representation of the `layer.toml` with an additional `sha` key, containing the digest of the uncompressed layer - The value MUST contain an additional `sha` key, containing the digest of the uncompressed layer -- `run-image.topLayer` must contain the uncompressed digest of the top layer of the run-image -- `run-image.reference` MUST uniquely identify the run image. It MAY contain one of the following +- `runImage.image` MUST be a tag reference to the run-image +- `runImage.mirrors` MUST be selected from `run.toml` +- `runImage.topLayer` MUST contain the uncompressed digest of the top layer of the run-image +- `runImage.reference` MUST uniquely identify the run image. It MAY contain one of the following - An image ID (the digest of the uncompressed config blob) - A digest reference to a manifest stored in an OCI registry -- `stack` MUST contain the json representation of `stack.toml` #### `io.buildpacks.project.metadata` (JSON) From 7c905e171b756b687e44c8b037f98e7361281ddc Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Thu, 16 Feb 2023 13:11:46 -0500 Subject: [PATCH 21/67] Rename stack -> run Signed-off-by: Natalie Arellano --- platform.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform.md b/platform.md index afa5344..aa83975 100644 --- a/platform.md +++ b/platform.md @@ -296,7 +296,7 @@ Usage: | `` | `CNB_LOG_LEVEL` | `info` | Log Level | | `` | `CNB_PREVIOUS_IMAGE` | `` | Image reference to be analyzed (usually the result of the previous build) | | `` | `CNB_RUN_PATH` | `/cnb/run.toml` | Path to run file (see [`run.toml`](#runtoml-toml)) | -| `` | `CNB_RUN_IMAGE` | resolved from `` | Run image reference | +| `` | `CNB_RUN_IMAGE` | resolved from `` | Run image reference | | `` | `CNB_SKIP_LAYERS` | `false` | Do not restore SBOM layer from previous image | | `...` | | | Additional tag to apply to exported image | | `` | `CNB_USER_ID` | | UID of the build image `User` | From 4de1087877002be79b4ece4236dc659d25445df4 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Thu, 16 Feb 2023 13:13:43 -0500 Subject: [PATCH 22/67] Detector doesn't need run without run image extension Signed-off-by: Natalie Arellano --- platform.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/platform.md b/platform.md index aa83975..1799855 100644 --- a/platform.md +++ b/platform.md @@ -348,7 +348,6 @@ Usage: [-order ] \ [-plan ] \ [-platform ] \ - [-run ] ``` ##### Inputs @@ -365,7 +364,6 @@ Usage: | `` | `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_RUN_PATH` | `/cnb/run.toml` | Path to run file (see [`run.toml`](#runtoml-toml)) | ##### Outputs | Output | Description | From 538e1d0ca8ef1a17a85826744f95eca51cc59968 Mon Sep 17 00:00:00 2001 From: Pavel Busko Date: Tue, 28 Feb 2023 10:25:12 +0100 Subject: [PATCH 23/67] Enhanced run image resolution Co-authored-by: Ralf Pannemans Co-authored-by: Pavel Busko Signed-off-by: Ralf Pannemans --- platform.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/platform.md b/platform.md index d89ce04..c6e9004 100644 --- a/platform.md +++ b/platform.md @@ -948,8 +948,9 @@ The launcher: ### Run Image Resolution Given stack metadata containing `run-image.image` and a set of `run-image.mirrors`. The `` for a given `` shall be resolved as follows: -- **If** any of `run-image.image` or `run-image.mirrors` has a registry matching that of ``, this value will become the `` -- **If** none of `run-image.image` or `run-image.mirrors` has a registry matching that of ``, `` will become the `` +- **If** any of `run-image.image` or `run-image.mirrors` has a registry matching that of `` with read permissions, this value will become the `` +- **If** any of `run-image.image` or `run-image.mirrors` is accessible with read permissions and has a registry matching that of ``, this value will become the `` +- **If** none of `run-image.image` or `run-image.mirrors` has a registry matching that of ``, the first value of `` or `run-image.mirrors` that is accessible with read permissions will become the `` ### Registry Authentication From 905754ee5791b093828b17c3aa07f65066693fc6 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Thu, 2 Mar 2023 16:09:52 -0500 Subject: [PATCH 24/67] Rename image -> images In lists we pluralize Signed-off-by: Natalie Arellano --- platform.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/platform.md b/platform.md index 1799855..fc07f05 100644 --- a/platform.md +++ b/platform.md @@ -915,9 +915,9 @@ The launcher: ### Run Image Resolution Given [run](#runtoml-toml) metadata, the `` for a given `` shall be resolved as follows: -- From the matching `[[image]]`: - - **If** the tag reference for the run image is known (e.g., from a `-run-image` argument), the `[[image]]` with matching `image` - - **Else** the first `[[image]]` +- From the matching `[[images]]`: + - **If** the tag reference for the run image is known (e.g., from a `-run-image` argument), the `[[images]]` with matching `image` + - **Else** the first `[[images]]` - **If** any of `[image.image]` or `[image.mirrors]` has a registry matching that of ``, this value will become the `` - **If** none of `[image.image]` or `[image.mirrors]` has a registry matching that of ``, `[image.image]` will become the `` @@ -1205,7 +1205,7 @@ Where: #### `run.toml` (TOML) ```toml -[[image]] +[[images]] image = "" mirrors = ["", ""] ``` From 8a5929f3e5a945db2e060635e4f94f4eefe0d373 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Thu, 2 Mar 2023 16:09:52 -0500 Subject: [PATCH 25/67] Rename image -> images In lists we pluralize Signed-off-by: Natalie Arellano --- platform.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/platform.md b/platform.md index 77966f6..e7b2e33 100644 --- a/platform.md +++ b/platform.md @@ -1005,9 +1005,9 @@ The launcher: ### Run Image Resolution Given [run](#runtoml-toml) metadata, the `` for a given `` shall be resolved as follows: -- From the matching `[[image]]`: - - **If** the tag reference for the run image is known (e.g., from a `-run-image` argument), the `[[image]]` with matching `image` - - **Else** the first `[[image]]` +- From the matching `[[images]]`: + - **If** the tag reference for the run image is known (e.g., from a `-run-image` argument), the `[[images]]` with matching `image` + - **Else** the first `[[images]]` - **If** any of `[image.image]` or `[image.mirrors]` has a registry matching that of ``, this value will become the `` - **If** none of `[image.image]` or `[image.mirrors]` has a registry matching that of ``, `[image.image]` will become the `` @@ -1304,7 +1304,7 @@ Where: #### `run.toml` (TOML) ```toml -[[image]] +[[images]] image = "" mirrors = ["", ""] ``` From 7822f9a3d10804798de8d5fd645dc7a617bdf617 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 3 Mar 2023 11:59:25 -0500 Subject: [PATCH 26/67] Update platform.md Co-authored-by: Terence Lee Signed-off-by: Natalie Arellano --- platform.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform.md b/platform.md index fc07f05..079da69 100644 --- a/platform.md +++ b/platform.md @@ -1070,7 +1070,7 @@ Where: - `run-image.target` contains the [target data](#target-data) for the image - If target data is missing but the image contains the label `io.buildpacks.stack.id` with value `io.buildpacks.stacks.bionic`, the lifecycle SHALL assume the following values: - `run-image.target.os = "linux"` - - `run-image.target.arch = "x86_64"` + - `run-image.target.arch = "arm64"` - `run-image.target.distribution.name = "ubuntu"` - `run-image.target.distribution.version = "18.04"` From 9957239f0a03a942a40d21f456e7ce285c1aea4d Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 3 Mar 2023 12:16:42 -0500 Subject: [PATCH 27/67] Define base image and update TOC Signed-off-by: Natalie Arellano --- platform.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/platform.md b/platform.md index e7b2e33..a85125e 100644 --- a/platform.md +++ b/platform.md @@ -40,7 +40,7 @@ Examples of a platform might include: - [Inputs](#inputs-2) - [Outputs](#outputs-2) - [Layer Restoration](#layer-restoration) - - [`extender` (**experimental**)](#extender-experimental) + - [`extender` (optional and **experimental**)](#extender-optional-and-experimental) - [Inputs](#inputs-3) - [Outputs](#outputs-3) - [`builder`](#builder) @@ -104,6 +104,8 @@ Platform API versions: A **buildpack** refers to software compliant with the [Buildpack Interface Specification](buildpack.md). +A **base image** is an OCI image containing the base, or initial set of layers, for other images. + A **build image** is an OCI image that provides the base of the **build environment**. A **run image** is an OCI image that provides the base from which **app images** are built. @@ -203,7 +205,7 @@ The platform SHOULD ensure that: ### Compatibility Guarantees -- Base image authors SHOULD ensure that build image versions maintain [ABI-compatibility](https://en.wikipedia.org/wiki/Application_binary_interface) with previous versions, although violating this requirement will not change the behavior of previously built images containing app and launch layers. +- Base image authors SHOULD ensure that new build image versions maintain [ABI-compatibility](https://en.wikipedia.org/wiki/Application_binary_interface) with previous versions, although violating this requirement will not change the behavior of previously built images containing app and launch layers. - Base image authors MUST ensure that new run image versions maintain [ABI-compatibility](https://en.wikipedia.org/wiki/Application_binary_interface) with previous versions. - Base image authors MUST ensure that app and launch layers do not change behavior when the run image layers are upgraded to newer versions, unless those behavior changes are intended to fix security vulnerabilities. From 1b0ea79c1943ee15eb0010c2a8a5f48dde0fec22 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 3 Mar 2023 12:18:47 -0500 Subject: [PATCH 28/67] Init platform 0.12 Signed-off-by: Natalie Arellano --- README.md | 2 +- platform.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index df2f7ce..e20a0b8 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.12` diff --git a/platform.md b/platform.md index d89ce04..1dfa3c4 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.12`. Platform API versions: - MUST be in form `.` or ``, where `` is equivalent to `.0` From 381ee5390359ba7bd7d541173de49c9fa7e4e073 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 3 Mar 2023 12:28:49 -0500 Subject: [PATCH 29/67] Add back base image Signed-off-by: Natalie Arellano --- platform.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/platform.md b/platform.md index 2acc75d..e62b6de 100644 --- a/platform.md +++ b/platform.md @@ -103,6 +103,8 @@ Platform API versions: #### CNB Terminology A **buildpack** refers to software compliant with the [Buildpack Interface Specification](buildpack.md). +A **base image** is an OCI image containing the base, or initial set of layers, for other images. + A **build image** is an OCI image that provides the base of the **build environment**. A **run image** is an OCI image that provides the base from which **app images** are built. From 8efb92a3ff0d220ad501b72af12f620136fb56d7 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 3 Mar 2023 12:31:25 -0500 Subject: [PATCH 30/67] Update platform.md Signed-off-by: Natalie Arellano --- platform.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform.md b/platform.md index e62b6de..b04d2a1 100644 --- a/platform.md +++ b/platform.md @@ -792,7 +792,7 @@ Usage: - **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 be derived from the first ``. -- **If** `` is not provided by the platform, the value will be [resolved](#run-image-resolution) from the contents of the `runImage` key in the `io.buildpacks.lifecycle.metdata` label on `` +- **If** `` is not provided by the platform, the value will be [resolved](#run-image-resolution) from the contents of the `runImage` key in the `io.buildpacks.lifecycle.metdata` label on ``. - **If** `` is `true` the following values in the output `` config MUST be derived from the new ``, or else they MUST match the old run image if `` is `false`: - `os` - `architecture` From d3069b8611452056902f6bd725163a2dae241d7f Mon Sep 17 00:00:00 2001 From: Johannes Dillmann Date: Wed, 1 Mar 2023 10:13:38 +0100 Subject: [PATCH 31/67] Apply feedback on run image resolution Co-authored-by: Ralf Pannemans Signed-off-by: Ralf Pannemans --- platform.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/platform.md b/platform.md index c6e9004..c32d12c 100644 --- a/platform.md +++ b/platform.md @@ -948,9 +948,10 @@ The launcher: ### Run Image Resolution Given stack metadata containing `run-image.image` and a set of `run-image.mirrors`. The `` for a given `` shall be resolved as follows: -- **If** any of `run-image.image` or `run-image.mirrors` has a registry matching that of `` with read permissions, this value will become the `` -- **If** any of `run-image.image` or `run-image.mirrors` is accessible with read permissions and has a registry matching that of ``, this value will become the `` -- **If** none of `run-image.image` or `run-image.mirrors` has a registry matching that of ``, the first value of `` or `run-image.mirrors` that is accessible with read permissions will become the `` + +**If** any of `run-image.image` or `run-image.mirrors` has a registry matching that of `` and is accessible with read permissions, this value will become the ``. + +**If** none of `run-image.image` or `run-image.mirrors` has a registry matching that of ``, the first value of `` or `run-image.mirrors` that is accessible with read permissions will become the ``. ### Registry Authentication From e22d523b7bb3d0a950b75f81673f5fe75eb3a06a Mon Sep 17 00:00:00 2001 From: Juan Bustamante Date: Mon, 6 Feb 2023 15:21:56 -0500 Subject: [PATCH 32/67] Draft of the OCI layout spec changes Signed-off-by: Juan Bustamante --- platform.md | 61 +++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 43 insertions(+), 18 deletions(-) diff --git a/platform.md b/platform.md index d89ce04..d30021d 100644 --- a/platform.md +++ b/platform.md @@ -146,6 +146,10 @@ The following is a non-exhaustive list of terms defined in the [OCI Distribution * **registry** - https://github.com/opencontainers/distribution-spec/blob/main/spec.md#definitions +* **image manifest** provides a configuration and set of layers for a single container image for a specific architecture and operating system. + +* **OCI Image Layout** format is the [directory structure](https://github.com/opencontainers/image-spec/blob/main/image-layout.md) for OCI content-addressable blobs and [location-addressable](https://en.wikipedia.org/wiki/Content-addressable_storage#Content-addressed_vs._location-addressed) references. + ## Stacks A typical stack might specify: @@ -307,6 +311,7 @@ Usage: [-stack ] \ [-tag ...] \ [-uid ] \ + [-layout] \ # analize images in OCI layout format ``` @@ -320,6 +325,7 @@ Usage: | `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | `` | | | Tag reference to which the app image will be written | `` | `CNB_LAUNCH_CACHE_DIR`| | Path to a cache directory containing launch layers +| `` | `CNB_USE_OCI_LAYOUT` | false | Enables the capability of resolving image from/to in OCI layout format on disk| | `` | `CNB_LOG_LEVEL` | `info` | Log Level | ``| `CNB_PREVIOUS_IMAGE` | `` | Image reference to be analyzed (usually the result of the previous build) | `` | `CNB_RUN_IMAGE` | resolved from `` | Run image reference @@ -341,6 +347,7 @@ Usage: - The lifecycle MUST write [analysis metadata](#analyzedtoml-toml) to ``, where: - `image` MUST describe the ``, if accessible - `run-image` MUST describe the `` +- **If** `` is `true` the lifecycle MUST [resolve](#map-an-image-reference-into-a-path-in-the-layout-repository) `` and `` following the rules to convert the reference to a path ##### Outputs | Output | Description @@ -449,19 +456,20 @@ Usage: ``` ##### Inputs -| Input | Environment Variable | Default Value | Description | +| 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_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) | +| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | +| `` | `CNB_USE_OCI_LAYOUT` | false | Enables the capability of resolving image from/to in OCI layout format on disk| +| `` | `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 | @@ -473,10 +481,10 @@ 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 | +| Exit Code | Result| |-----------------|---------------------------------------| | `0` | Success | | `11` | Platform API incompatibility error | @@ -534,11 +542,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 | +| Output | Description | |----------------------|----------------------------------------| -| [exit status] | (see Exit Code table below for values) | -| `/dev/stdout` | Logs (info) | -| `/dev/stderr` | Logs (warnings, errors) | +| [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 | @@ -647,6 +655,7 @@ Usage: | `` | | `/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_USE_OCI_LAYOUT` | false | Enables the capability of resolving image from/to in OCI layout format on disk | | `` | `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) | @@ -654,7 +663,7 @@ Usage: | `` | `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 | +| | `SOURCE_DATE_EPOCH` | | Timestamp for `created` time in app image config | - At least one `` must be provided - Each `` MUST be a valid tag reference @@ -1075,6 +1084,18 @@ All app image labels SHOULD contain only reproducible values. For more information on build reproducibility see [https://reproducible-builds.org/](https://reproducible-builds.org/) +### Map an image reference into a path in the layout repository + +Considering an **image reference** refers to either a tag reference or digest reference. It could have the following formats +- A tag reference refers to an identifier of form `//:` +- A digest reference refers to a content addressable identifier of form `//@:` + +The image look up will be done following these rules: + - WHEN `the image points to a tag reference` + - Lifecycle will load/save the image from/to disk in [OCI Image Layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md) format at `////` + - WHEN `the image points to a digest reference` + - Lifecycle will load the image from disk in [OCI Image Layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md) format at `/////` + ## Data Format ### Files @@ -1097,7 +1118,11 @@ For more information on build reproducibility see [https://reproducible-builds.o Where: - `previous-image.reference` MUST be either a digest reference to an image in an OCI registry or the ID of an image in a docker daemon + - In case an image in [OCI Image Layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md) format is being used, it will also include the path of the image in OCI layout format following the rules describe [previously](#how-to-map-an-image-reference-into-a-path-in-the-layout-repository) + - The format MUST be as follows: `[path]@[digest]` - `run-image.reference` MUST be either a digest reference to an image in an OCI registry or the ID of an image in a docker daemon + - In case an image in [OCI Image Layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md) format is being used, it will also include the path of the image in OCI layout format following the rules describe [previously](#how-to-map-an-image-reference-into-a-path-in-the-layout-repository) + - The format MUST be as follows: `[path]@[digest]` - `previous-image.metadata` MUST be the TOML representation of the layer [metadata label](#iobuildpackslifecyclemetadata-json) #### `group.toml` (TOML) From c8d3936aa12c3b91ee28bc97e2bcf4a8dafec402 Mon Sep 17 00:00:00 2001 From: Juan Bustamante Date: Mon, 6 Feb 2023 15:38:18 -0500 Subject: [PATCH 33/67] Apply suggestions from code review Signed-off-by: Juan Bustamante --- platform.md | 58 ++++++++++++++++++++++++++--------------------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/platform.md b/platform.md index d30021d..23e89e0 100644 --- a/platform.md +++ b/platform.md @@ -311,7 +311,7 @@ Usage: [-stack ] \ [-tag ...] \ [-uid ] \ - [-layout] \ # analize images in OCI layout format + [-layout] \ # sets ``` @@ -325,7 +325,7 @@ Usage: | `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | `` | | | Tag reference to which the app image will be written | `` | `CNB_LAUNCH_CACHE_DIR`| | Path to a cache directory containing launch layers -| `` | `CNB_USE_OCI_LAYOUT` | false | Enables the capability of resolving image from/to in OCI layout format on disk| +| `` | `CNB_USE_LAYOUT` | false | Analyze image from OCI layout directory | | `` | `CNB_LOG_LEVEL` | `info` | Log Level | ``| `CNB_PREVIOUS_IMAGE` | `` | Image reference to be analyzed (usually the result of the previous build) | `` | `CNB_RUN_IMAGE` | resolved from `` | Run image reference @@ -456,20 +456,20 @@ Usage: ``` ##### Inputs -| Input | Environment Variable | Default Value | Description | +| 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_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_USE_OCI_LAYOUT` | false | Enables the capability of resolving image from/to in OCI layout format on disk| -| `` | `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) | +| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | +| `` | `CNB_USE_LAYOUT` | false Analyze image from OCI layout 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 | @@ -481,10 +481,10 @@ 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| +| Exit Code | Result | |-----------------|---------------------------------------| | `0` | Success | | `11` | Platform API incompatibility error | @@ -542,11 +542,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 | +| Output | Description | |----------------------|----------------------------------------| -| [exit status] | (see Exit Code table below for values) | -| `/dev/stdout` | Logs (info) | -| `/dev/stderr` | Logs (warnings, errors) | +| [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 | @@ -655,7 +655,7 @@ Usage: | `` | | `/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_USE_OCI_LAYOUT` | false | Enables the capability of resolving image from/to in OCI layout format on disk | +| `` | `CNB_USE_LAYOUT` | false | Analyze image from OCI layout 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) | @@ -663,7 +663,7 @@ Usage: | `` | `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 | +| | `SOURCE_DATE_EPOCH` | | Timestamp for `created` time in app image config | - At least one `` must be provided - Each `` MUST be a valid tag reference @@ -1084,17 +1084,17 @@ All app image labels SHOULD contain only reproducible values. For more information on build reproducibility see [https://reproducible-builds.org/](https://reproducible-builds.org/) -### Map an image reference into a path in the layout repository +### Map an image reference to a path in the layout directory -Considering an **image reference** refers to either a tag reference or digest reference. It could have the following formats +An **image reference** refers to either a **tag reference** or a **digest reference**: - A tag reference refers to an identifier of form `//:` - A digest reference refers to a content addressable identifier of form `//@:` -The image look up will be done following these rules: - - WHEN `the image points to a tag reference` - - Lifecycle will load/save the image from/to disk in [OCI Image Layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md) format at `////` - - WHEN `the image points to a digest reference` - - Lifecycle will load the image from disk in [OCI Image Layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md) format at `/////` +The image reference will be mapped to a path in the layout directory following these rules: + - **If** the image points to a tag reference: + - The path MUST be `////` + - **Else if** the image points to a digest reference: + - The path MUST be `/////` ## Data Format From f8c5409746cf7cd5865b77a233e540bd27b88223 Mon Sep 17 00:00:00 2001 From: Juan Bustamante Date: Mon, 13 Feb 2023 15:01:28 -0500 Subject: [PATCH 34/67] adding -layout-dir flag Signed-off-by: Juan Bustamante --- platform.md | 64 +++++++++++++++++++++++++++++++---------------------- 1 file changed, 38 insertions(+), 26 deletions(-) diff --git a/platform.md b/platform.md index 23e89e0..8bb02a7 100644 --- a/platform.md +++ b/platform.md @@ -304,6 +304,8 @@ Usage: [-gid ] \ [-launch-cache ] \ [-layers ] \ + [-layout] \ # sets + [-layout-dir] \ # sets [-log-level ] \ [-previous-image ] \ [-run-image ] \ @@ -311,28 +313,28 @@ Usage: [-stack ] \ [-tag ...] \ [-uid ] \ - [-layout] \ # sets ``` ##### Inputs -| Input | Environment Variable | Default Value | Description -|-------------------|-----------------------|--------------------------|---------------------- -| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) -| `` | `CNB_CACHE_IMAGE` | | Reference to a cache image in an OCI registry -| `` | `CNB_USE_DAEMON` | `false` | Analyze image from docker daemon -| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` -| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory -| `` | | | Tag reference to which the app image will be written -| `` | `CNB_LAUNCH_CACHE_DIR`| | Path to a cache directory containing launch layers -| `` | `CNB_USE_LAYOUT` | false | Analyze image from OCI layout directory | -| `` | `CNB_LOG_LEVEL` | `info` | Log Level -| ``| `CNB_PREVIOUS_IMAGE` | `` | Image reference to be analyzed (usually the result of the previous build) -| `` | `CNB_RUN_IMAGE` | resolved from `` | Run image reference -| `` | `CNB_SKIP_LAYERS` | `false` | Do not restore SBOM layer from previous image -| `` | `CNB_STACK_PATH` | `/cnb/stack.toml` | Path to stack file (see [`stack.toml`](#stacktoml-toml)) -| `...` | | | Additional tag to apply to exported image -| `` | `CNB_USER_ID` | | UID of the build image `User` +| Input | Environment Variable | Default Value | Description +|-------------------|------------------------|--------------------------|----------------------------------------------------------------------------- +| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) +| `` | `CNB_CACHE_IMAGE` | | Reference to a cache image in an OCI registry +| `` | `CNB_USE_DAEMON` | `false` | Analyze image from docker daemon +| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` +| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory +| `` | | | Tag reference to which the app image will be written +| `` | `CNB_LAUNCH_CACHE_DIR` | | Path to a cache directory containing launch layers +| `` (**experimental**) | `CNB_USE_LAYOUT` | false | Analyze image from OCI layout directory +| `` (**experimental**) | `CNB_LAYOUT_DIR` | | Path to a directory where the images are saved in OCI layout format +| `` | `CNB_LOG_LEVEL` | `info` | Log Level +| ``| `CNB_PREVIOUS_IMAGE` | `` | Image reference to be analyzed (usually the result of the previous build) +| `` | `CNB_RUN_IMAGE` | resolved from `` | Run image reference +| `` | `CNB_SKIP_LAYERS` | `false` | Do not restore SBOM layer from previous image +| `` | `CNB_STACK_PATH` | `/cnb/stack.toml` | Path to stack file (see [`stack.toml`](#stacktoml-toml)) +| `...` | | | Additional tag to apply to exported image +| `` | `CNB_USER_ID` | | UID of the build image `User` -`` MUST be a valid image reference - **If** the platform provides one or more `` inputs, each `` MUST be a valid image reference. @@ -450,6 +452,8 @@ Usage: [-gid ] \ [-group ] \ [-layers ] \ + [-layout] \ # sets + [-layout-dir] \ # sets [-log-level ] \ [-skip-layers ] \ [-uid ] @@ -466,7 +470,8 @@ Usage: | `` | `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_USE_LAYOUT` | false Analyze image from OCI layout directory | +| `` (**experimental**) | `CNB_USE_LAYOUT` | false Analyze image from OCI layout directory | +| `` (**experimental**) | `CNB_LAYOUT_DIR` | | Path to a directory where the images are saved in OCI layout format | | `` | `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) | @@ -631,6 +636,8 @@ Usage: [-launcher ] \ [-launcher-sbom ] \ [-layers ] \ + [-layout] \ # sets + [-layout-dir] \ # sets [-log-level ] \ [-process-type ] \ [-project-metadata ] \ @@ -655,7 +662,8 @@ Usage: | `` | | `/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_USE_LAYOUT` | false | Analyze image from OCI layout directory | +| `` (**experimental**) | `CNB_USE_LAYOUT` | false | Analyze image from OCI layout directory | +| `` (**experimental**) | `CNB_LAYOUT_DIR` | | Path to a directory where the images are saved in OCI layout format | | `` | `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) | @@ -750,6 +758,8 @@ Usage: [-launch-cache ] \ [-launcher ] \ [-layers ] \ + [-layout] \ # sets + [-layout-dir] \ # sets [-log-level ] \ [-order ] \ [-platform ] \ @@ -1117,12 +1127,14 @@ The image reference will be mapped to a path in the layout directory following t ``` Where: -- `previous-image.reference` MUST be either a digest reference to an image in an OCI registry or the ID of an image in a docker daemon - - In case an image in [OCI Image Layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md) format is being used, it will also include the path of the image in OCI layout format following the rules describe [previously](#how-to-map-an-image-reference-into-a-path-in-the-layout-repository) - - The format MUST be as follows: `[path]@[digest]` -- `run-image.reference` MUST be either a digest reference to an image in an OCI registry or the ID of an image in a docker daemon - - In case an image in [OCI Image Layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md) format is being used, it will also include the path of the image in OCI layout format following the rules describe [previously](#how-to-map-an-image-reference-into-a-path-in-the-layout-repository) - - The format MUST be as follows: `[path]@[digest]` +- `previous-image.reference` MUST be either: + - A digest reference to an image in an OCI registry + - The ID of an image in a docker daemon + - The path to an image in OCI layout format +- `run-image.reference` MUST be either: + - A digest reference to an image in an OCI registry + - The ID of an image in a docker daemon + - The path to an image in OCI layout format - `previous-image.metadata` MUST be the TOML representation of the layer [metadata label](#iobuildpackslifecyclemetadata-json) #### `group.toml` (TOML) From 9a967d2c8a3002305ae41df67886b443df2f4c17 Mon Sep 17 00:00:00 2001 From: Juan Bustamante Date: Mon, 13 Feb 2023 15:05:08 -0500 Subject: [PATCH 35/67] adding -layout-dir flag Signed-off-by: Juan Bustamante --- platform.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/platform.md b/platform.md index 8bb02a7..8c427ec 100644 --- a/platform.md +++ b/platform.md @@ -317,24 +317,24 @@ Usage: ``` ##### Inputs -| Input | Environment Variable | Default Value | Description -|-------------------|------------------------|--------------------------|----------------------------------------------------------------------------- -| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) -| `` | `CNB_CACHE_IMAGE` | | Reference to a cache image in an OCI registry -| `` | `CNB_USE_DAEMON` | `false` | Analyze image from docker daemon -| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` -| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory -| `` | | | Tag reference to which the app image will be written -| `` | `CNB_LAUNCH_CACHE_DIR` | | Path to a cache directory containing launch layers +| Input | Environment Variable | Default Value | Description +|-------------------|-----------------------|--------------------------|---------------------- +| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) +| `` | `CNB_CACHE_IMAGE` | | Reference to a cache image in an OCI registry +| `` | `CNB_USE_DAEMON` | `false` | Analyze image from docker daemon +| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` +| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory +| `` | | | Tag reference to which the app image will be written +| `` | `CNB_LAUNCH_CACHE_DIR`| | Path to a cache directory containing launch layers | `` (**experimental**) | `CNB_USE_LAYOUT` | false | Analyze image from OCI layout directory -| `` (**experimental**) | `CNB_LAYOUT_DIR` | | Path to a directory where the images are saved in OCI layout format -| `` | `CNB_LOG_LEVEL` | `info` | Log Level -| ``| `CNB_PREVIOUS_IMAGE` | `` | Image reference to be analyzed (usually the result of the previous build) -| `` | `CNB_RUN_IMAGE` | resolved from `` | Run image reference -| `` | `CNB_SKIP_LAYERS` | `false` | Do not restore SBOM layer from previous image -| `` | `CNB_STACK_PATH` | `/cnb/stack.toml` | Path to stack file (see [`stack.toml`](#stacktoml-toml)) -| `...` | | | Additional tag to apply to exported image -| `` | `CNB_USER_ID` | | UID of the build image `User` +| `` (**experimental**) | `CNB_LAYOUT_DIR` | | Path to a directory where the images are saved in OCI layout format +| `` | `CNB_LOG_LEVEL` | `info` | Log Level +| ``| `CNB_PREVIOUS_IMAGE` | `` | Image reference to be analyzed (usually the result of the previous build) +| `` | `CNB_RUN_IMAGE` | resolved from `` | Run image reference +| `` | `CNB_SKIP_LAYERS` | `false` | Do not restore SBOM layer from previous image +| `` | `CNB_STACK_PATH` | `/cnb/stack.toml` | Path to stack file (see [`stack.toml`](#stacktoml-toml)) +| `...` | | | Additional tag to apply to exported image +| `` | `CNB_USER_ID` | | UID of the build image `User` -`` MUST be a valid image reference - **If** the platform provides one or more `` inputs, each `` MUST be a valid image reference. From 24b950d6e8e3df780e58b4ac723f61f382c09e0b Mon Sep 17 00:00:00 2001 From: Juan Bustamante Date: Mon, 27 Mar 2023 15:38:28 -0500 Subject: [PATCH 36/67] reviewing and making some fix before undraft the PR Signed-off-by: Juan Bustamante --- platform.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/platform.md b/platform.md index 8c427ec..5a342f5 100644 --- a/platform.md +++ b/platform.md @@ -326,8 +326,8 @@ Usage: | `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | `` | | | Tag reference to which the app image will be written | `` | `CNB_LAUNCH_CACHE_DIR`| | Path to a cache directory containing launch layers -| `` (**experimental**) | `CNB_USE_LAYOUT` | false | Analyze image from OCI layout directory -| `` (**experimental**) | `CNB_LAYOUT_DIR` | | Path to a directory where the images are saved in OCI layout format +| `` | `CNB_USE_LAYOUT` | false | (**[experimental](#experimental-features)**) Analyze image from disk in OCI layout format +| `` | `CNB_LAYOUT_DIR` | | (**[experimental](#experimental-features)**) Path to a root directory where the images are saved in OCI layout format | `` | `CNB_LOG_LEVEL` | `info` | Log Level | ``| `CNB_PREVIOUS_IMAGE` | `` | Image reference to be analyzed (usually the result of the previous build) | `` | `CNB_RUN_IMAGE` | resolved from `` | Run image reference @@ -349,7 +349,7 @@ Usage: - The lifecycle MUST write [analysis metadata](#analyzedtoml-toml) to ``, where: - `image` MUST describe the ``, if accessible - `run-image` MUST describe the `` -- **If** `` is `true` the lifecycle MUST [resolve](#map-an-image-reference-into-a-path-in-the-layout-repository) `` and `` following the rules to convert the reference to a path +- **If** `` is `true`, `` MUST be provided and the lifecycle MUST [resolve](#map-an-image-reference-to-a-path-in-the-layout-directory) `` and `` following the rules to convert the reference to a path ##### Outputs | Output | Description @@ -452,8 +452,6 @@ Usage: [-gid ] \ [-group ] \ [-layers ] \ - [-layout] \ # sets - [-layout-dir] \ # sets [-log-level ] \ [-skip-layers ] \ [-uid ] @@ -470,8 +468,6 @@ Usage: | `` | `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 | -| `` (**experimental**) | `CNB_USE_LAYOUT` | false Analyze image from OCI layout directory | -| `` (**experimental**) | `CNB_LAYOUT_DIR` | | Path to a directory where the images are saved in OCI layout format | | `` | `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) | @@ -662,8 +658,8 @@ Usage: | `` | | `/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 | -| `` (**experimental**) | `CNB_USE_LAYOUT` | false | Analyze image from OCI layout directory | -| `` (**experimental**) | `CNB_LAYOUT_DIR` | | Path to a directory where the images are saved in OCI layout format | +| `` | `CNB_USE_LAYOUT` | false | (**[experimental](#experimental-features)**) Export image to disk in OCI layout format | +| `` | `CNB_LAYOUT_DIR` | | (**[experimental](#experimental-features)**) Path to a root directory where the images are saved in OCI layout format | | `` | `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) | @@ -743,6 +739,9 @@ Usage: - 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 +- **If** `` is `true` the lifecycle: + - SHALL write the app image on disk following the [rules](#map-an-image-reference-to-a-path-in-the-layout-directory) to convert the reference to a path + #### `creator` The platform MUST execute `creator` in the **build environment** From 417b853ebac06e4b7cb97854432fef907b421bf5 Mon Sep 17 00:00:00 2001 From: Hernan Garcia Date: Wed, 10 May 2023 11:07:30 -0500 Subject: [PATCH 37/67] add lifecycle output to update stack after rebase Signed-off-by: Hernan Garcia --- platform.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/platform.md b/platform.md index f5de11d..520c33b 100644 --- a/platform.md +++ b/platform.md @@ -822,7 +822,7 @@ Usage: | [exit status] | (see Exit Code table below for values) | `/dev/stdout` | Logs (info) | `/dev/stderr` | Logs (warnings, errors) -| `` | Rebased app image (see [Buildpack Interface Specfication](buildpack.md) +| `` | Rebased app image (see [Buildpack Interface Specfication](buildpack.md)) | Exit Code | Result| |-----------|-------| @@ -840,6 +840,8 @@ Usage: - `run-image.reference` SHALL uniquely identify `` - `run-image.top-layer` SHALL be set to the uncompressed digest of the top layer in `` - The value of `io.buildpacks.stack.*` labels SHALL be modified to that of the new `run-image` + - `stack.run-image.image` SHALL uniquely identify `` + - `stack.run-image.mirrors` SHALL be EMPTY - To ensure [build reproducibility](#build-reproducibility), the lifecycle: - SHOULD set the `created` time in image config to a constant From c05b08eefc01e2ab5742ccdc313ebd68a325f5c6 Mon Sep 17 00:00:00 2001 From: Hernan Garcia Date: Tue, 16 May 2023 09:38:34 -0500 Subject: [PATCH 38/67] Update platform.md Co-authored-by: Natalie Arellano Signed-off-by: Hernan Garcia --- platform.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/platform.md b/platform.md index 520c33b..f0053db 100644 --- a/platform.md +++ b/platform.md @@ -840,8 +840,9 @@ Usage: - `run-image.reference` SHALL uniquely identify `` - `run-image.top-layer` SHALL be set to the uncompressed digest of the top layer in `` - The value of `io.buildpacks.stack.*` labels SHALL be modified to that of the new `run-image` - - `stack.run-image.image` SHALL uniquely identify `` - - `stack.run-image.mirrors` SHALL be EMPTY +- **If** the provided `` is not found in `stack.run-image.image` or `stack.run-image.mirrors`: + - `stack.run-image.image` SHALL be the provided `` + - `stack.run-image.mirrors` SHALL be omitted - To ensure [build reproducibility](#build-reproducibility), the lifecycle: - SHOULD set the `created` time in image config to a constant From fb093a37ff2204c601573e56daa917b9c0468904 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 23 May 2023 12:18:11 -0400 Subject: [PATCH 39/67] Update platform.md Signed-off-by: Natalie Arellano --- platform.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform.md b/platform.md index b04d2a1..d14961b 100644 --- a/platform.md +++ b/platform.md @@ -792,7 +792,7 @@ Usage: - **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 be derived from the first ``. -- **If** `` is not provided by the platform, the value will be [resolved](#run-image-resolution) from the contents of the `runImage` key in the `io.buildpacks.lifecycle.metdata` label on ``. +- **If** `` is not provided by the platform, the value will be [resolved](#run-image-resolution) from the contents of the `runImage` key in the `io.buildpacks.lifecycle.metdata` label on ``, or `stack.runImage` if not found (for compatibility with older platforms). - **If** `` is `true` the following values in the output `` config MUST be derived from the new ``, or else they MUST match the old run image if `` is `false`: - `os` - `architecture` From 8422bfedfda3407dda493ee33db10047377b7d37 Mon Sep 17 00:00:00 2001 From: Hernan Garcia Date: Tue, 23 May 2023 11:44:25 -0500 Subject: [PATCH 40/67] Update platform.md Co-authored-by: Natalie Arellano Signed-off-by: Hernan Garcia --- platform.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/platform.md b/platform.md index 13a426b..46a9551 100644 --- a/platform.md +++ b/platform.md @@ -825,8 +825,8 @@ Usage: - `run-image.top-layer` SHALL be set to the uncompressed digest of the top layer in `` - The value of `io.buildpacks.stack.*` labels SHALL be modified to that of the new `run-image` - **If** the provided `` is not found in `stack.run-image.image` or `stack.run-image.mirrors`: - - `stack.run-image.image` SHALL be the provided `` - - `stack.run-image.mirrors` SHALL be omitted + - `run-image.image` SHALL be the provided `` + - `run-image.mirrors` SHALL be omitted - To ensure [build reproducibility](#build-reproducibility), the lifecycle: - SHOULD set the `created` time in image config to a constant From 32be97287fed1d2e29bcce2c6f9272f367c76767 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Wed, 31 May 2023 17:37:12 -0400 Subject: [PATCH 41/67] Update platform.md Signed-off-by: Natalie Arellano --- platform.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform.md b/platform.md index 46a9551..a9e6809 100644 --- a/platform.md +++ b/platform.md @@ -824,7 +824,7 @@ Usage: - `run-image.reference` SHALL uniquely identify `` - `run-image.top-layer` SHALL be set to the uncompressed digest of the top layer in `` - The value of `io.buildpacks.stack.*` labels SHALL be modified to that of the new `run-image` -- **If** the provided `` is not found in `stack.run-image.image` or `stack.run-image.mirrors`: +- **If** the provided `` is not found in `runImage.image` or `runImage.mirrors`: - `run-image.image` SHALL be the provided `` - `run-image.mirrors` SHALL be omitted - To ensure [build reproducibility](#build-reproducibility), the lifecycle: From 8f6c0282cc89efe51578c62b763ba0da097928d9 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 5 Jun 2023 10:34:32 -0400 Subject: [PATCH 42/67] Apply suggestions from code review Signed-off-by: Natalie Arellano --- platform.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/platform.md b/platform.md index a85125e..7e5917b 100644 --- a/platform.md +++ b/platform.md @@ -426,12 +426,12 @@ When image extensions are present in the order (optional and **[experimental](#e - **Else** the selected run image SHALL be the last image referenced in the `FROM` statement of the last `run.Dockerfile` not to declare `FROM ${base_image}` - `run-image.image` SHALL be the name of the selected run image - `run-image.reference` and `run-image.target` SHALL be cleared (as they may no longer be accurate) - - All preceding `run.Dockerfile`s SHALL be renamed `run.Dockerfile.ignore` + - All preceding `run.Dockerfile`s SHALL be copied to `` with suffix `.ignore` - **If** there are no `run.Dockerfile`s following the Dockerfile with the selected run image: - `run-image.extend` SHALL be `false` - **Else** - `run-image.extend` SHALL be `true` -- SHALL fail if the selected run image is not found in `` +- SHALL warn if the selected run image is not found in `` #### `restorer` @@ -442,7 +442,6 @@ Usage: [-build-image ] \ [-cache-dir ] \ [-cache-image ] \ - [-generated ] \ [-gid ] \ [-group ] \ [-layers ] \ @@ -459,7 +458,6 @@ Usage: | ``* | `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_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_LAYERS_DIR` | `/layers` | Path to layers directory | @@ -497,11 +495,11 @@ Usage: - 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. - **Else** the lifecycle MUST perform [layer restoration](#layer-restoration) for any app image layers or cached layers created by any buildpack present in the provided ``. -- When `/build` contains Dockerfiles (optional and **[experimental](#experimental-features)**), the lifecycle: +- When `` is provided (optional and **[experimental](#experimental-features)**), the lifecycle: - MUST record the digest reference to the provided `` in `` - MUST copy the OCI manifest and config file for `` to `/cache` -- When `/run` contains Dockerfiles, the lifecycle: - - MUST resolve `run-image.reference` to a digest in `` if not present +- The lifecycle: + - MUST resolve `run-image.reference` to a digest reference in `` if not present - MUST populate `run-image.target` data in `` if not present - **If** `` has `run-image.extend = true`, the lifecycle: - MUST download from the registry and save in OCI layout format the `run-image` in `` to `/cache` @@ -588,7 +586,7 @@ When extending the build image: - When extending the run image, after all `run.Dockefile`s are applied, the lifecycle: - **If** any `run.Dockerfile` set the label `io.buildpacks.rebasable` to `false` or left the label unset: - SHALL set the label `io.buildpacks.rebasable` to `false` on the extended run image - - SHALL copy the manifest and config for the extended run image, along with any new layers, to `` + - SHALL copy the manifest and config for the extended run image, along with any new layers, to ``/run #### `builder` @@ -721,7 +719,7 @@ Usage: - The lifecycle SHALL write the same app image to each `` tag - The app image: - **If** image extensions were used to extend the `run-image` in [`analyzed.toml`](#analyzedtoml-toml): - - MUST be based on the image in `` + - MUST be based on the image in ``/run - **Else**: - MUST be based on the `run-image` in [`analyzed.toml`](#analyzedtoml-toml) - All base image layers and any extension layers SHALL be preserved @@ -753,7 +751,7 @@ Usage: - `io.buildpacks.lifecycle.metadata`: see [lifecycle metadata label](#iobuildpackslifecyclemetadata-json) - `io.buildpacks.project.metadata`: the value of which SHALL be the json representation of `` - `io.buildpacks.build.metadata`: see [build metadata](#iobuildpacksbuildmetadata-json) - - **If** image extensions were used to extend the run image and `/` has the label `io.buildpacks.rebasable` set to `true`: + - **If** image extensions were used to extend the run image and `/run/` has the label `io.buildpacks.rebasable` set to `true`: - `io.buildpacks.rebasable` SHALL be `true` - **Else** - `io.buildpacks.rebasable` SHALL be `false` From 46dc116a3b8810bc29757f73295409435f112f12 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 5 Jun 2023 10:40:51 -0400 Subject: [PATCH 43/67] Apply suggestions from code review Signed-off-by: Natalie Arellano --- platform.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform.md b/platform.md index 5cd8fdc..d2ba659 100644 --- a/platform.md +++ b/platform.md @@ -1101,7 +1101,7 @@ Where: - `run-image.reference` MUST be either a digest reference to an image in an OCI registry or the ID of an image in a docker daemon - `run-image.target.id` is optional and MUST be the value of the label `io.buildpacks.id` - `run-image.target` contains the [target data](#target-data) for the image - - If target data is missing but the image contains the label `io.buildpacks.stack.id` with value `io.buildpacks.stacks.bionic`, the lifecycle SHALL assume the following values: + - If target distribution data is missing, it will be inferred from `/etc/os-release` for Linux images; furthermore, if the image contains the label `io.buildpacks.stack.id` with value `io.buildpacks.stacks.bionic`, the lifecycle SHALL assume the following values: - `run-image.target.os = "linux"` - `run-image.target.arch = "arm64"` - `run-image.target.distribution.name = "ubuntu"` From 1fe9fd48afe3418ba1b7b67c2c039360a1c1ba25 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 5 Jun 2023 10:41:06 -0400 Subject: [PATCH 44/67] Added -analyzed to builder Signed-off-by: Natalie Arellano --- platform.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/platform.md b/platform.md index d2ba659..6d87c86 100644 --- a/platform.md +++ b/platform.md @@ -536,6 +536,7 @@ The platform MUST execute `builder` in the **build environment** Usage: ``` /cnb/lifecycle/builder \ + [-analyzed ] \ [-app ] \ [-buildpacks ] \ [-build-config ] \ @@ -547,16 +548,17 @@ 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_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_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 @@ -578,6 +580,7 @@ Usage: | `50`, `52-59`| Build-specific lifecycle errors - The lifecycle SHALL execute all buildpacks in the order defined in `` according to the process outlined in the [Buildpack Interface Specification](buildpack.md). +- SHALL provide `run-image.target` data in `` to buildpacks according to the process outlined in the [Buildpack Interface Specification](buildpack.md). - The lifecycle SHALL add all invoked buildpacks to`/config/metadata.toml`. - The lifecycle SHALL aggregate all `processes` and `slices` returned by buildpacks in `/config/metadata.toml`. - The lifecycle SHALL record the buildpack-provided default process type in `/config/metadata.toml`. From 31dd9c3c94ea5c5ea005af047b9cc6563f13c768 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 5 Jun 2023 12:35:14 -0400 Subject: [PATCH 45/67] `stack` key is deprecated. Signed-off-by: Natalie Arellano --- platform.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/platform.md b/platform.md index f01911a..02595bf 100644 --- a/platform.md +++ b/platform.md @@ -1386,3 +1386,24 @@ Where: } ``` This label MUST contain the JSON representation of [`project-metadata.toml`](#project-metadatatoml-toml) + + +## Deprecations +This section describes all the features that are deprecated. + +### `io.buildpacks.lifecycle.metadata` (JSON) `stack` Key + +_Deprecated in Platform API 0.12._ + +The `stack` key is deprecated. + +```json + "stack": { + "runImage": { + "image": "cnbs/sample-stack-run:bionic", + "mirrors": = ["", ""] + } + } +``` + +To upgrade, platform operators SHOULD read the same information from the `runImage` key. From a29f7fea62891f46da7c10c0f0e7f377702cb6a4 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 5 Jun 2023 12:57:28 -0400 Subject: [PATCH 46/67] Apply suggestions from code review Signed-off-by: Natalie Arellano --- platform.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform.md b/platform.md index 02595bf..d687678 100644 --- a/platform.md +++ b/platform.md @@ -350,7 +350,7 @@ Usage: [-log-level ] \ [-order ] \ [-plan ] \ - [-platform ] \ + [-platform ] ``` ##### Inputs From 2e06dd6c3b395c674584e94c3b5c66c255060e0a Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 5 Jun 2023 13:00:38 -0400 Subject: [PATCH 47/67] Add more deprecations Signed-off-by: Natalie Arellano --- platform.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/platform.md b/platform.md index d687678..31bfbcd 100644 --- a/platform.md +++ b/platform.md @@ -1391,6 +1391,16 @@ This label MUST contain the JSON representation of [`project-metadata.toml`](#pr ## Deprecations This section describes all the features that are deprecated. +### `io.buildpacks.stack.*` Labels + +For compatibility with older platforms and older buildpacks, base image authors SHOULD ensure for build images and run images: + +- The image config's `Env` field has the environment variable `CNB_STACK_ID` set to the stack ID. +- The image config's `Label` field has the label `io.buildpacks.stack.id` set to the stack ID. +- The image config's `Label` field has the label `io.buildpacks.stack.mixins` set to a JSON array containing mixin names for each mixin applied to the image. + +To upgrade, the platform SHOULD upgrade all buildpacks to use Buildpack API `0.10` or greater. + ### `io.buildpacks.lifecycle.metadata` (JSON) `stack` Key _Deprecated in Platform API 0.12._ @@ -1401,9 +1411,9 @@ The `stack` key is deprecated. "stack": { "runImage": { "image": "cnbs/sample-stack-run:bionic", - "mirrors": = ["", ""] + "mirrors": ["", ""] } } ``` -To upgrade, platform operators SHOULD read the same information from the `runImage` key. +To upgrade, the platform SHOULD read the same information from the `runImage` key. From 9741479b7f8bb5f0a93bbe2b6b292aae52f8be13 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 5 Jun 2023 13:01:32 -0400 Subject: [PATCH 48/67] Add when labels were deprecated Signed-off-by: Natalie Arellano --- platform.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/platform.md b/platform.md index 31bfbcd..8266a20 100644 --- a/platform.md +++ b/platform.md @@ -1393,6 +1393,8 @@ This section describes all the features that are deprecated. ### `io.buildpacks.stack.*` Labels +_Deprecated in Platform API 0.12._ + For compatibility with older platforms and older buildpacks, base image authors SHOULD ensure for build images and run images: - The image config's `Env` field has the environment variable `CNB_STACK_ID` set to the stack ID. From a2d78bb626ad0051ff9c65244e190948f5119c1e Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 6 Jun 2023 11:00:16 -0400 Subject: [PATCH 49/67] Add more information in deprecations Also update table of contents Signed-off-by: Natalie Arellano --- platform.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/platform.md b/platform.md index 8266a20..0b69910 100644 --- a/platform.md +++ b/platform.md @@ -72,6 +72,7 @@ Examples of a platform might include: - [Buildpack Environment](#buildpack-environment) - [Base Image-Provided Variables](#base-image-provided-variables) - [User-Provided Variables](#user-provided-variables) + - [Operator-Defined Variables](#operator-defined-variables) - [Launch Environment](#launch-environment) - [Caching](#caching) - [Build Reproducibility](#build-reproducibility) @@ -89,6 +90,9 @@ Examples of a platform might include: - [`io.buildpacks.build.metadata` (JSON)](#iobuildpacksbuildmetadata-json) - [`io.buildpacks.lifecycle.metadata` (JSON)](#iobuildpackslifecyclemetadata-json) - [`io.buildpacks.project.metadata` (JSON)](#iobuildpacksprojectmetadata-json) + - [Deprecations](#deprecations) + - [`io.buildpacks.stack.*` Labels](#iobuildpacksstack-labels) + - [`io.buildpacks.lifecycle.metadata` (JSON) `stack` Key](#iobuildpackslifecyclemetadata-json-stack-key) ## Platform API Version @@ -125,6 +129,8 @@ The **launcher** refers to a lifecycle executable packaged in the **app image** 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. +A **stack** (deprecated, see [deprecations](#deprecations)) is a contract, implemented by a **build image** and **run image**, that guarantees properties of the **build environment** and **app image**. + #### Additional Terminology An **image reference** refers to either a **tag reference** or **digest reference**. @@ -143,7 +149,7 @@ The following is a non-exhaustive list of terms defined in the [OCI Distribution ### Build Image -A typical build image might specify: +A typical build image might determine: * The OS distro in the build environment. * OS packages installed in the build environment. * Trusted CA certificates in the build environment. @@ -166,7 +172,7 @@ The platform SHOULD ensure that: ### Run Image -A typical run image might specify: +A typical run image might determine: * The OS distro or distroless OS in the launch environment. * OS packages installed in the launch environment. * Trusted CA certificates in the launch environment. @@ -795,7 +801,7 @@ Usage: - **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 be derived from the first ``. -- **If** `` is not provided by the platform, the value will be [resolved](#run-image-resolution) from the contents of the `runImage` key in the `io.buildpacks.lifecycle.metdata` label on ``, or `stack.runImage` if not found (for compatibility with older platforms). +- **If** `` is not provided by the platform, the value will be [resolved](#run-image-resolution) from the contents of the `runImage` key in the `io.buildpacks.lifecycle.metdata` label on ``, or `stack.runImage` if not found (for compatibility with older platforms; see [deprecations](#deprecations)). - **If** `` is `true` the following values in the output `` config MUST be derived from the new ``, or else they MUST match the old run image if `` is `false`: - `os` - `architecture` @@ -1401,6 +1407,8 @@ For compatibility with older platforms and older buildpacks, base image authors - The image config's `Label` field has the label `io.buildpacks.stack.id` set to the stack ID. - The image config's `Label` field has the label `io.buildpacks.stack.mixins` set to a JSON array containing mixin names for each mixin applied to the image. +Where `CNB_STACK_ID` SHALL be directly inherited by buildpacks without modification. + To upgrade, the platform SHOULD upgrade all buildpacks to use Buildpack API `0.10` or greater. ### `io.buildpacks.lifecycle.metadata` (JSON) `stack` Key @@ -1418,4 +1426,6 @@ The `stack` key is deprecated. } ``` -To upgrade, the platform SHOULD read the same information from the `runImage` key. +Where `stack` MUST contain the same data as the top-level `runImage` key. + +To upgrade, the platform SHOULD read the same information from the top-level `runImage` key. From f2b87a29c1622cbf29e388975a602f92fdf6cf08 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 6 Jun 2023 11:03:32 -0400 Subject: [PATCH 50/67] Wording Signed-off-by: Natalie Arellano --- platform.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform.md b/platform.md index 0b69910..696d00d 100644 --- a/platform.md +++ b/platform.md @@ -1428,4 +1428,4 @@ The `stack` key is deprecated. Where `stack` MUST contain the same data as the top-level `runImage` key. -To upgrade, the platform SHOULD read the same information from the top-level `runImage` key. +To upgrade, the platform SHOULD read the top-level `runImage` key instead. From 22ceb7f91029d80016428f79d85504987d893c84 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 13 Jun 2023 13:07:42 -0400 Subject: [PATCH 51/67] Apply suggestions from code review Signed-off-by: Natalie Arellano --- platform.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform.md b/platform.md index 696d00d..162e9d0 100644 --- a/platform.md +++ b/platform.md @@ -185,7 +185,7 @@ The platform MUST ensure that: The platform SHOULD ensure that: - The image config's `User` field is set to a user with a **DIFFERENT** user [†](README.md#operating-system-conventions)UID/[‡](README.md#operating-system-conventions)SID as the build image. -- The image config's `Label` field has the label `io.buildpacks.id` set to the target ID (e.g., "minimal") of the image. +- The image config's `Label` field has the label `io.buildpacks.id` set to the target ID (e.g., "minimal") of the run image. - The image config's `Label` field has the label `io.buildpacks.base.maintainer` set to the name of the image maintainer. - The image config's `Label` field has the label `io.buildpacks.base.homepage` set to the homepage of the image. - The image config's `Label` field has the label `io.buildpacks.base.released` set to the release date of the image. From 2caf4d641315bf471a2aaab917ea7cd9896fae69 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 13 Jun 2023 13:10:43 -0400 Subject: [PATCH 52/67] Update labels to update during rebase Signed-off-by: Natalie Arellano --- platform.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform.md b/platform.md index 162e9d0..7ebae5a 100644 --- a/platform.md +++ b/platform.md @@ -832,7 +832,7 @@ Usage: - The value of `io.buildpacks.lifecycle.metadata` SHALL be modified as follows - `run-image.reference` SHALL uniquely identify `` - `run-image.top-layer` SHALL be set to the uncompressed digest of the top layer in `` - - The value of `io.buildpacks.stack.*` labels SHALL be modified to that of the new `run-image` + - The value of `io.buildpacks.base.*` labels and `io.buildpacks.stack.*` labels (if present) SHALL be modified to that of the new `run-image` - **If** the provided `` is not found in `runImage.image` or `runImage.mirrors`: - `run-image.image` SHALL be the provided `` - `run-image.mirrors` SHALL be omitted From 910c3de050af5024d11e9643fa71ee91df0c627f Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Wed, 14 Jun 2023 13:55:57 -0400 Subject: [PATCH 53/67] Update platform.md Signed-off-by: Natalie Arellano --- platform.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/platform.md b/platform.md index 76d66c0..2988e02 100644 --- a/platform.md +++ b/platform.md @@ -591,6 +591,8 @@ When extending the build image: - When extending the run image, after all `run.Dockefile`s are applied, the lifecycle: - **If** any `run.Dockerfile` set the label `io.buildpacks.rebasable` to `false` or left the label unset: - SHALL set the label `io.buildpacks.rebasable` to `false` on the extended run image + - **If** after the final `run.Dockerfile` the run image user is `root`, + - SHALL fail - SHALL copy the manifest and config for the extended run image, along with any new layers, to ``/run #### `builder` From 5f0936c0034a25280edb80fccee567fbf98a49ee Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Wed, 5 Jul 2023 10:31:32 -0400 Subject: [PATCH 54/67] Rebaser: update -force cases Signed-off-by: Natalie Arellano --- platform.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/platform.md b/platform.md index 7ebae5a..b1245f4 100644 --- a/platform.md +++ b/platform.md @@ -802,12 +802,6 @@ Usage: - **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 be derived from the first ``. - **If** `` is not provided by the platform, the value will be [resolved](#run-image-resolution) from the contents of the `runImage` key in the `io.buildpacks.lifecycle.metdata` label on ``, or `stack.runImage` if not found (for compatibility with older platforms; see [deprecations](#deprecations)). -- **If** `` is `true` the following values in the output `` config MUST be derived from the new ``, or else they MUST match the old run image if `` is `false`: - - `os` - - `architecture` - - `variant` (if specified) - - `io.buildpacks.distribution.name` (if specified) - - `io.buildpacks.distribution.version` (if specified) ##### Outputs | Output | Description @@ -833,9 +827,17 @@ Usage: - `run-image.reference` SHALL uniquely identify `` - `run-image.top-layer` SHALL be set to the uncompressed digest of the top layer in `` - The value of `io.buildpacks.base.*` labels and `io.buildpacks.stack.*` labels (if present) SHALL be modified to that of the new `run-image` -- **If** the provided `` is not found in `runImage.image` or `runImage.mirrors`: - - `run-image.image` SHALL be the provided `` - - `run-image.mirrors` SHALL be omitted +- **If** `` is `true`, the following [target data](#target-data) values in the output `` config MUST be derived from the new ``: + - `os` + - `architecture` + - `variant` (if specified) + - `io.buildpacks.distribution.name` (if specified) + - `io.buildpacks.distribution.version` (if specified) +- **Else** they MUST match the old run image if `` is `false` +- **If** `` is `true` and the provided `` is not found in `runImage.image` or `runImage.mirrors`: + - `run-image.image` SHALL be the provided `` + - `run-image.mirrors` SHALL be omitted +- **Else** the provided `` MUST be found in `runImage.image` or `runImage.mirrors` if `` is `false` - To ensure [build reproducibility](#build-reproducibility), the lifecycle: - SHOULD set the `created` time in image config to a constant From 3deb45069441b8b2666dc5453af4ebc188758d8e Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Wed, 5 Jul 2023 16:59:57 -0400 Subject: [PATCH 55/67] Update analyzed.toml description Signed-off-by: Natalie Arellano --- platform.md | 1 + 1 file changed, 1 insertion(+) diff --git a/platform.md b/platform.md index 2988e02..ba5ca80 100644 --- a/platform.md +++ b/platform.md @@ -1203,6 +1203,7 @@ Where: - `image.reference` MUST be either a digest reference to an image in an OCI registry or the ID of an image in a docker daemon - `image.metadata` MUST be the TOML representation of the layer [metadata label](#iobuildpackslifecyclemetadata-json) - `run-image.reference` MUST be either a digest reference to an image in an OCI registry or the ID of an image in a docker daemon +- `run-image.image` MUST be the platform- or extension-provided image name - `run-image.target.id` is optional and MUST be the value of the label `io.buildpacks.id` - `run-image.target` contains the [target data](#target-data) for the image - If target distribution data is missing, it will be inferred from `/etc/os-release` for Linux images; furthermore, if the image contains the label `io.buildpacks.stack.id` with value `io.buildpacks.stacks.bionic`, the lifecycle SHALL assume the following values: From c6dd08c7ab7e7f920874429a14be3044b65ba3a0 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Thu, 6 Jul 2023 11:03:56 -0400 Subject: [PATCH 56/67] Clarify run image selection Signed-off-by: Natalie Arellano --- platform.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/platform.md b/platform.md index b1245f4..2f59c96 100644 --- a/platform.md +++ b/platform.md @@ -945,16 +945,15 @@ The launcher: ### Run Image Resolution -Given [run](#runtoml-toml) metadata, the `` for a given `` shall be resolved as follows: -- By choosing an image from `[[images]]` - - **If** the tag reference for the desired run image is known (e.g., from a `-run-image` flag or `analyzed.toml`): - - The first image in `[[images]]` where `image.image` or one of `image.mirrors` has a matching tag reference - - **Else** the first image in `[[images]]` -- By choosing the best mirror for an image - - **If** any of `image.image` or `image.mirrors` has a registry matching that of `` and is accessible with read permissions: +Given [run](#runtoml-toml) metadata shall be resolved as follows: +- By choosing the `` for a given ``: + - **If** any of `image.image` or `image.mirrors` has a registry matching that of `` and is accessible with read permissions: - This value will become the `` - - **If** none of `image.image` or `image.mirrors` has a registry matching that of ``: + - **If** none of `image.image` or `image.mirrors` has a registry matching that of ``: - The first value of `image.image` or `image.mirrors` that is accessible with read permissions will become the `` +- By choosing mirrors information for a given ``: + - The first image in `[[images]]` where `image.image` or one of `image.mirrors` matches `` + - **Else** the first image in `[[images]]` ### Registry Authentication @@ -1371,8 +1370,7 @@ Where: - The key MUST be the name of the layer - The value MUST contain JSON representation of the `layer.toml` with an additional `sha` key, containing the digest of the uncompressed layer - The value MUST contain an additional `sha` key, containing the digest of the uncompressed layer -- `runImage.image` MUST be a tag reference to the run-image -- `runImage.mirrors` MUST be selected from `run.toml` +- `runImage.image` and `runImage.mirrors` MUST be [resolved](#run-image-resolution) from `run.toml` from the given `` - `runImage.topLayer` MUST contain the uncompressed digest of the top layer of the run-image - `runImage.reference` MUST uniquely identify the run image. It MAY contain one of the following - An image ID (the digest of the uncompressed config blob) From aec9203a468dd2bda46544bb1743108d5e21dc95 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 24 Jul 2023 13:03:36 -0400 Subject: [PATCH 57/67] Apply suggestions from code review Co-authored-by: Terence Lee Signed-off-by: Natalie Arellano --- platform.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/platform.md b/platform.md index 2f59c96..b88d0b0 100644 --- a/platform.md +++ b/platform.md @@ -833,11 +833,11 @@ Usage: - `variant` (if specified) - `io.buildpacks.distribution.name` (if specified) - `io.buildpacks.distribution.version` (if specified) -- **Else** they MUST match the old run image if `` is `false` +- **Else** the target data above MUST match the old run image if `` is `false` - **If** `` is `true` and the provided `` is not found in `runImage.image` or `runImage.mirrors`: - `run-image.image` SHALL be the provided `` - `run-image.mirrors` SHALL be omitted -- **Else** the provided `` MUST be found in `runImage.image` or `runImage.mirrors` if `` is `false` +- **Else if** ` is `false`, the provided `` MUST be found in `runImage.image` or `runImage.mirrors` - To ensure [build reproducibility](#build-reproducibility), the lifecycle: - SHOULD set the `created` time in image config to a constant From 5feb0b5206de39550641333018a02e103ce67020 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 24 Jul 2023 13:19:08 -0400 Subject: [PATCH 58/67] Fix: platform-defined env vars are not actually overridable by buildpacks Signed-off-by: Natalie Arellano --- platform.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/platform.md b/platform.md index ead40f9..5cfae67 100644 --- a/platform.md +++ b/platform.md @@ -1027,7 +1027,7 @@ The platform SHOULD NOT assume any other stack-provided environment variables ar User-provided environment variables 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. -User-provided environment variables MAY be modified by prior buildpacks before they are provided to a given buildpack. +User-provided environment variables MAY NOT be modified by prior buildpacks before they are provided to a given buildpack. The platform SHOULD NOT set user-provided environment variables directly in the lifecycle execution environment. @@ -1038,7 +1038,7 @@ Operator-provided environment varaiables MUST be supplied by the platform as fil 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. +Operator-defined environment variables MAY NOT be modified by prior buildpacks before they are provided to a given buildpack. The platform SHOULD NOT set operator-provided environment variables directly in the lifecycle execution environment. From b4f953901c717bfddcfe1e0398054920a109dd7f Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 24 Jul 2023 16:37:56 -0400 Subject: [PATCH 59/67] Update platform.md Signed-off-by: Natalie Arellano --- platform.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform.md b/platform.md index 45cb492..df9c784 100644 --- a/platform.md +++ b/platform.md @@ -270,7 +270,7 @@ If an SBOM is available, platforms MAY: #### Launch -`/cnb/lifecycle/launcher` is responsible for launching user- and buildpack-provided processes in the correct execution environment. +`/cnb/lifecycle/launcher` is responsible for launching user-provided and buildpack-provided processes in the correct execution environment. `/cnb/lifecycle/launcher`, or a symlink to it (see [exporter outputs](#outputs-4)), SHALL be the `ENTRYPOINT` for all app images. ### Usage From d6db12261e02a01fa100cee2a898e512dff305c9 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 28 Jul 2023 10:14:54 -0400 Subject: [PATCH 60/67] Apply suggestions from code review Signed-off-by: Natalie Arellano --- platform.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/platform.md b/platform.md index b88d0b0..286c76e 100644 --- a/platform.md +++ b/platform.md @@ -185,7 +185,7 @@ The platform MUST ensure that: The platform SHOULD ensure that: - The image config's `User` field is set to a user with a **DIFFERENT** user [†](README.md#operating-system-conventions)UID/[‡](README.md#operating-system-conventions)SID as the build image. -- The image config's `Label` field has the label `io.buildpacks.id` set to the target ID (e.g., "minimal") of the run image. +- The image config's `Label` field has the label `io.buildpacks.base.id` set to the target ID (e.g., "minimal") of the run image. - The image config's `Label` field has the label `io.buildpacks.base.maintainer` set to the name of the image maintainer. - The image config's `Label` field has the label `io.buildpacks.base.homepage` set to the homepage of the image. - The image config's `Label` field has the label `io.buildpacks.base.released` set to the release date of the image. @@ -197,14 +197,14 @@ The platform SHOULD ensure that: For both build images and run images, the platform MUST ensure that: - The image config's `os` and `architecture` fields are set to valid identifiers as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md). -- The build image config and the run image config both specify the same `os`, `architecture`, `variant` (if specified), `io.buildpacks.distribution.name` (if specified), and `io.buildpacks.distribution.version` (if specified). +- The build image config and the run image config both specify the same `os`, `architecture`, `variant` (if specified), `io.buildpacks.base.distro.name` (if specified), and `io.buildpacks.base.distro.version` (if specified). The platform SHOULD ensure that: - The image config's `variant` field is set to a valid identifier as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md). -- The image config's `Label` field has the label `io.buildpacks.distribution.name` set to the OS distribution and the label `io.buildpacks.distribution.version` set to the OS distribution version. +- The image config's `Label` field has the label `io.buildpacks.base.distro.name` set to the OS distribution and the label `io.buildpacks.base.distro.version` set to the OS distribution version. - For Linux-based images, each label 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, `io.buildpacks.distribution.name` should be empty; `io.buildpacks.distribution.version` should contain the value of `os.version` in the image config (e.g., `10.0.14393.1066`). + - For Windows-based images, `io.buildpacks.base.distro.name` should be empty; `io.buildpacks.base.distro.version` should contain the value of `os.version` in the image config (e.g., `10.0.14393.1066`). ### Compatibility Guarantees From ea0bcde72fb459e4033ee47c0a29d61a05a90226 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 28 Jul 2023 10:16:54 -0400 Subject: [PATCH 61/67] Update more label names Signed-off-by: Natalie Arellano --- platform.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/platform.md b/platform.md index 286c76e..447514d 100644 --- a/platform.md +++ b/platform.md @@ -831,8 +831,8 @@ Usage: - `os` - `architecture` - `variant` (if specified) - - `io.buildpacks.distribution.name` (if specified) - - `io.buildpacks.distribution.version` (if specified) + - `io.buildpacks.base.distro.name` (if specified) + - `io.buildpacks.base.distro.version` (if specified) - **Else** the target data above MUST match the old run image if `` is `false` - **If** `` is `true` and the provided `` is not found in `runImage.image` or `runImage.mirrors`: - `run-image.image` SHALL be the provided `` @@ -1113,7 +1113,7 @@ Where: - `image.reference` MUST be either a digest reference to an image in an OCI registry or the ID of an image in a docker daemon - `image.metadata` MUST be the TOML representation of the layer [metadata label](#iobuildpackslifecyclemetadata-json) - `run-image.reference` MUST be either a digest reference to an image in an OCI registry or the ID of an image in a docker daemon -- `run-image.target.id` is optional and MUST be the value of the label `io.buildpacks.id` +- `run-image.target.id` is optional and MUST be the value of the label `io.buildpacks.base.id` - `run-image.target` contains the [target data](#target-data) for the image - If target distribution data is missing, it will be inferred from `/etc/os-release` for Linux images; furthermore, if the image contains the label `io.buildpacks.stack.id` with value `io.buildpacks.stacks.bionic`, the lifecycle SHALL assume the following values: - `run-image.target.os = "linux"` From 4f4aa24be5a141ede8540c84bf21e33a251d8c1d Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 28 Jul 2023 10:20:22 -0400 Subject: [PATCH 62/67] Update definition Signed-off-by: Natalie Arellano --- platform.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/platform.md b/platform.md index 447514d..04c6c63 100644 --- a/platform.md +++ b/platform.md @@ -109,9 +109,9 @@ A **buildpack** refers to software compliant with the [Buildpack Interface Speci A **base image** is an OCI image containing the base, or initial set of layers, for other images. -A **build image** is an OCI image that provides the base of the **build environment**. +A **build image** is an OCI image that serves as the base image for the **build environment**. -A **run image** is an OCI image that provides the base from which **app images** are built. +A **run image** is an OCI image that serves as the base image for the **app image**. The **build environment** refers to the containerized environment in which the lifecycle executes buildpacks. From bc1e7535a84ce5e7017555e6b5e55103813d8002 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 31 Jul 2023 10:03:03 -0400 Subject: [PATCH 63/67] Add further guidance about target ID Signed-off-by: Natalie Arellano --- platform.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/platform.md b/platform.md index 04c6c63..8b79f27 100644 --- a/platform.md +++ b/platform.md @@ -185,7 +185,6 @@ The platform MUST ensure that: The platform SHOULD ensure that: - The image config's `User` field is set to a user with a **DIFFERENT** user [†](README.md#operating-system-conventions)UID/[‡](README.md#operating-system-conventions)SID as the build image. -- The image config's `Label` field has the label `io.buildpacks.base.id` set to the target ID (e.g., "minimal") of the run image. - The image config's `Label` field has the label `io.buildpacks.base.maintainer` set to the name of the image maintainer. - The image config's `Label` field has the label `io.buildpacks.base.homepage` set to the homepage of the image. - The image config's `Label` field has the label `io.buildpacks.base.released` set to the release date of the image. @@ -194,6 +193,15 @@ The platform SHOULD ensure that: ### Target Data +For run images, the platform SHOULD ensure that: + +- The image config's `Label` field has the label `io.buildpacks.base.id` set to the target ID of the run image. + +**The target ID:** +- MUST only contain numbers, letters, and the characters `.`, `/`, and `-`. +- MUST NOT be identical to any other target ID when using a case-insensitive comparison. +- SHOULD use reverse domain notation to avoid name collisions - i.e. buildpacks.io will be `io.buildpacks`. + For both build images and run images, the platform MUST ensure that: - The image config's `os` and `architecture` fields are set to valid identifiers as defined in the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/config.md). From 85819652ea598af9074b7af777bd6ec4d5815fb4 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Mon, 31 Jul 2023 10:09:31 -0400 Subject: [PATCH 64/67] Add -daemon to restorer This is needed when extensions were used to switch (but not extend) the run image and we need to re-read the target data from the image config. In such cases, we don't need the run image to exist in a registry, because we don't need a manifest for kaniko. Signed-off-by: Natalie Arellano --- platform.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/platform.md b/platform.md index df9c784..a0926e8 100644 --- a/platform.md +++ b/platform.md @@ -451,6 +451,7 @@ Usage: [-build-image ] \ [-cache-dir ] \ [-cache-image ] \ + [-daemon] \ # sets [-gid ] \ [-group ] \ [-layers ] \ @@ -467,6 +468,7 @@ Usage: | ``* | `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_USE_DAEMON` | `false` | Read additional target data for run image from docker daemon | | `` | `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`) | From 134bdde60b387d1b5dad275b0d86870a84d020fc Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 1 Aug 2023 10:06:00 -0400 Subject: [PATCH 65/67] Fix Signed-off-by: Natalie Arellano --- platform.md | 39 +++++++++++++++++++++++++-------------- 1 file changed, 25 insertions(+), 14 deletions(-) diff --git a/platform.md b/platform.md index 5cfae67..96bb496 100644 --- a/platform.md +++ b/platform.md @@ -59,6 +59,7 @@ Examples of a platform might include: - [Outputs](#outputs-7) - [`launcher`](#launcher) - [Inputs](#inputs-8) + - [Execution](#execution) - [Outputs](#outputs-8) - [Run Image Resolution](#run-image-resolution) - [Registry Authentication](#registry-authentication) @@ -72,7 +73,9 @@ Examples of a platform might include: - [Environment](#environment) - [Buildpack Environment](#buildpack-environment) - [Stack-Provided Variables](#stack-provided-variables) + - [POSIX Path Variables](#posix-path-variables) - [User-Provided Variables](#user-provided-variables) + - [Operator-Defined Variables](#operator-defined-variables) - [Launch Environment](#launch-environment) - [Caching](#caching) - [Build Reproducibility](#build-reproducibility) @@ -1011,38 +1014,46 @@ The following variables SHOULD be set in the lifecycle execution environment and | `CNB_STACK_ID` | Chosen stack ID | `HOME` | Current user's home directory +##### POSIX Path Variables + The following variables SHOULD be set in the lifecycle execution environment and MAY be modified by prior buildpacks before they are provided to a given buildpack: -| Env Variable | Layer Path | Contents -|-------------------|--------------|------------------ -| `PATH` | `/bin` | binaries -| `LD_LIBRARY_PATH` | `/lib` | shared libraries -| `LIBRARY_PATH` | `/lib` | static libraries -| `CPATH` | `/include` | header files -| `PKG_CONFIG_PATH` | `/pkgconfig` | pc files +| Env Variable | Layer Path | Contents | +|-------------------|--------------|------------------| +| `PATH` | `/bin` | binaries | +| `LD_LIBRARY_PATH` | `/lib` | shared libraries | +| `LIBRARY_PATH` | `/lib` | static libraries | +| `CPATH` | `/include` | header files | +| `PKG_CONFIG_PATH` | `/pkgconfig` | pc files | The platform SHOULD NOT assume any other stack-provided environment variables are inherited by the buildpack. ##### User-Provided Variables + User-provided environment variables 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. -User-provided environment variables MAY NOT be modified by prior buildpacks before they are provided to a given buildpack. +User-provided environment variables that are [POSIX path variables](#posix-path-variables) MAY be modified by prior buildpacks before they are provided to a given buildpack, +however the user-provided value is always prepended to the buildpack-provided value. -The platform SHOULD NOT set user-provided environment variables directly in the lifecycle execution environment. +User-provided environment variables that are not POSIX path variables MAY NOT be modified by prior buildpacks before they are provided to a given buildpack. -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). +The platform SHOULD NOT set user-provided environment variables directly in the lifecycle execution environment. ##### Operator-Defined Variables -Operator-provided environment varaiables MUST be supplied by the platform as files in the `/env/` directory. + +Operator-provided environment variables 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 NOT be modified by prior buildpacks before they are provided to a given buildpack. +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`. -The platform SHOULD NOT set operator-provided environment variables directly in the lifecycle execution environment. +Operator-defined environment variables MAY be modified by prior buildpacks before they are provided to a given buildpack, +however the operator-defined value is always applied after the buildpack-provided value. -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`. +The platform SHOULD NOT set operator-provided environment variables directly in the lifecycle execution environment. #### Launch Environment User-provided modifications to the process execution environment SHOULD be set directly in the lifecycle execution environment. From 3324444812c10d0f21628a8ce749ad89f951d520 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Wed, 2 Aug 2023 10:02:53 -0400 Subject: [PATCH 66/67] Apply suggestions from code review Signed-off-by: Natalie Arellano --- platform.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/platform.md b/platform.md index ca09895..4a65717 100644 --- a/platform.md +++ b/platform.md @@ -1244,7 +1244,7 @@ The image reference will be mapped to a path in the layout directory following t os = "" arch = "" variant = "" - [target.distribution] + [target.distro] name = "" version = "" @@ -1268,8 +1268,8 @@ Where: - If target distribution data is missing, it will be inferred from `/etc/os-release` for Linux images; furthermore, if the image contains the label `io.buildpacks.stack.id` with value `io.buildpacks.stacks.bionic`, the lifecycle SHALL assume the following values: - `run-image.target.os = "linux"` - `run-image.target.arch = "arm64"` - - `run-image.target.distribution.name = "ubuntu"` - - `run-image.target.distribution.version = "18.04"` + - `run-image.target.distro.name = "ubuntu"` + - `run-image.target.distro.version = "18.04"` #### `group.toml` (TOML) From 2d58de770bb819c0588ea21d805837e42c7b4f1a Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Thu, 3 Aug 2023 11:49:54 -0400 Subject: [PATCH 67/67] Remove `target.id` from the lifecycle Base images may still express this identifier as a label, but it will not be used by the lifecycle nor provided to buildpacks. Signed-off-by: Natalie Arellano --- platform.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/platform.md b/platform.md index 4a65717..dd50486 100644 --- a/platform.md +++ b/platform.md @@ -1240,7 +1240,6 @@ The image reference will be mapped to a path in the layout directory following t reference = "" extend = false [target] - id = "" os = "" arch = "" variant = "" @@ -1263,7 +1262,6 @@ Where: - The ID of an image in a docker daemon - The path to an image in OCI layout format - `run-image.image` MUST be the platform- or extension-provided image name -- `run-image.target.id` is optional and MUST be the value of the label `io.buildpacks.base.id` - `run-image.target` contains the [target data](#target-data) for the image - If target distribution data is missing, it will be inferred from `/etc/os-release` for Linux images; furthermore, if the image contains the label `io.buildpacks.stack.id` with value `io.buildpacks.stacks.bionic`, the lifecycle SHALL assume the following values: - `run-image.target.os = "linux"`