Merge pull request #40787 from ousleyp/updates-4-10

CNV-14816: workload updates are no longer tech preview

Author: ousleyp

_topic_maps/_topic_map.yml

@@ -2916,10 +2916,10 @@ Topics:
   - Name: Uninstalling OKD Virtualization using the CLI
     File: uninstalling-virt-cli
     Distros: openshift-origin
-- Name: Upgrading OpenShift Virtualization
+- Name: Updating OpenShift Virtualization
   File: upgrading-virt
   Distros: openshift-enterprise
-- Name: Upgrading OKD Virtualization
+- Name: Updating OKD Virtualization
   File: upgrading-virt
   Distros: openshift-origin
 - Name: Additional security privileges granted for kubevirt-controller and virt-launcher

modules/virt-about-upgrading-virt.adoc

@@ -2,29 +2,30 @@
 //
 // * virt/upgrading-virt.adoc
 
+:_content-type: CONCEPT
 [id="virt-about-upgrading-virt_{context}"]
-= About upgrading {VirtProductName}
+= About updating {VirtProductName}
 
 * 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.
 
-* 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}.
+* OLM provides z-stream and minor version updates for {VirtProductName}. Minor version updates become available when you update {product-title} to the next minor version. You cannot update {VirtProductName} to the next minor version without first updating {product-title}.
 
 * {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}.
+* If your subscription's approval strategy is set to *Automatic*, the update 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.
 
-* Upgrading does not interrupt network connections.
+* Updating {VirtProductName} does not interrupt network connections.
 
-* Data volumes and their associated persistent volume claims are preserved during upgrade.
+* Data volumes and their associated persistent volume claims are preserved during update.
 
 [IMPORTANT]
 ====
-If you have virtual machines running that use hostpath provisioner storage, they cannot be live migrated and might block an {product-title} cluster upgrade. 
+If you have virtual machines running that use hostpath provisioner storage, they cannot be live migrated and might block an {product-title} cluster update.
 
-As a workaround, you can reconfigure the virtual machines so that they can be powered off automatically during a cluster upgrade. Remove the `evictionStrategy: LiveMigrate` field and set the `runStrategy` field to `Always`.
+As a workaround, you can reconfigure the virtual machines so that they can be powered off automatically during a cluster update. Remove the `evictionStrategy: LiveMigrate` field and set the `runStrategy` field to `Always`.
 ====

modules/virt-about-workload-updates.adoc

@@ -2,26 +2,53 @@
 //
 // * virt/upgrading-virt.adoc
 
+:_content-type: CONCEPT
 [id="virt-about-workload-updates_{context}"]
 = About workload updates
 
-* When you upgrade {VirtProductName}, virtual machine workloads including `libvirt`, `virt-launcher`, and `qemu` update automatically if they support live migration.
-+
+When you update {VirtProductName}, virtual machine workloads, including `libvirt`, `virt-launcher`, and `qemu`, update automatically if they support live migration.
+
 [NOTE]
 ====
 Each virtual machine has a `virt-launcher` pod that runs the virtual machine
-instance. The `virt-launcher` pod runs an instance of `libvirt`, which is
-used to manage the virtual machine process.
+instance (VMI). The `virt-launcher` pod runs an instance of `libvirt`, which is
+used to manage the virtual machine (VM) process.
 ====
 
-** There are two available workload update methods: `LiveMigrate` and `Evict`. By default, only `LiveMigrate` is enabled, which means that:
+You can configure how workloads are updated by editing the `spec.workloadUpdateStrategy` stanza of the `HyperConverged` custom resource (CR). There are two available workload update methods: `LiveMigrate` and `Evict`.
+
+Because the `Evict` method shuts down VMI pods, only the `LiveMigrate` update strategy is enabled by default.
+
+When `LiveMigrate` is the only update strategy enabled:
+
+* VMIs that support live migration are migrated during the update process. The VM guest moves into a new pod with the updated components enabled.
+
+* VMIs that do not support live migration are not disrupted or updated.
+
+** If a VMI has the `LiveMigrate` eviction strategy but does not support live migration, it is not updated.
+
+If you enable both `LiveMigrate` and `Evict`:
+
+* VMIs that support live migration use the `LiveMigrate` update strategy.
 
