This document specifies the artifact format, delivery mechanism, and order resolution process for buildpacks.
This document specifies Distribution API version 0.2
.
Distribution API versions:
- MUST be in form
<major>.<minor>
or<major>
, where<major>
is equivalent to<major>.0
- When
<major>
is greater than0
increments to<minor>
SHALL exclusively indicate additive changes
A buildpack MUST contain a buildpack.toml
file at its root directory.
A buildpackage MUST exist as either an OCI image on an image registry, an OCI image in a Docker daemon, or a .cnb
file.
A .cnb
file MUST be an uncompressed tar archive containing an OCI image. Its file name SHOULD end in .cnb
.
†For Linux buildpackages, all FS layers MUST be buildpack layers.
‡For Windows buildpackages, all FS layers MUST be either buildpack or OS layers.
Each buildpack layer blob MUST contain a single buildpack at the following file path:
/cnb/buildpacks/<buildpack ID>/<buildpack version>/
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
{
"id": "<entrypoint buildpack ID>",
"version": "<entrypoint buildpack version>",
"stacks": [
{
"id": "<stack ID>",
"mixins": ["<mixin name>"]
}
]
}
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 each listed stack, all associated buildpacks MUST be a candidate for detection when the entrypoint buildpack ID and version are selected.
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.
Fewer stack entries as well as additional mixins for a stack entry MAY be specified.