OLMv1 support for olm.maxOpenShiftVersion

adellape · adellape · commit 20ab6dc67b57 · 2024-12-20T13:47:28.000-07:00
diff --git a/_attributes/common-attributes.adoc b/_attributes/common-attributes.adoc
@@ -10,6 +10,10 @@
 :toc-title:
 :imagesdir: images
 :prewrap!:
+// n-1 and n+1 OCP versions relative to the current branch's {product-version} attr
+:ocp-nminus1: 4.17
+:ocp-nplus1: 4.19
+// Operating system attributes
 :op-system-first: Red Hat Enterprise Linux CoreOS (RHCOS)
 :op-system: RHCOS
 :op-system-lowercase: rhcos
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -2087,8 +2087,8 @@ Topics:
   Topics:
   - Name: Managing extensions
     File: managing-ce
-  - Name: Upgrade edges
-    File: upgrade-edges
+  - Name: Update paths
+    File: update-paths
   - Name: CRD upgrade safety
     File: crd-upgrade-safety
 ---
diff --git a/extensions/ce/managing-ce.adoc b/extensions/ce/managing-ce.adoc
@@ -25,13 +25,13 @@ include::modules/olmv1-installing-an-operator.adoc[leveloffset=+1]
 .Additional resources
 * xref:../../extensions/ce/managing-ce.adoc#olmv1-supported-extensions_managing-ce[Supported extensions]
 * xref:../../extensions/ce/managing-ce.adoc#olmv1-creating-a-service-account_managing-ce[Creating a service account]
-* xref:../../extensions/ce/upgrade-edges.adoc#olmv1-about-target-versions_upgrade-edges[Example custom resources (CRs) that specify a target version]
-* xref:../../extensions/ce/upgrade-edges.adoc#olmv1-version-range-support_upgrade-edges[Support for version ranges]
+* xref:../../extensions/ce/update-paths.adoc#olmv1-about-target-versions_update-paths[Example custom resources (CRs) that specify a target version]
+* xref:../../extensions/ce/update-paths.adoc#olmv1-version-range-support_update-paths[Support for version ranges]
 
 include::modules/olmv1-updating-an-operator.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
-* xref:../../extensions/ce/upgrade-edges.adoc#upgrade-edges[Upgrade edges]
+* xref:../../extensions/ce/update-paths.adoc#update-paths[Update paths]
 
 include::modules/olmv1-deleting-an-operator.adoc[leveloffset=+1]
