📖 [Docs] Add support for skip ranges and replacements #1215
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,33 +1,58 @@ | ||
| # Upgrade support | ||
|
|
||
| This document explains how OLM v1 handles upgrades. | ||
|
|
||
| OLM v1 introduces a simplified UX for package authors and package admins to implicitly define upgrade edges via [Semantic Versioning](https://semver.org/). | ||
|
|
||
| It also introduces an API to enable independently verified upgrades and downgrades. | ||
|
|
||
| ## Upgrade constraint semantics | ||
|
|
||
| When determining upgrade edges, also known as upgrade paths or upgrade constraints, for an installed cluster extension, Operator Lifecycle Manager (OLM) v1 supports [legacy OLM semantics](https://olm.operatorframework.io/docs/concepts/olm-architecture/operator-catalog/creating-an-update-graph/) by default. This support follows the behavior from legacy OLM, including `replaces`, `skips`, and `skipRange` directives, with a few noted differences. | ||
|
|
||
| By supporting legacy OLM semantics, OLM v1 now honors the upgrade graph from catalogs accurately. | ||
|
|
||
| * If there are multiple possible successors, OLM v1 behavior differs in the following ways: | ||
| * In legacy OLM, the successor closest to the channel head is chosen. | ||
| * In OLM v1, the successor with the highest semantic version (semver) is chosen. | ||
| * Consider the following set of file-based catalog (FBC) channel entries: | ||
|
|
||
| ```yaml | ||
| # ... | ||
| - name: example.v3.0.0 | ||
| skips: ["example.v2.0.0"] | ||
| - name: example.v2.0.0 | ||
| skipRange: >=1.0.0 <2.0.0 | ||
| ``` | ||
| If `1.0.0` is installed, OLM v1 behavior differs in the following ways: | ||
|
|
||
| * Legacy OLM does not detect an upgrade edge to `v2.0.0` because `v2.0.0` is skipped and not on the `replaces` chain. | ||
| * OLM v1 detects the upgrade edge because OLM v1 does not have a concept of a `replaces` chain. OLM v1 finds all entries that have a `replace`, `skip`, or `skipRange` value that covers the currently installed version. | ||
|
|
||
| You can change the default behavior of the upgrade constraints by setting the `upgradeConstraintPolicy` parameter in your cluster extension's custom resource (CR). | ||
|
|
||
| ``` yaml hl_lines="10" | ||
| apiVersion: olm.operatorframework.io/v1alpha1 | ||
| kind: ClusterExtension | ||
| metadata: | ||
| name: <extension_name> | ||
| spec: | ||
| installNamespace: <namespace> | ||
| packageName: <package_name> | ||
| serviceAccount: | ||
| name: <service_account> | ||
| upgradeConstraintPolicy: Ignore | ||
| version: "<version_or_version_range>" | ||
| ``` | ||
|
|
||
| where setting the `upgradeConstraintPolicy` to: | ||
|
|
||
| `Ignore` | ||
| : Does not limit the next version to the set of successors, and instead allows for any downgrade, sidegrade, or upgrade. | ||
|
|
||
| `Enforce` | ||
|
Comment on lines
+51
to
+54
Contributor
Author
There was a problem hiding this comment. @joelanford Do you want to change to the new value now? Or should we to update #1151 with a comment or a docs issue?
Member
There was a problem hiding this comment. Use what you have, which is what is on |
||
| : Only allows the next version to come from the successors list. This is the default value. If the `upgradeConstraintPolicy` parameter is not defined in an extension's CR, then the policy is set to `Enforce` by default. | ||
|
|
||
| ## Upgrades | ||
|
|
||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Non-blocking (I think we'll need to sweep the entire repo once all the API changes are finished): All these fields are getting moved around:
mainright now, there are other open PRs that will invalidate it (e.g. ✨ logically group fields in the spec #1200)Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
With Material MK Docs, we can actually embed YAML files into a markdown file.
Maybe we can create an issue right before or after 1.0.0 GA to switch our inline examples to embedded YAML files? That way we can update our examples all in one go.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It looks like #1200 has the relevant doc changes already queued up.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
#1200 merged, which makes this section incorrect if it merges. I'm happy to merge this and fix in a follow up (hence my approval on the PR), but I'll defer to you if you want to go ahead and fix now.