# ...
- name: example.v3.0.0
skips: ["example.v2.0.0"]
- name: example.v2.0.0
skipRange: >=1.0.0 <2.0.0
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 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.
Currently, Operator Lifecycle Manager (OLM) v1 cannot authenticate private registries, such as the Red Hat-provided Operator catalogs. This is a known issue. As a result, the OLM v1 procedures that rely on having the Red Hat Operators catalog installed do not work. (OCPBUGS-36364) |
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.
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.
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.
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.
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:
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.
Wildcard comparison | Matching string |
---|---|
|
|
|
|
|
|
|
|
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.
Patch release comparison | Matching string |
---|---|
|
|
|
|
|
|
|
|
|
|
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.
Major release comparison | Matching string |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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.
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.
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.
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:
$ oc apply -f <extension_name>.yaml
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. |
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.
Edit the custom resource (CR) of your Operator or extension as shown in the following example:
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 . |
Apply the changes to your Operator or extensions CR by running the following command:
$ oc apply -f <extension_name>.yaml