Merge pull request #64579 from apinnick/CNV-24272-live-migration-improvements

CNV- 24272: Live migration improvements

Author: apinnick

_topic_maps/_topic_map.yml

@@ -2721,7 +2721,7 @@ Topics:
   Dir: application_backup_and_restore
   Topics:
   - Name: Introduction to OpenShift API for Data Protection
-    File: oadp-intro         
+    File: oadp-intro
   - Name: OADP release notes
     File: oadp-release-notes
   - Name: OADP features and plugins
@@ -3759,7 +3759,6 @@ Topics:
       File: virt-high-availability-for-vms
     - Name: Control plane tuning
       File: virt-vm-control-plane-tuning
-#A BETTER NAME THAN 'STORAGE 4 U'
   - Name: VM disks
     Dir: virtual_disks
     Topics:
@@ -3819,29 +3818,23 @@ Topics:
 - Name: Live migration
   Dir: live_migration
   Topics:
-  - Name: Virtual machine live migration
-    File: virt-live-migration
-  - Name: Live migration limits and timeouts
-    File: virt-live-migration-limits
-  - Name: Migrating a virtual machine instance to another node
-    File: virt-migrate-vmi
-  - Name: Cancelling the live migration of a virtual machine instance
-    File: virt-cancel-vmi-migration
-  - Name: Configuring virtual machine eviction strategy
-    File: virt-configuring-vmi-eviction-strategy
-  - Name: Configuring live migration policies
-    File: virt-configuring-live-migration-policies
+  - Name: About live migration
+    File: virt-about-live-migration
+  - Name: Configuring live migration
+    File: virt-configuring-live-migration
+  - Name: Initiating and canceling live migration
+    File: virt-initiating-live-migration
 # Node maintenance mode
 - Name: Nodes
   Dir: nodes
   Topics:
-  - Name: About node maintenance
-    File: virt-about-node-maintenance
+  - Name: Node maintenance
+    File: virt-node-maintenance
   - Name: Managing node labeling for obsolete CPU models
     File: virt-managing-node-labeling-obsolete-cpu-models
   - Name: Preventing node reconciliation
     File: virt-preventing-node-reconciliation
-  - Name: Deleting a failed node to trigger virtual machine failover
+  - Name: Deleting a failed node to trigger VM failover
     File: virt-triggering-vm-failover-resolving-failed-node
 - Name: Monitoring
   Dir: monitoring

modules/virt-about-live-migration.adoc

@@ -1,12 +1,12 @@
 // Module included in the following assemblies:
 //
-// * virt/live_migration/virt-cancel-vmi-migration.adoc
+// * virt/live_migration/virt-initiating-live-migration.adoc
 
 :_content-type: PROCEDURE
-[id="virt-cancelling-vm-migration-cli_{context}"]
-= Cancelling live migration of a virtual machine instance in the CLI
+[id="virt-canceling-vm-migration-cli_{context}"]
+= Canceling live migration by using the command line
 
-Cancel the live migration of a virtual machine instance by deleting the
+Cancel the live migration of a virtual machine by deleting the
 `VirtualMachineInstanceMigration` object associated with the migration.
 
 .Procedure

modules/virt-about-node-maintenance.adoc

@@ -0,0 +1,15 @@
+// Module included in the following assemblies:
+//
+// * virt/live_migration/virt-initiating-live-migration.adoc
+
+:_content-type: PROCEDURE
+[id="virt-canceling-vm-migration-web_{context}"]
+= Canceling live migration by using the web console
+
+You can cancel the live migration of a virtual machine (VM) by using the {product-title} web console.
+
+.Procedure
+
+. Navigate to *Virtualization* -> *VirtualMachines* in the web console.
+. Select *Cancel Migration* on the Options menu {kebab} beside a VM.
+

modules/virt-about-runstrategies-vms.adoc

@@ -1,45 +1,36 @@
 // Module included in the following assemblies:
 //
-// * virt/live_migration/virt-configuring-live-migration-policies.adoc
-
+// * virt/live_migration/virt-configuring-live-migration.adoc
 
 :_content-type: PROCEDURE
 [id="virt-configuring-a-live-migration-policy_{context}"]
-= Configuring a live migration policy from the command line
-
-Use the `MigrationPolicy` custom resource definition (CRD) to define migration policies for one or more groups of selected virtual machine instances (VMIs).
+= Creating a live migration policy by using the command line
 
-You can specify groups of VMIs by using any combination of the following:
+You can create a live migration policy by using the command line. A live migration policy is applied to selected virtual machines (VMs) by using any combination of labels:
 
-* Virtual machine instance labels such as `size`, `os`, `gpu`, and other VMI labels.
-* Namespace labels such as `priority`, `bandwidth`, `hpc-workload`, and other namespace labels.
+* VM labels such as `size`, `os`, or `gpu`
+* Project labels such as `priority`, `bandwidth`, or `hpc-workload`
 
-For the policy to apply to a specific group of VMIs, all labels on the group of VMIs must match the labels in the policy.
+For the policy to apply to a specific group of VMs, all labels on the group of VMs must match the labels of the policy.
 
 [NOTE]
 ====
