Skip to content
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

Jump to bottom

channeltypepreference attribute for semver template; providing hyperlinks to example sections #296

Merged
merged 3 commits into from
May 24, 2023
Merged

channeltypepreference attribute for semver template; providing hyperlinks to example sections #296

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b5d4f42
channeltypepreference attribute for semver template; providing hyperl…
grokspawn May 17, 2023
85f55c9
implementation review comments
grokspawn May 17, 2023
7212c8a
doc review comments
grokspawn May 17, 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
57 changes: 56 additions & 1 deletion content/en/docs/Reference/catalog-templates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -254,6 +254,9 @@ The `olm.semver` [cue](https://cuelang.org/docs/references/spec/) schema is:
// optional flag to control generating major-version channels, defaults to _false_ if unspecified
GenerateMajorChannels?: bool

// optional preference for major- or minor-version channels, when both are generated and identical in stability and version
DefaultChannelTypePreference?: string
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a requirement that this is within a specific set of values or can this be any string value?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We enforce it in the code to either 'minor' or 'major': https://github.com/operator-framework/operator-registry/blob/master/alpha/template/semver/semver.go#LL95-L112


// optional candidate channel
Candidate?: {
Bundles: [...#ImageEntry]
Expand Down Expand Up @@ -291,7 +294,7 @@ opm alpha render-template semver [flags] <filename>

`--skip-tls-verify` and `--use-http` are mutually exclusive flags.

### Example
### Examples

With the following (hypothetical) example we define a mock bundle which has 11 versions, represented across each of the channel types:

Expand Down Expand Up @@ -326,6 +329,8 @@ Stable:

In this example, `Candidate` has the entire version range of bundles, `Fast` has a mix of older and more-recent versions, and `Stable` channel only has a single published entry.

#### Generating major-version channels

If we set the template attributes

```yaml
Expand Down Expand Up @@ -402,6 +407,8 @@ schema: olm.channel
We generated a channel for each template channel entity corresponding to each of the 0.\#.\#, 1.\#.\# major version ranges with skips to the head of the highest semver in a channel. We also generated a replaces edge to traverse across minor version transitions within each major channel. Finally, we generated an `olm.package` object, setting as default the most-stable channel head we created. This process will prefer `Stable` channel over `Fast`, over `Candidate` and then a higher bundle version over a lower version.
(Please note that the naming of the generated channels indicates the digits of significance for that channel. For example, `fast-v1` is a decomposed channel of the `fast` type which contains only major versions of contributing bundles matching `v1`.)

#### Generating minor-version channels

For contrast, if we set the template attributes

```yaml
Expand Down Expand Up @@ -504,6 +511,54 @@ schema: olm.channel

Here, a channel is generated for each template channel which differs by minor version, and each channel has a `replaces` edge from the predecessor channel to the next-lesser minor bundle version. Please note that at no time do we transgress across major-version boundaries with the channels, to be consistent with [the semver convention](https://semver.org/) for major versions, where the purpose is to make incompatible API changes.

#### Generating both channel types, and disambiguating default channel selection

In the case that we generate both major-version and minor-version channels:

```yaml
GenerateMinorChannels: true
GenerateMajorChannels: true
```

we can easily end up in a situation where our results yield indifferentiable results, for e.g.:

```yaml
---
entries:
- name: testoperator.v1.0.1
name: stable-v1
package: testoperator
schema: olm.channel
---
entries:
- name: testoperator.v1.0.1
name: stable-v1.0
package: testoperator
schema: olm.channel
```

In this situation, both channels have matching channel archetypes and the channel heads have the same versions. The `DefaultChannelTypePreference` attribute allows us to deterministically select a single channel in this case. This attribute defaults to prefer minor-version channels (`DefaultChannelTypePreference: minor`), but can be overridden in the schema if the author wishes to prefer major-version channels instead (`DefaultChannelTypePreference: major`).

With `DefaultChannelTypePreference` set to `major`, our most-stable channels and package output would look like
```yaml
---
defaultChannel: stable-v1
name: testoperator
schema: olm.package
---
entries:
- name: testoperator.v1.0.1
name: stable-v1
package: testoperator
schema: olm.channel
---
entries:
- name: testoperator.v1.0.1
name: stable-v1.0
package: testoperator
schema: olm.channel
```

## Composite Template
A `composite template` can help an operator author manage FBC contributions to multiple catalogs. The template functionality is composed of schemas which represent the author's role and the catalog maintainer's role, and rendering the template performs an explicit negotiation between them.

Expand Down