From 82f8f3b060b23f8d101c89c0d88044dd96199301 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 22 Aug 2023 11:00:34 -0400 Subject: [PATCH 01/14] Add migration guide for Platform 0.11 Signed-off-by: Natalie Arellano --- .../spec/migration/platform-api-0.10-0.11.md | 66 +++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 content/docs/reference/spec/migration/platform-api-0.10-0.11.md diff --git a/content/docs/reference/spec/migration/platform-api-0.10-0.11.md b/content/docs/reference/spec/migration/platform-api-0.10-0.11.md new file mode 100644 index 000000000..c9ffcb075 --- /dev/null +++ b/content/docs/reference/spec/migration/platform-api-0.10-0.11.md @@ -0,0 +1,66 @@ ++++ +title="Platform API 0.10 -> 0.11" ++++ + + + +This guide is most relevant to platform operators. + +See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%2Fv0.11) for platform API 0.11 for the full list of changes and further details. + +## Platform Operator + +### SBOM files for the `launcher` are included in the application image + +In Platform 0.11, the lifecycle ships with standardized SBOM files describing the `lifecycle` and `launcher` binaries +(these are included in the tarball on the GitHub release page and within the image at `index.docker.io/buildpacksio/lifecycle:`). +SBOM files describing the `launcher` are included in the application image at `/sbom/launch/buildpacksio_lifecycle/launcher/sbom.`, +where `` is each of: `cdx.json`, `spdx.json`, and `syft.json`. +Additionally, SBOM files describing the `lifecycle` are copied to `/sbom/build/buildpacksio_lifecycle/sbom.`, +where they may be saved off by the platform prior to the build container exiting. + +This mirrors what is already being done as of Platform 0.8 for buildpack-provided standardized SBOM files, +which are exported to `/sbom/launch///sbom.` (for runtime dependencies) +and copied to `/sbom/launch//sbom.` (for build-time dependencies). +Platforms that are already handling these files should not need to take additional action - +the resulting SBOMs will simply be more complete. + +### Platforms can specify build time environment variables + +Builders can include a `/cnb/build-config/env/` directory to define environment variables for buildpacks. + +As an example, file `/cnb/build-config/env/SOME_VAR` with contents `some-val` will become `SOME_VAR=some-val` in the buildpack environment. + +Files in the `/cnb/build-config/env/` directory can use suffixes to control the behavior when another entity defines the same variable - +e.g., if `/cnb/build-config/env/SOME_VAR.override` has contents `some-builder-val` and `/env/SOME_VAR` has contents `some-user-val`, +the buildpack environment will contain `SOME_VAR=some-builder-val`. +This is similar to the [environment modification rules for buildpacks](https://github.com/buildpacks/spec/blob/main/buildpack.md#environment-variable-modification-rules), +except that the default behavior when no file suffix is provided is `default`. + +The order of application for env directories is: +* Buildpack: `////` +* User: `/env/` - overrides buildpack values +* Builder: `/cnb/build-config/env/` + +For additional information, see the [buildpack environment](https://github.com/buildpacks/spec/blob/main/platform.md#buildpack-environment) section in the Platform spec. + +To use this feature, during builder creation operators should include a `/cnb/build-config/env/` directory with the desired configuration. + +### The rebaser accepts a -previous-image flag to allow rebasing by digest reference + +Previously, when rebasing an image, the rebased image would always be saved to the same tag as the original image. +This prevented rebasing by digest, among other use cases. + +In Platform 0.11, the original image may be specified separately from the destination image with the `previous-image` flag, as in the following: + +```bash +/cnb/lifecycle/rebaser -previous-image some-original-image some-destination-image +``` + +As before, additional tags for the destination image can also be provided: + +```bash +/cnb/lifecycle/rebaser -previous-image some-original-image -tag some-additional-tag:latest some-destination-image +``` + +To use this feature, platforms can provide the new `-previous-image` flag to the `rebaser`. From 3339793c140f52e7e8f959c6d01edbd65fdf2f75 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 22 Aug 2023 13:07:03 -0400 Subject: [PATCH 02/14] Add migration guide for Platform 0.12 (WIP) Signed-off-by: Natalie Arellano --- .../spec/migration/buildpack-api-0.8-0.9.md | 4 +- .../spec/migration/platform-api-0.10-0.11.md | 46 ++++--- .../spec/migration/platform-api-0.11-0.12.md | 128 ++++++++++++++++++ .../spec/migration/platform-api-0.3-0.4.md | 2 +- .../spec/migration/platform-api-0.4-0.5.md | 2 +- .../spec/migration/platform-api-0.5-0.6.md | 2 +- .../spec/migration/platform-api-0.6-0.7.md | 2 +- .../spec/migration/platform-api-0.7-0.8.md | 2 +- .../spec/migration/platform-api-0.8-0.9.md | 2 +- .../spec/migration/platform-api-0.9-0.10.md | 2 +- 10 files changed, 161 insertions(+), 31 deletions(-) create mode 100644 content/docs/reference/spec/migration/platform-api-0.11-0.12.md diff --git a/content/docs/reference/spec/migration/buildpack-api-0.8-0.9.md b/content/docs/reference/spec/migration/buildpack-api-0.8-0.9.md index e34c5f24b..df1eb48d1 100644 --- a/content/docs/reference/spec/migration/buildpack-api-0.8-0.9.md +++ b/content/docs/reference/spec/migration/buildpack-api-0.8-0.9.md @@ -20,9 +20,9 @@ Buildpack processes can still use a shell! However, the `command` must now expli Hand-in-hand with shell removal is the introduction of overridable process arguments. -In `launch.toml`, `command` is now a list. The first element in `command` is the command, and all following entries are arguments that are always provided to the process, regardless of how the application is started. The `args` list now designates arguments that can be overridden by the end user - if supported by the platform (platform API version 0.10 and above). For further details, see the platform [migration guide](/docs/reference/spec/migration/platform-api-0.9-0.10). +In `launch.toml`, `command` is now a list. The first element in `command` is the command, and all following entries are arguments that are always provided to the process, regardless of how the application is started. The `args` list now designates arguments that can be overridden by the end user - if supported by the platform (Platform API version 0.10 and above). For further details, see the platform [migration guide](/docs/reference/spec/migration/platform-api-0.9-0.10). -For older platforms (platform API version 0.9 and below), arguments in `args` will be appended to arguments in `command`, negating the new functionality (but preserving compatibility). +For older platforms (Platform API version 0.9 and below), arguments in `args` will be appended to arguments in `command`, negating the new functionality (but preserving compatibility). ### Image extensions are supported (experimental) diff --git a/content/docs/reference/spec/migration/platform-api-0.10-0.11.md b/content/docs/reference/spec/migration/platform-api-0.10-0.11.md index c9ffcb075..08d570075 100644 --- a/content/docs/reference/spec/migration/platform-api-0.10-0.11.md +++ b/content/docs/reference/spec/migration/platform-api-0.10-0.11.md @@ -4,9 +4,9 @@ title="Platform API 0.10 -> 0.11" -This guide is most relevant to platform operators. +This guide is most relevant to platform operators and builder authors. -See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%2Fv0.11) for platform API 0.11 for the full list of changes and further details. +See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%2Fv0.11) for Platform API 0.11 for the full list of changes and further details. ## Platform Operator @@ -25,6 +25,27 @@ and copied to `/sbom/launch//sbom.` (for build-time d Platforms that are already handling these files should not need to take additional action - the resulting SBOMs will simply be more complete. +### The rebaser accepts a -previous-image flag to allow rebasing by digest reference + +Previously, when rebasing an image, the rebased image would always be saved to the same tag as the original image. +This prevented rebasing by digest, among other use cases. + +In Platform 0.11, the original image may be specified separately from the destination image with the `previous-image` flag, as in the following: + +```bash +/cnb/lifecycle/rebaser -previous-image some-original-image some-destination-image +``` + +As before, additional tags for the destination image can also be provided: + +```bash +/cnb/lifecycle/rebaser -previous-image some-original-image -tag some-additional-tag:latest some-destination-image +``` + +To use this feature, platforms can provide the new `-previous-image` flag to the `rebaser`. + +## Builder Author + ### Platforms can specify build time environment variables Builders can include a `/cnb/build-config/env/` directory to define environment variables for buildpacks. @@ -44,23 +65,4 @@ The order of application for env directories is: For additional information, see the [buildpack environment](https://github.com/buildpacks/spec/blob/main/platform.md#buildpack-environment) section in the Platform spec. -To use this feature, during builder creation operators should include a `/cnb/build-config/env/` directory with the desired configuration. - -### The rebaser accepts a -previous-image flag to allow rebasing by digest reference - -Previously, when rebasing an image, the rebased image would always be saved to the same tag as the original image. -This prevented rebasing by digest, among other use cases. - -In Platform 0.11, the original image may be specified separately from the destination image with the `previous-image` flag, as in the following: - -```bash -/cnb/lifecycle/rebaser -previous-image some-original-image some-destination-image -``` - -As before, additional tags for the destination image can also be provided: - -```bash -/cnb/lifecycle/rebaser -previous-image some-original-image -tag some-additional-tag:latest some-destination-image -``` - -To use this feature, platforms can provide the new `-previous-image` flag to the `rebaser`. +To use this feature, builder authors should include a `/cnb/build-config/env/` directory with the desired configuration. diff --git a/content/docs/reference/spec/migration/platform-api-0.11-0.12.md b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md new file mode 100644 index 000000000..b64891625 --- /dev/null +++ b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md @@ -0,0 +1,128 @@ ++++ +title="Platform API 0.11 -> 0.12" ++++ + + + +This guide is most relevant to platform operators, base image authors, and builder authors. + +See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%2Fv0.12) for Platform API 0.12 for the full list of changes and further details. + +## Platform Operator + +### Stacks are deprecated + +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. + +#### During build + +The `-stack` flag is removed from the `analyzer` and `exporter` and replaced with a `-run` flag +that indicates the location of a `run.toml` file with schema: + +```toml +[[images]] + image = "" + mirrors = ["", ""] +``` + +For each image in `[[images]]`, `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 `run.toml`. + +#### After build + +The `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 `runImage.image` and `runImage.mirrors` in `io.buildpacks.lifecycle.metadata`. + +#### During rebase + +Additional validations were added to the `rebaser` along with a `-force` flag to force rebase when validations are not satisfied. + +If `-force` is not provided, +* The following values in the image config for the new run image must match the original image config: + * `os` + * `architecture` + * `variant` (if specified) + * `io.buildpacks.base.distro.name` label (if specified) + * `io.buildpacks.base.distro.version` label (if specified) +* If `-run-image` is provided it must be found in `io.buildpacks.lifecycle.metadata` in either `runImage.image` or `runImage.mirrors` +* `io.buildpacks.rebasable` must be `true` (see run image extension below) + +### Run image extensions is supported (experimental) + +In Platform 0.12 extensions can be used to extend not only build-time base images, but runtime base images as well. + +TODO + +### OCI layout is a supported export format + +TODO + +## Base Image Author + +### Stacks are deprecated + +When creating build-time or runtime base images, base image authors should set `io.buildpacks.base.distro.name` and `io.buildpacks.base.distro.version` labels +containing the values specified in `/etc/os-release` (`$ID` and `$VERSION_ID`). +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](https://github.com/buildpacks/spec/blob/main/platform.md#target-data) 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 `io.buildpacks.base.maintainer`, +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. + +## Builder Author + +### Stacks are deprecated + +With the removal of stacks, there is also a new way to reference build-time and runtime base images in `builder.toml`. +Builder authors should ensure their `pack` version is at least `0.30.0` in order to create builders that will work with newer platforms. + +The new `builder.toml` schema is: + +```toml +[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: + +```toml +[[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: + +```toml +[run-image] + image = "cnbs/some-run-image" + mirrors = ["mirror1", "mirror2"] +``` + +The old `builder.toml` schema is still valid: + +```toml +[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 `run.toml` and `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. diff --git a/content/docs/reference/spec/migration/platform-api-0.3-0.4.md b/content/docs/reference/spec/migration/platform-api-0.3-0.4.md index ade0c3bfb..c6e9b0c9d 100644 --- a/content/docs/reference/spec/migration/platform-api-0.3-0.4.md +++ b/content/docs/reference/spec/migration/platform-api-0.3-0.4.md @@ -6,7 +6,7 @@ title="Platform API 0.3 -> 0.4" This guide is most relevant to platform operators. -See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%2Fv0.4) for platform API 0.4 for the full list of changes and further details. +See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%2Fv0.4) for Platform API 0.4 for the full list of changes and further details. ### Windows support diff --git a/content/docs/reference/spec/migration/platform-api-0.4-0.5.md b/content/docs/reference/spec/migration/platform-api-0.4-0.5.md index 273297f47..112f26a65 100644 --- a/content/docs/reference/spec/migration/platform-api-0.4-0.5.md +++ b/content/docs/reference/spec/migration/platform-api-0.4-0.5.md @@ -6,7 +6,7 @@ title="Platform API 0.4 -> 0.5" This guide is most relevant to platform operators and stack authors. -See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%2Fv0.5) for platform API 0.5 for the full list of changes and further details. +See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%2Fv0.5) for Platform API 0.5 for the full list of changes and further details. ## Platform Operator diff --git a/content/docs/reference/spec/migration/platform-api-0.5-0.6.md b/content/docs/reference/spec/migration/platform-api-0.5-0.6.md index ee81aae26..bfd71099b 100644 --- a/content/docs/reference/spec/migration/platform-api-0.5-0.6.md +++ b/content/docs/reference/spec/migration/platform-api-0.5-0.6.md @@ -6,7 +6,7 @@ title="Platform API 0.5 -> 0.6" This guide is most relevant to platform operators. -See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%2Fv0.6) for platform API 0.6 for the full list of changes and further details. +See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%2Fv0.6) for Platform API 0.6 for the full list of changes and further details. ## Platform Operator diff --git a/content/docs/reference/spec/migration/platform-api-0.6-0.7.md b/content/docs/reference/spec/migration/platform-api-0.6-0.7.md index 84de32fc4..e9367aa86 100644 --- a/content/docs/reference/spec/migration/platform-api-0.6-0.7.md +++ b/content/docs/reference/spec/migration/platform-api-0.6-0.7.md @@ -6,7 +6,7 @@ title="Platform API 0.6 -> 0.7" This guide is most relevant to platform operators. -See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%2Fv0.7) for platform API 0.7 for the full list of changes and further details. +See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%2Fv0.7) for Platform API 0.7 for the full list of changes and further details. ## Platform Operator diff --git a/content/docs/reference/spec/migration/platform-api-0.7-0.8.md b/content/docs/reference/spec/migration/platform-api-0.7-0.8.md index d52c63f18..3a189840c 100644 --- a/content/docs/reference/spec/migration/platform-api-0.7-0.8.md +++ b/content/docs/reference/spec/migration/platform-api-0.7-0.8.md @@ -6,7 +6,7 @@ title="Platform API 0.7 -> 0.8" This guide is most relevant to platform operators. -See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%2Fv0.8) for platform API 0.8 for the full list of changes and further details. +See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%2Fv0.8) for Platform API 0.8 for the full list of changes and further details. ## Platform Operator diff --git a/content/docs/reference/spec/migration/platform-api-0.8-0.9.md b/content/docs/reference/spec/migration/platform-api-0.8-0.9.md index a816f861c..984338f32 100644 --- a/content/docs/reference/spec/migration/platform-api-0.8-0.9.md +++ b/content/docs/reference/spec/migration/platform-api-0.8-0.9.md @@ -6,7 +6,7 @@ title="Platform API 0.8 -> 0.9" This guide is most relevant to platform operators. -See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%2Fv0.9) for platform API 0.9 for the full list of changes and further details. +See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%2Fv0.9) for Platform API 0.9 for the full list of changes and further details. ## Platform Operator diff --git a/content/docs/reference/spec/migration/platform-api-0.9-0.10.md b/content/docs/reference/spec/migration/platform-api-0.9-0.10.md index 2c0624387..491f50f8a 100644 --- a/content/docs/reference/spec/migration/platform-api-0.9-0.10.md +++ b/content/docs/reference/spec/migration/platform-api-0.9-0.10.md @@ -6,7 +6,7 @@ title="Platform API 0.9 -> 0.10" This guide is most relevant to platform operators. -See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%2Fv0.10) for platform API 0.10 for the full list of changes and further details. +See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%2Fv0.10) for Platform API 0.10 for the full list of changes and further details. ## Platform Operator From f768621b5fdd88a291029ba60f309c130518a171 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 22 Aug 2023 13:12:25 -0400 Subject: [PATCH 03/14] WIP Signed-off-by: Natalie Arellano --- .../docs/reference/spec/migration/platform-api-0.11-0.12.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/content/docs/reference/spec/migration/platform-api-0.11-0.12.md b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md index b64891625..b16d2aa44 100644 --- a/content/docs/reference/spec/migration/platform-api-0.11-0.12.md +++ b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md @@ -26,8 +26,9 @@ that indicates the location of a `run.toml` file with schema: mirrors = ["", ""] ``` -For each image in `[[images]]`, `image` is a tag reference to a run image and `mirrors` contains tag references to its mirrors. +This file will be created automatically during `pack builder create` if the `pack` version is at least `0.30.0` (see below). +For each image in `[[images]]`, `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 `run.toml`. @@ -50,7 +51,7 @@ If `-force` is not provided, * `io.buildpacks.base.distro.name` label (if specified) * `io.buildpacks.base.distro.version` label (if specified) * If `-run-image` is provided it must be found in `io.buildpacks.lifecycle.metadata` in either `runImage.image` or `runImage.mirrors` -* `io.buildpacks.rebasable` must be `true` (see run image extension below) +* `io.buildpacks.rebasable` must be `true` (see below) ### Run image extensions is supported (experimental) From 64d81392a31e28dee19274f686bd545e145c0288 Mon Sep 17 00:00:00 2001 From: Juan Bustamante Date: Tue, 22 Aug 2023 12:58:37 -0500 Subject: [PATCH 04/14] adding section to migrate and use OCI layout format Signed-off-by: Juan Bustamante --- .../spec/migration/platform-api-0.11-0.12.md | 25 +++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/content/docs/reference/spec/migration/platform-api-0.11-0.12.md b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md index b16d2aa44..05fe8600d 100644 --- a/content/docs/reference/spec/migration/platform-api-0.11-0.12.md +++ b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md @@ -59,9 +59,30 @@ In Platform 0.12 extensions can be used to extend not only build-time base image TODO -### OCI layout is a supported export format +### OCI layout is a supported export format (experimental) -TODO +In Platform 0.12 a new capability to [export an application images on disk in OCI format](https://github.com/buildpacks/rfcs/blob/main/text/0119-export-to-oci.md) was added. + +Platform must take care of preparing a [local storage](https://github.com/buildpacks/rfcs/blob/main/text/0119-export-to-oci.md#how-it-works) on disk where images are being saved in OCI layout format and passing it through to the lifecycle. + +#### Lifecycle phases affected + +The lifecycle phases affected by this new behavior are: +- [Analyze](https://buildpacks.io/docs/concepts/components/lifecycle/analyze/) +- [Restore](https://buildpacks.io/docs/concepts/components/lifecycle/restore/) +- [Export](https://buildpacks.io/docs/concepts/components/lifecycle/export/) +- [Create](https://buildpacks.io/docs/concepts/components/lifecycle/create/) + +#### Before executing the lifecycle + +Input images required by any phase, like the `run-image`, must be saved on disk in OCI layout format in the local storage previously defined following the +[rules](https://github.com/buildpacks/spec/blob/platform/v0.12/platform.md#map-an-image-reference-to-a-path-in-the-layout-directory) to convert the reference to a path. + +#### During lifecycle execution + +For the phases affected, the feature is enabled using a new flag `-layout` or setting to **true** an environment variable named `CNB_USE_LAYOUT`. +* If the feature is enabled: + * A path to a directory where the images are saved in OCI layout format must be specified, either by setting the flag `-layout-dir` or the environment variable `CNB_LAYOUT_DIR`. ## Base Image Author From 05c2a2d598c17f427cadf735bf243f2dfeae9b8a Mon Sep 17 00:00:00 2001 From: Juan Bustamante Date: Tue, 22 Aug 2023 14:09:10 -0500 Subject: [PATCH 05/14] Apply suggestions from code review Co-authored-by: Natalie Arellano Signed-off-by: Juan Bustamante --- .../reference/spec/migration/platform-api-0.11-0.12.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/docs/reference/spec/migration/platform-api-0.11-0.12.md b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md index 05fe8600d..9cd85444e 100644 --- a/content/docs/reference/spec/migration/platform-api-0.11-0.12.md +++ b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md @@ -61,9 +61,9 @@ TODO ### OCI layout is a supported export format (experimental) -In Platform 0.12 a new capability to [export an application images on disk in OCI format](https://github.com/buildpacks/rfcs/blob/main/text/0119-export-to-oci.md) was added. +In Platform 0.12, a new capability to [export application images on disk in OCI layout format](https://github.com/buildpacks/rfcs/blob/main/text/0119-export-to-oci.md) was added. -Platform must take care of preparing a [local storage](https://github.com/buildpacks/rfcs/blob/main/text/0119-export-to-oci.md#how-it-works) on disk where images are being saved in OCI layout format and passing it through to the lifecycle. +Platform must prepare a [layout directory](https://github.com/buildpacks/rfcs/blob/main/text/0119-export-to-oci.md#how-it-works) containing input images in OCI layout format, and provide the location of the directory to the lifecycle. #### Lifecycle phases affected @@ -80,9 +80,9 @@ Input images required by any phase, like the `run-image`, must be saved on disk #### During lifecycle execution -For the phases affected, the feature is enabled using a new flag `-layout` or setting to **true** an environment variable named `CNB_USE_LAYOUT`. +For the phases affected, the feature is enabled by providing a new `-layout` flag or by setting the `CNB_USE_LAYOUT` environment variable to `true`. * If the feature is enabled: - * A path to a directory where the images are saved in OCI layout format must be specified, either by setting the flag `-layout-dir` or the environment variable `CNB_LAYOUT_DIR`. + * A path to a directory where the images are located and saved must be specified, either by providing a `-layout-dir` flag or by setting the `CNB_LAYOUT_DIR` environment variable. ## Base Image Author From aff636cc8dfa596642e1ea4a65921de6223dc66a Mon Sep 17 00:00:00 2001 From: Juan Bustamante Date: Tue, 22 Aug 2023 14:18:45 -0500 Subject: [PATCH 06/14] fixing some feedback from review Signed-off-by: Juan Bustamante --- .../docs/reference/spec/migration/platform-api-0.11-0.12.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/docs/reference/spec/migration/platform-api-0.11-0.12.md b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md index 9cd85444e..cb8526091 100644 --- a/content/docs/reference/spec/migration/platform-api-0.11-0.12.md +++ b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md @@ -73,9 +73,11 @@ The lifecycle phases affected by this new behavior are: - [Export](https://buildpacks.io/docs/concepts/components/lifecycle/export/) - [Create](https://buildpacks.io/docs/concepts/components/lifecycle/create/) +**Note** [Rebase](https://buildpacks.io/docs/concepts/components/lifecycle/rebase/) an image exported to OCI layout format is not supported. + #### Before executing the lifecycle -Input images required by any phase, like the `run-image`, must be saved on disk in OCI layout format in the local storage previously defined following the +Input images required by any phase, like the `run-image` or `previous-image`, must be saved on disk in OCI layout format in the local storage previously defined following the [rules](https://github.com/buildpacks/spec/blob/platform/v0.12/platform.md#map-an-image-reference-to-a-path-in-the-layout-directory) to convert the reference to a path. #### During lifecycle execution From f9fa4ba1bfeb524b60fbe0b72a2633d1025aec69 Mon Sep 17 00:00:00 2001 From: Juan Bustamante Date: Tue, 22 Aug 2023 15:46:49 -0500 Subject: [PATCH 07/14] Apply suggestions from code review Co-authored-by: Natalie Arellano Signed-off-by: Juan Bustamante --- .../docs/reference/spec/migration/platform-api-0.11-0.12.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/reference/spec/migration/platform-api-0.11-0.12.md b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md index cb8526091..61bff6aed 100644 --- a/content/docs/reference/spec/migration/platform-api-0.11-0.12.md +++ b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md @@ -73,11 +73,11 @@ The lifecycle phases affected by this new behavior are: - [Export](https://buildpacks.io/docs/concepts/components/lifecycle/export/) - [Create](https://buildpacks.io/docs/concepts/components/lifecycle/create/) -**Note** [Rebase](https://buildpacks.io/docs/concepts/components/lifecycle/rebase/) an image exported to OCI layout format is not supported. +**Note** [Rebasing](https://buildpacks.io/docs/concepts/components/lifecycle/rebase/) an image exported to OCI layout format is not supported. #### Before executing the lifecycle -Input images required by any phase, like the `run-image` or `previous-image`, must be saved on disk in OCI layout format in the local storage previously defined following the +Input images required by any phase, like the `run-image` or `previous-image`, must be saved on disk in OCI layout format in the layout directory following the [rules](https://github.com/buildpacks/spec/blob/platform/v0.12/platform.md#map-an-image-reference-to-a-path-in-the-layout-directory) to convert the reference to a path. #### During lifecycle execution From a4213175c3ce02114917227af0d4230010f8eced Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Wed, 23 Aug 2023 12:22:28 -0400 Subject: [PATCH 08/14] Finish TODO Signed-off-by: Natalie Arellano --- .../spec/migration/platform-api-0.11-0.12.md | 50 ++++++++++++------- .../spec/migration/platform-api-0.9-0.10.md | 4 +- 2 files changed, 33 insertions(+), 21 deletions(-) diff --git a/content/docs/reference/spec/migration/platform-api-0.11-0.12.md b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md index 61bff6aed..79f968e46 100644 --- a/content/docs/reference/spec/migration/platform-api-0.11-0.12.md +++ b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md @@ -51,40 +51,52 @@ If `-force` is not provided, * `io.buildpacks.base.distro.name` label (if specified) * `io.buildpacks.base.distro.version` label (if specified) * If `-run-image` is provided it must be found in `io.buildpacks.lifecycle.metadata` in either `runImage.image` or `runImage.mirrors` -* `io.buildpacks.rebasable` must be `true` (see below) +* `io.buildpacks.rebasable` must be `true` (see image extensions below) ### Run image extensions is supported (experimental) -In Platform 0.12 extensions can be used to extend not only build-time base images, but runtime base images as well. - -TODO +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: +* Invoke `analyzer` as usual for Platform 0.12 +* Invoke `detector` with the `-run` flag, to specify the location of a `run.toml` file containing run image information + * When extensions switch the run image, this is used to log a warning if the new run image is not a known run image +* Invoke `restorer` with the `-dameon` flag (newly added in this Platform API version) if the export target is a daemon + * When extensions switch the run image, the `restorer` must re-read target data from the new run image in order to provide this information to buildpacks; if `-daemon` is provided the `restorer` will look for the run image in a daemon instead of a registry + * When extensions extend the run image, the `-daemon` flag has no effect as the `restorer` must be able to pull the run image manifest from a registry +* Invoke `extender` as usual to extend the builder image (see [migration guide](TODO) for Platform 0.10) +* Inspect the contents of `analyzed.toml` - if `run-image.extend` is `true` we must run the `extender` on the run image +* Using the **run image** as the basis for the container, invoke `extender` with flags `-kind run` and `-extended ` + * `` is the directory where layers from applying each `run.Dockerfile` to the run image will be saved for use by the `exporter`; it defaults to `/extended` +* Invoke `exporter` with the `-extended` flag + +Note that unlike buildpack-provided layers, layers from extensions may NOT be safe to rebase. +The `io.buildpacks.rebasable` label on the exported application image will be `false` if rebase is unsafe. +The `-force` flag must be provided to the `rebaser` in order to rebase images with unsafe extension layers, +and should be used with great care. ### OCI layout is a supported export format (experimental) -In Platform 0.12, a new capability to [export application images on disk in OCI layout format](https://github.com/buildpacks/rfcs/blob/main/text/0119-export-to-oci.md) was added. +Platform 0.12 adds a new capability to [export application images on disk in OCI layout format](https://github.com/buildpacks/rfcs/blob/main/text/0119-export-to-oci.md). + +#### Before build -Platform must prepare a [layout directory](https://github.com/buildpacks/rfcs/blob/main/text/0119-export-to-oci.md#how-it-works) containing input images in OCI layout format, and provide the location of the directory to the lifecycle. +To use the feature, platforms must prepare a [layout directory](https://github.com/buildpacks/rfcs/blob/main/text/0119-export-to-oci.md#how-it-works) containing input images (`` or `` if available) in OCI layout format, +following the [rules](https://github.com/buildpacks/spec/blob/platform/v0.12/platform.md#map-an-image-reference-to-a-path-in-the-layout-directory) to convert the image reference to a path. + +#### During build -#### Lifecycle phases affected +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: -The lifecycle phases affected by this new behavior are: - [Analyze](https://buildpacks.io/docs/concepts/components/lifecycle/analyze/) - [Restore](https://buildpacks.io/docs/concepts/components/lifecycle/restore/) - [Export](https://buildpacks.io/docs/concepts/components/lifecycle/export/) - [Create](https://buildpacks.io/docs/concepts/components/lifecycle/create/) -**Note** [Rebasing](https://buildpacks.io/docs/concepts/components/lifecycle/rebase/) an image exported to OCI layout format is not supported. - -#### Before executing the lifecycle - -Input images required by any phase, like the `run-image` or `previous-image`, must be saved on disk in OCI layout format in the layout directory following the -[rules](https://github.com/buildpacks/spec/blob/platform/v0.12/platform.md#map-an-image-reference-to-a-path-in-the-layout-directory) to convert the reference to a path. - -#### During lifecycle execution +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. -For the phases affected, the feature is enabled by providing a new `-layout` flag or by setting the `CNB_USE_LAYOUT` environment variable to `true`. -* If the feature is enabled: - * A path to a directory where the images are located and saved must be specified, either by providing a `-layout-dir` flag or by setting the `CNB_LAYOUT_DIR` environment variable. +**Note**: [Rebasing](https://buildpacks.io/docs/concepts/components/lifecycle/rebase/) an image exported to OCI layout format +and extending OCI layout base images with Dockerfiles are currently not supported. ## Base Image Author diff --git a/content/docs/reference/spec/migration/platform-api-0.9-0.10.md b/content/docs/reference/spec/migration/platform-api-0.9-0.10.md index 491f50f8a..2d14230d6 100644 --- a/content/docs/reference/spec/migration/platform-api-0.9-0.10.md +++ b/content/docs/reference/spec/migration/platform-api-0.9-0.10.md @@ -71,11 +71,11 @@ Note: image extensions are not supported for Windows container images. * To create a builder with extensions, ensure the `pack` version in use is at least `0.28.0` and enable experimental features: `pack config experimental`. * Enable experimental features in the lifecycle by setting `CNB_EXPERIMENTAL_MODE=warn` or `CNB_EXPERIMENTAL_MODE=silent` in the lifecycle execution environment for ALL lifecycle phases * Invoke `analyzer` as usual -* Invoke `detector` with a new optional argument: `-generated`, to specify the directory where Dockerfiles generated by image extensions will be output (defaults to `/generated`) and include image extensions in `order.toml` +* Invoke `detector` with a new optional flag: `-generated`, to specify the directory where Dockerfiles generated by image extensions will be output (defaults to `/generated`) and include image extensions in `order.toml` * Dockerfiles for customizing the build image can be found in `/build//Dockerfile` * Dockerfiles for customizing the run image can be found in `/run//Dockerfile` * The new run image will be written to `analyzed.toml` -* Invoke `restorer` with a new required argument (when using extensions): `-build-image`, a tag reference to the builder image in use +* Invoke `restorer` with a new required flag (when using extensions): `-build-image`, a tag reference to the builder image in use * A new volume mount is introduced with target `/kaniko`; this volume must be writable by the `restorer` user * Invoke `extender` (new lifecycle binary), instead of `builder`; the extender will use kaniko to apply the relevant generated Dockerfiles to the build image and then drop privileges to run the `build` phase * The same volume from `restore` should be mounted at `/kaniko` From e898cf4eb3adaa8339f39d5e620c626c478f4917 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Wed, 23 Aug 2023 12:32:48 -0400 Subject: [PATCH 09/14] Fix broken link Signed-off-by: Natalie Arellano --- .../reference/spec/migration/platform-api-0.10-0.11.md | 8 +++++--- .../reference/spec/migration/platform-api-0.11-0.12.md | 7 ++++++- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/content/docs/reference/spec/migration/platform-api-0.10-0.11.md b/content/docs/reference/spec/migration/platform-api-0.10-0.11.md index 08d570075..b2d19a882 100644 --- a/content/docs/reference/spec/migration/platform-api-0.10-0.11.md +++ b/content/docs/reference/spec/migration/platform-api-0.10-0.11.md @@ -14,7 +14,8 @@ See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform% In Platform 0.11, the lifecycle ships with standardized SBOM files describing the `lifecycle` and `launcher` binaries (these are included in the tarball on the GitHub release page and within the image at `index.docker.io/buildpacksio/lifecycle:`). -SBOM files describing the `launcher` are included in the application image at `/sbom/launch/buildpacksio_lifecycle/launcher/sbom.`, + +After a build, SBOM files describing the `launcher` are included in the application image at `/sbom/launch/buildpacksio_lifecycle/launcher/sbom.`, where `` is each of: `cdx.json`, `spdx.json`, and `syft.json`. Additionally, SBOM files describing the `lifecycle` are copied to `/sbom/build/buildpacksio_lifecycle/sbom.`, where they may be saved off by the platform prior to the build container exiting. @@ -22,8 +23,9 @@ where they may be saved off by the platform prior to the build container exiting This mirrors what is already being done as of Platform 0.8 for buildpack-provided standardized SBOM files, which are exported to `/sbom/launch///sbom.` (for runtime dependencies) and copied to `/sbom/launch//sbom.` (for build-time dependencies). -Platforms that are already handling these files should not need to take additional action - -the resulting SBOMs will simply be more complete. + +To use this feature, no additional action is required from platforms that are already handling buildpack-provided SBOM files. +The SBOMs for the image will simply be more complete. ### The rebaser accepts a -previous-image flag to allow rebasing by digest reference diff --git a/content/docs/reference/spec/migration/platform-api-0.11-0.12.md b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md index 79f968e46..e63ce01ff 100644 --- a/content/docs/reference/spec/migration/platform-api-0.11-0.12.md +++ b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md @@ -57,6 +57,8 @@ If `-force` is not provided, In Platform 0.12, extensions can be used to extend not only build-time base images, but runtime base images as well. +#### During build + To use the feature, platforms should: * Invoke `analyzer` as usual for Platform 0.12 * Invoke `detector` with the `-run` flag, to specify the location of a `run.toml` file containing run image information @@ -64,12 +66,15 @@ To use the feature, platforms should: * Invoke `restorer` with the `-dameon` flag (newly added in this Platform API version) if the export target is a daemon * When extensions switch the run image, the `restorer` must re-read target data from the new run image in order to provide this information to buildpacks; if `-daemon` is provided the `restorer` will look for the run image in a daemon instead of a registry * When extensions extend the run image, the `-daemon` flag has no effect as the `restorer` must be able to pull the run image manifest from a registry -* Invoke `extender` as usual to extend the builder image (see [migration guide](TODO) for Platform 0.10) +* Invoke `extender` as usual to extend the builder image (see [migration guide](/docs/reference/spec/migration/platform-api-0.9-0.10/index.html) for Platform 0.10) * Inspect the contents of `analyzed.toml` - if `run-image.extend` is `true` we must run the `extender` on the run image * Using the **run image** as the basis for the container, invoke `extender` with flags `-kind run` and `-extended ` * `` is the directory where layers from applying each `run.Dockerfile` to the run image will be saved for use by the `exporter`; it defaults to `/extended` + * Run image extension may be done in parallel with builder image extension * Invoke `exporter` with the `-extended` flag +#### After build + Note that unlike buildpack-provided layers, layers from extensions may NOT be safe to rebase. The `io.buildpacks.rebasable` label on the exported application image will be `false` if rebase is unsafe. The `-force` flag must be provided to the `rebaser` in order to rebase images with unsafe extension layers, From 312a62812a3835e83a5c691d14b56b86abf36675 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Wed, 23 Aug 2023 12:43:21 -0400 Subject: [PATCH 10/14] Note cache cleanup Signed-off-by: Natalie Arellano --- .../reference/spec/migration/platform-api-0.11-0.12.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/content/docs/reference/spec/migration/platform-api-0.11-0.12.md b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md index e63ce01ff..84d100591 100644 --- a/content/docs/reference/spec/migration/platform-api-0.11-0.12.md +++ b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md @@ -80,6 +80,13 @@ The `io.buildpacks.rebasable` label on the exported application image will be `f The `-force` flag must be provided to the `rebaser` in order to rebase images with unsafe extension layers, and should be used with great care. +### The `exporter` no longer deletes cache images + +The `exporter` will no longer delete the previous version of the cache image before saving the new version - +which could lead to untagged blobs in the registry. + +Platforms should ensure that any untagged blobs are cleaned periodically if their registry does not already support such pruning. + ### OCI layout is a supported export format (experimental) Platform 0.12 adds a new capability to [export application images on disk in OCI layout format](https://github.com/buildpacks/rfcs/blob/main/text/0119-export-to-oci.md). From 9cbbcbfdd448807b8cdec65742d2d641e58800fe Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Wed, 23 Aug 2023 13:04:46 -0400 Subject: [PATCH 11/14] Apply suggestions from code review Signed-off-by: Natalie Arellano --- .../docs/reference/spec/migration/platform-api-0.11-0.12.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/reference/spec/migration/platform-api-0.11-0.12.md b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md index 84d100591..9f35c0279 100644 --- a/content/docs/reference/spec/migration/platform-api-0.11-0.12.md +++ b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md @@ -26,7 +26,7 @@ that indicates the location of a `run.toml` file with schema: mirrors = ["", ""] ``` -This file will be created automatically during `pack builder create` if the `pack` version is at least `0.30.0` (see below). +This file will be created automatically at `/cnb/run.toml` during `pack builder create` if the `pack` version is at least `0.30.0` (see below). For each image in `[[images]]`, `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. @@ -69,7 +69,7 @@ To use the feature, platforms should: * Invoke `extender` as usual to extend the builder image (see [migration guide](/docs/reference/spec/migration/platform-api-0.9-0.10/index.html) for Platform 0.10) * Inspect the contents of `analyzed.toml` - if `run-image.extend` is `true` we must run the `extender` on the run image * Using the **run image** as the basis for the container, invoke `extender` with flags `-kind run` and `-extended ` - * `` is the directory where layers from applying each `run.Dockerfile` to the run image will be saved for use by the `exporter`; it defaults to `/extended` + * `` is the directory where layers created from the application of each `run.Dockerfile` to the run image will be saved for use by the `exporter`; it defaults to `/extended` * Run image extension may be done in parallel with builder image extension * Invoke `exporter` with the `-extended` flag From fa68c1246d46ad16185fc3a116f2983a61cef2e3 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Wed, 23 Aug 2023 13:07:17 -0400 Subject: [PATCH 12/14] Fix formatting Signed-off-by: Natalie Arellano --- content/docs/app-developer-guide/using-inline-buildpacks.md | 2 +- .../create-extension/building-blocks-extension.md | 2 +- .../docs/reference/spec/migration/buildpack-api-0.4-0.5.md | 2 +- .../docs/reference/spec/migration/buildpack-api-0.5-0.6.md | 2 +- .../docs/reference/spec/migration/buildpack-api-0.6-0.7.md | 2 +- .../docs/reference/spec/migration/buildpack-api-0.7-0.8.md | 2 +- .../docs/reference/spec/migration/buildpack-api-0.8-0.9.md | 2 +- .../docs/reference/spec/migration/platform-api-0.3-0.4.md | 2 +- .../docs/reference/spec/migration/platform-api-0.9-0.10.md | 6 +++--- 9 files changed, 11 insertions(+), 11 deletions(-) diff --git a/content/docs/app-developer-guide/using-inline-buildpacks.md b/content/docs/app-developer-guide/using-inline-buildpacks.md index 0e2a66946..713e2d9a2 100644 --- a/content/docs/app-developer-guide/using-inline-buildpacks.md +++ b/content/docs/app-developer-guide/using-inline-buildpacks.md @@ -27,7 +27,7 @@ id = "me/rake-tasks" inline = "rake package" ``` -In this example, the `me/rake-tasks` inline buildpack is configured to run after the `example/ruby` buildpack. The inline script is compatible with buildpack API version `0.6` (this is a required field), and it will execute the `rake package` command during the build step. +In this example, the `me/rake-tasks` inline buildpack is configured to run after the `example/ruby` buildpack. The inline script is compatible with Buildpack API version `0.6` (this is a required field), and it will execute the `rake package` command during the build step. > **Note:** Inline buildpacks will _always_ pass detection. diff --git a/content/docs/extension-guide/create-extension/building-blocks-extension.md b/content/docs/extension-guide/create-extension/building-blocks-extension.md index 3cd2322b4..6b126d8b3 100644 --- a/content/docs/extension-guide/create-extension/building-blocks-extension.md +++ b/content/docs/extension-guide/create-extension/building-blocks-extension.md @@ -26,7 +26,7 @@ You should see something akin to the following: ``` * The `extension.toml` describes the extension, containing information such as its name, ID, and version, as well as the - buildpack API that it implements. Though extensions are not buildpacks, they are expected to conform to the buildpack + Buildpack API that it implements. Though extensions are not buildpacks, they are expected to conform to the Buildpack API except where noted. Consult the [spec](https://github.com/buildpacks/spec/blob/main/image_extension.md) for further details. * `./bin/detect` is invoked during the `detect` phase. It analyzes application source code to determine if the extension diff --git a/content/docs/reference/spec/migration/buildpack-api-0.4-0.5.md b/content/docs/reference/spec/migration/buildpack-api-0.4-0.5.md index 6f3bef485..e43706615 100644 --- a/content/docs/reference/spec/migration/buildpack-api-0.4-0.5.md +++ b/content/docs/reference/spec/migration/buildpack-api-0.4-0.5.md @@ -6,7 +6,7 @@ title="Buildpack API 0.4 -> 0.5" This guide is most relevant to buildpack authors. -See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.5) for buildpack API 0.5 for the full list of changes and further details. +See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.5) for Buildpack API 0.5 for the full list of changes and further details. ### Stack ID The buildpack may now indicate compatibility with any stack by specifying the special value `*`. diff --git a/content/docs/reference/spec/migration/buildpack-api-0.5-0.6.md b/content/docs/reference/spec/migration/buildpack-api-0.5-0.6.md index 470c55f68..760d4f11e 100644 --- a/content/docs/reference/spec/migration/buildpack-api-0.5-0.6.md +++ b/content/docs/reference/spec/migration/buildpack-api-0.5-0.6.md @@ -6,7 +6,7 @@ title="Buildpack API 0.5 -> 0.6" This guide is most relevant to buildpack authors. -See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.6) for buildpack API 0.6 for the full list of changes and further details. +See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.6) for Buildpack API 0.6 for the full list of changes and further details. ### Opt-in layer caching and launch.toml format changes diff --git a/content/docs/reference/spec/migration/buildpack-api-0.6-0.7.md b/content/docs/reference/spec/migration/buildpack-api-0.6-0.7.md index ae8931bbd..cb508e41e 100644 --- a/content/docs/reference/spec/migration/buildpack-api-0.6-0.7.md +++ b/content/docs/reference/spec/migration/buildpack-api-0.6-0.7.md @@ -6,7 +6,7 @@ title="Buildpack API 0.6 -> 0.7" This guide is most relevant to buildpack authors. -See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.7) for buildpack API 0.7 for the full list of changes and further details. +See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.7) for Buildpack API 0.7 for the full list of changes and further details. ### New standardized SBOM format diff --git a/content/docs/reference/spec/migration/buildpack-api-0.7-0.8.md b/content/docs/reference/spec/migration/buildpack-api-0.7-0.8.md index 3b022713d..9e3d2cf2f 100644 --- a/content/docs/reference/spec/migration/buildpack-api-0.7-0.8.md +++ b/content/docs/reference/spec/migration/buildpack-api-0.7-0.8.md @@ -6,7 +6,7 @@ title="Buildpack API 0.7 -> 0.8" This guide is most relevant to buildpack authors. -See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.8) for buildpack API 0.8 for the full list of changes and further details. +See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.8) for Buildpack API 0.8 for the full list of changes and further details. ### Process-Specific Working Directory diff --git a/content/docs/reference/spec/migration/buildpack-api-0.8-0.9.md b/content/docs/reference/spec/migration/buildpack-api-0.8-0.9.md index e34c5f24b..8e6bbb62b 100644 --- a/content/docs/reference/spec/migration/buildpack-api-0.8-0.9.md +++ b/content/docs/reference/spec/migration/buildpack-api-0.8-0.9.md @@ -6,7 +6,7 @@ title="Buildpack API 0.8 -> 0.9" This guide is most relevant to buildpack authors. -See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.9) for buildpack API 0.9 for the full list of changes and further details. +See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.9) for Buildpack API 0.9 for the full list of changes and further details. ### Shell removal diff --git a/content/docs/reference/spec/migration/platform-api-0.3-0.4.md b/content/docs/reference/spec/migration/platform-api-0.3-0.4.md index ade0c3bfb..95a4dfd85 100644 --- a/content/docs/reference/spec/migration/platform-api-0.3-0.4.md +++ b/content/docs/reference/spec/migration/platform-api-0.3-0.4.md @@ -30,7 +30,7 @@ When building, platforms can optionally specify the location of the report, or s When interpreting the Bill-of-Materials (BOM), `version` [will no longer be found at the top level](https://github.com/buildpacks/spec/pull/117). The lifecycle will convert any `version` provided by buildpacks to `metadata.version`. -Related: as of buildpack API 0.3, `version` is [deprecated](https://github.com/buildpacks/spec/pull/97) as a top-level key in the build plan. +Related: as of Buildpack API 0.3, `version` is [deprecated](https://github.com/buildpacks/spec/pull/97) as a top-level key in the build plan. ### New exit code definition diff --git a/content/docs/reference/spec/migration/platform-api-0.9-0.10.md b/content/docs/reference/spec/migration/platform-api-0.9-0.10.md index 2c0624387..d3241bf52 100644 --- a/content/docs/reference/spec/migration/platform-api-0.9-0.10.md +++ b/content/docs/reference/spec/migration/platform-api-0.9-0.10.md @@ -12,11 +12,11 @@ See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform% ### The `launcher` supports overridable process arguments -The way user-provided arguments are handled by the launcher depends on the buildpack API of the buildpack that created the process definition. +The way user-provided arguments are handled by the launcher depends on the Buildpack API of the buildpack that created the process definition. #### Newer buildpacks -Process types contributed by newer buildpacks (buildpack API 0.9 and above) may have overridable process arguments. Looking at metadata.toml: +Process types contributed by newer buildpacks (Buildpack API 0.9 and above) may have overridable process arguments. Looking at metadata.toml: ``` [[processes]] type = "from-newer-buildpack" @@ -40,7 +40,7 @@ will result in the following command invocation: `some-command always-1 always-2 #### Older buildpacks -Process types contributed by older buildpacks (buildpack API 0.8 and below) do not have overridable process arguments. Looking at metadata.toml: +Process types contributed by older buildpacks (Buildpack API 0.8 and below) do not have overridable process arguments. Looking at metadata.toml: ``` [[processes]] type = "from-older-buildpack" From 6742a6a7174f9c90677c6277cdfdf501e93889fb Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Wed, 23 Aug 2023 13:07:27 -0400 Subject: [PATCH 13/14] Add migration guide for Buildpack 0.10 Signed-off-by: Natalie Arellano --- .../spec/migration/buildpack-api-0.9-0.10.md | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 content/docs/reference/spec/migration/buildpack-api-0.9-0.10.md diff --git a/content/docs/reference/spec/migration/buildpack-api-0.9-0.10.md b/content/docs/reference/spec/migration/buildpack-api-0.9-0.10.md new file mode 100644 index 000000000..7835b30f7 --- /dev/null +++ b/content/docs/reference/spec/migration/buildpack-api-0.9-0.10.md @@ -0,0 +1,55 @@ ++++ +title="Buildpack API 0.9 -> 0.10" ++++ + + + +This guide is most relevant to buildpack authors. + +See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.10) for Buildpack API 0.10 for the full list of changes and further details. + +### Stacks are deprecated + +In Buildpack 0.10, 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. + +#### Before build + +`builder.toml` contains a new table for buildpacks to express the os/arch combinations that they are compatible with: + +```toml +[[targets]] +os = "" +arch = "" +variant = "" +[[targets.distros]] +name = "" +version = "" +``` + +All fields are optional and any missing field is assumed to "match any". + +This information will be used by the lifecycle to skip running detect on any buildpack that is not compatible with the current os/arch. + +Note that the `[[stacks]]` table is still supported and buildpack authors are encouraged to continue to provide this information for the time being +in order to maintain compatibility with older platforms. + +#### During build + +The lifecycle will provide the following environment variables during `detect` and `build` to describe the target os/arch: + +| Env Variable | Description | +|-----------------------------|-------------------------------------------| +| `CNB_TARGET_OS` | Target OS | +| `CNB_TARGET_ARCH` | Target architecture | +| `CNB_TARGET_ARCH_VARIANT` | Target architecture variant (optional) | +| `CNB_TARGET_DISTRO_NAME` | Target OS distribution name (optional) | +| `CNB_TARGET_DISTRO_VERISON` | Target OS distribution version (optional) | + +Buildpacks can use this information to modify their behavior depending on the target. + +### Run image extensions is supported (experimental) + +In Platform 0.12, extensions can be used to extend not only build-time base images, but runtime base images as well. + +For more information, see [authoring an image extension](/docs/extension-guide/create-extension). From 2822f65f06d65db8d8dca28cb74d39368fc6a854 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 25 Aug 2023 11:35:24 -0400 Subject: [PATCH 14/14] Remove cache cleanup from 0.12 migration as it isn't implemented until 0.13 Signed-off-by: Natalie Arellano --- .../reference/spec/migration/platform-api-0.11-0.12.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/content/docs/reference/spec/migration/platform-api-0.11-0.12.md b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md index 9f35c0279..84e913cb8 100644 --- a/content/docs/reference/spec/migration/platform-api-0.11-0.12.md +++ b/content/docs/reference/spec/migration/platform-api-0.11-0.12.md @@ -80,13 +80,6 @@ The `io.buildpacks.rebasable` label on the exported application image will be `f The `-force` flag must be provided to the `rebaser` in order to rebase images with unsafe extension layers, and should be used with great care. -### The `exporter` no longer deletes cache images - -The `exporter` will no longer delete the previous version of the cache image before saving the new version - -which could lead to untagged blobs in the registry. - -Platforms should ensure that any untagged blobs are cleaned periodically if their registry does not already support such pruning. - ### OCI layout is a supported export format (experimental) Platform 0.12 adds a new capability to [export application images on disk in OCI layout format](https://github.com/buildpacks/rfcs/blob/main/text/0119-export-to-oci.md).