|
| 1 | ++++ |
| 2 | +title="Platform API 0.11 -> 0.12" |
| 3 | ++++ |
| 4 | + |
| 5 | +<!--more--> |
| 6 | + |
| 7 | +This guide is most relevant to platform operators, base image authors, and builder authors. |
| 8 | + |
| 9 | +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. |
| 10 | + |
| 11 | +## Platform Operator |
| 12 | + |
| 13 | +### Stacks are deprecated |
| 14 | + |
| 15 | +In Platform 0.12, the concepts of stacks and mixins are removed |
| 16 | +in favor of existing constructs in the container image ecosystem such as operating system name, operating system distribution, and architecture. |
| 17 | + |
| 18 | +#### During build |
| 19 | + |
| 20 | +The `-stack` flag is removed from the `analyzer` and `exporter` and replaced with a `-run` flag |
| 21 | +that indicates the location of a `run.toml` file with schema: |
| 22 | + |
| 23 | +```toml |
| 24 | +[[images]] |
| 25 | + image = "<image>" |
| 26 | + mirrors = ["<mirror>", "<mirror>"] |
| 27 | +``` |
| 28 | + |
| 29 | +For each image in `[[images]]`, `image` is a tag reference to a run image and `mirrors` contains tag references to its mirrors. |
| 30 | + |
| 31 | +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. |
| 32 | +This is because of image extensions and the possibility of run image switching, introduced in Platform 0.10. |
| 33 | +For platforms that do not use image extensions, only a single run image with mirrors is needed in `run.toml`. |
| 34 | + |
| 35 | +#### After build |
| 36 | + |
| 37 | +The `stack` key in the `io.buildpacks.lifecycle.metadata` is removed. |
| 38 | +To find a tag reference to the run image and mirrors information, |
| 39 | +platforms should read the newly added `runImage.image` and `runImage.mirrors` in `io.buildpacks.lifecycle.metadata`. |
| 40 | + |
| 41 | +#### During rebase |
| 42 | + |
| 43 | +Additional validations were added to the `rebaser` along with a `-force` flag to force rebase when validations are not satisfied. |
| 44 | + |
| 45 | +If `-force` is not provided, |
| 46 | +* The following values in the image config for the new run image must match the original image config: |
| 47 | + * `os` |
| 48 | + * `architecture` |
| 49 | + * `variant` (if specified) |
| 50 | + * `io.buildpacks.base.distro.name` label (if specified) |
| 51 | + * `io.buildpacks.base.distro.version` label (if specified) |
| 52 | +* If `-run-image` is provided it must be found in `io.buildpacks.lifecycle.metadata` in either `runImage.image` or `runImage.mirrors` |
| 53 | +* `io.buildpacks.rebasable` must be `true` (see run image extension below) |
| 54 | + |
| 55 | +### Run image extensions is supported (experimental) |
| 56 | + |
| 57 | +In Platform 0.12 extensions can be used to extend not only build-time base images, but runtime base images as well. |
| 58 | + |
| 59 | +TODO |
| 60 | + |
| 61 | +### OCI layout is a supported export format |
| 62 | + |
| 63 | +TODO |
| 64 | + |
| 65 | +## Base Image Author |
| 66 | + |
| 67 | +### Stacks are deprecated |
| 68 | + |
| 69 | +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 |
| 70 | +containing the values specified in `/etc/os-release` (`$ID` and `$VERSION_ID`). |
| 71 | +This information - along with operating system, architecture, and architecture variant from the OCI image config, |
| 72 | +will be exposed to buildpacks through `$CNB_TARGET_*` environment variables. |
| 73 | + |
| 74 | +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. |
| 75 | + |
| 76 | +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. |
| 77 | +Note that "information only" labels such as `io.buildpacks.stack.maintainer` have new equivalents in `io.buildpacks.base.maintainer`, |
| 78 | +and it is recommended to set both sets of labels for the time being. |
| 79 | + |
| 80 | +To maintain compatibility with older buildpacks, build-time base images should continue to set `$CNB_STACK_ID` in the build environment. |
| 81 | + |
| 82 | +## Builder Author |
| 83 | + |
| 84 | +### Stacks are deprecated |
| 85 | + |
| 86 | +With the removal of stacks, there is also a new way to reference build-time and runtime base images in `builder.toml`. |
| 87 | +Builder authors should ensure their `pack` version is at least `0.30.0` in order to create builders that will work with newer platforms. |
| 88 | + |
| 89 | +The new `builder.toml` schema is: |
| 90 | + |
| 91 | +```toml |
| 92 | +[run] |
| 93 | +[[run.images]] |
| 94 | +image = "cnbs/some-run-image" |
| 95 | +mirrors = ["mirror1", "mirror2"] |
| 96 | +[build] |
| 97 | +image = "cnbs/some-build-image" |
| 98 | +``` |
| 99 | + |
| 100 | +Run image information will be translated to `run.toml` in the builder with schema: |
| 101 | + |
| 102 | +```toml |
| 103 | +[[images]] |
| 104 | + image = "cnbs/some-run-image" |
| 105 | + mirrors = ["mirror1", "mirror2"] |
| 106 | +``` |
| 107 | + |
| 108 | +Run image information will also be translated to `stack.toml` (for compatibility with older platforms) in the builder with schema: |
| 109 | + |
| 110 | +```toml |
| 111 | +[run-image] |
| 112 | + image = "cnbs/some-run-image" |
| 113 | + mirrors = ["mirror1", "mirror2"] |
| 114 | +``` |
| 115 | + |
| 116 | +The old `builder.toml` schema is still valid: |
| 117 | + |
| 118 | +```toml |
| 119 | +[stack] |
| 120 | +id = "some.stack.id" |
| 121 | +run-image = "cnbs/some-run-image" |
| 122 | +run-image-mirrors = ["mirror1", "mirror2"] |
| 123 | +build-image = "cnbs/some-build-image" |
| 124 | +``` |
| 125 | + |
| 126 | +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. |
| 127 | + |
| 128 | +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. |
0 commit comments