diff --git a/README.md b/README.md index bfc4f265..4c2b824a 100644 --- a/README.md +++ b/README.md @@ -52,4 +52,4 @@ These documents currently specify: - Buildpack API: `0.7` - Distribution API: `0.3` -- Platform API: `0.8` \ No newline at end of file +- Platform API: `0.9` diff --git a/platform.md b/platform.md index 45ed367e..4cbf40cf 100644 --- a/platform.md +++ b/platform.md @@ -87,7 +87,7 @@ Examples of a platform might include: ## Platform API Version -This document specifies Platform API version `0.7`. +This document specifies Platform API version `0.9`. Platform API versions: - MUST be in form `.` or ``, where `` is equivalent to `.0` @@ -285,10 +285,12 @@ Usage: [-cache-image ] \ [-daemon] \ # sets [-gid ] \ + [-launch-cache ] \ [-layers ] \ [-log-level ] \ [-previous-image ] \ [-run-image ] \ + [-skip-layers ] \ [-stack ] \ [-tag ...] \ [-uid ] \ @@ -304,9 +306,11 @@ Usage: | `` | `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` @@ -316,6 +320,7 @@ Usage: - **If** `` is `false` and the platform provides one or more `` inputs, each `` MUST refer to the same registry as ``. - **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. - The lifecycle MUST accept valid references to non-existent ``, ``, and `` without error. - The lifecycle MUST ensure registry write access to ``, `` and any provided ``s. @@ -493,7 +498,7 @@ Usage: - The lifecycle SHALL execute all buildpacks in the order defined in `` 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`, `slices` and `bom` entries returned by buildpacks in `/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`. - The lifecycle SHALL treat `web` processes defined by buildpacks implementing Buildpack API < 0.6 as `default = true`. @@ -541,6 +546,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 | - At least one `` must be provided - Each `` MUST be a valid tag reference @@ -570,8 +576,9 @@ Usage: - All run-image config values SHALL be preserved unless this conflicts with another requirement - MUST contain all buildpack-provided launch layers as determined by the [Buildpack Interface Specfication](buildpack.md) - MUST contain a layer containing all buildpack-provided Software Bill of Materials (SBOM) files for `launch` as determined by the [Buildpack Interface Specfication](buildpack.md) if they are present - - `/sbom//launch.sbom.` MUST contain the buildpack-provided `launch` SBOM - - `/sbom///launch.sbom.` MUST contain the buildpack-provided layer SBOM if `` is a `launch` layer + - `/sbom/launch//sbom.` MUST contain the buildpack-provided `launch` SBOM + - `/sbom/launch///sbom.` MUST contain the buildpack-provided layer SBOM if `` is a `launch` layer + - `/sbom/launch/sbom.legacy.json` MAY contain the legacy non-standard Bill of Materials for `launch` (where [supported](buildpack.md)) - MUST contain one or more app layers as determined by the [Buildpack Interface Specfication](buildpack.md) - MUST contain one or more launcher layers that include: - A file with the contents of the `` file at path `/cnb/lifecycle/launcher` @@ -596,15 +603,15 @@ Usage: - `io.buildpacks.build.metadata`: see [build metadata](#iobuildpacksbuildmetadata-json) - 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 a constant value + - SHOULD set the `created` time in image config to `SOURCE_DATE_EPOCH`, or to a constant value if not defined - The lifecycle SHALL write a [report](#reporttoml-toml) to `` describing the exported app image - The `` directory: - MUST include all buildpack-provided Software Bill of Materials (SBOM) files for `build` as determined by the [Buildpack Interface Specfication](buildpack.md) if they are present - - `/sbom//build.sbom.` MUST contain the buildpack-provided `build` SBOM - - `/sbom///build.sbom.` MUST contain the buildpack-provided layer SBOM if `` is not a `launch` layer - + - `/sbom/build//sbom.` MUST contain the buildpack-provided `build` SBOM + - `/sbom/build///sbom.` MUST contain the buildpack-provided layer SBOM if `` is not a `launch` layer. + - `/sbom/build/sbom.legacy.json` MAY contain the legacy non-standard Bill of Materials for `build` (where [supported](buildpack.md)) - *If* a cache is provided the lifecycle: - SHALL write the contents of all cached layers and any provided layer-associated SBOM files to the cache - SHALL record the diffID and layer content metadata of all cached layers in the cache @@ -645,10 +652,10 @@ Running `creator` SHALL be equivalent to running `detector`, `analyzer`, `restor | Input | Environment Variable| Default Value| Description |-------------------|---------------------|--------------|---------------------- | ``| `CNB_PREVIOUS_IMAGE`| `` | Image reference to be analyzed (usually the result of the previous build) -| `` | `CNB_SKIP_RESTORE` | `false` | Do not write layer metadata or restore cached layers +| `` | `CNB_SKIP_RESTORE` | `false` | Prevent buildpacks from reusing layers from previous builds, by skipping the restoration of any data to each buildpack's layers directory, with the exception of `store.toml`. | `...` | | | Additional tag to apply to exported image -- **If** `` is `true` the `creator` SHALL skip layer analysis and skip the entire Restore phase. +- **If** `` is `true` the `creator` SHALL skip sbom layer restoration and skip the entire Restore phase. - **If** the platform provides one or more `` inputs they SHALL be treated as additional `` inputs to the `exporter` ##### Outputs @@ -733,44 +740,47 @@ Usage: /cnb/lifecycle/launcher [--] [ ...] ``` ##### Inputs -| Input | Environment Variable | Default Value | Description -|---------------------|-----------------------|----------------|--------------------------------------- -| `` | `CNB_APP_DIR` | `/workspace` | Path to application directory -| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layer directory -| `` | | | `type` of process to launch -| `` | | | Process execution strategy -| `` | | | Command to execute -| `` | | | Arguments to command -| `/config/metadata.toml` | | | Build metadata (see [`metadata.toml`](#metadatatoml-toml) -| `///` | | | Launch Layers - -A command (``), arguments to that command (``), and an execution strategy (``) comprise a process definition. Processes MAY be buildpack-defined or user-defined. +| Input | Environment Variable | Default Value | Description | +|------------------------------------|----------------------|---------------|-----------------------------------------------------------| +| `` | `CNB_APP_DIR` | `/workspace` | Path to application directory | +| `` | `CNB_LAYERS_DIR` | `/layers` | Path to layer directory | +| `` | | | `type` of process to launch | +| `` | | | Process execution strategy | +| `` | | | Command to execute | +| `` | | | Arguments to command | +| `/config/metadata.toml` | | | Build metadata (see [`metadata.toml`](#metadatatoml-toml) | +| `///` | | | Launch Layers | + +A command (``), arguments to that command (``), a working directory (``), and an execution strategy (``) comprise a process definition. Processes MAY be buildpack-defined or user-defined. The launcher: -- MUST derive the values of ``, ``, and `` as follows: +- MUST derive the values of ``, ``, ``, and `` as follows: - **If** the final path element in `$0`, matches the type of any buildpack-provided process type - `` SHALL be the final path element in `$0` - The lifecycle: - MUST select the process with type equal to `` from `/config/metadata.toml` + - MUST set `` to the value defined for the process in `/config/metadata.toml`, or to `` if not defined - MUST append any user-provided `` to process arguments - **Else** - **If** `$1` is `--` - `` SHALL be `true` - `` SHALL be `$2` - `` SHALL be `${@3:}` + - `` SHALL be `` - **Else** - `` SHALL be `false` - `` SHALL be `$1` - `` SHALL be `${@2:}` + - `` ##### Outputs If the launcher errors before executing the process it will have one of the following error codes: -| Exit Code | Result| -|-----------|-------| -| `11` | Platform API incompatibility error -| `12` | Buildpack API incompatibility error -| `80-89`| Launch-specific lifecycle errors +| Exit Code | Result | +|-----------|-------------------------------------| +| `11` | Platform API incompatibility error | +| `12` | Buildpack API incompatibility error | +| `80-89` | Launch-specific lifecycle errors | Otherwise, the exit code shall be the exit code of the launched process. @@ -926,18 +936,16 @@ type = "" command = "" args = [""] direct = false +working-dir = "" [[slices]] paths = [""] - -[bom] ``` Where: - `id`, `version`, and `api` MUST be present for each buildpack - `processes` contains the complete set of processes contributed by all buildpacks - `slices` contains the complete set of slices defined by all buildpacks -- `bom` contains the Bill of Materials contributed by buildpacks implementing Buildpack API < 0.7 #### `order.toml` (TOML) @@ -1000,17 +1008,6 @@ tags = [""] digest = "" image-id = "" manifest-size = "" - -[build] -[[build.bom]] -name = "" - -[build.bom.metadata] -version = "" - -[build.bom.buildpack] -id = "" -version = "" ``` Where: - `tags` MUST contain all tag references to the exported app image @@ -1019,8 +1016,6 @@ Where: - `manifest-size` MUST contain the manifest size in bytes - **If** the app image was exported to a docker daemon - `imageID` MUST contain the imageID -- **If** the app image was the result of a build operation - - `build.bom` MUST contain any build Bill of Materials entries returned by buildpacks implementing Buildpack API < 0.7 #### `stack.toml` (TOML) @@ -1051,7 +1046,8 @@ Where: "args": [ "" ], - "direct": false + "direct": false, + "working-dir": "", } ], "buildpacks": [ @@ -1061,18 +1057,6 @@ Where: "homepage": "" } ], - "bom": [ - { - "name": "", - "metadata": { - // arbitrary buildpack provided metadata - }, - "buildpack": { - "id": "", - "version": "" - } - }, - ], "launcher": { "version": "", "source": { @@ -1087,7 +1071,6 @@ Where: Where: - `processes` MUST contain all buildpack contributed processes - `buildpacks` MUST contain the detected group -- `bom` MUST contain the Bill of Materials contributed by buildpacks implementing Buildpack API < 0.7 - `launcher.version` SHOULD contain the version of the `launcher` binary included in the app - `launcher.source.git.repository` SHOULD contain the git repository containing the `launcher` source code - `launcher.source.git.commit` SHOULD contain the git commit from which the given `launcher` was built