OSDOCS#8861: Semver support and updating Operators

SME feedback

Author: michaelryanpeter

modules/olmv1-about-target-versions.adoc

@@ -3,106 +3,70 @@
 // * operators/olm_v1/olmv1-installing-an-operator-from-a-catalog.adoc
 // * operators/olm_v1/arch/olmv1-operator-controller.adoc
 
-:_mod-docs-content-type: CONCEPT
+:_mod-docs-content-type: REFERENCE
 
-[id="olmv1-about-operator-updates_{context}"]
-= About target versions in {olmv1}
+[id="olmv1-about-target-versions_{context}"]
+= Example custom resources (CRs) that specify a target version
 
-In {olmv1-first}, cluster administrators set the target version of an Operator declaratively in the Operator's custom resource (CR).
+In {olmv1-first}, cluster administrators can declaratively set the target version of an Operator or extension in the custom resource (CR).
 
-If you specify a channel in the Operator's CR, {olmv1} installs the latest release from the specified channel. When updates are published to the specified channel, {olmv1} automatically updates to the latest release from the channel.
+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, {olmv1} 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, {olmv1} automatically updates to the latest release that can be resolved from the channel.
 
 .Example CR with a specified channel
 [source,yaml]
 ----
 apiVersion: operators.operatorframework.io/v1alpha1
 kind: Operator
 metadata:
-  name: quay-example
+  name: pipelines-operator
 spec:
-  packageName: quay-operator
-  channel: stable-3.8 <1>
+  packageName: openshift-pipelines-operator-rh
+  channel: latest <1>
 ----
-<1> Installs the latest release published to the specified channel. Updates to the channel are automatically installed.
+<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's target version in the CR, {olmv1} installs the specified version. When the target version is specified in the Operator's CR, {olmv1} does not change the target version when updates are published to the catalog.
+If you specify the Operator or extension's target version in the CR, {olmv1} installs the specified version. When the target version is specified in the CR, {olmv1} 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 update the Operator's CR. Specifying a Operator's target version pins the Operator's version to the specified release.
+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
 [source,yaml]
 ----
 apiVersion: operators.operatorframework.io/v1alpha1
 kind: Operator
 metadata:
-  name: quay-example
+  name: pipelines-operator
 spec:
-  packageName: quay-operator
-  version: 3.8.12 <1>
+  packageName: openshift-pipelines-operator-rh
+  version: 1.11.1 <1>
 ----
-<1> Specifies the target version. If you want to update the version of the Operator that is installed on the cluster, you must manually update this field the Operator's CR to the desired target version.
-
-If you want to change the installed version of an Operator, edit the Operator's CR to the desired target version.
+<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.
 
-[WARNING]
-====
-In previous versions of OLM, Operator authors could define upgrade edges to prevent you from updating to unsupported versions. In its current state of development, {olmv1} does not enforce upgrade edge definitions. You can specify any version of an Operator, and {olmv1} attempts to apply the update.
-====
+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, {olmv1} installs the latest version of an Operator or extension that can be resolved by the Operator Controller.
 
-You can inspect an Operator's catalog contents, including available versions and channels, by running the following command:
-
-.Command syntax
-[source,terminal]
+.Example CR with a version range specified
+[source,yaml]
 ----
-$ oc get package <catalog_name>-<package_name> -o yaml
+apiVersion: operators.operatorframework.io/v1alpha1
+kind: Operator
+metadata:
+  name: pipelines-operator
+spec:
+  packageName: openshift-pipelines-operator-rh
+  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, create or configure the Operator by running the following command:
+After you create or update a CR, apply the configuration file by running the following command:
 
 .Command syntax
 [source,terminal]
 ----
 $ oc apply -f <extension_name>.yaml
 ----
-
-.Troubleshooting
-
-* If you specify a target version or channel that does not exist, you can run the following command to check the status of your Operator:
-+
-[source,terminal]
-----
-$ oc get operator.operators.operatorframework.io <operator_name> -o yaml
-----
-+
-.Example output
-[source,text]
-----
-apiVersion: operators.operatorframework.io/v1alpha1
-kind: Operator
-metadata:
-  annotations:
-    kubectl.kubernetes.io/last-applied-configuration: |
-      {"apiVersion":"operators.operatorframework.io/v1alpha1","kind":"Operator","metadata":{"annotations":{},"name":"quay-example"},"spec":{"packageName":"quay-operator","version":"999.99.9"}}
-  creationTimestamp: "2023-10-19T18:39:37Z"
-  generation: 3
-  name: quay-example
-  resourceVersion: "51505"
-  uid: 2558623b-8689-421c-8ed5-7b14234af166
-spec:
-  packageName: quay-operator
-  version: 999.99.9
-status:
-  conditions:
-  - lastTransitionTime: "2023-10-19T18:50:34Z"
-    message: package 'quay-operator' at version '999.99.9' not found
-    observedGeneration: 3
-    reason: ResolutionFailed
-    status: "False"
-    type: Resolved
-  - lastTransitionTime: "2023-10-19T18:50:34Z"
-    message: installation has not been attempted as resolution failed
-    observedGeneration: 3
-    reason: InstallationStatusUnknown
-    status: Unknown
-    type: Installed
-----

modules/olmv1-forcing-an-update-or-rollback.adoc

