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

📖 Draft documentation for initial upgrade support #559

Merged
merged 1 commit into from
Dec 4, 2023
Merged

📖 Draft documentation for initial upgrade support #559

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
66 changes: 66 additions & 0 deletions docs/drafts/upgrade-support.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# Upgrade support

This document explains how OLM 1.0 handles upgrades.

OLM 1.0 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

As of Operator Controller release 0.8.0, OLM 1.0 supports the following upgrade constraint semantics:

* [Semantic Versioning](https://semver.org/) (Semver)
* The `replaces` directive from the [legacy OLM 0 semantics](https://olm.operatorframework.io/docs/concepts/olm-architecture/operator-catalog/creating-an-update-graph/#methods-for-specifying-updates)

The Kubernetes manifests in this repo enable Semver support by default. Cluster admins can control which semantics to use by passing one of the following arguments to the `manager` binary:
Copy link
Contributor

@michaelryanpeter michaelryanpeter Dec 1, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

This might be out of scope for this issue, but it might be worth explaining in a follow up issue why a cluster admin would want to deviate from the upgrade constraint semantics specified by the package author.

Copy link
Member Author

Choose a reason for hiding this comment

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

I added the following:

We plan to remove the ForceSemverUpgradeConstraints feature gate and enable package authors to specify which upgrade constraint semantics they wish to use on the catalog level.

* `--feature-gates=ForceSemverUpgradeConstraints=true` - enable Semver
* `--feature-gates=ForceSemverUpgradeConstraints=false` - disable Semver, use legacy semantics

For example, to enable Semver update the `controller-manager` Deployment manifest to include the following argument:

```yaml
- command:
- /manager
args:
- --feature-gates=ForceSemverUpgradeConstraints=true
image: controller:latest
```

In a future release, it is planned to remove the `ForceSemverUpgradeConstraints` feature gate and allow package authors to specify upgrade constraint semantics at the catalog level.

## Upgrades

OLM supports Semver to provide a simplified way for package authors to define compatible upgrades. According to the Semver standard, releases within a major version (e.g. `>=1.0.0 <2.0.0`) must be compatible. As a result, package authors can publish a new package version following the Semver specification, and OLM assumes compatibility. Package authors do not have to explicitly define upgrade edges in the catalog.
Copy link
Contributor

@tmshort tmshort Dec 4, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

Nit: There are various levels of Semver compatibility, as specified by all three component versions. There's no mention of patch compatibility here. But, we don't want to get ourselves too deep in the weeds with explanations here, as we reference Semver above.

Copy link
Member Author

Choose a reason for hiding this comment

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

@tmshort Here we say that anything witing the major version is expected to be compatible. E.g. 1.0.3 is compatible with 1.3.0. So pacakge authors can release accordingly. I think it is not necessary to go into the details of semver spec itself here (e.g. patch versions are for bug fixes, minor versions are fore backward compatible features).

But I'm happy to add more info if you think we should stress some specific aspect of semver here. Let me know.


**Note:** Currently, OLM 1.0 does not support automatic upgrades to the next major version. You must manually verify and perform major version upgrades. For more information about major version upgrades, see [Manually verified upgrades and downgrades](#manually-verified-upgrades-and-downgrades).
Copy link
Contributor

Choose a reason for hiding this comment

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

Nit: Not sure if we've landed on a standard or anything like that for how we want to do notes, warnings, etc. in our docs but I find that combining the quote (>) markdown syntax with the bolded "Note", "Warning", etc. is more eye catching than only the bolded text and helps with readability (at least for me).

Not sure how the docs site we use renders them, but in GitHub's markdown you can even do:

Note

Something of great importance

Warning

Something of even greater importance

How ^ is done:

>[!NOTE]
>Something of great importance

>[!WARNING]
>Something of _even greater_ importance

Examples

With Quote/Note syntax

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Note

Something worthy of catching my eye due to it's importance

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

With Bolded Text

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Note: Something worthy of catching my eye due to it's importance

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Copy link
Member Author

Choose a reason for hiding this comment

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

Nice one! I'll submit a follow up PR to use this markdown. Thanks for the suggestion.

Copy link
Member Author

Choose a reason for hiding this comment

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

PR: #562


### Upgrades within the major version zero

According to the Semver specification, a major version zero release is for initial development. It is assumed that breaking changes might be introduced at any time. As a result, the following special conditions apply to upgrades within a major version zero release:

* You cannot automatically upgrade from one patch version to another when both major and minor versions are `0`. For example, automatic upgrades within the following version range are not allowed: `>= 0.0.1 <0.1.0`.
* You cannot automatically upgrade from one minor version to another minor version within the major version zero. For example, no upgrades from `0.1.0` to `0.2.0`. However, you can upgrade from patch versions. For example, upgrades are possible in ranges `>= 0.1.0 <0.2.0`, `>= 0.2.0 <0.3.0`, `>= 0.3.0 <0.4.0`, and so on.

You must verify and perform upgrades manually in cases where automatic upgrades are blocked.

## Manually verified upgrades and downgrades

**Warning:** If you want to force an upgrade manually, you must thoroughly verify the outcome before applying any changes to production workloads. Failure to test and verify the upgrade might lead to catastrophic consequences such as data loss.

As a package admin, if you must upgrade or downgrade to version that might be incompatible with the currently installed version, you can set the `.spec.upgradeConstraintPolicy` field to `Ignore` on the relevant `Operator` resource.

If you set the field to `Ignore`, no upgrade constraints are set on the package. As a result, you can change the version to any version available in the catalogs for a given package.
m1kola marked this conversation as resolved.
Show resolved Hide resolved

Example `Operator` with `.spec.upgradeConstraintPolicy` field set to `Ignore`:

```yaml
apiVersion: operators.operatorframework.io/v1alpha1
kind: Operator
metadata:
name: operator-sample
spec:
packageName: argocd-operator
version: 0.6.0
upgradeConstraintPolicy: Ignore
```