1. Documentation
×

Upgrade edges

When determining upgrade edges, also known as upgrade paths or upgrade constraints, for an installed cluster extension, Operator Lifecycle Manager (OLM) v1 supports existing OLM semantics starting in OKD 4.16. This support follows the behavior from existing OLM, including replaces, skips, and skipRange directives, with a few noted differences.

By supporting existing OLM semantics, OLM v1 now honors the upgrade graph from catalogs accurately.

Differences from original existing OLM implementation

  • If there are multiple possible successors, OLM v1 behavior differs in the following ways:

    • In existing 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:

    • Existing 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

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>
  serviceAccount:
    name: <service_account>
  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>
  serviceAccount:
    name: <service_account>
  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>
  serviceAccount:
    name: <service_account>
  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.

  • You have created a service account and assigned enough role-based access controls (RBAC) to install, update, and manage the extension you want to install. For more information, see Creating a service account.

Procedure

  1. 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>
  serviceAccount:
    name: <service_account>
  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.

  2. Apply the changes to your Operator or extensions CR by running the following command:

    $ oc apply -f <extension_name>.yaml
Additional resources