diff --git a/README.md b/README.md index 48d6060..df2f7ce 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.10` +- Platform API: `0.11` diff --git a/platform.md b/platform.md index 223a6e9..d89ce04 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.10`. +This document specifies Platform API version `0.11`. Platform API versions: - MUST be in form `.` or ``, where `` is equivalent to `.0` @@ -367,6 +367,7 @@ Usage: [-app ] \ [-analyzed ] \ [-buildpacks ] \ + [-build-config ] \ [-extensions ] \ [-generated ] \ [-group ] \ @@ -378,19 +379,21 @@ 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_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` | (**[experimental](#experimental-features)**) 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)) | +| `` | `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 | @@ -446,19 +449,19 @@ 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_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) | ##### Outputs | Output | Description | @@ -470,16 +473,16 @@ 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| -|-----------------|-------| -| `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 +| 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. @@ -514,11 +517,13 @@ Usage: |----------------------|------------------------|--------------------------|-------------------------------------------------------------------------------------------------| | `` | `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_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 | +| `` | | | Kaniko directory (must be `/kaniko`) | | `` | `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)) | @@ -529,11 +534,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 | -|-----------------|----------------------------------------| -| [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 | @@ -558,6 +563,7 @@ Usage: /cnb/lifecycle/builder \ [-app ] \ [-buildpacks ] \ + [-build-config ] \ [-group ] \ [-layers ] \ [-log-level ] \ @@ -566,15 +572,16 @@ Usage: ``` ##### Inputs -| Input | Env | 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 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_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 @@ -614,6 +621,7 @@ Usage: [-group ] \ [-launch-cache ] \ [-launcher ] \ + [-launcher-sbom ] \ [-layers ] \ [-log-level ] \ [-process-type ] \ @@ -625,27 +633,28 @@ 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_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/lifecycle` | Path to directory containing SBOM files describing 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 | - At least one `` must be provided - Each `` MUST be a valid tag reference @@ -674,10 +683,11 @@ Usage: - All run-image layers SHALL be preserved - 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 + - MUST contain a layer containing all 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.legacy.json` MAY contain the legacy non-standard Bill of Materials for `launch` (where [supported](buildpack.md)) + - `/sbom/launch/sbom.legacy.json` MAY contain the legacy buildpack-provided non-standard Bill of Materials for `launch` (where [supported](buildpack.md)) + - `/sbom/launch/buildpacksio_lifecycle/launcher/sbom.` MUST contain the CNB-provided launcher SBOM if present in the `/cnb/lifecycle` directory - 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` @@ -707,10 +717,11 @@ Usage: - 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 + - MUST include all 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.legacy.json` MAY contain the legacy non-standard Bill of Materials for `build` (where [supported](buildpack.md)) + - `/sbom/build/sbom.legacy.json` MAY contain the legacy buildpack-provided non-standard Bill of Materials for `build` (where [supported](buildpack.md)) + - `/sbom/build/buildpacksio_lifecycle/sbom.` MUST contain the CNB-provided lifecycle SBOM if present in the `/cnb/lifecycle` directory - *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 @@ -779,6 +790,7 @@ Usage: [-daemon] \ # sets [-gid ] \ [-log-level ] \ + [-previous-image ] \ [-report ] \ [-run-image | -image ] \ # -image is Deprecated [-uid ] \ @@ -792,6 +804,7 @@ Usage: | `` | `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` @@ -799,6 +812,8 @@ Usage: - 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 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 ``. ##### Outputs @@ -1014,6 +1029,19 @@ 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. +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). + +##### Operator-Defined Variables +Operator-provided environment varaiables 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 be modified by subsequent buildpacks before they are provided to a given buildpack. + +The platform SHOULD NOT set operator-provided environment variables directly in the lifecycle execution environment. + +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`. + #### Launch Environment User-provided modifications to the process execution environment SHOULD be set directly in the lifecycle execution environment. @@ -1231,20 +1259,23 @@ Where: ], "direct": false, "working-dir": "", + "buildpackID": "" } ], "buildpacks": [ { "id": "", "version": "", - "homepage": "" + "homepage": "", + "api": "" } ], "extensions": [ { "id": "", "version": "", - "homepage": "" + "homepage": "", + "api": "" } ], "launcher": {