diff --git a/platform.md b/platform.md index 4c8a0b7..51a420d 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) + - [Target Data](#target-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,8 +70,9 @@ 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) + - [Operator-Defined Variables](#operator-defined-variables) - [Launch Environment](#launch-environment) - [Caching](#caching) - [Build Reproducibility](#build-reproducibility) @@ -85,11 +85,14 @@ 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) - [`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 @@ -104,15 +107,11 @@ 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 **base image** is an OCI image containing the base, or initial set of layers, for other images. -A **stack ID** uniquely identifies a particular **stack**. +A **build image** is an OCI image that serves as the base image for the **build environment**. -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. +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. @@ -128,9 +127,12 @@ A **launcher layer** refers to a layer in the app OCI image containing the **lau The **launcher** refers to a lifecycle executable packaged in the **app image** for the purpose of executing processes at runtime. -An **image extension** refers to software compliant with the [Image Extension Interface Specification](image-extension.md). Image extensions participate in detection and execute before the buildpack build process. +An **image extension** refers to software compliant with the [Image Extension Interface Specification](image_extension.md). Image extensions participate in detection and execute before the buildpack build process. + +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**. 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. @@ -138,106 +140,88 @@ A **tag reference** refers to an identifier of form `/:` wh A **digest reference** refers to a [content addressable](https://en.wikipedia.org/wiki/Content-addressable_storage) 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. The following is a non-exhaustive list of terms defined in the [OCI Image Format Specification](https://github.com/opencontainers/image-spec) used throughout this document: -* **image config** https://github.com/opencontainers/image-spec/blob/master/config.md#oci-image-configuration +* **image manifest** provides an **image config** and a set of layers for a single container image for a specific architecture and operating system. +* **image config** - https://github.com/opencontainers/image-spec/blob/master/config.md#oci-image-configuration * **imageID** - https://github.com/opencontainers/image-spec/blob/master/config.md#imageid * **diffID** - https://github.com/opencontainers/image-spec/blob/master/config.md#layer-diffid +* **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. The following is a non-exhaustive list of terms defined in the [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec/blob/main/spec.md) used throughout this document: * **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 +### Build Image -A typical stack 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. -* 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 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 `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 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. +* The default user in the run environment. + 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 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. +- 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. -### Mixins +### Target Data -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. +For run images, the platform SHOULD ensure that: -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. +- The image config's `Label` field has the label `io.buildpacks.base.id` set to the target ID of the run image. -A platform MAY support any number of mixins for a given stack in order to support application code or buildpacks that require those mixins. +**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`. -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). +For both build images and run images, the platform MUST ensure that: -### Compatibility Guarantees +- 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.base.distro.name` (if specified), and `io.buildpacks.base.distro.version` (if specified). -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. +The platform SHOULD ensure that: -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. +- 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.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.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`). -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. +### Compatibility Guarantees -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 @@ -273,7 +257,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. @@ -282,6 +266,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. @@ -308,33 +296,33 @@ Usage: [-layout-dir] \ # sets [-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_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 -| `` | `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 | +| `` | `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 | +| `` | | | 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. @@ -342,7 +330,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 ``. @@ -373,8 +361,8 @@ The platform MUST execute `detector` in the **build environment** Usage: ``` /cnb/lifecycle/detector \ - [-app ] \ [-analyzed ] \ + [-app ] \ [-buildpacks ] \ [-build-config ] \ [-extensions ] \ @@ -390,7 +378,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_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)) | @@ -403,7 +391,6 @@ Usage: | `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to output resolved build plan | | `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory | - ##### Outputs | Output | Description | |----------------------------------------------------------|-----------------------------------------------------------------------------------------------| @@ -432,6 +419,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.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). @@ -469,8 +457,8 @@ Usage: | `` | | | 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_USER_ID` | | UID of the build image `User` | ##### Outputs | Output | Description | @@ -570,6 +558,7 @@ The platform MUST execute `builder` in the **build environment** Usage: ``` /cnb/lifecycle/builder \ + [-analyzed ] \ [-app ] \ [-buildpacks ] \ [-build-config ] \ @@ -581,16 +570,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 @@ -612,6 +602,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`. @@ -638,7 +629,7 @@ Usage: [-process-type ] \ [-project-metadata ] \ [-report ] \ - [-stack ] \ + [-run ] \ [-uid ] \ [...] ``` @@ -655,8 +646,9 @@ Usage: | `` | `CNB_GROUP_PATH` | `/group.toml` | Path to group file (see [`group.toml`](#grouptoml-toml)) | | `` | | | Tag reference to which the app image will be written | | `` | `CNB_LAUNCH_CACHE_DIR` | | Path to a cache directory containing launch layers | -| `` | | `/cnb/lifecycle/launcher` | Path to the `launcher` executable | | `` | | `/cnb/lifecycle` | Path to directory containing SBOM files describing the `launcher` executable | +| `` | | `/cnb/lifecycle/launcher` | Path to the `launcher` executable | +| `/config/metadata.toml` | | | Build metadata (see [`metadata.toml`](#metadatatoml-toml) | | `` | `CNB_LAYERS_DIR` | `/layers` | Path to layer directory | | `` | `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 | @@ -664,9 +656,8 @@ 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 | - At least one `` must be provided @@ -766,9 +757,9 @@ Usage: [-process-type ] \ [-project-metadata ] \ [-report ] \ + [-run ] \ [-run-image ] \ [-skip-restore ] \ - [-stack ] \ [-tag ...] \ [-uid ] \ @@ -806,6 +797,7 @@ Usage: ``` /cnb/lifecycle/rebaser \ [-daemon] \ # sets + [-force] \ [-gid ] \ [-log-level ] \ [-previous-image ] \ @@ -816,23 +808,25 @@ 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 -| `` | | derived from `` | Previous image reference -| `` | `CNB_REPORT_PATH` | `/report.toml` | Path to report (see [`report.toml`](#reporttoml-toml) -| `` | `CNB_RUN_IMAGE` | derived from `` | Run image reference -| `` | `CNB_USER_ID` | | UID of the build image `User` + +| 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 | +| `` | | derived from `` | Previous image reference | +| `` | `CNB_REPORT_PATH` | `/report.toml` | Path to report (see [`report.toml`](#reporttoml-toml) | +| `` | `CNB_RUN_IMAGE` | derived from `` | Run image reference | +| `` | `CNB_USER_ID` | | UID of the build image `User` | - 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 `false` and more than one `` is provided, they MUST refer to the same registry - **If** `` is provided by the platform, the value will be used as the app image to rebase. `` must NOT be modified unless specified again in ``. -- **Else** `` value will derived from the first ``. -- **If** `` is not provided by the platform the value will be [resolved](#run-image-resolution) from the contents of the `stack` key in the `io.buildpacks.lifecycle.metdata` label on ``. +- **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)). ##### Outputs | Output | Description @@ -840,7 +834,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| |-----------|-------| @@ -857,7 +851,18 @@ 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** `` 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.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 `` + - `run-image.mirrors` SHALL be omitted +- **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 @@ -965,11 +970,15 @@ 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 `` 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 ``. +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 ``: + - 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 @@ -1022,24 +1031,26 @@ 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. +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. @@ -1065,7 +1076,7 @@ The `/env/` directory follows the [Environment Variable Modificati #### 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). @@ -1122,6 +1133,14 @@ The image reference will be mapped to a path in the layout directory following t [run-image] reference = "" + [target] + id = "" + os = "" + arch = "" + variant = "" + [target.distribution] + name = "" + version = "" [build-image] reference = "" @@ -1132,11 +1151,18 @@ Where: - 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) - `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) +- `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"` + - `run-image.target.arch = "arm64"` + - `run-image.target.distribution.name = "ubuntu"` + - `run-image.target.distribution.version = "18.04"` #### `group.toml` (TOML) @@ -1266,21 +1292,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] +[[images]] 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 @@ -1366,13 +1392,10 @@ Where: } ], "runImage": { + "image": "cnbs/sample-stack-run:bionic", + "mirrors": = ["", ""], "topLayer": "", "reference": "" - }, - "stack": { - "runImage": { - "image": "cnbs/sample-stack-run:bionic" - } } } ``` @@ -1390,11 +1413,11 @@ 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` 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) - 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) @@ -1412,3 +1435,40 @@ 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.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. +- 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 + +_Deprecated in Platform API 0.12._ + +The `stack` key is deprecated. + +```json + "stack": { + "runImage": { + "image": "cnbs/sample-stack-run:bionic", + "mirrors": ["", ""] + } + } +``` + +Where `stack` MUST contain the same data as the top-level `runImage` key. + +To upgrade, the platform SHOULD read the top-level `runImage` key instead.