Skip to content

Commit 83d5002

Browse files
sheriff-rhsheriff-rh
authored
Merge pull request #92361 from openshift-cherrypick-robot/cherry-pick-91828-to-enterprise-4.18
2 parents 1ce55ac + 3bfee0b commit 83d5002

6 files changed

+315
-0
lines changed

‎_topic_maps/_topic_map.yml

+2
Original file line numberDiff line numberDiff line change
@@ -3803,6 +3803,8 @@ Topics:
38033803
File: migrating-applications-with-mtc
38043804
- Name: Advanced migration options
38053805
File: advanced-migration-options-mtc
3806+
- Name: Migrating virtual machine storage
3807+
File: mtc-migrating-vms
38063808
- Name: Troubleshooting
38073809
File: troubleshooting-mtc
38083810
---

‎migration_toolkit_for_containers/mtc-migrating-vms.adoc

+108
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="mtc-migrating-vms"]
3+
= Migrating virtual machine storage
4+
include::_attributes/common-attributes.adoc[]
5+
:context: mtc-migrating-vms
6+
7+
toc::[]
8+
9+
You can migrate virtual machine (VM) storage _offline_, when you have the VM turned off, or _online_, when the VM is running.
10+
11+
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:
12+
13+
* You are rebalancing between different storage providers.
14+
* New storage is available that is better suited to the workload running inside the VM.
15+
16+
:FeatureName: Virtual machine storage migration
17+
include::snippets/technology-preview.adoc[]
18+
19+
include::modules/mtc-vm-storage-migration-process-works.adoc[leveloffset=+1]
20+
21+
[id="mtc-supported-persistent-volumes-actions-vms_{context}"]
22+
== Supported persistent volume actions
23+
24+
.Supported persistent volume actions
25+
[width="100%",cols="15%,15%,70%",options="header"]
26+
|===
27+
|Action
28+
|Supported
29+
|User-initiated steps
30+
31+
|Copy
32+
|Yes
33+
a|
34+
* Create a new persistent volume (PV) in the same namespace.
35+
* Copy data from the source PV to the target PV, and change the VM definition to point to the new PV.
36+
** If you have the `liveMigrate` flag set, the VM migrates live.
37+
** 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.
38+
39+
|Move
40+
|No
41+
|This action is not supported.
42+
|===
43+
44+
45+
[id="mtc-vm-storage-prerequisites-for-migration_{context}"]
46+
== Prerequisites
47+
48+
Before migrating virtual machine storage, you must install xref:../virt/install/installing-virt.adoc#installing-virt-operator_installing-virt[{VirtProductName} Operator].
49+
50+
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.
51+
52+
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].
53+
54+
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.
55+
56+
Enable the feature gate by running the following command:
57+
58+
[source,terminal]
59+
----
60+
$ 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"} ]'
61+
----
62+
63+
[WARNING]
64+
====
65+
Red{nbsp}Hat does not support clusters with the annotation enabling this feature gate.
66+
67+
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.
68+
====
69+
70+
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].
71+
72+
[NOTE]
73+
====
74+
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.
75+
76+
Restart the `mig-controller` pod in the `openshift-migration` namespace after installing {VirtProductName}.
77+
====
78+
79+
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. 
80+
81+
.Storage live migration requirements 
82+
[width="100%",cols="50%,50%",options="header",]
83+
|===
84+
|Resource |Purpose
85+
|`MigCluster`
86+
|Represents the cluster to use when migrating the storage.
87+
88+
|`StorageClass`
89+
|The storage class, ensure there are at least two storage classes.
90+
91+
|`VirtualMachine`
92+
|A virtual machine definition, installed by KubeVirt.
93+
94+
|`VirtualMachineInstance`
95+
|A running virtual machine, installed by KubeVirt.
96+
97+
|`DataVolume`
98+
|A definition on how to populate a persistent volume (PV) with a VM disk, installed by Containerized Data Importer (CDI).
99+
|===
100+
101+
102+
include::modules/mtc-deploying-a-vm.adoc[leveloffset=+1]
103+
104+
include::modules/migration-creating-migration-plan-cam.adoc[leveloffset=+1]
105+
106+
include::modules/mtc-vm-creating-mig-plan-yaml.adoc[leveloffset=+2]
107+
108+
include::modules/mtc-migrating-vms-known-issues.adoc[leveloffset=+1]

