[enterprise-4.18] MIG-1620: MTC VM storage migration

_topic_maps/_topic_map.yml

@@ -3803,6 +3803,8 @@ Topics:
   File: migrating-applications-with-mtc
 - Name: Advanced migration options
   File: advanced-migration-options-mtc
+- Name: Migrating virtual machine storage
+  File: mtc-migrating-vms
 - Name: Troubleshooting
   File: troubleshooting-mtc
 ---

migration_toolkit_for_containers/mtc-migrating-vms.adoc

@@ -0,0 +1,108 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="mtc-migrating-vms"]
+= Migrating virtual machine storage
+include::_attributes/common-attributes.adoc[]
+:context: mtc-migrating-vms
+
+toc::[]
+
+You can migrate virtual machine (VM) storage _offline_, when you have the VM turned off, or _online_, when the VM is running.
+
+For KubeVirt VMs, the primary use case for VM storage migration is if you want to migrate from one storage class to another. You might migrate VM storage for one of the following reasons:
+
+* You are rebalancing between different storage providers.
+* New storage is available that is better suited to the workload running inside the VM.
+
+:FeatureName: Virtual machine storage migration
+include::snippets/technology-preview.adoc[]
+
+include::modules/mtc-vm-storage-migration-process-works.adoc[leveloffset=+1]
+
+[id="mtc-supported-persistent-volumes-actions-vms_{context}"]
+== Supported persistent volume actions
+
+.Supported persistent volume actions
+[width="100%",cols="15%,15%,70%",options="header"]
+|===
+|Action
+|Supported
+|User-initiated steps
+
+|Copy
+|Yes
+a|
+* Create a new persistent volume (PV) in the same namespace.
+* Copy data from the source PV to the target PV, and change the VM definition to point to the new PV.
+** If you have the `liveMigrate` flag set, the VM migrates live.
+** If you do have the `liveMigrate` flag set, the VM shuts down, the source PV contents are copied to the target PV, and the the VM is started.
+
+|Move
+|No
+|This action is not supported.
+|===
+
+
+[id="mtc-vm-storage-prerequisites-for-migration_{context}"]
+== Prerequisites
+
+Before migrating virtual machine storage, you must install xref:../virt/install/installing-virt.adoc#installing-virt-operator_installing-virt[{VirtProductName} Operator].
+
+To support storage live migration, you need to deploy {VirtProductName} version 4.17 or later. Earlier versions of {VirtProductName} do not support live storage migration.
+
+You also need to configure `KubeVirt` to enable storage live migration according to the xref:../virt/live_migration/virt-configuring-live-migration.adoc#virt-configuring-live-migration-limits_virt-configuring-live-migration[Configuring live migration].
+
+In {VirtProductName} 4.17.0, not all the required feature gates are enabled. However, to use the storage live migration feature, you must enable the feature gate.
+
+Enable the feature gate by running the following command:
+
+[source,terminal]
+----
+$ oc annotate --overwrite -n openshift-cnv hco kubevirt-hyperconverged kubevirt.kubevirt.io/jsonpatch='[ {"op": "add", "path": "/spec/configuration/developerConfiguration/featureGates/-", "value": "VolumesUpdateStrategy"}, {"op": "add", "path": "/spec/configuration/developerConfiguration/featureGates/-", "value": "VolumeMigration"} ]'
+----
+
+[WARNING]
+====
+Red{nbsp}Hat does not support clusters with the annotation enabling this feature gate.
+
+Do not add this annotation in a production cluster, if you add that annotation you receive a cluster wide alert indicating that your cluster is no longer supported.
+====
+
+For more information about the deployments and custom resource definitions (CRDs) that the migration controller uses to manipulate the VMs, see xref:../migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc#migration-controller-options_advanced-migration-options-3-4[Migration controller options].
+
+[NOTE]
+====
+If the `mig-controller` pod starts before you install {VirtProductName}, the migration controller does not automatically see that you have the {VirtProductName} Custom Resource Definition (CRD) installed.
+
+Restart the `mig-controller` pod in the `openshift-migration` namespace after installing {VirtProductName}.
+====
+
+The following table explains that to use storage live migrations, you need to have {VirtProductName} installed. Moreover, you must use {mtc-short} CRDs and at least two storage classes. 
+
+.Storage live migration requirements 
+[width="100%",cols="50%,50%",options="header",]
+|===
+|Resource |Purpose
+|`MigCluster`
+|Represents the cluster to use when migrating the storage.
+
+|`StorageClass`
+|The storage class, ensure there are at least two storage classes.
+
+|`VirtualMachine`
+|A virtual machine definition, installed by KubeVirt.
+
+|`VirtualMachineInstance`
+|A running virtual machine, installed by KubeVirt.
+
+|`DataVolume`
+|A definition on how to populate a persistent volume (PV) with a VM disk, installed by Containerized Data Importer (CDI).
+|===
+
+
+include::modules/mtc-deploying-a-vm.adoc[leveloffset=+1]
+
+include::modules/migration-creating-migration-plan-cam.adoc[leveloffset=+1]
+
+include::modules/mtc-vm-creating-mig-plan-yaml.adoc[leveloffset=+2]
+
+include::modules/mtc-migrating-vms-known-issues.adoc[leveloffset=+1]

