diff --git a/platform.md b/platform.md index cf1a29e..6c27630 100644 --- a/platform.md +++ b/platform.md @@ -42,21 +42,24 @@ Examples of a platform might include: - [Inputs](#inputs-2) - [Outputs](#outputs-2) - [Layer Restoration](#layer-restoration) - - [`builder`](#builder) + - [`extender` (**experimental**)](#extender-experimental) - [Inputs](#inputs-3) - [Outputs](#outputs-3) - - [`exporter`](#exporter) + - [`builder`](#builder) - [Inputs](#inputs-4) - [Outputs](#outputs-4) - - [`creator`](#creator) + - [`exporter`](#exporter) - [Inputs](#inputs-5) - [Outputs](#outputs-5) - - [`rebaser`](#rebaser) + - [`creator`](#creator) - [Inputs](#inputs-6) - [Outputs](#outputs-6) - - [`launcher`](#launcher) + - [`rebaser`](#rebaser) - [Inputs](#inputs-7) - [Outputs](#outputs-7) + - [`launcher`](#launcher) + - [Inputs](#inputs-8) + - [Outputs](#outputs-8) - [Run Image Resolution](#run-image-resolution) - [Registry Authentication](#registry-authentication) - [Experimental Features](#experimental-features) @@ -335,6 +338,9 @@ Usage: - 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 ``. +- The lifecycle MUST write [analysis metadata](#analyzedtoml-toml) to ``, where: + - `image` MUST describe the ``, if accessible + - `run-image` MUST describe the `` ##### Outputs | Output | Description @@ -352,10 +358,6 @@ Usage: | `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 - - `run-image` MUST describe the `` - #### `detector` The platform MUST execute `detector` in the **build environment** @@ -391,15 +393,17 @@ Usage: | `` | `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)) | -| `` | Updated to include the run image obtained from applying generated Dockerfiles | -| `/run//Dockerfile` | Generated Dockerfiles (see [Image Extension Specfication](image-extension.md)) | +| 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)) | +| `/build//Dockerfile` | Generated Dockerfiles (see [Image Extension Specfication](image-extension.md)) | +| `/build//` | Configuration for the `extend` phase (see [Image Extension Specfication](image-extension.md)) | | Exit Code | Result | |-----------------|-----------------------------------------------------------------------------------| @@ -419,7 +423,9 @@ The lifecycle: 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 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. @@ -428,6 +434,7 @@ Usage: ``` /cnb/lifecycle/restorer \ [-analyzed ] \ + [-build-image ] \ [-cache-dir ] \ [-cache-image ] \ [-gid ] \ @@ -439,28 +446,32 @@ 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_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) +| Input | Environment Variable | Default Value | Description | +|-----------------|----------------------|--------------------------|-----------------------------------------------------------------------------| +| `` | `CNB_ANALYZED_PATH` | `/analyzed.toml` | Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) | +| `` | `CNB_BUILD_IMAGE` | | Reference to the current build image in an OCI registry (if used `` must be provided) | +| `` | `CNB_CACHE_DIR` | | Path to a cache directory | +| `` | `CNB_CACHE_IMAGE` | | Reference to a cache image in an OCI registry | +| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` | +| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to group definition (see [`group.toml`](#grouptoml-toml)) | +| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | +| `` | `CNB_LOG_LEVEL` | `info` | Log Level | +| `` | `CNB_USER_ID` | | UID of the build image `User` | +| `` | `CNB_SKIP_LAYERS` | `false` | Do not perform [layer restoration](#layer-restoration) | +|``| | | Kaniko directory (must be `/kaniko`) | ##### Outputs -| Output | Description -|---------------------------------------------|---------------------------------------------- -| [exit status] | (see Exit Code table below for values) -| `/dev/stdout` | Logs (info) -| `/dev/stderr` | Logs (warnings, errors) -| `//store.toml` | Persistent metadata (see data format in [Buildpack Interface Specification](buildpack.md)) -| `//.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 +| Output | Description | +|---------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------| +| [exit status] | (see Exit Code table below for values) | +| `/dev/stdout` | Logs (info) | +| `/dev/stderr` | Logs (warnings, errors) | +| `//store.toml` | Persistent metadata (see data format in [Buildpack Interface Specification](buildpack.md)) | +| `//.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 | + | Exit Code | Result| |-----------------|-------| @@ -473,10 +484,72 @@ 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: + - MUST record the digest reference to the provided `` in `` + - MUST copy the OCI manifest and config file for `` 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)**) +Usage: +``` +/cnb/lifecycle/extender \ + [-analyzed ] \ + [-app ] \ + [-buildpacks ] \ + [-generated ] \ + [-gid ] \ + [-group ] \ + [-kaniko-cache-ttl ] \ + [-layers ] \ + [-log-level ] \ + [-plan ] \ + [-platform ] + [-uid ] \ +``` + +##### 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_GENERATED_DIR` | `/generated` | (**[experimental](#experimental-features)**) Path to directory containing generated Dockerfiles | +| `` | `CNB_GROUP_ID` | | Primary GID of the build image `User` | +| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to group definition (see [`group.toml`](#grouptoml-toml)) | +| `` | `CNB_KANIKO_CACHE_TTL` | 2 weeks | Kaniko cache TTL | +| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory | +| `` | `CNB_LOG_LEVEL` | `info` | Log Level | +| `` | `CNB_PLAN_PATH` | `/plan.toml` | Path to resolved build plan (see [`plan.toml`](#plantoml-toml)) | +| `` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory | +| `` | `CNB_USER_ID` | | UID of the build image `User` | + +##### 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`. + +| 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 | +|-----------------|-------------------------------------| +| `0` | Success | +| `11` | Platform API incompatibility error | +| `12` | Buildpack API incompatibility error | +| `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 `` + #### `builder` The platform MUST execute `builder` in the **build environment** @@ -699,7 +772,6 @@ Outputs produced by `creator` are identical to those produced by `exporter`, wit | `50-59`| Build-specific lifecycle errors | `60-69`| Export-specific lifecycle errors - #### `rebaser` Usage: ``` @@ -947,6 +1019,9 @@ For more information on build reproducibility see [https://reproducible-builds.o [run-image] reference = "" + +[build-image] + reference = "" ``` Where: