Merge pull request #38149 from ousleyp/tp-auto-workload-updates

BZ2017573: CNV-9800 is now TP for 4.9

modules/virt-about-upgrading-virt.adoc

@@ -5,9 +5,6 @@
 [id="virt-about-upgrading-virt_{context}"]
 = About upgrading {VirtProductName}
 
-[id="how-upgrades-work_{context}"]
-== How {VirtProductName} upgrades work
-
 * 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}.
@@ -21,34 +18,10 @@
 * 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
-
-* When you upgrade {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.
-====
-
-** There are two supported workload update methods: `LiveMigrate` and `Evict`. By default, only `LiveMigrate` is enabled, which means that:
-
-*** Virtual machine instances (VMIs) that support live migration are migrated during the upgrade process.
-
-*** VMIs are not updated at all if the following conditions are both true:
-
-**** 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).
-
 * Upgrading does not interrupt network connections.
 
 * Data volumes and their associated persistent volume claims are preserved during upgrade.
-+
+
 [IMPORTANT]
 ====
 If you have virtual machines running that cannot be live migrated, they might block an {product-title} cluster upgrade.

modules/virt-about-workload-updates.adoc

@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * virt/upgrading-virt.adoc
+
+[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.
++
+[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.
+====
+
+** There are two available workload update methods: `LiveMigrate` and `Evict`. By default, only `LiveMigrate` is enabled, which means that:
+
+*** Virtual machine instances (VMIs) that support live migration are migrated during the upgrade process.
+
+*** VMIs are not updated at all if the following conditions are both true:
+
+**** 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

@@ -5,15 +5,15 @@
 [id="virt-configuring-workload-update-methods_{context}"]
 = Configuring workload update methods
 
-When you upgrade {VirtProductName}, virtual machine instance (VMI) workloads, such as `virt-launcher` pods, update automatically if they support live migration. You can configure workload update strategies or opt out of workload updates by editing the `HyperConverged` custom resource (CR).
+You can configure workload update methods by editing the `HyperConverged` custom resource (CR).
 
 .Prerequisites
 
 * To use live migration as an update method, you must first enable live migration in the cluster.
 +
 [NOTE]
 ====
-If a `VirtualMachineInstance` CR contains `evictionStrategy: LiveMigrate` and the VMI does not support live migration, the VMI will not update.
+If a `VirtualMachineInstance` CR contains `evictionStrategy: LiveMigrate` and the virtual machine instance (VMI) does not support live migration, the VMI will not update.
 ====
 
 .Procedure
@@ -40,11 +40,18 @@ spec:
     - Evict <3>
     batchEvictionSize: 10 <4>
     batchEvictionInterval: "1m0s" <5>
+...
 ----
-<1> The methods that can be used to perform automated workload updates. The supported values are `LiveMigrate` and `Evict`. By default, only `LiveMigrate` is enabled. If you enable both options as shown in this example, updates use `LiveMigrate` for VMIs that support live migration and `Evict` for any VMIs that do not support live migration. To disable automatic workload updates, set `workloadUpdateMethods: []` to leave the array empty.
-<2> The least disruptive update method. VMIs that support live migration are updated by migrating the virtual machine (VM) guest into a new pod with the updated components enabled. If `LiveMigrate` is the only workload update method listed, VMIs that do not support live migration are not disrupted or updated. `LiveMigrate` is enabled by default.
-<3> A disruptive method that shuts down VMI pods during upgrade. `Evict` is the only update method available if live migration is not enabled in the cluster. If a VMI is controlled by a `VirtualMachine` object that has `runStrategy: always` configured, a new VMI is created in a new pod with updated components. `Evict` is not enabled by default.
-<4> The number of VMIs that can be forced to be updated at a time. The default value is `10`.
-<5> The interval to wait before evicting the next batch of workloads. The default value is `"1m0s"`.
+<1> The methods that can be used to perform automated workload updates. The available values are `LiveMigrate` and `Evict`. If you enable both options as shown in this example, updates use `LiveMigrate` for VMIs that support live migration and `Evict` for any VMIs that do not support live migration. To disable automatic workload updates, you can either remove the `workloadUpdateStrategy` stanza or set `workloadUpdateMethods: []` to leave the array empty.
+//NOTE: in 4.10, removing the stanza will not disable the feature.
+<2> The least disruptive update method. VMIs that support live migration are updated by migrating the virtual machine (VM) guest into a new pod with the updated components enabled. If `LiveMigrate` is the only workload update method listed, VMIs that do not support live migration are not disrupted or updated.
+<3> A disruptive method that shuts down VMI pods during upgrade. `Evict` is the only update method available if live migration is not enabled in the cluster. If a VMI is controlled by a `VirtualMachine` object that has `runStrategy: always` configured, a new VMI is created in a new pod with updated components.
+<4> The number of VMIs that can be forced to be updated at a time by using the `Evict` method. This does not apply to the `LiveMigrate` method.
+<5> The interval to wait before evicting the next batch of workloads. This does not apply to the `LiveMigrate` method.
++
+[NOTE]
+====
+You can configure live migration limits and timeouts by editing the `spec.liveMigrationConfig` stanza of the `HyperConverged` CR.
+====
 
 . To apply your changes, save and exit the editor.

virt/upgrading-virt.adoc

@@ -11,16 +11,27 @@ Learn how Operator Lifecycle Manager (OLM) delivers z-stream and minor version u
 include::modules/virt-about-upgrading-virt.adoc[leveloffset=+1]
 
 [id="configuring-workload-updates_upgrading-virt"]
-== Configuring workload updates
+== Configuring automatic workload updates
 
-[NOTE]
-====
-Automatic workload updates are enabled by default in {VirtProductName} {VirtVersion}. You can opt out by following a xref:../virt/upgrading-virt.adoc#virt-opting-out-workload-updates_upgrading-virt[workaround to disable this feature] before you upgrade to {VirtVersion}.
-====
+// Uncomment this in 4.10
+//[NOTE]
+//====
+//Automatic workload updates are enabled by default in {VirtProductName} {VirtVersion}. You can opt out by following a xref:../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::modules/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-configuring-workload-update-methods.adoc[leveloffset=+2]
 
-include::modules/virt-opting-out-workload-updates.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
@@ -34,10 +45,11 @@ include::modules/virt-monitoring-upgrade-status.adoc[leveloffset=+2]
 
 include::modules/virt-viewing-outdated-workloads.adoc[leveloffset=+2]
 
-[NOTE]
-====
-xref:../virt/upgrading-virt.adoc#configuring-workload-updates_upgrading-virt[Configure workload updates] to ensure that VMIs update automatically.
-====
+// 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.
+//====
 
 [id="additional-resources_upgrading-virt"]
 == Additional resources
@@ -51,3 +63,5 @@ xref:../virt/upgrading-virt.adoc#configuring-workload-updates_upgrading-virt[Con
 * xref:../virt/live_migration/virt-live-migration.adoc#virt-live-migration[Virtual machine live migration]
 
 * xref:../virt/live_migration/virt-configuring-vmi-eviction-strategy.adoc#virt-configuring-vmi-eviction-strategy[Configuring virtual machine eviction strategy]
+
+* xref:../virt/live_migration/virt-live-migration-limits.adoc#virt-configuring-live-migration-limits_virt-live-migration-limits[Configuring live migration limits and timeouts]