diff --git a/extensions/ce/update-paths.adoc b/extensions/ce/update-paths.adoc
@@ -0,0 +1,66 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="update-paths"]
+= Update paths
+include::_attributes/common-attributes.adoc[]
+:context: update-paths
+
+toc::[]
+
+When determining _update paths_, also known as upgrade edges or upgrade constraints, for an installed cluster extension, {olmv1-first} supports {olmv0} semantics starting in {product-title} 4.16. This support follows the behavior from {olmv0}, including `replaces`, `skips`, and `skipRange` directives, with a few noted differences.
+
+By supporting {olmv0} semantics, {olmv1} accurately reflects the update graph from catalogs.
+
+.Differences from original {olmv0} implementation
+
+* If there are multiple possible successors, {olmv1} behavior differs in the following ways:
+** In {olmv0}, the successor closest to the channel head is chosen.
+** In {olmv1}, the successor with the highest semantic version (semver) is chosen.
+
+* Consider the following set of file-based catalog (FBC) channel entries:
++
+[source,yaml]
+----
+# ...
+- 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, {olmv1} behavior differs in the following ways:
++
+--
+** {olmv0-caps} will not detect an update path to `v2.0.0` because `v2.0.0` is skipped and not on the `replaces` chain.
+** {olmv1} will detect the update path because {olmv1} does not have a concept of a `replaces` chain. {olmv1} finds all entries that have a `replace`, `skip`, or `skipRange` value that covers the currently installed version.
+--
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../../operators/understanding/olm/olm-workflow.adoc#olm-upgrades_olm-workflow[{olmv0-caps} upgrade semantics]
+
+include::modules/olmv1-version-range-support.adoc[leveloffset=+1]
+
+include::modules/olmv1-version-range-comparisons.adoc[leveloffset=+1]
+include::modules/olmv1-about-target-versions.adoc[leveloffset=+1]
+include::modules/olmv1-forcing-an-update-or-rollback.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../../extensions/ce/update-paths.adoc#olmv1-version-range-support_update-paths[Support for version ranges]
+// after #82245 merges, add an xref to _Creating a service account to manage cluster extensions_
+
+include::modules/olmv1-ocp-compat.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+* link:https://kubernetes.io/docs/reference/using-api/deprecation-guide/[Deprecated API Migration Guide] (Kubernetes documentation)
+
+
+include::modules/olmv1-blocked-cluster-updates.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../../updating/understanding_updates/intro-to-updates.adoc#understanding_clusteroperator_conditiontypes_understanding-openshift-updates[Understanding cluster Operator condition types]
+* xref:../../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Upgrading installed Operators]
+* xref:../../operators/admin/olm-deleting-operators-from-cluster.adoc#olm-deleting-operators-from-a-cluster[Deleting Operators from a cluster]
+* xref:../../operators/operator-reference.adoc#cluster-operators-ref-olmv1_cluster-operators-ref[Cluster Operators reference -> {olmv1-first} Operator]
diff --git a/extensions/ce/upgrade-edges.adoc b/extensions/ce/upgrade-edges.adoc
diff --git a/modules/olm-channel-schema.adoc b/modules/olm-channel-schema.adoc
@@ -5,7 +5,7 @@
 [id="olm-channel-schema_{context}"]
 = olm.channel schema
 
-The `olm.channel` schema defines a channel within a package, the bundle entries that are members of the channel, and the upgrade edges for those bundles.
+The `olm.channel` schema defines a channel within a package, the bundle entries that are members of the channel, and the upgrade paths for those bundles.
 
 If a bundle entry represents an edge in multiple `olm.channel` blobs, it can only appear once per channel.
 
diff --git a/modules/olm-fb-catalogs-guidelines.adoc b/modules/olm-fb-catalogs-guidelines.adoc
@@ -12,12 +12,12 @@ Consider the following guidelines when maintaining file-based catalogs.
 
 The general advice with Operator Lifecycle Manager (OLM) is that bundle images and their metadata should be treated as immutable.
 
-If a broken bundle has been pushed to a catalog, you must assume that at least one of your users has upgraded to that bundle. Based on that assumption, you must release another bundle with an upgrade edge from the broken bundle to ensure users with the broken bundle installed receive an upgrade. OLM will not reinstall an installed bundle if the contents of that bundle are updated in the catalog.
+If a broken bundle has been pushed to a catalog, you must assume that at least one of your users has upgraded to that bundle. Based on that assumption, you must release another bundle with an upgrade path from the broken bundle to ensure users with the broken bundle installed receive an upgrade. OLM will not reinstall an installed bundle if the contents of that bundle are updated in the catalog.
 
 However, there are some cases where a change in the catalog metadata is preferred:
 
 * Channel promotion: If you already released a bundle and later decide that you would like to add it to another channel, you can add an entry for your bundle in another `olm.channel` blob.
-* New upgrade edges: If you release a new `1.2.z` bundle version, for example `1.2.4`, but `1.3.0` is already released, you can update the catalog metadata for `1.3.0` to skip `1.2.4`.
+* New upgrade paths: If you release a new `1.2.z` bundle version, for example `1.2.4`, but `1.3.0` is already released, you can update the catalog metadata for `1.3.0` to skip `1.2.4`.
 
 [id="olm-fb-catalogs-source-control_{context}"]
 == Source control
diff --git a/modules/olm-fb-catalogs.adoc b/modules/olm-fb-catalogs.adoc
@@ -16,7 +16,7 @@ This editability enables the following features and user-defined extensions:
 --
 * Promoting an existing bundle to a new channel
 * Changing the default channel of a package
