Merge pull request #36464 from ousleyp/cnv-14044

CNV-14044: fixing upgrade and install docs for 4.8 and beyond

Author: ousleyp

modules/olm-approving-pending-upgrade.adoc

@@ -1,6 +1,7 @@
 // Module included in the following assemblies:
 //
 // * operators/admin/olm-upgrading-operators.adoc
+// * virt/upgrading-virt.adoc
 
 [id="olm-approving-pending-upgrade_{context}"]
 = Manually approving a pending Operator upgrade

modules/virt-about-upgrading-virt.adoc

@@ -5,20 +5,23 @@
 [id="virt-about-upgrading-virt_{context}"]
 = About upgrading {VirtProductName}
 
+[id="how-upgrades-work_{context}"]
 == How {VirtProductName} upgrades work
 
-* You can upgrade to the next minor version of {VirtProductName} by using the
-{product-title} web console to change the channel of your Operator subscription.
+* Operator Lifecycle Manager (OLM) manages the lifecycle of the {VirtProductName} Operator. The Marketplace Operator, which is deployed during {product-title} installation, makes external Operators available to your cluster.
 
-* You can enable automatic _z-stream_ updates during {VirtProductName} installation.
+* OLM provides z-stream and minor version updates for {VirtProductName}. Minor version updates become available when you upgrade {product-title} to the next minor version. You cannot upgrade {VirtProductName} to the next minor version without first upgrading {product-title}.
 
-* Updates are delivered via the _Marketplace Operator_, which is deployed
-during {product-title} installation. The Marketplace Operator makes
-external Operators available to your cluster.
+* {VirtProductName} subscriptions use a single update channel that is named *stable*. The *stable* channel ensures that your {VirtProductName} and {product-title} versions are compatible.
+
+* If your subscription's approval strategy is set to *Automatic*, the upgrade process starts as soon as a new version of the Operator is available in the *stable* channel. It is highly recommended to use the *Automatic* approval strategy to maintain a supportable environment. Each minor version of {VirtProductName} is only supported if you run the corresponding {product-title} version. For example, you must run {VirtProductName} {VirtVersion} on {product-title} {VirtVersion}.
+
+** Though it is possible to select the *Manual* approval strategy, this is not recommended because it risks the supportability and functionality of your cluster. With the *Manual* approval strategy, you must manually approve every pending update. If {product-title} and {VirtProductName} updates are out of sync, your cluster becomes unsupported.
 
 * The amount of time an update takes to complete depends on your network
 connection. Most automatic updates complete within fifteen minutes.
 
+[id="how-upgrades-affect-cluster_{context}"]
 == How {VirtProductName} upgrades affect your cluster
 
 * Upgrading does not interrupt virtual machine workloads.

modules/virt-installing-virt-operator.adoc

@@ -14,8 +14,6 @@ You can install the {VirtProductName} Operator from the {product-title} web cons
 
 .Procedure
 
-. Open a browser window and log in to the {product-title} web console.
-
 . From the *Administrator* perspective, click *Operators* -> *OperatorHub*.
 
 . In the *Filter by keyword* field, type *{VirtProductName}*.
@@ -26,9 +24,7 @@ You can install the {VirtProductName} Operator from the {product-title} web cons
 
 . On the *Install Operator* page:
 
-.. Select *stable* from the list of available *Update Channel* options. This ensures that:
-* You install the version of {VirtProductName} that is compatible with your {product-title} version.
-* When you update {product-title}, {VirtProductName} automatically updates to the next minor version.
+.. Select *stable* from the list of available *Update Channel* options. This ensures that you install the version of {VirtProductName} that is compatible with your {product-title} version.
 
 .. For *Installed Namespace*, ensure that the *Operator recommended namespace* option is selected. This installs the Operator in the mandatory `openshift-cnv` namespace, which is automatically created if it does not exist.
 +
@@ -37,7 +33,14 @@ You can install the {VirtProductName} Operator from the {product-title} web cons
 Attempting to install the {VirtProductName} Operator in a namespace other than `openshift-cnv` causes the installation to fail.
 ====
 
-.. For *Approval Strategy*, ensure that *Automatic*, which is the default value, is selected. {VirtProductName} automatically updates when a new z-stream release is available.
+.. For *Approval Strategy*, it is highly recommended that you select *Automatic*, which is the default value, so that {VirtProductName} automatically updates when a new version is available in the *stable* update channel.
++
+While it is possible to select the *Manual* approval strategy, this is inadvisable because of the high risk that it presents to the supportability and functionality of your cluster. Only select *Manual* if you fully understand these risks and cannot use *Automatic*.
++
+[WARNING]
+====
+Because {VirtProductName} is only supported when used with the corresponding {product-title} version, missing {VirtProductName} updates can cause your cluster to become unsupported.
+====
 
 . Click *Install* to make the Operator available to the `openshift-cnv` namespace.
 

modules/virt-monitoring-upgrade-status.adoc

@@ -26,7 +26,7 @@ available information.
 +
 [source,terminal]
 ----
-$ oc get csv
+$ oc get csv -n openshift-cnv
 ----
 
 . Review the output, checking the `PHASE` field. For example:
@@ -35,8 +35,8 @@ $ oc get csv
 [source,terminal,subs="attributes+"]
 ----
 VERSION  REPLACES                                        PHASE
-2.5.0    kubevirt-hyperconverged-operator.v2.4.3         Installing
-2.4.3                                                    Replacing
+4.8.0    kubevirt-hyperconverged-operator.v2.6.5         Installing
+4.8.1    kubevirt-hyperconverged-operator.v4.8.0         Replacing
 ----
 
 . Optional: Monitor the aggregated status of all {VirtProductName} component

modules/virt-upgrading-virt.adoc

@@ -1,23 +1,28 @@
 [id="upgrading-virt"]
 = Upgrading {VirtProductName}
 include::modules/virt-document-attributes.adoc[]
+include::modules/common-attributes.adoc[]
 :context: upgrading-virt
 
 toc::[]
 
-You can manually upgrade to the next minor version of {VirtProductName} and
-monitor the status of an update by using the web console.
+Learn how Operator Lifecycle Manager (OLM) delivers z-stream and minor version updates for {VirtProductName}.
 
 include::modules/virt-about-upgrading-virt.adoc[leveloffset=+1]
 
 //include::modules/virt-upgrade-pathways.adoc[leveloffset=+1]
 
-include::modules/virt-upgrading-virt.adoc[leveloffset=+1]
+include::modules/olm-approving-pending-upgrade.adoc[leveloffset=+1]
 
 include::modules/virt-monitoring-upgrade-status.adoc[leveloffset=+1]
 
+[id="additional-resources_upgrading-virt"]
 == Additional resources
 
+* xref:../operators/understanding/olm-what-operators-are.adoc#olm-what-operators-are[What are Operators?]
+
+* xref:../operators/understanding/olm/olm-understanding-olm.adoc#olm-understanding-olm[Operator Lifecycle Manager concepts and resources]
+
 * xref:../operators/understanding/olm/olm-understanding-olm.adoc#olm-csv_olm-understanding-olm[Cluster service versions (CSVs)]
 
 * xref:../virt/live_migration/virt-configuring-vmi-eviction-strategy.adoc#virt-configuring-vmi-eviction-strategy[Configuring virtual machine eviction strategy]