modules/mtc-deploying-a-vm.adoc

@@ -0,0 +1,111 @@
+// Module included in the following assemblies:
+// * migration_toolkit_for_containers/mtc-migrating-vms.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="mtc-deploying-a-vm_{context}"]
+= Deploying a virtual machine
+
+After installing and activating {VirtProductName} and Containerized Data Importer (CDI), create a namespace and deploy a virtual machine (VM).
+
+.Procedure
+
+* Deploy the YAML, which creates both a VM definition and a data volume containing the Fedora operating system. 
++
+In the following example, the namespace `mig-vm` is used and the following YAML is used to create a Fedora VM,  create and a datavolume containing the Fedora operating system:
+
++
+[source,yaml]
+----
+apiVersion: kubevirt.io/v1
+kind: VirtualMachine
+metadata:
+  name: rhel9-lime-damselfly-72
+  namespace: mig-vm # <1>
+  labels:
+    app: rhel9-lime-damselfly-72
+    kubevirt.io/dynamic-credentials-support: 'true'
+    vm.kubevirt.io/template: rhel9-server-small
+    vm.kubevirt.io/template.namespace: openshift
+    vm.kubevirt.io/template.revision: '1'
+    vm.kubevirt.io/template.version: v0.31.1
+spec:
+  dataVolumeTemplates:
+    - apiVersion: cdi.kubevirt.io/v1beta1
+      kind: DataVolume
+      metadata:
+        name: rhel9-lime-damselfly-72
+      spec:
+        sourceRef:
+          kind: DataSource
+          name: rhel9
+          namespace: openshift-virtualization-os-images
+        storage:
+          resources:
+            requests:
+              storage: 30Gi
+  running: true # <2>
+  template:
+    metadata:
+      annotations:
+        vm.kubevirt.io/flavor: small
+        vm.kubevirt.io/os: rhel9
+        vm.kubevirt.io/workload: server
+      creationTimestamp: null
+      labels:
+        kubevirt.io/domain: rhel9-lime-damselfly-72 # <3>
+        kubevirt.io/size: small
+        network.kubevirt.io/headlessService: headless
+    spec:
+      architecture: amd64
+      domain:
+        cpu:
+          cores: 1
+          sockets: 1
+          threads: 1
+        devices:
+          disks:
+            - disk:
+                bus: virtio
+              name: rootdisk
+            - disk:
+                bus: virtio
+              name: cloudinitdisk
+          interfaces:
+            - masquerade: {}
+              model: virtio
+              name: default
+          rng: {}
+        features:
+          acpi: {}
+          smm:
+            enabled: true
+        firmware:
+          bootloader:
+            efi: {}
+        machine:
+          type: pc-q35-rhel9.4.0
+        memory:
+          guest: 2Gi
+        resources: {}
+      networks:
+        - name: default
+          pod: {}
+      terminationGracePeriodSeconds: 180
+      volumes:
+        - dataVolume:
+            name: rhel9-lime-damselfly-72
+          name: rootdisk
+        - cloudInitNoCloud:
+            userData: |-
+              #cloud-config
+              user: cloud-user
+              password: password
+              chpasswd: { expire: False }
+          name: cloudinitdisk
+----
+
+<1> In this example, the namespace `mig-vm` is used.
+<2> Use `running: true` to indicate that the VM should be started after creation.
+<3> The data volume creates a persistent volume claim (PVC) called `rhel9-lime-damselfly-72`, which is the same name as the data volume.
+
+The persistent volume (PV) is populated with the operating system, and the VM is started.