-*** Virtual machine instances (VMIs) that support live migration are migrated during the upgrade process.
+* VMIs that do not support live migration use the `Evict` update strategy. If a VMI is controlled by a `VirtualMachine` object that has a `runStrategy` value of `always`, a new VMI is created in a new pod with updated components.
 
-*** VMIs are not updated at all if the following conditions are both true:
+[discrete]
+[id="migration-attempts-timeouts_{context}"]
+== Migration attempts and timeouts
+
+When updating workloads, live migration fails if a pod is in the `Pending` state for the following periods:
+
+5 minutes:: If the pod is pending because it is `Unschedulable`.
+
+15 minutes:: If the pod is stuck in the pending state for any reason.
+
+When a VMI fails to migrate, the `virt-controller` tries to migrate it again. It repeats this process until all migratable VMIs are running on new `virt-launcher` pods. If a VMI is improperly configured, however, these attempts can repeat indefinitely.
+
+[NOTE]
+====
+Each attempt corresponds to a migration object. Only the five most recent attempts are held in a buffer. This prevents migration objects from accumulating on the system while retaining information for debugging.
+====
 
-**** The VMI does not support live migration.
 
-**** The VMI is configured to use the `LiveMigrate` eviction strategy.
 
-** You can configure how workloads are updated by editing the `spec.workloadUpdateStrategy` stanza of the `HyperConverged` custom resource (CR).

modules/virt-configuring-workload-update-methods.adoc

@@ -2,6 +2,7 @@
 //
 // * virt/upgrading-virt.adoc
 
+:_content-type: PROCEDURE
 [id="virt-configuring-workload-update-methods_{context}"]
 = Configuring workload update methods
 

modules/virt-opting-out-workload-updates.adoc

@@ -2,7 +2,7 @@
 [id="upgrading-virt"]
 include::modules/virt-document-attributes.adoc[]
 include::modules/common-attributes.adoc[]
-= Upgrading {VirtProductName}
+= Updating {VirtProductName}
 :context: upgrading-virt
 
 toc::[]
@@ -14,43 +14,26 @@ include::modules/virt-about-upgrading-virt.adoc[leveloffset=+1]
 [id="configuring-workload-updates_upgrading-virt"]
 == Configuring automatic workload updates
 
-// Uncomment this in 4.10 and replace prefix
-//[NOTE]
-//====
-//Automatic workload updates are enabled by default in {VirtProductName} {VirtVersion}. You can opt out by following a ../virt/upgrading-virt.adoc#virt-opting-out-workload-updates_upgrading-virt[workaround to disable this feature] before you upgrade to {VirtVersion}.
-//====
-
-// Remove TP module in 4.10
-ifdef::openshift-enterprise[]
-:FeatureName: Automatically updating workloads
-include::snippets/technology-preview.adoc[leveloffset=+2]
-endif::[]
-
-// Uncomment this in 4.10 if it is still relevant (describes default behavior)
-//include::modules/virt-about-workload-updates.adoc[leveloffset=+2]
+include::modules/virt-about-workload-updates.adoc[leveloffset=+2]
 
 include::modules/virt-configuring-workload-update-methods.adoc[leveloffset=+2]
 
-// Uncomment and/or change this procedure in 4.10
-//include::modules/virt-opting-out-workload-updates.adoc[leveloffset=+2]
-
 [id="approving-operator-upgrades_upgrading-virt"]
-== Approving pending Operator upgrades
+== Approving pending Operator updates
 
 include::modules/olm-approving-pending-upgrade.adoc[leveloffset=+2]
 
 [id="monitoring-upgrade-status_upgrading-virt"]
-== Monitoring upgrade status
+== Monitoring update status
 
 include::modules/virt-monitoring-upgrade-status.adoc[leveloffset=+2]
 
 include::modules/virt-viewing-outdated-workloads.adoc[leveloffset=+2]
 
-// Uncomment this in 4.10
-//[NOTE]
-//====
-//xref:../virt/upgrading-virt.adoc#configuring-workload-updates_upgrading-virt[Configure workload updates] to ensure that VMIs update automatically.
-//====
+[NOTE]
+====
+xref:../virt/upgrading-virt.adoc#configuring-workload-updates_upgrading-virt[Configure workload updates] to ensure that VMIs update automatically.
+====
 
 [id="additional-resources_upgrading-virt"]
 == Additional resources