‎modules/mtc-deploying-a-vm.adoc

+111
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
// Module included in the following assemblies:
2+
// * migration_toolkit_for_containers/mtc-migrating-vms.adoc
3+
4+
:_mod-docs-content-type: PROCEDURE
5+
[id="mtc-deploying-a-vm_{context}"]
6+
= Deploying a virtual machine
7+
8+
After installing and activating {VirtProductName} and Containerized Data Importer (CDI), create a namespace and deploy a virtual machine (VM).
9+
10+
.Procedure
11+
12+
* Deploy the YAML, which creates both a VM definition and a data volume containing the Fedora operating system.
13+
+
14+
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:
15+
16+
+
17+
[source,yaml]
18+
----
19+
apiVersion: kubevirt.io/v1
20+
kind: VirtualMachine
21+
metadata:
22+
name: rhel9-lime-damselfly-72
23+
namespace: mig-vm # <1>
24+
labels:
25+
app: rhel9-lime-damselfly-72
26+
kubevirt.io/dynamic-credentials-support: 'true'
27+
vm.kubevirt.io/template: rhel9-server-small
28+
vm.kubevirt.io/template.namespace: openshift
29+
vm.kubevirt.io/template.revision: '1'
30+
vm.kubevirt.io/template.version: v0.31.1
31+
spec:
32+
dataVolumeTemplates:
33+
- apiVersion: cdi.kubevirt.io/v1beta1
34+
kind: DataVolume
35+
metadata:
36+
name: rhel9-lime-damselfly-72
37+
spec:
38+
sourceRef:
39+
kind: DataSource
40+
name: rhel9
41+
namespace: openshift-virtualization-os-images
42+
storage:
43+
resources:
44+
requests:
45+
storage: 30Gi
46+
running: true # <2>
47+
template:
48+
metadata:
49+
annotations:
50+
vm.kubevirt.io/flavor: small
51+
vm.kubevirt.io/os: rhel9
52+
vm.kubevirt.io/workload: server
53+
creationTimestamp: null
54+
labels:
55+
kubevirt.io/domain: rhel9-lime-damselfly-72 # <3>
56+
kubevirt.io/size: small
57+
network.kubevirt.io/headlessService: headless
58+
spec:
59+
architecture: amd64
60+
domain:
61+
cpu:
62+
cores: 1
63+
sockets: 1
64+
threads: 1
65+
devices:
66+
disks:
67+
- disk:
68+
bus: virtio
69+
name: rootdisk
70+
- disk:
71+
bus: virtio
72+
name: cloudinitdisk
73+
interfaces:
74+
- masquerade: {}
75+
model: virtio
76+
name: default
77+
rng: {}
78+
features:
79+
acpi: {}
80+
smm:
81+
enabled: true
82+
firmware:
83+
bootloader:
84+
efi: {}
85+
machine:
86+
type: pc-q35-rhel9.4.0
87+
memory:
88+
guest: 2Gi
89+
resources: {}
90+
networks:
91+
- name: default
92+
pod: {}
93+
terminationGracePeriodSeconds: 180
94+
volumes:
95+
- dataVolume:
96+
name: rhel9-lime-damselfly-72
97+
name: rootdisk
98+
- cloudInitNoCloud:
99+
userData: |-
100+
#cloud-config
101+
user: cloud-user
102+
password: password
103+
chpasswd: { expire: False }
104+
name: cloudinitdisk
105+
----
106+
107+
<1> In this example, the namespace `mig-vm` is used.
108+
<2> Use `running: true` to indicate that the VM should be started after creation.
109+
<3> The data volume creates a persistent volume claim (PVC) called `rhel9-lime-damselfly-72`, which is the same name as the data volume.
110+
111+
The persistent volume (PV) is populated with the operating system, and the VM is started.

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

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
// Module included in the following assemblies:
2+
// * migration_toolkit_for_containers/mtc-migrating-vms.adoc
3+
4+
:_mod-docs-content-type: REFERENCE
5+
[id="mtc-migrating-vms-known-issues_{context}"]
6+
= Known issues
7+
8+
The following known issues apply when migrating virtual machine (VM) storage:
9+
10+
* You can only migrate VM storage in the same namespace.
11+
12+
[id="mtc-migrating-vms-limitations_{context}"]
13+
== Online migration limitations
14+
15+
The following limitations apply to the online migration:
16+
17+
* The VM must be running.
18+
* The volume housing the disk must not have any of the following limitations:
19+
** Shared disks cannot be migrated live.
20+
** The `virtio-fs` filesystem volume cannot be migrated live.
21+
** LUN-to-Disk and Disk-to-LUN migrations are not supported in `libvirt`.
22+
** LUNs must have persistent reservations.
23+
** Target PV size must match the source PV size.
24+
* The VM must be migrated to a different node.

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

