Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Platform api changes to support phase 1 of Dockerfiles implementation #308

Merged
merged 14 commits into from
Aug 23, 2022
Merged
160 changes: 114 additions & 46 deletions platform.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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**.

Expand Down Expand Up @@ -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=<platform API version>` in the lifecycle's execution environment
The platform SHOULD set `CNB_PLATFORM_API=<platform API version>` 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
Expand Down Expand Up @@ -334,13 +340,13 @@ Usage:
| `/dev/stderr` | Logs (warnings, errors)
| `<analyzed>` | 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 `<analyzed>`, where:
- `image` MUST describe the `<previous-image>`, if accessible
Expand All @@ -353,50 +359,66 @@ Usage:
```
/cnb/lifecycle/detector \
[-app <app>] \
[-analyzed <analyzed>] \
[-buildpacks <buildpacks>] \
[-extensions <extensions>] \
[-group <group>] \
[-layers <layers>] \
[-log-level <log-level>] \
[-order <order>] \
[-output-dir <output-dir>] \
[-plan <plan>] \
[-platform <platform>]
```

##### Inputs
| Input | Environment Variable | Default Value | Description
|---------------|-------------------------|--------------------------------------------------------|-------
| `<app>` | `CNB_APP_DIR` | `/workspace` | Path to application directory
| `<buildpacks>` | `CNB_BUILDPACKS_DIR` | `/cnb/buildpacks` | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout))
| `<group>` | `CNB_GROUP_PATH` | `<layers>/group.toml` | Path to output group definition
| `<layers>` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory
| `<log-level>` | `CNB_LOG_LEVEL` | `info` | Log Level
| `<order>` | `CNB_ORDER_PATH` | `<layers>/order.toml` if present, or `/cnb/order.toml` | Path resolution for order definition (see [`order.toml`](#ordertoml-toml))
| `<plan>` | `CNB_PLAN_PATH` | `<layers>/plan.toml` | Path to output resolved build plan
| `<platform>` | `CNB_PLATFORM_DIR` | `/platform` | Path to platform directory
| Input | Environment Variable | Default Value | Description |
|----------------|----------------------|--------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `<analyzed>` | `CNB_ANALYZED_PATH` | `<layers>/analyzed.toml` | (**[experimental](#experimental-features)**) Path to output analysis metadata (see [`analyzed.toml`](#analyzedtoml-toml) |
| `<app>` | `CNB_APP_DIR` | `/workspace` | Path to application directory |
| `<buildpacks>` | `CNB_BUILDPACKS_DIR` | `/cnb/buildpacks` | Path to buildpacks directory (see [Buildpacks Directory Layout](#buildpacks-directory-layout)) |
| `<extensions>` | `CNB_EXTENSIONS_DIR` | `/cnb/extensions` | (**[experimental](#experimental-features)**) Path to image extensions directory (see [Image Extensions Directory Layout](#image-extensions-directory-layout) |
| `<group>` | `CNB_GROUP_PATH` | `<layers>/group.toml` | Path to output group definition |
| `<layers>` | `CNB_LAYERS_DIR` | `/layers` | Path to layers directory |
| `<log-level>` | `CNB_LOG_LEVEL` | `info` | Log Level |
| `<order>` | `CNB_ORDER_PATH` | `<layers>/order.toml` if present, or `/cnb/order.toml` | Path resolution for order definition (see [`order.toml`](#ordertoml-toml)) |
| `<output-dir>` | `CNB_OUTPUT_DIR` | `<layers>` | (**[experimental](#experimental-features)**) Path to output directory for generated Dockerfiles |
| `<plan>` | `CNB_PLAN_PATH` | `<layers>/plan.toml` | Path to output resolved build plan |
natalieparellano marked this conversation as resolved.
Show resolved Hide resolved
| `<platform>` | `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)
| `<group>` | Detected buildpack group (see [`group.toml`](#grouptoml-toml))
| `<plan>` | 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) |
| `<group>` | Detected buildpack group (see [`group.toml`](#grouptoml-toml)) |
| `<plan>` | Resolved Build Plan (see [`plan.toml`](#plantoml-toml)) |
| `<analyzed>` | Updated to include the run image obtained from applying generated Dockerfiles |
| `<output>/generated/run/<image extension ID>/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 |
natalieparellano marked this conversation as resolved.
Show resolved Hide resolved
| `91` | Extension generate error |
| `92-99` | Generation-specific lifecycle errors |

The lifecycle:
- SHALL detect a single group from `<order>` and write it to `<group>` 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 `<plan>`

When image extensions are present in the order (**[experimental](#experimental-features)**), the lifecycle:
- SHALL execute all image extensions in the order defined in `<group>` according to the process outlined in the [Buildpack Interface Specification](buildpack.md).
- SHALL copy all generated run.Dockerfiles to `<output>/generated/run/<image extension ID>/Dockerfile`.
- SHALL replace the `run-image` reference in `<analyzed>` 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.
natalieparellano marked this conversation as resolved.
Show resolved Hide resolved
- SHALL filter the build plan with dependencies provided by image extensions.

#### `restorer`
Usage:
```
Expand Down Expand Up @@ -436,13 +458,13 @@ Usage:
| `<layers>/<buidpack-id>/<layer>.sbom.<ext>` | Files containing the Software Bill of Materials for each analyzed layer (see [Buildpack Interface Specification](buildpack.md))
| `<layers>/<buidpack-id>/<layer>/*`. | 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 `<group>`, if persistent metadata for that buildpack exists in the analysis metadata, lifecycle MUST write a toml representation of the persistent metadata to `<layers>/<buildpack-id>/store.toml`
- **If** `<skip-layers>` is `true` the lifecycle MUST NOT perform layer restoration.
Expand Down Expand Up @@ -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=<warn|error|silent>` 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
Expand All @@ -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.
Expand Down Expand Up @@ -915,6 +958,12 @@ id = "<buildpack ID>"
version = "<buildpack version>"
api = "<buildpack API version>"
homepage = "<buildpack homepage>"

[[group-extensions]]
id = "<image extension ID>"
version = "<image extension version>"
api = "<image extension API version>"
homepage = "<image extension homepage>"
```

Where:
Expand All @@ -931,6 +980,11 @@ version = "<buildpack version>"
api = "<buildpack API version>"
optional = false

[[extensions]]
id = "<image extension ID>"
version = "<image extension version>"
api = "<image extension API version>"

[[processes]]
type = "<process type>"
command = "<command>"
Expand All @@ -955,20 +1009,26 @@ Where:
id = "<buildpack ID>"
version = "<buildpack version>"
optional = false

[[order-extensions]]
[[order-extensions.group]]
id = "<image extension ID>"
version = "<image extension 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 = "<buildpack ID>"
version = "buildpack Version"
id = "<buildpack or image extension ID>"
version = "<buildpack or image extension version>"
extension = false

[[entries.requires]]
name = "<dependency name>"
Expand All @@ -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 `<dependency name>`

Expand Down Expand Up @@ -1057,6 +1118,13 @@ Where:
"homepage": "<buildpack homepage>"
}
],
"extensions": [
{
"id": "<extension ID>",
"version": "<extension version>",
"homepage": "<extension homepage>"
}
],
"launcher": {
"version": "<launcher-version>",
"source": {
Expand Down