Skip to content

OTA-949: README: Define a 1.2.0 filesystem schema for release signatures #3509

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
openshift-merge-robot merged 2 commits into from
Apr 19, 2023
Merged

OTA-949: README: Define a 1.2.0 filesystem schema for release signatures #3509

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9366385
README: Explicit versions for each directory/file/property
wking Apr 19, 2023
9e9e97c
README: Define a 1.2.0 filesystem schema for release signatures
wking Apr 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 22 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ And 4.2.14+amd64 would only apply to the amd64 release image.

### Add Releases To Channels

Edit the appropriate file in `channels/`.
Edit the appropriate file in `channels/` (1.0.0).
For example, to add a release to candidate-4.2 you would edit [`channels/candidate-4.2.yaml`](channels/candidate-4.2.yaml).

The file contains a list of versions.
Expand All @@ -47,7 +47,7 @@ Some time after landing in `fast-4.2`, it will appear in `stable-4.2`.
_Note:_ Once we have phased release rollouts, we will drop the fast/stable distinction from this repository and promote to a unified fast/stable channel with a start time and rollout duration.
Until then, we are using fast channels to feed stable channels with a delay, just like candidate channels feed fast channels.

In this repository, the intended promotion flow is reflected by a `feeder` property in the channel declaration.
In this repository, the intended promotion flow is reflected by a `feeder` property in the channel declaration, since version 1.0.0.
For example, for [`channels/fast-4.2.yaml`](channels/fast-4.2.yaml):

```yaml
Expand All @@ -58,8 +58,8 @@ feeder:
```

which declares the intention that nodes and edges will be considered for promotion from `candidate-4.2` into `fast-4.2` after the errata becomes public.
The optional `errata` property only accepts one value, `public`, and marks a public errata as sufficient, but not necessary, for promoting a feeder node.
The `filter` value excludes `4.2.0-rc.5` and other releases, while allowing for `4.2.0-0.hotfix-2020-09-19-234758` and `4.2.10-s390x` and `4.2.14+amd64`.
The optional `errata` property (1.0.0) only accepts one value, `public`, and marks a public errata as sufficient, but not necessary, for promoting a feeder node.
The `filter` value (1.0.0) excludes `4.2.0-rc.5` and other releases, while allowing for `4.2.0-0.hotfix-2020-09-19-234758` and `4.2.10-s390x` and `4.2.14+amd64`.

Another example is [`channels/stable-4.2.yaml`](channels/stable-4.2.yaml):

Expand All @@ -70,7 +70,7 @@ feeder:
```

which declares the intention that nodes and edges will be considered for promotion from `fast-4.2` into `stable-4.2` after a delay of 48 hours.
The `delay` value is an [ISO 8601][rfc-3339-p13] [duration][iso-8601-durations], and spending sufficient time in the feeder channel is sufficient, but not necessary, for promoting the feeder node.
The `delay` value (1.0.0) is an [ISO 8601][rfc-3339-p13] [duration][iso-8601-durations], and spending sufficient time in the feeder channel is sufficient, but not necessary, for promoting the feeder node.

If both `errata` and `delay` are set, the feeder nodes will be promoted when `delay` has elapsed or the release errata becomes public, whichever comes first.

Expand All @@ -84,7 +84,7 @@ $ hack/stabilization-change.py

Removing a node from a channel can strand existing clusters with a `VersionNotFound` error.
To avoid that, unstable nodes are left in their existing channels, but should not be promoted to additional channels.
This is reflected through entries in the optional `tombstones` property.
This is reflected through entries in the optional `tombstones` property, since version 1.0.0.
For example, [`channels/candidate-4.2.yaml`](channels/candidate-4.2.yaml) has:

```yaml
Expand All @@ -97,19 +97,19 @@ declaring that, while 4.1.18 and 4.1.20 are in `candidate-4.2`, they should not

### Block Edges

Create/edit an appropriate file in `blocked_edges/`.
Create/edit an appropriate file in `blocked_edges/`, since version 1.0.0.