-If multiple live migration policies apply to a VMI, the policy with the highest number of matching labels takes precedence. If multiple policies meet this criteria, the policies are sorted by lexicographic order of the matching labels keys, and the first one in that order takes precedence.
+If multiple live migration policies apply to a VM, the policy with the greatest number of matching labels takes precedence.
+
+If multiple policies meet this criteria, the policies are sorted by alphabetical order of the matching label keys, and the first one in that order takes precedence.
 ====
 
 .Procedure
 
-. Create a `MigrationPolicy` CRD for your specified group of VMIs. The following example YAML configures a group with the labels `hpc-workloads:true`, `xyz-workloads-type: ""`, `workload-type: db`, and `operating-system: ""`:
-
+. Create a `MigrationPolicy` object as in the following example:
 +
 [source,yaml]
 ----
-apiVersion: migrations.kubevirt.io/v1beta1
+apiVersion: migrations.kubevirt.io/v1alpha1
 kind: MigrationPolicy
 metadata:
-  name: my-awesome-policy
+  name: <migration_policy>
 spec:
-  # Migration Configuration
-  allowAutoConverge: true
-  bandwidthPerMigration: 217Ki
-  completionTimeoutPerGiB: 23
-  allowPostCopy: false
-
-  # Matching to VMIs
   selectors:
     namespaceSelector: <1>
       hpc-workloads: "True"
@@ -48,5 +39,12 @@ spec:
       workload-type: "db"
       operating-system: ""
 ----
-<1> Use `namespaceSelector` to define a group of VMIs by using namespace labels.
-<2> Use `virtualMachineInstanceSelector` to define a group of VMIs by using VMI labels.
+<1> Specify project labels.
+<2> Specify VM labels.
+
+. Create the migration policy by running the following command:
++
+[source,terminal]
+----
+$ oc create migrationpolicy -f <migration_policy>.yaml
+----

modules/virt-cancelling-vm-migration-cli.adoc renamed to modules/virt-canceling-vm-migration-cli.adoc

@@ -0,0 +1,33 @@
+// Module included in the following assemblies:
+//
+// * virt/nodes/virt-node-maintenance.adoc
+
+:_content-type: PROCEDURE
+[id="virt-configuring-cluster-eviction-strategy-cli_{context}"]
+= Configuring a cluster eviction strategy by using the command line
+
+You can configure an eviction strategy for a cluster by using the command line.
+
+.Procedure
+
+. Edit the `hyperconverged` resource by running the following command:
++
+[source,terminal,subs="attributes+"]
+----
+$ oc edit hyperconverged kubevirt-hyperconverged -n {CNVNamespace}
+----
+
+. Set the cluster eviction strategy as shown in the following example:
++
+.Example cluster eviction strategy
+[source,yaml]
+----
+apiVersion: hco.kubevirt.io/v1beta1
+kind: HyperConverged
+metadata:
+  name: kubevirt-hyperconverged
+spec:
+  evictionStrategy: LiveMigrate
+# ...
+----
+

modules/virt-canceling-vm-migration-web.adoc

@@ -1,7 +1,7 @@
 
 // Module included in the following assemblies:
 //
-// * virt/live_migration/virt-live-migration-limits.adoc
+// * virt/live_migration/virt-configuring-live-migration.adoc
 
 :_content-type: PROCEDURE
 [id="virt-configuring-live-migration-limits_{context}"]
@@ -12,7 +12,7 @@ Configure live migration limits and timeouts for the cluster by updating the `Hy
 
 .Procedure
 
-* Edit the `HyperConverged` CR and add the necessary live migration parameters.
+* Edit the `HyperConverged` CR and add the necessary live migration parameters:
 +
 [source,terminal,subs="attributes+"]
 ----
@@ -28,15 +28,19 @@ metadata:
   name: kubevirt-hyperconverged
   namespace: {CNVNamespace}
 spec:
-  liveMigrationConfig: <1>
-    bandwidthPerMigration: 64Mi
-    completionTimeoutPerGiB: 800
-    parallelMigrationsPerCluster: 5
-    parallelOutboundMigrationsPerNode: 2
-    progressTimeout: 150
+  liveMigrationConfig:
+    bandwidthPerMigration: 64Mi <1>
+    completionTimeoutPerGiB: 800 <2>
+    parallelMigrationsPerCluster: 5 <3>
+    parallelOutboundMigrationsPerNode: 2 <4>
+    progressTimeout: 150 <5>
 ----
-<1> In this example, the `spec.liveMigrationConfig` array contains the default values for each field.
-+
+<1> Bandwidth limit of each migration, in MiB/s or GiB/s. Default: `0`, which is unlimited.
+<2> The migration is canceled if it has not completed in this time, in seconds per GiB of memory. For example, a VM with 6GiB memory times out if it has not completed migration in 4800 seconds. If the `Migration Method` is `BlockMigration`, the size of the migrating disks is included in the calculation.
+<3> Number of migrations running in parallel in the cluster. Default: `5`.
+<4> Maximum number of outbound migrations per node. Default: `2`.
+<5> The migration is canceled if memory copy fails to make progress in this time, in seconds. Default: `150`.
+
 [NOTE]
 ====
 You can restore the default value for any `spec.liveMigrationConfig` field by deleting that key/value pair and saving the file. For example, delete `progressTimeout: <value>` to restore the default `progressTimeout: 150`.