diff --git a/distribution.md b/distribution.md index 6b217a1..c5a3771 100644 --- a/distribution.md +++ b/distribution.md @@ -15,11 +15,12 @@ This document specifies the artifact format, delivery mechanism, and order resol ## Distribution API Version -This document specifies Distribution API version `0.3`. +This document specifies Distribution API version `0.4`. 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 ## Artifact Format @@ -43,29 +44,212 @@ Each buildpack layer blob MUST contain a single buildpack at the following file /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. + + A buildpack ID, buildpack version, and at least one stack MUST be provided in the OCI image config as a Label. -Label: `io.buildpacks.buildpackage.metadata` +#### Labels + +The following labels MUST be set in the buildpack image(through the image config's `Labels` field): + +| 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) + ```json { - "id": "", - "version": "", - "stacks": [ - { - "id": "", - "mixins": [""] + "id": "", + "name": "", + "version": "", + "homepage": "", +} +``` + +##### `io.buildpacks.buildpack.layers` (JSON) + +```json +{ + # schema of a meta-buildpack + "": { + "": { + "api": "", + "order": [ + { + "group": [ + { + "id": "", + "version": "" + } + ] + } + ], + "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 stacks. +For a buildpackage to be valid, each `buildpack.toml` describing a buildpack implementation MUST have all listed targets. + +### 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. + +#### Labels -For each listed stack, all associated buildpacks MUST be a candidate for detection when the entrypoint buildpack ID and version are selected. +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. + +## Data Format + +### Files + +#### `builder.toml` (TOML) +```toml +description = "a human readable description output when you run `pack inspect-builder`" + +[[buildpacks]] +id = "" +version = "" +uri = "" + +[[order]] +[[order.group]] +id = "" +version = "" +optional = false + +[stack] +id = "" +build-image = "build image" +run-image = "run image" +run-image-mirrors = "mirrors" + +[build] +image = "build image" + +[run] +[[run.images]] +image = "run image" +mirrors = "mirrors" + +``` + +Where: +- buildpacks list MAY be provided. + - buildpacks.id and .version are optional but if provided MUST match an available buildpack in its buildpack.toml file. + - buildpacks.uri MUST be provided. +- order list MUST be provided and MUST have at least one group list + - order.group.id + - MUST be provided + - SHOULD match an available buildpack in the buildpacks list + - MUST be unique within a group + - MAY be repeated within the order + - order.group.version (optional) MAY be omitted if the ID alone is sufficient to identify a unique buildpack. + - order.group.optional (optional) MUST be a boolean value specifying whether or not this buildpack is optional during detection. +- stack MAY be provided to platforms >= 0.12, but is deprecated in favor of `build` and `run` (see below). MUST be provided to platforms <= 0.11. + - build-image MUST be included in a stack + - run-image MUST be included + - run-image-mirrors MAY be included +- build SHOULD be provided to platforms >= 0.12, and MUST include an image +- run SHOULD be provided to platforms >= 0.12 + - run MUST have at least one `images` entry + - each `run.images` MUST include an image + - each `run.images` MAY include a list of mirrors (in the format `["mirror url", "mirror, url", ...]`) +- either stack or build and run images MUST be provided. + + +#### `package.toml` (TOML) + +```(toml) +[buildpack] +uri = "uri" + +[[buildpacks]] +uri = "uri" + +[platform] +os = "operating system" + +[[dependencies]] +uri = "uri" +image = "image uri" + +``` -Each stack ID MUST only be present once. -For a given stack, the `mixins` list MUST enumerate mixins such that no included buildpacks are missing a mixin for the stack. +Where: +- buildpack or buildpacks MUST be present, and MUST include a URI, which MAY be a relative or absolute path, or URL. +- platform MAY be provided to specify the operating system compatibility. If provided, `os` SHOULD be either `linux` (default) or `windows` +- dependencies list MAY be provided to specify URIs of order groups within a meta-buildpack. -Fewer stack entries as well as additional mixins for a stack entry MAY be specified.