-* Custom algorithms for adding, updating, and removing upgrade edges
+* Custom algorithms for adding, updating, and removing upgrade paths
 --
 
 Composability::
@@ -34,6 +34,6 @@ Because Operator authors are most familiar with their Operator, its dependencies
 Extensibility::
 The file-based catalog specification is a low-level representation of a catalog. While it can be maintained directly in its low-level form, catalog maintainers can build interesting extensions on top that can be used by their own custom tooling to make any number of mutations.
 +
-For example, a tool could translate a high-level API, such as `(mode=semver)`, down to the low-level, file-based catalog format for upgrade edges. Or a catalog maintainer might need to customize all of the bundle metadata by adding a new property to bundles that meet a certain criteria.
+For example, a tool could translate a high-level API, such as `(mode=semver)`, down to the low-level, file-based catalog format for upgrade paths. Or a catalog maintainer might need to customize all of the bundle metadata by adding a new property to bundles that meet a certain criteria.
 +
 While this extensibility allows for additional official tooling to be developed on top of the low-level APIs for future {product-title} releases, the major benefit is that catalog maintainers have this capability as well.
diff --git a/modules/olm-terms.adoc b/modules/olm-terms.adoc
@@ -43,6 +43,13 @@ An Operator may have a _dependency_ on another Operator being present in the clu
 
 OLM resolves dependencies by ensuring that all specified versions of Operators and CRDs are installed on the cluster during the installation phase. This dependency is resolved by finding and installing an Operator in a catalog that satisfies the required CRD API, and is not related to packages or bundles.
 
+[id="olm-common-terms-extension_{context}"]
+== Extension
+
+Extensions enable cluster administrators to extend capabilities for users on their {product-tile} cluster. Extensions are managed by {olmv1-first}.
+
+The `ClusterExtension` API streamlines management of installed extensions, which includes Operators via the `registry+v1` bundle format, by consolidating user-facing APIs into a single object. Administrators and SREs can use the API to automate processes and define desired states by using GitOps principles.
+
 [id="olm-common-terms-index-image_{context}"]
 == Index image
 In the bundle format, an _index image_ refers to an image of a database (a database snapshot) that contains information about Operator bundles including CSVs and CRDs of all versions. This index can host a history of Operators on a cluster and be maintained by adding or removing Operators using the `opm` CLI tool.
@@ -57,6 +64,13 @@ A _tenant_ in {product-title} is a user or group of users that share common acce
 
 When a cluster is shared by multiple users or groups, it is considered a _multitenant_ cluster.
 
+[id="olm-common-terms-operator_{context}"]
+== Operator
+
+Operators are a method of packaging, deploying, and managing a Kubernetes application. A Kubernetes application is an app that is both deployed on Kubernetes and managed using the Kubernetes APIs and `kubectl` or `oc` tooling.
+
+In {olmv1-first}, the `ClusterExtension` API streamlines management of installed extensions, which includes Operators via the `registry+v1` bundle format.
+
 [id="olm-common-terms-operatorgroup_{context}"]
 == Operator group
 
@@ -77,3 +91,5 @@ A _subscription_ keeps CSVs up to date by tracking a channel in a package.
 [id="olm-common-terms-update-graph_{context}"]
 == Update graph
 An _update graph_ links versions of CSVs together, similar to the update graph of any other packaged software. Operators can be installed sequentially, or certain versions can be skipped. The update graph is expected to grow only at the head with newer versions being added.
