Skip to content

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

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.

Sign up for GitHub

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

Merged
merged 14 commits into from
Aug 23, 2022
Merged

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

Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
42a62e9
Platform api changes to support phase 1 of Dockerfiles implementation
Apr 15, 2022
e669a53
Add extensions to build metadata
May 2, 2022
9867543
Updates from implementation
Jun 15, 2022
da18b78
Add extension to build plan
Jun 15, 2022
b8e6b13
Updates per recent Working Group discussions
Jun 24, 2022
1d79fcb
Update with information about experimental features
Jun 24, 2022
251c7a0
Fix generate exit code
Jun 29, 2022
b900760
Update env var name
Jul 7, 2022
642eaf4
Update platform.md
Jul 12, 2022
e9b350a
Update platform.md
Jul 12, 2022
be44080
Update platform.md
Jul 12, 2022
e8dda22
Clarify the meaning of `extension` in plan.toml
Jul 12, 2022
a5acc10
Update platform.md
Aug 16, 2022
2d73272
Merge branch 'main' into extensions-platform-api
Aug 16, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 114 additions & 46 deletions platform.md
View file
Open in desktop
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 |
| `<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 |
| `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.
- 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