Upgrade edges - Cluster extensions | Extensions (OLM v1)

Support for version ranges
Version comparison strings
Example custom resources (CRs) that specify a target version
Forcing an update or rollback

Operator Lifecycle Manager (OLM) v1 is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

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 starting in OKD 4.16. 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.

Differences from original legacy OLM implementation

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:
```
# ...
- 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 will not detect an upgrade edge to v2.0.0 because v2.0.0 is skipped and not on the replaces chain.
- OLM v1 will detect 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.

Additional resources

Legacy OLM upgrade semantics

Support for version ranges

In Operator Lifecycle Manager (OLM) v1, you can specify a version range by using a comparison string in an Operator or extension’s custom resource (CR). If you specify a version range in the CR, OLM v1 installs or updates to the latest version of the Operator that can be resolved within the version range.

Resolved version workflow

The resolved version is the latest version of the Operator that satisfies the constraints of the Operator and the environment.
An Operator update within the specified range is automatically installed if it is resolved successfully.
An update is not installed if it is outside of the specified range or if it cannot be resolved successfully.

Version comparison strings

You can define a version range by adding a comparison string to the spec.version field in an Operator or extension’s custom resource (CR). A comparison string is a list of space- or comma-separated values and one or more comparison operators enclosed in double quotation marks ("). You can add another comparison string by including an OR, or double vertical bar (||), comparison operator between the strings.

Table 1. Basic comparisons
Comparison operator	Definition
`=`	Equal to
`!=`	Not equal to
`>`	Greater than
`<`	Less than
`>=`	Greater than or equal to
`<=`	Less than or equal to

You can specify a version range in an Operator or extension’s CR by using a range comparison similar to the following example:

Example version range comparison

apiVersion: olm.operatorframework.io/v1alpha1
kind: ClusterExtension
metadata:
  name: pipelines-operator
spec:
  packageName: openshift-pipelines-operator-rh
  installNamespace: <namespace_name>
  version: ">=1.11, <1.13"

You can use wildcard characters in all types of comparison strings. OLM v1 accepts x, X, and asterisks (*) as wildcard characters. When you use a wildcard character with the equal sign (=) comparison operator, you define a comparison at the patch or minor version level.

Table 2. Example wildcard characters in comparison strings
Wildcard comparison	Matching string
`1.11.x`	`>=1.11.0, <1.12.0`
`>=1.12.X`	`>=1.12.0`
`<=2.x`	`<3`
`*`	`>=0.0.0`

You can make patch release comparisons by using the tilde (~) comparison operator. Patch release comparisons specify a minor version up to the next major version.

Table 3. Example patch release comparisons
Patch release comparison	Matching string
`~1.11.0`	`>=1.11.0, <1.12.0`
`~1`	`>=1, <2`
`~1.12`	`>=1.12, <1.13`
`~1.12.x`	`>=1.12.0, <1.13.0`
`~1.x`	`>=1, <2`

You can use the caret (^) comparison operator to make a comparison for a major release. If you make a major release comparison before the first stable release is published, the minor versions define the API’s level of stability. In the semantic versioning (semver) specification, the first stable release is published as the 1.0.0 version.

Table 4. Example major release comparisons
Major release comparison	Matching string
`^0`	`>=0.0.0, <1.0.0`
`^0.0`	`>=0.0.0, <0.1.0`
`^0.0.3`	`>=0.0.3, <0.0.4`
`^0.2`	`>=0.2.0, <0.3.0`
`^0.2.3`	`>=0.2.3, <0.3.0`
`^1.2.x`	`>= 1.2.0, < 2.0.0`
`^1.2.3`	`>= 1.2.3, < 2.0.0`
`^2.x`	`>= 2.0.0, < 3`
`^2.3`	`>= 2.3, < 3`

Example custom resources (CRs) that specify a target version

In Operator Lifecycle Manager (OLM) v1, cluster administrators can declaratively set the target version of an Operator or extension in the custom resource (CR).

You can define a target version by specifying any of the following fields:

Channel
Version number
Version range

If you specify a channel in the CR, OLM v1 installs the latest version of the Operator or extension that can be resolved within the specified channel. When updates are published to the specified channel, OLM v1 automatically updates to the latest release that can be resolved from the channel.

Example CR with a specified channel

apiVersion: olm.operatorframework.io/v1alpha1
kind: ClusterExtension
metadata:
  name: pipelines-operator
spec:
  packageName: openshift-pipelines-operator-rh
  installNamespace: <namespace_name>
  channel: latest (1)

1	Installs the latest release that can be resolved from the specified channel. Updates to the channel are automatically installed.

If you specify the Operator or extension’s target version in the CR, OLM v1 installs the specified version. When the target version is specified in the CR, OLM v1 does not change the target version when updates are published to the catalog.

If you want to update the version of the Operator that is installed on the cluster, you must manually edit the Operator’s CR. Specifying an Operator’s target version pins the Operator’s version to the specified release.

Example CR with the target version specified

apiVersion: olm.operatorframework.io/v1alpha1
kind: ClusterExtension
metadata:
  name: pipelines-operator
spec:
  packageName: openshift-pipelines-operator-rh
  installNamespace: <namespace_name>
  version: "1.11.1" (1)

1	Specifies the target version. If you want to update the version of the Operator or extension that is installed, you must manually update this field the CR to the desired target version.

If you want to define a range of acceptable versions for an Operator or extension, you can specify a version range by using a comparison string. When you specify a version range, OLM v1 installs the latest version of an Operator or extension that can be resolved by the Operator Controller.

Example CR with a version range specified

apiVersion: olm.operatorframework.io/v1alpha1
kind: ClusterExtension
metadata:
  name: pipelines-operator
spec:
  packageName: openshift-pipelines-operator-rh
  installNamespace: <namespace_name>
  version: ">1.11.1" (1)

1	Specifies that the desired version range is greater than version `1.11.1`. For more information, see "Support for version ranges".

After you create or update a CR, apply the configuration file by running the following command:

Command syntax

$ oc apply -f <extension_name>.yaml

Forcing an update or rollback

OLM v1 does not support automatic updates to the next major version or rollbacks to an earlier version. If you want to perform a major version update or rollback, you must verify and force the update manually.

You must verify the consequences of forcing a manual update or rollback. Failure to verify a forced update or rollback might have catastrophic consequences such as data loss.

Prerequisites

You have a catalog installed.
You have an Operator or extension installed.

Procedure

Edit the custom resource (CR) of your Operator or extension as shown in the following example:

Example CR

apiVersion: olm.operatorframework.io/v1alpha1
kind: Operator
metadata:
  name: <operator_name> (1)
spec:
  packageName: <package_name> (2)
  installNamespace: <namespace_name>
  version: <version> (3)
  upgradeConstraintPolicy: Ignore (4)

1	Specifies the name of the Operator or extension, such as `pipelines-operator`
2	Specifies the package name, such as `openshift-pipelines-operator-rh`.
3	Specifies the blocked update or rollback version.
4	Optional: Specifies the upgrade constraint policy. To force an update or rollback, set the field to `Ignore`. If unspecified, the default setting is `Enforce`.

Apply the changes to your Operator or extensions CR by running the following command:
```
$ oc apply -f <extension_name>.yaml
```

Additional resources

Support for version ranges