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.

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

Distribution Specs (v3) - Builder Distribution Spec #271

Merged
merged 10 commits into from
Feb 16, 2022
Merged

Distribution Specs (v3) - Builder Distribution Spec #271

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
b9b9396
feat: buildpacks builder distribution specs
jimil749 Nov 15, 2021
0e8bfd6
fix: avoid hyphenating
jimil749 Nov 30, 2021
5b920df
add buildpacks path variation
jimil749 Dec 6, 2021
1418e4a
feat: add builder environment variables
jimil749 Dec 6, 2021
f6c99de
update env vars from MUST to MAY
jimil749 Dec 10, 2021
9369ccd
minor tweaks
jimil749 Dec 22, 2021
928840b
add order.toml in the builder fs
jimil749 Dec 22, 2021
14cbc7b
change builder case to smaller case
jimil749 Jan 6, 2022
eee0b60
minor nit
jimil749 Jan 6, 2022
35e5cce
Changes to labels, remove defaults from Env Var
jromero Jan 26, 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
219 changes: 157 additions & 62 deletions distribution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,27 +2,46 @@

This document specifies the artifact format and the delivery mechanism for the buildpacks core components.


## Table of Contents

<!-- Using https://github.com/yzhang-gh/vscode-markdown to manage toc -->
- [Distribution Specification](#distribution-specification)
- [Table of Contents](#table-of-contents)
- [Distribution API Version](#distribution-api-version)
- [Artifact Format](#artifact-format)
- [Buildpackage](#buildpackage)
- [Lifecycle](#lifecycle)
- [Build Image](#build-image)
- [Run Image](#run-image)
<!-- TOC -->

- [Table of Contents](#table-of-contents)
- [Distribution API Version](#distribution-api-version)
- [Artifact Format](#artifact-format)
- [Buildpackage](#buildpackage)
- [Labels](#labels)
- [`io.buildpacks.buildpack.metadata` (JSON)](#iobuildpacksbuildpackmetadata-json)
- [`io.buildpacks.buildpack.layers` (JSON)](#iobuildpacksbuildpacklayers-json)
- [Lifecycle](#lifecycle)
- [Filesystem](#filesystem)
- [Labels](#labels)
- [Build Image](#build-image)
- [Image Configuration](#image-configuration)
- [Environment Variables](#environment-variables)
- [Labels](#labels)
- [Run Image](#run-image)
- [Image Configuration](#image-configuration)
- [Environment Variables](#environment-variables)
- [Labels](#labels)
- [Builder](#builder)
- [General Requirements](#general-requirements)
- [Filesystem](#filesystem)
- [Environment Variables](#environment-variables)
- [Labels](#labels)
- [`io.buildpacks.builder.metadata` (JSON)](#iobuildpacksbuildermetadata-json)

<!-- /TOC -->

## Distribution API Version

This document specifies Distribution API version `0.3`.

Distribution API versions:
- MUST be in form `<major>.<minor>` or `<major>`, where `<major>` is equivalent to `<major>.0`
- When `<major>` is greater than `0` increments to `<minor>` SHALL exclusively indicate additive changes
- Each Distributable artifact MUST contain the label `io.buildpacks.distribution.api` denoting the distribution API

- MUST be in form `<major>.<minor>` or `<major>`, where `<major>` is equivalent to `<major>.0`
- When `<major>` is greater than `0` increments to `<minor>` SHALL exclusively indicate additive changes
- Each Distributable artifact MUST contain the label `io.buildpacks.distribution.api` denoting the distribution API

## Artifact Format

Expand All @@ -37,7 +56,6 @@ A buildpackage MUST exist in one of the following formats:
* An uncompressed tar archive in [oci-layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md) format.
* The file SHOULD have the extension `.cnb`.


[†](README.md#linux-only)For Linux buildpackages, all FS layers MUST be buildpack layers.

[‡](README.md#windows-only)For Windows buildpackages, all FS layers MUST be either buildpack or OS layers.
Expand All @@ -48,62 +66,67 @@ Each buildpack layer blob MUST contain a single [buildpack](./buildpack.md) at t
/cnb/buildpacks/<buildpack ID>/<buildpack version>/
```

If the buildpack ID contains a `/`, it MUST be replaced with `_` in the directory name.

A buildpack MUST contain a `buildpack.toml` file at its root directory.

#### Labels

For each buildpack layer, the buildpack ID and the buildpack version MUST be provided in `io.buildpacks.buildpackage.layers`

The following labels MUST be set in the buildpack image(through the image config's `Labels` field):

| Label | Description |
| -------- | --------
| `io.buildpacks.buildpackage.metadata` | A JSON object representing Buildpack Metadata |
| `io.builpacks.buildpackage.layers`| A JSON object representing the buildpack layers |
| Label | Description |
| ------------------------------------ | ------------------------------------------------------------------------------------------------- |
| `io.buildpacks.buildpack.metadata` | A JSON object representing information about the packaged entrypoint buildpack |
| `io.buildpacks.buildpack.layers` | A JSON object representing information about all packaged buildpacks and their associated layers. |

##### `io.buildpacks.buildpack.metadata` (JSON)

`io.buildpacks.buildpackage.metadata` (JSON)
```json
{
"id": "<entrypoint buildpack ID>",
"name": "<buildpack name>",
"version": "<entrypoint buildpack version>",
"homepage": "<buildpack home page",
"id": "<buildpack ID (required)>",
"name": "<buildpack name (optional)>",
"version": "<buildpack version (required)>",
"homepage": "<buildpack home page (optional)>",
}
```

`io.buildpacks.buildpackage.layers` (JSON)
##### `io.buildpacks.buildpack.layers` (JSON)

```json
{
"<buildpack ID>": {
"<buildpack version>": {
"api": "<buildpack API>",
# schema of a meta-buildpack
"<buildpack ID (required)>": {
"<buildpack version (required)>": {
"api": "<buildpack API (required)>",
"order": [
{
"group": [
{
"id": "<inner buildpack ID>",
"version": "<inner buildpack version>"
"id": "<inner buildpack ID (required)>",
"version": "<inner buildpack version (required)>"
}
]
}
],
"layerDiffID": "<diff-ID>",
"homepage": "<buildpack homepage>",
"name": "<buildpack name>",
"layerDiffID": "<diff ID of buildpack layer (required)>",
"homepage": "<buildpack homepage (optional)>",
"name": "<buildpack name (optional)>"
}
},
"<inner buildpack>": {
"<inner buildpack version>": {
"api": "<buildpack API>",
"layerDiffID": "<diff-ID>",
"homepage": "<buildpack homepage>",
"name": "<buildpack name>",
# schema of a regular buildpack
"<buildpack ID (required)>": {
"<buildpack version (required)>": {
"api": "<buildpack API (required)>",
"layerDiffID": "<diff ID of buildpack layer (required)>",
"homepage": "<buildpack homepage (optional)>",
"name": "<buildpack name (optional)>"
}
}
}
```

For each buildpack layer, the buildpack ID and the buildpack version MUST be provided in `io.buildpacks.buildpack.layers`.

The buildpack ID and version MUST match a buildpack provided by a layer blob.

For a buildpackage to be valid, each `buildpack.toml` describing a buildpack implementation MUST have all listed targets.
Expand All @@ -126,12 +149,12 @@ A lifecycle image MUST have the following directories/files

#### Labels

| Label | Description
| -------- | --------
| `io.buildpacks.lifecycle.version` | A string, representing the semver version of the lifecycle.
| `io.buildpacks.lifecycle.apis` | A JSON object representing the APIs the lifecycle supports.
| Label | Description |
| --------------------------------- | ----------------------------------------------------------- |
| `io.buildpacks.lifecycle.version` | A string, representing the semver version of the lifecycle. |
| `io.buildpacks.lifecycle.apis` | A JSON object representing the APIs the lifecycle supports. |

`io.buildpacks.lifecycle.apis` (JSON)
##### `io.buildpacks.lifecycle.apis` (JSON)

```json
{
Expand All @@ -145,18 +168,20 @@ A lifecycle image MUST have the following directories/files
}
}
```

Where:

* `supported`:
* contains an array of support API versions:
* for versions `1.0+`, version `x.n` implies support for [`x.0`, `x.n`]
* should be a superset of `deprecated`
* should only contain APIs that correspond to a spec release

* contains an array of support API versions:
* for versions `1.0+`, version `x.n` implies support for [`x.0`, `x.n`]
* should be a superset of `deprecated`
* should only contain APIs that correspond to a spec release
* `deprecated`:
* contain an array of deprecated APIs:
* should only contain `0.x` or major versions
* should only contain APIs that correspond to a spec release

* contain an array of deprecated APIs:
* should only contain `0.x` or major versions
* should only contain APIs that correspond to a spec release

### Build Image

Expand All @@ -166,7 +191,7 @@ The image configuration refers to the OCI Image configuration as mentioned [here

#### Image Configuration

The Build Image MUST contain the following configurations:
The Build Image MUST contain the following configurations:

* Image Config's `config.User` field MUST be set to the user [†](README.md#operating-system-conventions)UID/[‡](README.md#operating-system-conventions)SID with a writable home directory.
* Image Config's `os` field MUST be set to the underlying operating system used by the build image.
Expand All @@ -184,10 +209,10 @@ The Build Image MUST contain the following Environment Variables:

The Build Image SHOULD contain the following Labels on the image configuration:

| Label | Description
|------- |------------
| `io.buildpacks.distribution.name` | A string denoting the operating system distribution
| `io.buildpacks.distribution.version` | A string denoting the operating system version
| Label | Description |
| ------------------------------------ | --------------------------------------------------- |
| `io.buildpacks.distribution.name` | A string denoting the operating system distribution |
| `io.buildpacks.distribution.version` | A string denoting the operating system version |

### Run Image

Expand Down Expand Up @@ -219,12 +244,82 @@ The Run Image MUST contain the following Environment Variables:

The Run Image SHOULD contain the following Labels on the image configuration:

| Label | Description
| -------- | --------
| `io.buildpacks.distribution.name` | A string denoting the Operating System distribution
| `io.buildpacks.distribution.version` | A string denoting the Operating System distribution version
| `io.buildpacks.id` | `<Target ID>`
| Label | Description |
| ------------------------------------ | ----------------------------------------------------------- |
| `io.buildpacks.distribution.name` | A string denoting the Operating System distribution |
| `io.buildpacks.distribution.version` | A string denoting the Operating System distribution version |
| `io.buildpacks.id` | `<Target ID>` |

Where,

`<Target ID>` is an identifier specified on the runtime image that MAY be used to apply target-specific logic.

### Builder

The following specifies the artifact format for a buildpacks builder.
jimil749 marked this conversation as resolved.
Show resolved Hide resolved

A builder is an OCI Image that provides a distributable build environment.

A platform supporting builders SHOULD allow users to configure the build environment for a provided builder.

#### General Requirements

The builder image MUST contain an implementation of the [lifecycle](#lifecycle), and a [build-time](#build-image) environment, and MAY contain [buildpacks](#buildpackage). Platforms SHOULD use builders to ease the build process.

#### Filesystem

A builder MUST have the following directories/files:

* `/cnb/order.toml` &rarr; As defined in the [platform specification](https://github.com/buildpacks/spec/blob/main/platform.md#ordertoml-toml).

#### Environment Variables

A builder MUST be an extension of a Build Image, and MUST retain all the specified environment variables set on the original build image, as specified in the Build Image specifications.

The following environment variables MAY be set on the builder (through the image config's `Env` field):

| Env Variable | Description |
| ---------------------- | ---------------------------------------------------------------------------------- |
| `CNB_APP_DIR` | Application directory of the build environment. |
| `CNB_LAYERS_DIR` | The directory to create and store `layers` in the build environment. |
| `CNB_PLATFORM_DIR` | The directory to create and store platform focused files in the build environment. |
| `SERVICE_BINDING_ROOT` | The directory where services are bound. |

If any environment variable defined above is set on the builder, the specified path MUST be present and writable by the Build Image user.

#### Labels

A builder MUST be an extension of a Build Image, and MUST retain all the specified Labels set on the original build image, as specified in the Build Image specifications.

A builder image MUST contain an implementation of the [lifecycle](#lifecycle), and MUST retain all the specified Labels set on the original Lifecycle image, as specified in the lifecycle distribution specifications.

A builder image MAY contain buildpacks, and MAY retain all the specified Labels set on the original buildpackage, as specified in the [buildpackage](#buildpackage) specification with the following exceptions:

- `io.buildpacks.buildpack.metadata` MUST not be set.
- `io.buildpacks.buildpack.layers` on the builder SHOULD be a merged version based on all buildpackages combined and thereby have of all packaged buildpacks represented.

In addition to all inherited labels above, the following labels MUST be set in the builder environment (through the image config's `Labels` field):

| Label | Description |
| -------------------------------- | ------------------------------------------------------------- |
| `io.buildpacks.builder.metadata` | A JSON object representing builder metadata. |
| `io.buildpacks.buildpack.order` | A JSON object representation of the `/cnb/order.toml` file. |

##### `io.buildpacks.builder.metadata` (JSON)

```json
{
"description": "<string>",
"createdBy": {
"name": "<string>",
"version": "<string>",
}
}
```

Where:

- `description` (optional) is a human readable description of the builder.
- `createdBy` (optional) is information about the tool that created the builder.
- `name` (optional) is the name of the tool that created the builder.
- `version` (optional) is the version of the tool that created the builder.