Skip to content

Commit 93b8489

Browse files
author
Natalie Arellano
committed
Add migration guides for latest apis
Signed-off-by: Natalie Arellano <[email protected]>
1 parent 248be20 commit 93b8489

File tree

3 files changed

+106
-1
lines changed

3 files changed

+106
-1
lines changed

‎content/docs/reference/spec/buildpack-api.md

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,7 @@ A buildpack must contain a `buildpack.toml` file in its root directory.
129129
### Example
130130

131131
```
132-
api = "0.5"
132+
api = "0.7"
133133
134134
[buildpack]
135135
id = "example.com/python"
@@ -163,6 +163,27 @@ The schema is as follows:
163163

164164
- **`clear-env`** _(boolean, optional, default: `false`)_\
165165
Clears user-defined environment variables when `true` on executions of `bin/detect` and `bin/build`.
166+
167+
- **`homepage`** _(string, optional)_\
168+
Buildpack homepage.
169+
170+
- **`description`** _(string, optional)_\
171+
A short description of the buildpack.
172+
173+
- **`keywords`** _(string(s), optional)_\
174+
Keywords to help locate the buildpack. These can be useful if publishing to the [Buildpack Registry](https://registry.buildpacks.io/).
175+
176+
- **`sbom-formats`** _(string(s), optional)_\
177+
SBOM formats output by the buildpack. Supported values are the following media types: `application/vnd.cyclonedx+json`, `application/spdx+json`, and `application/vnd.syft+json`.
178+
179+
- **`licenses`** _(list, optional)_\
180+
A list of licenses pertaining to the buildpack.
181+
182+
- **`type`** _(string, optional)_\
183+
The type of the license. This may use the [SPDX 2.1 license expression](https://spdx.org/spdx-specification-21-web-version), but it is not limited to identifiers in the [SPDX Licenses List](https://spdx.org/licenses/). If the buildpack is using a nonstandard license, then the `uri` key may be specified in lieu of or in addition to `type` to point to the license.
184+
185+
- **`uri`** _(string, optional)_\
186+
A URL or path to the license.
166187

167188
- **`stacks`** _(list, optional)_\
168189
A list of stacks supported by the buildpack.

‎content/docs/reference/spec/migration/buildpack-api-0.6-0.7.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
+++
2+
title="Buildpack API 0.6 -> 0.7"
3+
+++
4+
5+
<!--more-->
6+
7+
This guide is most relevant to buildpack authors.
8+
9+
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.
10+
11+
### New standardized SBOM format
12+
13+
Buildpacks may write Software Bill of Materials (SBOM) files describing build- or run-time dependencies. These files must use the `application/vnd.cyclonedx+json`, `application/spdx+json`, or `application/vnd.syft+json` media types (a buildpack may output SBOM files in multiple formats). Files may be written to the following locations:
14+
15+
* `<layers>/<layer>.sbom.<ext>` - for describing dependencies associated with a layer
16+
* Example (launch layer): libraries that were included in an output compiled binary (e.g., `go` libraries in a `go` binary)
17+
* Example (build layer): tools like a package manager
18+
* `<layers>/launch.sbom.<ext>` - for describing run-time dependencies not associated with a layer
19+
* Example: dependencies installed in the `/workspace` directory
20+
* `<layers>/build.sbom.<ext>` - for describing build-time dependencies not associated with a layer
21+
* Example: build time configuration
22+
23+
Valid `<ext>` extensions are as follows:
24+
| SBOM Media Type | File Extension
25+
|----------------------------------|----------------------------------------------
26+
| `application/vnd.cyclonedx+json` | `cdx.json`
27+
| `application/spdx+json` | `spdx.json`
28+
| `application/vnd.syft+json` | `syft.json`
29+
30+
SBOM files for launch will be included in the application image if the platform api supports it; SBOM files for build may be saved off by the platform prior to the build container exiting. Layer-associated SBOM files will be cached and restored to the buildpack layers directory on re-builds of the same image (much like the `<layers>/<layer>.toml` metadata file).
31+
32+
The `[bom]` tables in launch.toml and build.toml are no longer supported.
33+
34+
### New fields in buildpack descriptor
35+
36+
* A `sbom-formats` array indicating the SBOM formats output by the buildpack.

‎content/docs/reference/spec/migration/platform-api-0.7-0.8.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
+++
2+
title="Platform API 0.7 -> 0.8"
3+
+++
4+
5+
<!--more-->
6+
7+
This guide is most relevant to platform operators.
8+
9+
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.
10+
11+
## Platform Operator
12+
13+
### New standardized SBOM format
14+
15+
Buildpacks implementing Buildpack API 0.7+ may output write Software Bill of Materials (SBOM) files describing build- or run-time dependencies. These files must use the `application/vnd.cyclonedx+json`, `application/spdx+json`, or `application/vnd.syft+json` media types (a buildpack may output SBOM files in multiple formats). Files may be written to the following locations:
16+
17+
* `<layers>/<buildpack-id>/<layer>.sbom.<ext>` - for describing dependencies associated with a layer
18+
* `<layers>/<buildpack-id>/launch.sbom.<ext>` - for describing run-time dependencies not associated with a layer
19+
* `<layers>/<buildpack-id>/build.sbom.<ext>` - for describing build-time dependencies not associated with a layer
20+
21+
Valid `<ext>` extensions are as follows:
22+
| SBOM Media Type | File Extension
23+
|----------------------------------|----------------------------------------------
24+
| `application/vnd.cyclonedx+json` | `cdx.json`
25+
| `application/spdx+json` | `spdx.json`
26+
| `application/vnd.syft+json` | `syft.json`
27+
28+
#### Launch
29+
30+
SBOM files for launch will be included in the application image at the following locations:
31+
32+
* `<layers>/<buildpack-id>/<layer>.sbom.<ext>` (as written by the buildpack) is moved to `<layers>/sbom/launch/<buildpack-id>/<layer>/sbom.<ext>` for launch layers
33+
* `<layers>/<buildpack-id>/launch.sbom.<ext>` (as written by the buildpack) is moved to `<layers>/sbom/launch/<buildpack-id>/sbom.<ext>`
34+
35+
The platform can retrieve the digest of the layer containing the SBOM files by reading the `sbom` key from the `io.buildpacks.lifecycle.metadata` label.
36+
37+
#### Build
38+
39+
SBOM files for build will be available in the build container at the following locations:
40+
41+
* `<layers>/<buildpack-id>/<layer>.sbom.<ext>` (as written by the buildpack) is moved to `<layers>/sbom/build/<buildpack-id>/<layer>/sbom.<ext>` for non-launch layers
42+
* `<layers>/<buildpack-id>/build.sbom.<ext>` (as written by the buildpack) is moved to `<layers>/sbom/build/<buildpack-id>/sbom.<ext>`
43+
44+
Note that the `<layers>/sbom/build` directory is NOT present in the application image. It may be saved off by the platform prior to the build container exiting.
45+
46+
#### Backwards compatibility - older buildpacks
47+
48+
Platforms can continue to retrieve BOM information output by buildpacks implementing Buildpack API < 0.7 by reading the `bom` key in the `io.buildpacks.build.metadata` label (for run-time dependencies), and by saving off report.toml prior to the build container exiting (for build-time dependencies).

0 commit comments

Comments
 (0)