* `to` (required, [string][json-string]) is the release which has the existing incoming edges.
* `from` (required, [string][json-string]) is a regex for the previous release versions.
* `to` (1.0.0, required, [string][json-string]) is the release which has the existing incoming edges.
* `from` (1.0.0, required, [string][json-string]) is a regex for the previous release versions.
If you want to require `from` to match the full version string (and not just a substring), you must include explicit `^` and `$` anchors.
Release version strings will receive [the architecture-suffix](#release-names) before being compared to this regular expression.
* `url` (optional, [string][json-string]), with a URI documenting the blocking reason.
* `url` (1.1.0, optional, [string][json-string]), with a URI documenting the blocking reason.
For example, this could link to a bug's impact statement or knowledge-base article.
* `name` (optional, [string][json-string]), with a CamelCase reason suitable for [a `ClusterOperatorStatusCondition` `reason` property][api-reason].
* `fixedIn` (optional, [string][json-string]), with the update-target release where the exposure was fixed, either directly, or because that target is newer than the 4.(y-1).z release where the exposure was fixed.
* `name` (1.1.0, optional, [string][json-string]), with a CamelCase reason suitable for [a `ClusterOperatorStatusCondition` `reason` property][api-reason].
* `fixedIn` (1.1.0, optional, [string][json-string]), with the update-target release where the exposure was fixed, either directly, or because that target is newer than the 4.(y-1).z release where the exposure was fixed.
This feeds risk-extension guards that require either a `fixedIn` declaration or an extension of unfixed risks to later releases to avoid shipping a release that is still exposed to a risk without declaring that risk.
* `message` (optional, [string][json-string]), with a human-oriented message describing the blocking reason, suitable for [a `ClusterOperatorStatusCondition` `message` property][api-message].
* `matchingRules` (optional, [array][json-array]), defining conditions for deciding which clusters have the update recommended and which do not.
* `message` (1.1.0, optional, [string][json-string]), with a human-oriented message describing the blocking reason, suitable for [a `ClusterOperatorStatusCondition` `message` property][api-message].
* `matchingRules` (1.1.0, optional, [array][json-array]), defining conditions for deciding which clusters have the update recommended and which do not.
The array is ordered by decreasing precedence.
Consumers should walk the array in order.
For a given entry, if a condition type is unrecognized, or fails to evaluate, consumers should proceed to the next entry.
Expand Down Expand Up @@ -138,6 +138,14 @@ from: ^4\.1\.(18|20)[+].*$

The `[+].*` portion absorbs [the architecture-suffix](#release-names) from the release name that consumers will use for comparisons.

### Signatures

Add release signatures under `signatures/{algorithm}/{digest}/signature-{number}` (1.2.0).
For example, the [`amd64` 4.12.0 is `sha256:4c5a7e26d707780be6466ddc9591865beb2e3baa5556432d23e8d57966a2dd18`][4.12.0-release] ([errata][4.12.0-errata]), and would have [signatures][4.12.0-signature] stored in `signatures/sha256/4c5a7e26d707780be6466ddc9591865beb2e3baa5556432d23e8d57966a2dd18/signature-1` (optionally with additional signatures as `signature-2`, etc.

[4.12.0-errata]: https://access.redhat.com/errata/RHSA-2022:7399
[4.12.0-release]: https://mirror.openshift.com/pub/openshift-v4/amd64/clients/ocp/4.12.0/release.txt
[4.12.0-signature]: https://mirror.openshift.com/pub/openshift-v4/signatures/openshift/release/sha256%3D4c5a7e26d707780be6466ddc9591865beb2e3baa5556432d23e8d57966a2dd18/signature-1
[api-message]: https://github.com/openshift/api/blob/67c28690af52a69e0b8fa565916fe1b9b7f52f10/config/v1/types_cluster_operator.go#L135-L139
[api-reason]: https://github.com/openshift/api/blob/67c28690af52a69e0b8fa565916fe1b9b7f52f10/config/v1/types_cluster_operator.go#L131-L133
[channel-semantics]: https://docs.openshift.com/container-platform/4.3/updating/updating-cluster-between-minor.html#understanding-upgrade-channels_updating-cluster-between-minor
Expand Down