+47
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
// Module included in the following assemblies:
2+
// * migration_toolkit_for_containers/mtc-migrating-vms.adoc
3+
4+
:_mod-docs-content-type: PROCEDURE
5+
[id="mtc-vm-creating-mig-plan-yaml_{context}"]
6+
= Creating the migration plan using YAML manifests
7+
8+
You can create a migration plan using YAML. However, it is recommended to create a migration plan in the {mtc-first} web console.
9+
10+
.Procedure
11+
12+
. To migrate the `mig-vm` namespace, ensure that the `namespaces` field of the migration plan includes `mig-vm`.
13+
. Modify the contents of the migration plan by adding `mig-vm` to the namespaces.
14+
+
15+
.Example migration plan YAML
16+
+
17+
[source,yaml]
18+
----
19+
apiVersion: migration.openshift.io/v1alpha1
20+
kind: MigPlan
21+
metadata:
22+
name: live-migrate-plan
23+
namespace: openshift-migration
24+
spec:
25+
namespaces:
26+
- mig-vm # <1>
27+
...
28+
----
29+
<1> Add `mig-vm` to the namespaces.
30+
31+
* 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.
32+
+
33+
[source,yaml]
34+
----
35+
apiVersion: migration.openshift.io/v1alpha1
36+
kind: MigPlan
37+
metadata:
38+
name: live-migrate-plan
39+
namespace: openshift-migration
40+
spec:
41+
liveMigrate: true # <2>
42+
namespaces:
43+
...
44+
----
45+
<2> Live migration only happens during the cutover of a migration plan.
46+
47+
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

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
// Module included in the following assemblies:
2+
// * migration_toolkit_for_containers/mtc-migrating-vms.adoc
3+
4+
:_mod-docs-content-type: REFERENCE
5+
[id="mtc-vm-storage-migration-process-works_{context}"]
6+
= About the virtual machine storage migration process
7+
8+
During the migration, a `MigMigration` resource is created indicating what type of migration is happening.
9+
10+
The types of migration are as follows:
11+
12+
* 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.
13+
* Rollback: Rolls back a completed migration.
14+
* Cutover: Cutover migration stops the transactions on the source cluster and moves the resources to the target cluster.
15+
16+
The status of the `MigMigration` resource contains progress information about any live storage migrations.
17+
18+
Any offline migrations contain the `DirectVolumeMigrationProgress` status that shows the progress of the offline migration.
19+
20+
Each `MigMigration` creates a `DirectVolumeMigration` if the migration plan is a direct volume migration plan.
21+
22+
To perform a storage live migration, a direct volume migration is required.
23+

0 commit comments

Comments
 (0)