This guide is most relevant to platform operators, base image authors, and builder authors.
See the spec release for Platform API 0.12 for the full list of changes and further details.
In Platform 0.12, the concepts of stacks and mixins are removed in favor of existing constructs in the container image ecosystem such as operating system name, operating system distribution, and architecture.
-stack flag is removed from the
exporter and replaced with a
that indicates the location of a
run.toml file with schema:
[[images]] image = "<image>" mirrors = ["<mirror>", "<mirror>"]
This file will be created automatically at
pack builder create if the
pack version is at least
0.30.0 (see below).
For each image in
image is a tag reference to a run image and
mirrors contains tag references to its mirrors.
Note that whereas
stack.toml (removed in this API version) only contained a single run image with mirrors,
run.toml contains a list of images.
This is because of image extensions and the possibility of run image switching, introduced in Platform 0.10.
For platforms that do not use image extensions, only a single run image with mirrors is needed in
stack key in the
io.buildpacks.lifecycle.metadata is removed.
To find a tag reference to the run image and mirrors information,
platforms should read the newly added
Additional validations were added to the
rebaser along with a
-force flag to force rebase when validations are not satisfied.
-force is not provided,
io.buildpacks.base.distro.namelabel (if specified)
io.buildpacks.base.distro.versionlabel (if specified)
-run-imageis provided it must be found in
true(see image extensions below)
In Platform 0.12, extensions can be used to extend not only build-time base images, but runtime base images as well.
To use the feature, platforms should:
analyzeras usual for Platform 0.12
-runflag, to specify the location of a
run.tomlfile containing run image information
-dameonflag (newly added in this Platform API version) if the export target is a daemon
restorermust re-read target data from the new run image in order to provide this information to buildpacks; if
-daemonis provided the
restorerwill look for the run image in a daemon instead of a registry
-daemonflag has no effect as the
restorermust be able to pull the run image manifest from a registry
extenderas usual to extend the builder image (see migration guide for Platform 0.10)
truewe must run the
extenderon the run image
-extended <extended dir>
<extended dir>is the directory where layers created from the application of each
run.Dockerfileto the run image will be saved for use by the
exporter; it defaults to
Note that unlike buildpack-provided layers, layers from extensions may NOT be safe to rebase.
io.buildpacks.rebasable label on the exported application image will be
false if rebase is unsafe.
-force flag must be provided to the
rebaser in order to rebase images with unsafe extension layers,
and should be used with great care.
Platform 0.12 adds a new capability to export application images on disk in OCI layout format.
To use the feature, platforms must prepare a layout directory containing input images (
<previous-image> if available) in OCI layout format,
following the rules to convert the image reference to a path.
The feature is enabled by providing a
-layout flag or by setting the
CNB_USE_LAYOUT environment variable to
true for the following lifecycle phases:
Additionally, the path to the layout directory must be specified, either by providing a
-layout-dir flag or by setting the
CNB_LAYOUT_DIR environment variable.
Note: Rebasing an image exported to OCI layout format and extending OCI layout base images with Dockerfiles are currently not supported.
When creating build-time or runtime base images, base image authors should set
containing the values specified in
This information - along with operating system, architecture, and architecture variant from the OCI image config,
will be exposed to buildpacks through
$CNB_TARGET_* environment variables.
Additionally, authors may set an
io.buildpacks.base.id label on runtime base images to uniquely identify the image “flavor” - see the Platform spec for further information and requirements.
To allow newer builders to run on older platforms, base image authors should continue to set any
io.buildpacks.stack.* labels that are still relevant.
Note that “information only” labels such as
io.buildpacks.stack.maintainer have new equivalents in
and it is recommended to set both sets of labels for the time being.
To maintain compatibility with older buildpacks, build-time base images should continue to set
$CNB_STACK_ID in the build environment.
With the removal of stacks, there is also a new way to reference build-time and runtime base images in
Builder authors should ensure their
pack version is at least
0.30.0 in order to create builders that will work with newer platforms.
builder.toml schema is:
[run] [[run.images]] image = "cnbs/some-run-image" mirrors = ["mirror1", "mirror2"] [build] image = "cnbs/some-build-image"
Run image information will be translated to
run.toml in the builder with schema:
[[images]] image = "cnbs/some-run-image" mirrors = ["mirror1", "mirror2"]
Run image information will also be translated to
stack.toml (for compatibility with older platforms) in the builder with schema:
[run-image] image = "cnbs/some-run-image" mirrors = ["mirror1", "mirror2"]
builder.toml schema is still valid:
[stack] id = "some.stack.id" run-image = "cnbs/some-run-image" run-image-mirrors = ["mirror1", "mirror2"] build-image = "cnbs/some-build-image"
If the old
builder.toml schema is used, run image information will be translated to the same
stack.toml file formats as above.
It is possible to define both the new and the old schema within
builder.toml, but they must be consistent or
pack builder create will fail.