diff --git a/distribution.md b/distribution.md index a3a1cf4a..b3cc07c9 100644 --- a/distribution.md +++ b/distribution.md @@ -2,27 +2,46 @@ This document specifies the artifact format and the delivery mechanism for the buildpacks core components. - ## Table of Contents - -- [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) + + +- [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) + + ## Distribution API Version This document specifies Distribution API version `0.3`. Distribution API versions: - - MUST be in form `.` or ``, where `` is equivalent to `.0` - - When `` is greater than `0` increments to `` SHALL exclusively indicate additive changes - - Each Distributable artifact MUST contain the label `io.buildpacks.distribution.api` denoting the distribution API + +- MUST be in form `.` or ``, where `` is equivalent to `.0` +- When `` is greater than `0` increments to `` SHALL exclusively indicate additive changes +- Each Distributable artifact MUST contain the label `io.buildpacks.distribution.api` denoting the distribution API ## Artifact Format @@ -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. @@ -48,62 +66,67 @@ Each buildpack layer blob MUST contain a single [buildpack](./buildpack.md) at t /cnb/buildpacks/// ``` +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": "", - "name": "", - "version": "", - "homepage": "", + "name": "", + "version": "", + "homepage": "", } ``` -`io.buildpacks.buildpackage.layers` (JSON) +##### `io.buildpacks.buildpack.layers` (JSON) + ```json { - "": { - "": { - "api": "", + # schema of a meta-buildpack + "": { + "": { + "api": "", "order": [ { "group": [ { - "id": "", - "version": "" + "id": "", + "version": "" } ] } ], - "layerDiffID": "", - "homepage": "", - "name": "", + "layerDiffID": "", + "homepage": "", + "name": "" } }, - "": { - "": { - "api": "", - "layerDiffID": "", - "homepage": "", - "name": "", + # schema of a regular buildpack + "": { + "": { + "api": "", + "layerDiffID": "", + "homepage": "", + "name": "" } } } ``` +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. @@ -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 { @@ -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 @@ -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. @@ -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 @@ -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` | `` +| 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` | `` | Where, `` 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. + +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` → 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": "", + "createdBy": { + "name": "", + "version": "", + } +} +``` + +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.