+
+Also known as _update edges_ or _update paths_.
diff --git a/modules/olmv1-blocked-cluster-updates.adoc b/modules/olmv1-blocked-cluster-updates.adoc
@@ -0,0 +1,11 @@
+// Module included in the following assemblies:
+//
+// * extensions/ce/update-paths.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="olmv1-blocked-cluster-updates_{context}"]
+= Cluster updates blocked by olm cluster Operator
+
+If an installed Operator's `olm.maxOpenShiftVersion` field is set and a cluster administrator attempts to update their cluster to a version that the Operator does not provide a valid update path for, the cluster update fails and the `Upgradeable` status for the `olm` cluster Operator is set to `False`.
+
+To resolve the issue, the cluster administrator must either update the installed Operator to a version with a valid update path, if one is available, or they must uninstall the Operator. Then, they can attempt the cluster update again.
diff --git a/modules/olmv1-ocp-compat.adoc b/modules/olmv1-ocp-compat.adoc
@@ -0,0 +1,35 @@
+// Module included in the following assemblies:
+//
+// * extensions/ce/update-paths.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="olmv1-ocp-compat_{context}"]
+= Compatibility with {product-title} versions
+
+Before cluster administrators can update their {product-title} cluster to its next minor version, they must ensure that all installed Operators are updated to a bundle version that is compatible with the cluster's next minor version (4.y+1).
+
+For example, Kubernetes periodically deprecates certain APIs that are removed in subsequent releases. If an extension is using a deprecated API, it might no longer work after the {product-title} cluster is updated to the Kubernetes version where the API has been removed.
+
+If an Operator author knows that a specific bundle version is not supported and will not work correctly, for any reason, on {product-title} later than a certain cluster minor version, they can configure the maximum version of {product-title} that their Operator is compatible with.
+
+In the Operator project's cluster service version (CSV), authors can set the `olm.maxOpenShiftVersion` annotation to prevent administrators from updating the cluster before updating the installed Operator to a compatible version.
+
+.Example CSV with `olm.maxOpenShiftVersion` annotation
+[source,yaml]
+----
+apiVersion: operators.coreos.com/v1alpha1
+kind: ClusterServiceVersion
+metadata:
+  annotations:
+    "olm.properties": '[{"type": "olm.maxOpenShiftVersion", "value": "<cluster_version>"}]' <1>
+----
+<1> Specifies the latest minor version of {product-title} (4.y) that an Operator is compatible with. For example, setting `value` to `{product-version}` prevents cluster updates to minor versions later than {product-version} when this bundle is installed on a cluster.
++
+If the `olm.maxOpenShiftVersion` field is omitted, cluster updates are not blocked by this Operator.
+
+[NOTE]
+====
+When determining a cluster's next minor version (4.y+1), {olmv1} only considers major and minor versions (x and y) for comparisons. It ignores any _z-stream_ versions (4.y.z), also known as patch releases, or pre-release versions.
+
+For example, if the cluster's current version is `{product-version}.0`, the next minor version is `{ocp-nplus1}`. If the current version is `{product-version}.0-rc1`, the next minor version is still `{ocp-nplus1}`.
+====
diff --git a/operators/operator-reference.adoc b/operators/operator-reference.adoc
@@ -176,7 +176,7 @@ include::modules/olmv1-clusteroperator.adoc[leveloffset=+1]
 [id="cluster-operators-ref-olmv1-addtl-resources"]
 === Additional resources
 * xref:../extensions/index.adoc#extensions-overview[Extensions overview]
-* xref:../extensions/ce/upgrade-edges.adoc#upgrade-edges[Compatibility with {product-title} versions]
+* xref:../extensions/ce/update-paths.adoc#olmv1-ocp-compat_update-paths[Compatibility with {product-title} versions]
 
 include::modules/openshift-service-ca-operator.adoc[leveloffset=+1]
 
diff --git a/snippets/olmv1-known-issue-private-registries.adoc b/snippets/olmv1-known-issue-private-registries.adoc
@@ -7,7 +7,7 @@
 // * extensions/catalogs/managing-catalogs.adoc
 // * extensions/catalogs/rh-catalogs.adoc
 // * extensions/ce/managing-ce.adoc
-// * extensions/ce/upgrade-edges.adoc
+// * extensions/ce/update-paths.adoc
 // * extensions/index.adoc
 
 :_mod-docs-content-type: SNIPPET
