Skip to content

Commit

Permalink
Update RFC96 to match what landed in the spec
Browse files Browse the repository at this point in the history
A few changes were made to what was in the RFC when it came to update the spec.

This backports those changes to the RFC to try and prevent user confusion if they use the RFC as a means of learning about targets when implementing.

Specifically:
- The `io.buildpacks.distribution.*` Docker labels were renamed to `io.buildpacks.base.distro.*`.
- The `io.buildpacks.id` Docker label was renamed to `io.buildpacks.base.id`.
- The `buildpack.toml` table `[[targets.distributions]]` was renamed to `[[targets.distros]]` and the `versions` field within it renamed to `version` (along with its type changing from an array to a string).

See:
https://github.com/buildpacks/spec/blob/platform/0.13/platform.md#target-data

Signed-off-by: Ed Morley <[email protected]>
  • Loading branch information
edmorley committed Apr 10, 2024
1 parent 822d702 commit 8c2a6a0
Showing 1 changed file with 32 additions and 12 deletions.
44 changes: 32 additions & 12 deletions text/0096-remove-stacks-mixins.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,19 +41,19 @@ Instead of a stack ID, runtime and build-time base images must contain the follo
- OS (e.g., "linux", `$GOOS`), specified as `os` in the base image `config`
- Architecture (e.g., "arm", `$GOARCH`), specified as `architecture` in the base image `config`
- Architecture Variant (optional) (e.g., "v6", `$GOARM`), specified as `variant` in the base image `config`
- Distribution (optional) (e.g., "ubuntu", `$ID`), specified as a label `io.buildpacks.distribution.name`
- Version (optional) (e.g., "18.04", `$VERSION_ID`), specified as a label `io.buildpacks.distribution.version`
- Distribution (optional) (e.g., "ubuntu", `$ID`), specified as a label `io.buildpacks.base.distro.name`
- Version (optional) (e.g., "18.04", `$VERSION_ID`), specified as a label `io.buildpacks.base.distro.version`

Additionally, the runtime base may contain the following metadata:
- Target ID (optional) (e.g., "minimal"), specified as a label `io.buildpacks.id`
- Target ID (optional) (e.g., "minimal"), specified as a label `io.buildpacks.base.id`

OS, Architecture, and Architecture Variant must be valid identifiers as defined in the [OCI Image specification](https://github.com/opencontainers/image-spec/blob/main/config.md).

Target ID is an identifier specified on the runtime base image that must be provided to buildpacks as `CNB_TARGET_ID` during the build process.
This allows buildpacks to change their behavior if a run image is selected (e.g., distroless) that has special properties outside of OS, architecture, etc.

For Linux-based images, each field should be canonicalized against values specified in `/etc/os-release` (`$ID` and `$VERSION_ID`).
The `os.version` field in an base image `config` may contain combined distribution and version information, but it is not used by the lifecycle.
The `os.version` field in a base image `config` may contain combined distribution and version information, but it is not used by the lifecycle.

For Windows-based images, Distribution should be empty. Version should be the [suggested value of `os.version`](https://github.com/opencontainers/image-spec/blob/main/config.md#properties) in the OCI spec (e.g., `10.0.14393.1066`).

Expand Down Expand Up @@ -81,17 +81,17 @@ versions = ["18.04", "20.04"]
[[targets]]
os = "linux"
arch = "amd64"
[[targets.distributions]]
[[targets.distros]]
name = "ubuntu"
versions = ["14.04", "16.04"]
version = "16.04"

[[targets]]
os = "linux"
arch = "arm"
variant = "v6"
[[targets.distributions]]
[[targets.distros]]
name = "ubuntu"
versions = ["14.04", "16.04"]
version = "16.04"
```

## Runtime Metadata
Expand Down Expand Up @@ -153,11 +153,11 @@ If the newly-specified field values are missing, the lifecycle and pack may used
```
config.os = "linux"
config.architecture = "amd64"
io.buildpacks.distribution.name = "ubuntu"
io.buildpacks.distribution.version = "18.04"
io.buildpacks.base.distro.name = "ubuntu"
io.buildpacks.base.distro.version = "18.04"
```

Moving forward it's encouraged for buildpack authors to support both `[[stacks]]` and `[[targets]]` sections in `buildpack.toml` for maximum compatibility. In order to ease this process for those using the `io.buildpacks.stacks.bionic`, lifecycle will translate any section that sets this as on of the `stacks`:
Moving forward it's encouraged for buildpack authors to support both `[[stacks]]` and `[[targets]]` sections in `buildpack.toml` for maximum compatibility. In order to ease this process for those using the `io.buildpacks.stacks.bionic`, lifecycle will translate any section that sets this as one of the `stacks`:

```toml
[[stacks]]
Expand All @@ -170,7 +170,7 @@ to
[[targets]]
os = "linux"
arch = "amd64"
[[targets.distributions]]
[[targets.distros]]
name = "ubuntu"
versions = ["18.04"]
```
Expand Down Expand Up @@ -210,3 +210,23 @@ rename x86_64 -> amd64 in keeping with all other usages of arch. descriptors.
### Motivation

This is how we do it everywhere else, this is the way.

## Amended
### Meta
[meta-1]: #meta-1
- Name: Rename Docker labels and `buildpack.toml` table names
- Start Date: 2024-04-08
- Author(s): @edmorley
- Amendment Pull Request: [rfcs#310](https://github.com/buildpacks/rfcs/pull/310)

### Summary

Changes were made to the Docker label and `buildpack.toml` table names between when this RFC was written and the changes were made to the spec in [spec#365](https://github.com/buildpacks/spec/pull/365), which have now been backported to the RFC:

- The `io.buildpacks.distributions.*` Docker labels were renamed to `io.buildpacks.base.distro.*`.
- The `io.buildpacks.id` Docker label was renamed to `io.buildpacks.base.id`.
- The `buildpack.toml` table `[[targets.distributions]]` was renamed to `[[targets.distros]]` and the `versions` field within it renamed to `version` (along with its type changing from an array to a string).

### Motivation

To prevent use of the wrong Docker label or `buildpack.toml` table names, if users base their implementations on the RFC rather than reading the spec.

0 comments on commit 8c2a6a0

Please sign in to comment.