From 85fc4621ed64be47c2eca4b060f6d74246aaf964 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 15 Apr 2022 16:17:13 -0400 Subject: [PATCH] Platform api changes to support phase 1 of Dockerfiles implementation Signed-off-by: Natalie Arellano --- platform.md | 153 ++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 124 insertions(+), 29 deletions(-) diff --git a/platform.md b/platform.md index 4cbf40cf..e91627b3 100644 --- a/platform.md +++ b/platform.md @@ -42,25 +42,33 @@ Examples of a platform might include: - [Inputs](#inputs-2) - [Outputs](#outputs-2) - [Layer Restoration](#layer-restoration) - - [`builder`](#builder) + - [`generator`](#generator) - [Inputs](#inputs-3) - [Outputs](#outputs-3) - - [`exporter`](#exporter) + - [`extender`](#extender) - [Inputs](#inputs-4) - [Outputs](#outputs-4) - - [`creator`](#creator) + - [`builder`](#builder) - [Inputs](#inputs-5) - [Outputs](#outputs-5) - - [`rebaser`](#rebaser) + - [`exporter`](#exporter) - [Inputs](#inputs-6) - [Outputs](#outputs-6) - - [`launcher`](#launcher) + - [`creator`](#creator) - [Inputs](#inputs-7) - [Outputs](#outputs-7) + - [`rebaser`](#rebaser) + - [Inputs](#inputs-8) + - [Outputs](#outputs-8) + - [`launcher`](#launcher) + - [Inputs](#inputs-9) + - [Outputs](#outputs-9) - [Run Image Resolution](#run-image-resolution) - [Registry Authentication](#registry-authentication) - [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) @@ -73,6 +81,7 @@ Examples of a platform might include: - [Data Format](#data-format) - [Files](#files) - [`analyzed.toml` (TOML)](#analyzedtoml-toml) + - [`extender.toml` (TOML)](#extendertoml-toml) - [`group.toml` (TOML)](#grouptoml-toml) - [`metadata.toml` (TOML)](#metadatatoml-toml) - [`order.toml` (TOML)](#ordertoml-toml) @@ -122,6 +131,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**. @@ -334,13 +345,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 @@ -354,6 +365,7 @@ Usage: /cnb/lifecycle/detector \ [-app ] \ [-buildpacks ] \ + [-exts ] \ [-group ] \ [-layers ] \ [-log-level ] \ @@ -363,16 +375,17 @@ 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_APP_DIR` | `/workspace` | Path to application directory | +| `` | `CNB_BUILDPACKS_DIR` | `/cnb/buildpacks` | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout)) | +| `` | `CNB_IMAGE_EXTS_DIR` | `/cnb/exts` | Path to image extensions directory (see [Image Extensions Directory Layout](#image-extensions-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 | ##### Outputs | Output | Description @@ -436,13 +449,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. @@ -451,6 +464,60 @@ Usage: ##### 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. +#### `generator` +The platform MAY execute `generator` in the **build environment** for Linux builds + +Usage: +``` +/cnb/lifecycle/generator \ + [-analyzed ] \ + [-app ] \ + [-extender ] \ + [-exts ] \ + [-group ] \ + [-log-level ] \ + [-output ] \ + [-plan ] \ + [-platform ] +``` + +##### 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_IMAGE_EXTS_DIR` | `/cnb/exts` | Path to image extensions directory (see [Image Extensions Directory Layout](#image-extensions-directory-layout) | +| `` | `CNB_GROUP_PATH` | `/group.toml` | Path to group definition (see [`group.toml`](#grouptoml-toml)) | +| `` | `CNB_LOG_LEVEL` | `info` | Log Level | +| `` | `CNB_EXT_OUTPUT_DIR` | `/exts` | Path to output directory | +| `` | `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 | +|----------------------------------------------|-------------------------------------------------------------------------------| +| [exit status] | (see Exit Code table below for values) | +| `/dev/stdout` | Logs (info) | +| `/dev/stderr` | Logs (warnings, errors) | +| `//` | Generated Dockerfiles (see [Image Extension Specfication](image-extension.md) | +| `/config/metadata.toml` | Build metadata (see [`metadata.toml`](#metadatatoml-toml)) | + +| Exit Code | Result | +|-----------------|--------------------------------------| +| `0` | Success | +| `11` | Platform API incompatibility error | +| `12` | Buildpack API incompatibility error | +| `1-10`, `13-19` | Generic lifecycle errors | +| `91` | Image extension build error | +| `90`, `92-99` | Generation-specific lifecycle errors | + +- The lifecycle SHALL execute all image extensions in the order defined in `` according to the process outlined in the [Buildpack Interface Specification](buildpack.md). +- The lifecycle SHALL replace the `run-image` reference in `` with the selected run image referece. +- The lifecycle SHALL add all invoked image extensions to`/config/metadata.toml`. +- The lifecycle SHALL record all Dockerfiles in ``. +- The lifecycle SHALL copy all output Dockerfiles to ``. +- The lifecycle SHALL filter the build plan with dependencies provided by image extensions. + #### `builder` The platform MUST execute `builder` in the **build environment** @@ -816,6 +883,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. @@ -907,6 +983,14 @@ Where: - `run-image.reference` MUST be either a digest reference to an image in a docker registry or the ID of an image in a docker daemon - `previous-image.metadata` MUST be the TOML representation of the layer [metadata label](#iobuildpackslifecyclemetadata-json) +#### `extender.toml` (TOML) + +```toml +[[dockerfiles]] + extension_id = "" + path = "" +``` + #### `group.toml` (TOML) ```toml @@ -915,6 +999,7 @@ id = "" version = "" api = "" homepage = "" +extension = false ``` Where: @@ -931,6 +1016,11 @@ version = "" api = "" optional = false +[[image-extensions]] +id = "" +version = "" +api = "" + [[processes]] type = "" command = "" @@ -955,6 +1045,11 @@ Where: id = "" version = "" optional = false + +[[order-ext]] +[[order-ext.group]] +id = "" +version = "" ``` Where: