diff --git a/README.md b/README.md index 9c88c986c..2ae84d1fd 100644 --- a/README.md +++ b/README.md @@ -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. @@ -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 @@ -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): @@ -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. @@ -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 @@ -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. @@ -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