Add "Upgrading installed Operators"

_topic_map.yml

@@ -876,12 +876,15 @@ Topics:
   - Name: Adding Operators to a cluster
     File: olm-adding-operators-to-cluster
     Distros: openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated
-  - Name: Configuring proxy support
-    File: olm-configuring-proxy-support
-    Distros: openshift-enterprise,openshift-webscale,openshift-origin
+  - Name: Upgrading installed Operators
+    File: olm-upgrading-operators
+    Distros: openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated
   - Name: Deleting Operators from a cluster
     File: olm-deleting-operators-from-cluster
     Distros: openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated
+  - Name: Configuring proxy support
+    File: olm-configuring-proxy-support
+    Distros: openshift-enterprise,openshift-webscale,openshift-origin
   - Name: Viewing Operator status
     File: olm-status
     Distros: openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated

modules/olm-approving-pending-upgrade.adoc

@@ -0,0 +1,34 @@
+// Module included in the following assemblies:
+//
+// * operators/admin/olm-upgrading-operators.adoc
+
+[id="olm-approving-pending-upgrade_{context}"]
+= Manually approving a pending Operator upgrade
+
+If an installed Operator has the approval strategy in its Subscription set to
+*Manual*, when new updates are released in its current update channel, the update must
+be manually approved before installation can begin.
+
+.Prerequisites
+
+* An Operator previously installed using Operator Lifecycle Manager (OLM).
+
+.Procedure
+
+. In the *Administrator* perspective of the {product-title} web console, navigate
+to *Operators -> Installed Operators*.
+
+. Operators that have a pending upgrade display a status with *Upgrade available*.
+Click the name of the Operator you want to upgrade.
+
+. Click the *Subscription* tab. Any upgrades requiring approval are displayed next
+to *Upgrade Status*. For example, it might display *1 requires approval*.
+
+. Click *1 requires approval*, then click *Preview Install Plan*.
+
+. Review the resources that are listed as available for upgrade. When satisfied,
+click *Approve*.
+
+. Navigate back to the *Operators -> Installed Operators* page to monitor the
+progress of the upgrade. When complete, the status changes to *Succeeded* and
+*Up to date*.

modules/olm-changing-update-channel.adoc

@@ -0,0 +1,56 @@
+// Module included in the following assemblies:
+//
+// * operators/admin/olm-upgrading-operators.adoc
+
+[id="olm-changing-update-channel_{context}"]
+= Changing the update channel for an Operator
+
+The Subscription of an installed Operator specifies an update channel, which is
+used to track and receive updates for the Operator. To upgrade the Operator to
+start tracking and receiving updates from a newer channel, you can change the
+update channel in the Subscription.
+
+The names of update channels in a Subscription can differ between Operators, but
+should follow a common convention within a given Operator. Some naming
+schemes include:
+
+- `4.3`, `4,4`, `4.5`
+- `stable-4.3`, `stable-4.4`, `stable-4.5`
+- `alpha`, `beta`, `stable`, `latest`
+
+Alternatively, the channel names might follow the version numbers of the
+application provided by the Operator.
+
+[NOTE]
+====
+Installed Operators cannot change to a channel that is older than the current
+channel.
+====
+
+If the approval strategy in the Subscription is set to *Automatic*, the upgrade
+process initiates immediately. If the approval strategy is set to *Manual*, you
+must manually approve the pending upgrade.
+
+.Prerequisites
+
+* An Operator previously installed using Operator Lifecycle Manager (OLM).
+
+.Procedure
+
+. In the *Administrator* perspective of the {product-title} web console, navigate
+to *Operators -> Installed Operators*.
+
+. Click the name of the Operator you want to change the update channel for.
+
+. Click the *Subscription* tab.
+
+. Click the name of the update channel under *Channel*.
+
+. Click the newer update channel that you want to change to, then click *Save*.
+
+. For Subscriptions with an *Automatic* approval strategy, the upgrade begins automatically. Navigate back to the *Operators -> Installed Operators*
+page to monitor the progress of the upgrade. When complete, the status changes
+to *Succeeded* and *Up to date*.
++
+For Subscriptions with a *Manual* approval strategy, you can manually approve
+the upgrade from the Subscription tab.

operators/admin/olm-upgrading-operators.adoc

@@ -0,0 +1,13 @@
+[id="olm-upgrading-operators"]
+= Upgrading installed Operators
+include::modules/common-attributes.adoc[]
+:context: olm-upgrading-operators
+
+toc::[]
+
+As a cluster administrator, you can upgrade Operators that have been previously
+installed using Operator Lifecycle Manager (OLM) on your {product-title}
+cluster.
+
+include::modules/olm-changing-update-channel.adoc[leveloffset=+1]
+include::modules/olm-approving-pending-upgrade.adoc[leveloffset=+1]

updating/updating-cluster-between-minor.adoc

@@ -17,10 +17,11 @@ Because of the difficulty of changing update channels by using `oc`, use the web
 * Have access to the cluster as a user with `admin` privileges.
 See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permissions].
 * Have a recent xref:../backup_and_restore/backing-up-etcd.adoc#backup-etcd[etcd backup] in case your upgrade fails and you must xref:../backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[restore your cluster to a previous state].
+* Ensure all Operators previously installed through Operator Lifecycle Manager (OLM) are updated to their latest version in their latest channel. Updating the Operators ensures they have a valid upgrade path when the default OperatorHub catalogs switch from the current minor version to the next during a cluster upgrade. See xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Upgrading installed Operators] for more information.
 
 [IMPORTANT]
 ====
-Using the `unsupportedConfigOverrides` section to modify an Operator's configuration is unsupported and might block cluster upgrades. You must remove this setting before you can upgrade your cluster.
+Using the `unsupportedConfigOverrides` section to modify the configuration of an Operator is unsupported and might block cluster upgrades. You must remove this setting before you can upgrade your cluster.
 ====
 
 include::modules/update-service-overview.adoc[leveloffset=+1]

updating/updating-cluster-cli.adoc

@@ -12,6 +12,12 @@ You can update, or upgrade, an {product-title} cluster within a minor version by
 * Have access to the cluster as a user with `admin` privileges.
 See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permissions].
 * Have a recent xref:../backup_and_restore/backing-up-etcd.adoc#backup-etcd[etcd backup] in case your upgrade fails and you must xref:../backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[restore your cluster to a previous state].
+* Ensure all Operators previously installed through Operator Lifecycle Manager (OLM) are updated to their latest version in their latest channel. Updating the Operators ensures they have a valid upgrade path when the default OperatorHub catalogs switch from the current minor version to the next during a cluster upgrade. See xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Upgrading installed Operators] for more information.
+
+[IMPORTANT]
+====
+Using the `unsupportedConfigOverrides` section to modify the configuration of an Operator is unsupported and might block cluster upgrades. You must remove this setting before you can upgrade your cluster.
+====
 
 include::modules/update-service-overview.adoc[leveloffset=+1]
 .Additional resources