diff --git a/platform.md b/platform.md index 4cbf40cf..f4c92ca9 100644 --- a/platform.md +++ b/platform.md @@ -59,8 +59,11 @@ Examples of a platform might include: - [Outputs](#outputs-7) - [Run Image Resolution](#run-image-resolution) - [Registry Authentication](#registry-authentication) + - [Experimental Features](#experimental-features) - [Buildpacks](#buildpacks) - [Buildpacks Directory Layout](#buildpacks-directory-layout) + - [Image Extensions](#image-extensions) + - [Image Extensions Directory Layout](#image-extensions-directory-layout) - [Security Considerations](#security-considerations) - [Additional Guidance](#additional-guidance) - [Environment](#environment) @@ -122,6 +125,8 @@ 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. + #### Additional Terminology An **image reference** refers to either a **tag reference** or **digest reference**. @@ -224,9 +229,10 @@ Mixin authors MUST ensure that mixins do not affect the [ABI-compatibility](http 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). ## Lifecycle Interface + ### Platform API Compatibility -The platform SHOULD set `CNB_PLATFORM_API=` in the lifecycle's execution environment +The platform SHOULD set `CNB_PLATFORM_API=` in the lifecycle's execution environment. If `CNB_PLATFORM_API` is set in the lifecycle's execution environment, the lifecycle: - MUST either conform to the matching version of this specification or @@ -334,13 +340,13 @@ Usage: | `/dev/stderr` | Logs (warnings, errors) | `` | Analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) -| Exit Code | Result| -|-----------|-------| -| `0` | Success -| `11` | Platform API incompatibility error -| `12` | Buildpack API incompatibility error -| `1-10`, `13-99` | Generic lifecycle errors -| `30-39` | Analysis-specific lifecycle errors +| Exit Code | Result| +|-----------------|-------| +| `0` | Success +| `11` | Platform API incompatibility error +| `12` | Buildpack API incompatibility error +| `1-10`, `13-19` | Generic lifecycle errors +| `30-39` | Analysis-specific lifecycle errors - The lifecycle MUST write [analysis metadata](#analyzedtoml-toml) to ``, where: - `image` MUST describe the ``, if accessible @@ -353,7 +359,10 @@ Usage: ``` /cnb/lifecycle/detector \ [-app ] \ + [-analyzed ] \ [-buildpacks ] \ + [-extensions ] \ + [-generated ] \ [-group ] \ [-layers ] \ [-log-level ] \ @@ -363,40 +372,53 @@ Usage: ``` ##### Inputs -| Input | Environment Variable | Default Value | Description -|---------------|-------------------------|--------------------------------------------------------|------- -| `` | `CNB_APP_DIR` | `/workspace` | Path to application directory -| `` | `CNB_BUILDPACKS_DIR` | `/cnb/buildpacks` | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout)) -| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to output group definition -| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory -| `` | `CNB_LOG_LEVEL` | `info` | Log Level -| `` | `CNB_ORDER_PATH` | `/order.toml` if present, or `/cnb/order.toml` | Path resolution for order definition (see [`order.toml`](#ordertoml-toml)) -| `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to output resolved build plan -| `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory +| Input | Environment Variable | Default Value | Description | +|----------------|----------------------|--------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | (**[experimental](#experimental-features)**) Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) | +| `` | `CNB_APP_DIR` | `/workspace` | Path to application directory | +| `` | `CNB_BUILDPACKS_DIR` | `/cnb/buildpacks` | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout)) | +| `` | `CNB_EXTENSIONS_DIR` | `/cnb/extensions` | (**[experimental](#experimental-features)**) Path to image extensions directory (see [Image Extensions Directory Layout](#image-extensions-directory-layout) | +| `` | `CNB_GENERATED_DIR` | `/generated` | (**[experimental](#experimental-features)**) Path to output directory for generated Dockerfiles | +| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to output group definition | +| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | +| `` | `CNB_LOG_LEVEL` | `info` | Log Level | +| `` | `CNB_ORDER_PATH` | `/order.toml` if present, or `/cnb/order.toml` | Path resolution for order definition (see [`order.toml`](#ordertoml-toml)) | +| `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to output resolved build plan | +| `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory | ##### Outputs -| Output | Description -|--------------------|---------------------------------------------- -| [exit status] | (see Exit Code table below for values) -| `/dev/stdout` | Logs (info) -| `/dev/stderr` | Logs (warnings, errors) -| `` | Detected buildpack group (see [`group.toml`](#grouptoml-toml)) -| `` | Resolved Build Plan (see [`plan.toml`](#plantoml-toml)) - -| Exit Code | Result| -|-----------|-------| -| `0` | Success -| `11` | Platform API incompatibility error -| `12` | Buildpack API incompatibility error -| `1-10`, `13-19` | Generic lifecycle errors -| `20` | All buildpacks groups have failed to detect w/o error -| `21` | All buildpack groups have failed to detect and at least one buildpack has errored -| `22-29` | Detection-specific lifecycle errors +| Output | Description | +|---------------------------------------------------|----------------------------------------------------------------------------------------------------------| +| [exit status] | (see Exit Code table below for values) | +| `/dev/stdout` | Logs (info) | +| `/dev/stderr` | Logs (warnings, errors) | +| `` | Detected buildpack group (see [`group.toml`](#grouptoml-toml)) | +| `` | Resolved Build Plan (see [`plan.toml`](#plantoml-toml)) | +| `` | Updated to include the run image obtained from applying generated Dockerfiles | +| `/run//Dockerfile` | Generated Dockerfiles (see [Image Extension Specfication](image-extension.md)) | + +| Exit Code | Result | +|-----------------|-----------------------------------------------------------------------------------| +| `0` | Success | +| `11` | Platform API incompatibility error | +| `12` | Buildpack API incompatibility error | +| `1-10`, `13-19` | Generic lifecycle errors | +| `20` | All buildpacks groups have failed to detect w/o error | +| `21` | All buildpack groups have failed to detect and at least one buildpack has errored | +| `22-29` | Detection-specific lifecycle errors | +| `91` | Extension generate error | +| `92-99` | Generation-specific lifecycle errors | 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 `` +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). +- SHALL copy all generated run.Dockerfiles to `/run//Dockerfile`. +- 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. + #### `restorer` Usage: ``` @@ -436,13 +458,13 @@ Usage: | `//.sbom.` | Files containing the Software Bill of Materials for each analyzed layer (see [Buildpack Interface Specification](buildpack.md)) | `///*`. | Restored layer contents -| Exit Code | Result| -|-----------|-------| -| `0` | Success -| `11` | Platform API incompatibility error -| `12` | Buildpack API incompatibility error -| `1-10`, `13-99` | Generic lifecycle errors -| `40-49` | Restoration-specific lifecycle errors +| Exit Code | Result| +|-----------------|-------| +| `0` | Success +| `11` | Platform API incompatibility error +| `12` | Buildpack API incompatibility error +| `1-10`, `13-19` | Generic lifecycle errors +| `40-49` | Restoration-specific lifecycle errors - For each buildpack in ``, if persistent metadata for that buildpack exists in the analysis metadata, lifecycle MUST write a toml representation of the persistent metadata to `//store.toml` - **If** `` is `true` the lifecycle MUST NOT perform layer restoration. @@ -807,6 +829,18 @@ The lifecycle MAY provide other mechanisms by which a platform can supply regist The lifecycle MUST attempt to authenticate anonymously if no matching credentials are found. +### Experimental Features + +Where noted, certain features are considered experimental and susceptible to change in a future API version. + +The platform SHOULD set `CNB_EXPERIMENTAL_MODE=` in the lifecycle's execution environment to control the behavior of experimental features. + +When an experimental feature is invoked, the lifecycle: +- SHALL fail if `CNB_EXPERIMENTAL_MODE` is unset +- SHALL warn and continue if `CNB_EXPERIMENTAL_MODE=warn` +- SHALL fail if `CNB_EXPERIMENTAL_MODE=error` +- SHALL continue without warning if `CNB_EXPERIMENTAL_MODE=silent` + ## Buildpacks ### Buildpacks Directory Layout @@ -816,6 +850,15 @@ The buildpacks directory MUST contain unarchived buildpacks such that: - Each top-level directory is a buildpack ID. - Each second-level directory is a buildpack version. +## Image Extensions + +### Image Extensions Directory Layout + +The image extensions directory MUST contain unarchived image extensions such that: + +- Each top-level directory is an image extension ID. +- Each second-level directory is an image extension version. + ## Security Considerations The platform SHOULD run each phase of the lifecycle in an isolated container to prevent untrusted app and buildpack code from accessing storage credentials needed during the export and analysis phases. @@ -915,6 +958,12 @@ id = "" version = "" api = "" homepage = "" + +[[group-extensions]] +id = "" +version = "" +api = "" +homepage = "" ``` Where: @@ -931,6 +980,11 @@ version = "" api = "" optional = false +[[extensions]] +id = "" +version = "" +api = "" + [[processes]] type = "" command = "" @@ -955,20 +1009,26 @@ Where: id = "" version = "" optional = false + +[[order-extensions]] +[[order-extensions.group]] +id = "" +version = "" ``` Where: - Both `id` and `version` MUST be present for each buildpack object in a group. -- The value of `optional` MUST default to false if not specified. +- The value of `optional` MUST default to `false` if not specified. #### `plan.toml` (TOML) ```toml [[entries]] [[entries.providers]] - id = "" - version = "buildpack Version" + id = "" + version = "" + extension = false [[entries.requires]] name = "" @@ -978,7 +1038,8 @@ Where: Where: - `entries` MAY be empty - Each entry: - - MUST contain at least one buildpack in `providers` + - 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 - MUST contain at least one dependency requirement in `requires` - MUST exclusively contain dependency requirements with the same `` @@ -1057,6 +1118,13 @@ Where: "homepage": "" } ], + "extensions": [ + { + "id": "", + "version": "", + "homepage": "" + } + ], "launcher": { "version": "", "source": {