modules/mtc-migrating-vms-known-issues.adoc

@@ -0,0 +1,24 @@
+// Module included in the following assemblies:
+// * migration_toolkit_for_containers/mtc-migrating-vms.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="mtc-migrating-vms-known-issues_{context}"]
+= Known issues
+
+The following known issues apply when migrating virtual machine (VM) storage: 
+
+* You can only migrate VM storage in the same namespace.
+
+[id="mtc-migrating-vms-limitations_{context}"]
+== Online migration limitations
+
+The following limitations apply to the online migration: 
+
+* The VM must be running.
+* The volume housing the disk must not have any of the following limitations:
+** Shared disks cannot be migrated live.
+** The `virtio-fs` filesystem volume cannot be migrated live.
+** LUN-to-Disk and Disk-to-LUN migrations are not supported in `libvirt`.
+** LUNs must have persistent reservations.
+** Target PV size must match the source PV size.
+* The VM must be migrated to a different node.

modules/mtc-vm-creating-mig-plan-yaml.adoc

@@ -0,0 +1,47 @@
+// Module included in the following assemblies:
+// * migration_toolkit_for_containers/mtc-migrating-vms.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="mtc-vm-creating-mig-plan-yaml_{context}"]
+= Creating the migration plan using YAML manifests
+
+You can create a migration plan using YAML. However, it is recommended to create a migration plan in the {mtc-first} web console.
+
+.Procedure
+
+. To migrate the `mig-vm` namespace, ensure that the `namespaces` field of the migration plan includes `mig-vm`.
+. Modify the contents of the migration plan by adding `mig-vm` to the namespaces.
++
+.Example migration plan YAML
++
+[source,yaml]
+----
+apiVersion: migration.openshift.io/v1alpha1
+kind: MigPlan
+metadata:
+  name: live-migrate-plan
+  namespace: openshift-migration
+spec:
+  namespaces:
+  - mig-vm # <1>
+...
+----
+<1> Add `mig-vm` to the namespaces.
+
+* To attempt a live storage migration, the `liveMigrate` field in the migration plan specification must be set to true, and `KubeVirt` must be configured, and be enabled to perform live storage migration.
++
+[source,yaml]
+----
+apiVersion: migration.openshift.io/v1alpha1
+kind: MigPlan
+metadata:
+  name: live-migrate-plan
+  namespace: openshift-migration
+spec:
+  liveMigrate: true # <2>
+  namespaces:
+...
+----
+<2> Live migration only happens during the cutover of a migration plan.
+
+Staging the migration plan skips any running virtual machines and does not sync the data. Any stopped virtual machine disks are synced.

modules/mtc-vm-storage-migration-process-works.adoc

@@ -0,0 +1,23 @@
+// Module included in the following assemblies:
+// * migration_toolkit_for_containers/mtc-migrating-vms.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="mtc-vm-storage-migration-process-works_{context}"]
+= About the virtual machine storage migration process
+
+During the migration, a `MigMigration` resource is created indicating what type of migration is happening. 
+
+The types of migration are as follows:
+
+* Stage: Stage migration copies data from the source cluster to the target cluster without stopping the application. You can run a stage migration multiple times to reduce the duration of the cutover migration.
+* Rollback:  Rolls back a completed migration.
+* Cutover: Cutover migration stops the transactions on the source cluster and moves the resources to the target cluster.
+
+The status of the `MigMigration` resource contains progress information about any live storage migrations.
+
+Any offline migrations contain the `DirectVolumeMigrationProgress` status that shows the progress of the offline migration.
+
+Each `MigMigration` creates a `DirectVolumeMigration` if the migration plan is a direct volume migration plan. 
+
+To perform a storage live migration, a direct volume migration is required. 
+