From 597d7b000b38eb98e5e41d976286e4cfdf8084df Mon Sep 17 00:00:00 2001 From: Pan Ousley Date: Thu, 16 Sep 2021 15:16:47 -0400 Subject: [PATCH] CNV-14044: fixing upgrade and install docs for 4.8 and beyond --- modules/olm-approving-pending-upgrade.adoc | 1 + modules/virt-about-upgrading-virt.adoc | 15 +++++---- modules/virt-installing-virt-operator.adoc | 15 +++++---- modules/virt-monitoring-upgrade-status.adoc | 6 ++-- modules/virt-upgrading-virt.adoc | 37 --------------------- virt/upgrading-virt.adoc | 11 ++++-- 6 files changed, 30 insertions(+), 55 deletions(-) delete mode 100644 modules/virt-upgrading-virt.adoc diff --git a/modules/olm-approving-pending-upgrade.adoc b/modules/olm-approving-pending-upgrade.adoc index 26f6d70e6d..401027cb66 100644 --- a/modules/olm-approving-pending-upgrade.adoc +++ b/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 diff --git a/modules/virt-about-upgrading-virt.adoc b/modules/virt-about-upgrading-virt.adoc index 87ffb2f3a8..a0161322f9 100644 --- a/modules/virt-about-upgrading-virt.adoc +++ b/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. diff --git a/modules/virt-installing-virt-operator.adoc b/modules/virt-installing-virt-operator.adoc index 7a2c9a444c..bbf22fd159 100644 --- a/modules/virt-installing-virt-operator.adoc +++ b/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. diff --git a/modules/virt-monitoring-upgrade-status.adoc b/modules/virt-monitoring-upgrade-status.adoc index be9095adbb..e11a4cd083 100644 --- a/modules/virt-monitoring-upgrade-status.adoc +++ b/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 diff --git a/modules/virt-upgrading-virt.adoc b/modules/virt-upgrading-virt.adoc deleted file mode 100644 index 70f1390705..0000000000 --- a/modules/virt-upgrading-virt.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/upgrading-virt.adoc - -[id="virt-upgrading-virt_{context}"] -= Upgrading {VirtProductName} to the next minor version - -You can manually upgrade {VirtProductName} to the next minor version by using the -{product-title} web console to change the channel of your Operator subscription. - -.Prerequisites - -* Log in to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. Access the {product-title} web console and navigate to *Operators* -> *Installed Operators*. - -. Click *{VirtProductName}* to open the *Operator Details* page. - -. Click the *Subscription* tab to open the *Subscription Overview* page. - -. In the *Channel* pane, click the pencil icon on the right side of the -version number to open the *Change Subscription Update Channel* window. - -. Select *stable*. This ensures that you install the version of {VirtProductName} -that is compatible with your {product-title} version. - -. Click *Save*. - -. Check the status of the upgrade by navigating to *Operators* -> *Installed Operators*. -You can also check the status by running the following `oc` command: -+ -[source,terminal] ----- -$ oc get csv -n openshift-cnv ----- diff --git a/virt/upgrading-virt.adoc b/virt/upgrading-virt.adoc index 9252f4331c..b829da2e70 100644 --- a/virt/upgrading-virt.adoc +++ b/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]