Skip to content

Commit

Permalink
Merge branch 'main' into feat/remove-windows-containers-suppport
Browse files Browse the repository at this point in the history
  • Loading branch information
AidanDelaney authored Dec 10, 2024
2 parents ff8c235 + ecb2711 commit 08622ca
Show file tree
Hide file tree
Showing 10 changed files with 856 additions and 50 deletions.
2 changes: 1 addition & 1 deletion .github/auto-assign-bat.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,4 @@ filterLabels:
assignees:
- ekcasey
- hone
- samj1912
- sambhav
1 change: 0 additions & 1 deletion .github/auto-assign-learning.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,3 @@ filterLabels:
assignees:
- jkutner
- jromero
- samj1912
31 changes: 6 additions & 25 deletions merge-rfc.sh
Original file line number Diff line number Diff line change
Expand Up @@ -50,13 +50,6 @@ require_command() {

require_command git
require_command jq
require_command issues-generation

if [[ -z "${GITHUB_TOKEN:-}" ]]; then
require_command op
echo "> Pulling GitHub token from vault..."
GITHUB_TOKEN=$(op read op://Shared/7xorpxvz3je3vozqg3fy3wrcg4/credential --account buildpacks)
fi

####
# INPUTS / VALIDATION
Expand Down Expand Up @@ -107,25 +100,13 @@ fi
RFC_ID=$(generate_id)
echo "> Generated RFC number: ${RFC_ID}"

echo "> Creating issues for PR#${PR_NUMBER}"
export GITHUB_TOKEN

issues-generation create --pr "${OWNER}/${REPO}#${PR_NUMBER}" --bot $BOT_USERNAME --prepend "[RFC #${RFC_ID}] "
ISSUES_TO_LINK=$(issues-generation list --pr "${OWNER}/${REPO}#${PR_NUMBER}" --bot $BOT_USERNAME --json | jq -r '[.[] | select(.num) | .repo + "#" + (.num|tostring) ] | join(" ")')

for ISSUE in ${ISSUES_TO_LINK}; do
if [[ $ISSUES_TEXT == "N/A" ]]; then
ISSUES_TEXT=$(link_issue "$ISSUE")
else
ISSUES_TEXT+=", $(link_issue "$ISSUE")"
fi
done


if [[ $NO_ISSUES = false && $ISSUES_TEXT == "N/A" ]]; then
echo -e "ERROR! No issues were provided. Are you sure there are no issues that should be linked?"
echo -e "ERROR! Either -i or -n is required\n"
usage
echo "> Please create an issue by following the link below:"
echo "https://github.com/buildpacks/rfcs/issues/new?assignees=&labels=type%2Ftracking&projects=&template=tracking.md&title=%5BRFC+%23${RFC_ID}%5D+%3C+-+INSERT+RFC+TITLE%3E"
echo ""
read -p "Press Enter to continue" </dev/tty

read -p "> Please enter the issue link: " ISSUES_TEXT
fi

echo "> Pulling latest changes...."
Expand Down
2 changes: 1 addition & 1 deletion text/0041-api-version-compat.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ The spec will use future `0.x` API releases to include any desired changes with
This RFC does not make changes to the API compatibility rules post 1.0. 1.x APIs version are stil assumed to be purely additive.

## Lifecycle
The lifecycle will use the [lifecycle descriptor](https://github.com/buildpacks/rfcs/blob/pack-publish-buildpack/text/0011-lifecycle-descriptor.md)
The lifecycle will use the [lifecycle descriptor](https://github.com/buildpacks/rfcs/blob/main/text/0011-lifecycle-descriptor.md)
to indicate the implemented API versions as before. However, the compatibility assumptions will change.
It will be assumed that a lifecycle declaring support for the `0.x` version of the API, supports all 0.2-0.x API versions.

Expand Down
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.
20 changes: 10 additions & 10 deletions text/0128-multiarch-builders-and-package.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,9 +95,9 @@ arch = "arm64"
os = "windows"
arch = "amd64"

[[targets.distributions]]
[[targets.distros]]
name = "windows"
versions = ["10.0.20348.1970"]
version = "10.0.20348.1970"

# Stacks (deprecated) the buildpack will work with
[[stacks]]
Expand Down Expand Up @@ -286,9 +286,9 @@ variant = "<architecture variant>"
# optional
path = "<path to look for the binaries if the folder structure convention is not followed>"

[[targets.distributions]]
[[targets.distros]]
name = "<distribution ID>"
versions = ["<distribution version>"]
version = "<distribution version>"
```
- When `more than 1 target is defined`
- When `--publish` is specified
Expand Down Expand Up @@ -681,9 +681,9 @@ arch = "arm64"
os = "windows"
arch = "amd64"

[[targets.distributions]]
[[targets.distros]]
name = "windows"
versions = ["10.0.20348.1970"]
version = "10.0.20348.1970"

# Stacks (deprecated) the buildpack will work with
[[stacks]]
Expand Down Expand Up @@ -763,9 +763,9 @@ os = "<operating system>"
arch = "<system architecture>"
variant = "<architecture variant>"

[[targets.distributions]]
[[targets.distros]]
name = "<distribution ID>"
versions = ["<distribution version>"]
version = "<distribution version>"

[[dependencies]]
uri = "<A URL or path to an archive, a packaged buildpack (saved as a .cnb file), or a directory. If path is relative, it must be relative to the package.toml>"
Expand Down Expand Up @@ -843,9 +843,9 @@ image = "<build image reference>"
os = "<operating system>"
arch = "<system architecture>"
variant = "<architecture variant>"
[[targets.distributions]]
[[targets.distros]]
name = "<distribution ID>"
versions = ["<distribution version>"]
version = "<distribution version>"
```
- Add a new `--target` optional flag with format `[os][/arch][/variant]:[name@version]` to create a builder for a
particular target, this will help end-users to specify the platform for which they want to create single OCI artifact.
Expand Down
141 changes: 141 additions & 0 deletions text/0129-export-run-image-metadata.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
# Meta
[meta]: #meta
- Name: Export Run Image Metadata
- Start Date: 2024-04-11
- Author(s): joeybrown-sf
- Status: Approved <!-- Acceptable values: Draft, Approved, On Hold, Superseded -->
- RFC Pull Request: https://github.com/buildpacks/rfcs/pull/313
- CNB Pull Request: (leave blank)
- CNB Issue: https://github.com/buildpacks/lifecycle/issues/1372
- Supersedes: N/A

# Summary
[summary]: #summary

The `report.toml` file created by the lifecycle exporter and rebaser should include the following properties:
- `run-image.image`
- `run-image.mirrors`
- `run-image.reference`
- `run-image.top-layer`

These values are not necessarily known prior to export or rebase they can be critical to a platform rebase process.

# Motivation
[motivation]: #motivation

Platform operators may need a comprehensive understanding of images on their platform in order to make decisions about rebase and image publishing. Run image metadata is likely part of this comprehensive understanding for rebase. It is likely that this data may only be known after an image is created or rebased, and today it is only accessible via reading the image. Therefore, in order to access this metadata, platform operators must query the image.

Querying the docker daemon or querying an image registry is suboptimal and we should make this data more accessible. It is suboptimal because it requires the platform to run an additional service to query the data it just published. If we make this data more accessible, we could potentially reduce image queries (registry calls) calls by a significant factor.

Putting this data into `report.toml` is advantageous over other methods, especially when considering the kubernetes `terminationMessagePath` message [pattern](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#pod-v1-core). In this pattern, the content of `report.toml` can be used as a container's termination message, making this data easily accessible after an image is exported or rebased within a kubernetes container.

# What it is
[what-it-is]: #what-it-is

These values will be included when the lifecycle exporter/creator/rebaser binary writes `report.toml`.

Here are two examples of `report.toml` content. (Other values are omitted for readability.)

#### Image published to a registry:
```
[image]
tags = ...
digest = ...
image-id = ...
manifest-size = ...
run-image.image = "run/name:foo"
run-image.reference = "index.docker.io/run/name@sha256:94f85561b0976bf1e2bef6b14de92299ebcd4c8148802cf9b217654651e4f416"
run-image.top-layer = "sha256:83ad2f0b091621ce19357e19d853c8be1b8f4d60d99c281fc2db75e0f56df42a"
run-image.mirrors = ["<mirror1>", "<mirror2>"]
```

#### Image exported to the docker daemon:
```
[image]
tags = ...
digest = ...
image-id = ...
manifest-size = ...
run-image.image = "run/name:foo"
run-image.reference = "5b90f9c0e189"
run-image.top-layer = "sha256:83ad2f0b091621ce19357e19d853c8be1b8f4d60d99c281fc2db75e0f56df42a"
run-image.mirrors = ["<mirror1>", "<mirror2>"]
```

# How it Works
[how-it-works]: #how-it-works

This metadata is readily available when `report.toml` is created, so it will be straight-forward to extend `report.toml`.

# Migration
[migration]: #migration

N/A

This is an additive change to a metadata file and will be backwards compatible.

# Drawbacks
[drawbacks]: #drawbacks

This metadata is written to the [`lifecycle.metadata` label](https://github.com/buildpacks/spec/blob/main/platform.md#iobuildpackslifecyclemetadata-json) and it can be accessed by querying a docker daemon or registry. So we will be writing this data to two outputs.

# Alternatives
[alternatives]: #alternatives

1. Do nothing and continue to require platforms to retrieve this information via alternative means--either querying the docker daemon or registry.
- Rebase process may remain suboptimal for some platform providers.

2. Write all the metadata labels to `report.toml`.
- This could break platform operators that are using the `terminationMessagePath` [pattern](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#pod-v1-core). Because some of the metadata includes unbounded arrays, we could explode this report beyond the max size of 4096 bytes.

3. Write another file that contains this metadata (and potentially more metadata).
- If we consider this approach and take it to the logical conclusion, we should consider writing a sparse image as output. A sparse image would contain all the metadata available, and it would be in a well-known format that other image tools like `crane`, `skopeo`, or `pack` can read.
- Writing to another file is not as simple as writing to `report.toml`.
- It increases the complexity of lifecycle exporter & rebaser.
- Writing to another file would not give platform operators the advantage of the `terminationMessagePath` [pattern](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#pod-v1-core), because they are likely already reading `report.toml`.

# Prior Art
[prior-art]: #prior-art

These values are written to image labels. And they are among values that `pack inspect` returns.

`report.toml` was introduced in [RFC 0040](/text/0040-export-report.md). That RFC includes some context for why `report.toml` exists.

# Unresolved Questions
[unresolved-questions]: #unresolved-questions

N/A

# Spec. Changes
[spec-changes]: #spec-changes

The following would be appended to the [`report.toml` spec](https://github.com/buildpacks/spec/blob/main/platform.md#reporttoml-toml) (this section would be materially identical to the [`lifecycle.metadata` label](https://github.com/buildpacks/spec/blob/main/platform.md#iobuildpackslifecyclemetadata-json)):

> runImage.topLayer MUST contain the uncompressed digest of the top layer of the run-image.
>
> runImage.reference MUST uniquely identify the run image. It MAY contain one of the following
> - An image ID (the digest of the uncompressed config blob)
> - A digest reference to a manifest stored in an OCI registry
>
> runImage.image and runImage.mirrors MUST be resolved from run.toml from the given <run-image>
# History
[history]: #history

<!--
## Amended
### Meta
[meta-1]: #meta-1
- Name: (fill in the amendment name: Variable Rename)
- Start Date: (fill in today's date: YYYY-MM-DD)
- Author(s): (Github usernames)
- Amendment Pull Request: (leave blank)
### Summary
A brief description of the changes.
### Motivation
Why was this amendment necessary?
--->
Loading

0 comments on commit 08622ca

Please sign in to comment.