@@ -0,0 +1,48 @@
+// Module included in the following assemblies:
+//
+// * operators/olm_v1/olmv1-installing-an-operator-from-a-catalog.adoc
+
+:_mod-docs-content-type: PROCEDURE
+
+[id="olmv1-forcing-an-update-or-rollback_{context}"]
+= Forcing an update or rollback
+
+{olmv1} 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.
+
+[WARNING]
+====
+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
+[source,yaml]
+----
+apiVersion: olm.operatorframework.io/v1alpha1
+kind: Operator
+metadata:
+  name: <operator_name> <1>
+spec:
+  packageName: <package_name> <2>
+  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:
++
+[source,terminal]
+----
+$ oc apply -f <extension_name>.yaml
+----

modules/olmv1-installing-an-operator.adoc

@@ -7,7 +7,7 @@
 [id="olmv1-installing-an-operator_{context}"]
 = Installing an Operator from a catalog
 
-{olmv1-first} supports installing Operators and extensions scoped to the cluster. You can install an Operator from a catalog by creating an Operator custom resource (CR) and applying it to the cluster.
+{olmv1-first} supports installing Operators and extensions scoped to the cluster. You can install an Operator or extension from a catalog by creating a custom resource (CR) and applying it to the cluster.
 
 [IMPORTANT]
 ====
@@ -23,6 +23,7 @@ Operators and extensions that use webhooks or that target a single or specified
 
 * You have added a catalog to your cluster.
 * You have downloaded a local copy of the catalog file.
+* You have installed the `jq` CLI tool.
 
 .Procedure
 
@@ -95,7 +96,7 @@ select( .schema == "olm.channel" ) | select( .name == "latest" ) | \
 ----
 ====
 
-. Create an Operator CR, similar to the following example:
+. Create a CR, similar to the following example:
 +
 .Example `pipelines-operator.yaml` CR
 [source,yaml]
@@ -113,9 +114,13 @@ spec:
 where:
 +
 <channel>:: Optional: Specifies the channel, such as `pipelines-1.11` or `latest`, for the package you want to install or update.
-<version>:: Optional: Specifies the specific version or version range, such as `1.11.1`, `1.12.x`, or `>=1.12.1`, of the package you want to install or update. For more information, see "About target versions in OLM 1.0" and "Support for version ranges".
+<version>:: Optional: Specifies the version or version range, such as `1.11.1`, `1.12.x`, or `>=1.12.1`, of the package you want to install or update. For more information, see "Example custom resources (CRs) that specify a target version" and "Support for version ranges".
++
+--
+include::snippets/olmv1-multi-catalog-admon.adoc[]
+--
 
-. Apply the Operator CR to the cluster by running the following command:
+. Apply the CR to the cluster by running the following command:
 +
 [source,terminal]
 ----
@@ -130,19 +135,16 @@ operator.operators.operatorframework.io/pipelines-operator created
 
 .Verification
 
-. View the Operator's CR in the YAML format by running the following command:
+. View the Operator or extension's CR in the YAML format by running the following command:
 +
 [source,terminal]
 ----
 $ oc get operator.operators.operatorframework.io pipelines-operator -o yaml
 ----
 +
-[NOTE]
-====
-If you specify a channel or define a version range in your Operator or extension's CR, {olmv1} does not display the resolved version installed on the cluster. Only the version and channel information specified in the CR are displayed.
-
-If you want to find the specific version that is installed, you must compare the SHA of the image of the `spec.source.image.ref` field to the image reference in the catalog.
-====
+--
+include::snippets/olmv1-version-range-cr-adomn.adoc[]
+--
 +
 .Example output
 [%collapsible]
@@ -184,7 +186,7 @@ status:
 ----
 ====
 
-. Get information about your Operator's bundle deployment by running the following command:
+. Get information about your bundle deployment by running the following command:
 +
 [source,terminal]
 ----

modules/olmv1-semver-support.adoc

@@ -0,0 +1,32 @@
+// Module included in the following assemblies:
+//
+// * operators/olm_v1/olmv1-installing-an-operator-from-a-catalog.adoc
+// * operators/olm_v1/arch/olmv1-operator-controller.adoc
+
+:_mod-docs-content-type: CONCEPT
+
+[id="olmv1-semver-support_{context}"]
+= Support for semantic versioning
+
+Support for link:https://semver.org/[semantic versioning (semver)] is enabled in {olmv1} by default. Operator and extension authors can use the semver standard to define compatible updates.
+
+{olmv1-first} can use an Operator or extension's version number to determine if an update can be resolved successfully.
+
+Cluster administrators can define a range of acceptable versions to install and automtically update. For Operators and extensions that follow the semver standard, you can use comparison strings to define to specify a desired version range.
+
+[NOTE]
+====
+{olmv1} does not support automatic updates to the next major version. If you want to perform a major version update, you must verify and apply the update manually. For more information, see "Forcing an update or rollback".
+====
+
+== Major version zero releases
+
+The semver standard specifies that major version zero releases (`O.y.z`) are reserved for initial development. During the initial development stage, the API is not stable and breaking changes might be introduced in any published version. As a result, major version zero releases apply a special set of update conditions.
+
+.Update conditions for major version zero releases
+
+* You cannot apply automatic updates when the major and minor versions are both zero, such as `0.0.*`. For example, automatic updates with the version range of `>=0.0.1 <0.1.0` are not allowed.
+* You cannot apply automatic updates from one minor version to another within a major version zero release. For example, {olmv1} does not automatically apply an update from `0.1.0` to `0.2.0`.
+* You can apply automatic updates from patch versions, such as `>=0.1.0 <0.2.0` or `>=0.2.0 <0.3.0`.
+
+When an automatic update is blocked by {olmv1}, you must manually verify and force the update by editing the Operator or extension's custom resource (CR).