Chapter 2. Prerequisites
Review the following prerequisites to ensure that your environment is prepared for migration.
2.1. Software requirements
You must install compatible versions of Red Hat OpenShift and OpenShift Virtualization.
2.2. Storage support and default modes
MTV uses the following default volume and access modes for supported storage.
| Provisioner | Volume mode | Access mode |
|---|---|---|
| kubernetes.io/aws-ebs | Block | ReadWriteOnce |
| kubernetes.io/azure-disk | Block | ReadWriteOnce |
| kubernetes.io/azure-file | Filesystem | ReadWriteMany |
| kubernetes.io/cinder | Block | ReadWriteOnce |
| kubernetes.io/gce-pd | Block | ReadWriteOnce |
| kubernetes.io/hostpath-provisioner | Filesystem | ReadWriteOnce |
| manila.csi.openstack.org | Filesystem | ReadWriteMany |
| openshift-storage.cephfs.csi.ceph.com | Filesystem | ReadWriteMany |
| openshift-storage.rbd.csi.ceph.com | Block | ReadWriteOnce |
| kubernetes.io/rbd | Block | ReadWriteOnce |
| kubernetes.io/vsphere-volume | Block | ReadWriteOnce |
If the OpenShift Virtualization storage does not support dynamic provisioning, you must apply the following settings:
Filesystemvolume modeFilesystemvolume mode is slower thanBlockvolume mode.ReadWriteOnceaccess modeReadWriteOnceaccess mode does not support live virtual machine migration.
See Enabling a statically-provisioned storage class for details on editing the storage profile.
If your migration uses block storage and persistent volumes created with an EXT4 file system, increase the file system overhead in CDI to be more than 10%. The default overhead that is assumed by CDI does not completely include the reserved place for the root partition. If you do not increase the file system overhead in CDI by this amount, your migration might fail.
When migrating from OpenStack or running a cold-migration from RHV to the OCP cluster that MTV is deployed on, the migration allocates persistent volumes without CDI. In these cases, you might need to adjust the file system overhead.
If the configured file system overhead, which has a default value of 10%, is too low, the disk transfer will fail due to lack of space. In such a case, you would want to increase the file system overhead.
In some cases, however, you might want to decrease the file system overhead to reduce storage consumption.
You can change the file system overhead by changing the value of the controller_filesystem_overhead in the spec portion of the forklift-controller CR, as described in Configuring the MTV Operator.
2.3. Network prerequisites
The following prerequisites apply to all migrations:
- IP addresses, VLANs, and other network configuration settings must not be changed before or during migration. The MAC addresses of the virtual machines are preserved during migration.
- The network connections between the source environment, the OpenShift Virtualization cluster, and the replication repository must be reliable and uninterrupted.
- If you are mapping more than one source and destination network, you must create a network attachment definition for each additional destination network.
2.3.1. Ports
The firewalls must enable traffic over the following ports:
| Port | Protocol | Source | Destination | Purpose |
|---|---|---|---|---|
| 443 | TCP | OpenShift nodes | VMware vCenter | VMware provider inventory Disk transfer authentication |
| 443 | TCP | OpenShift nodes | VMware ESXi hosts | Disk transfer authentication |
| 902 | TCP | OpenShift nodes | VMware ESXi hosts | Disk transfer data copy |
| Port | Protocol | Source | Destination | Purpose |
|---|---|---|---|---|
| 443 | TCP | OpenShift nodes | RHV Engine | RHV provider inventory Disk transfer authentication |
| 443 | TCP | OpenShift nodes | RHV hosts | Disk transfer authentication |
| 54322 | TCP | OpenShift nodes | RHV hosts | Disk transfer data copy |
2.4. Source virtual machine prerequisites
The following prerequisites apply to all migrations:
- ISO/CDROM disks must be unmounted.
- Each NIC must contain one IPv4 and/or one IPv6 address.
- The VM operating system must be certified and supported for use as a guest operating system with OpenShift Virtualization.
-
VM names must contain only lowercase letters (
a-z), numbers (0-9), or hyphens (-), up to a maximum of 253 characters. The first and last characters must be alphanumeric. The name must not contain uppercase letters, spaces, periods (.), or special characters. VM names must not duplicate the name of a VM in the OpenShift Virtualization environment.
NoteMigration Toolkit for Virtualization automatically assigns a new name to a VM that does not comply with the rules.
Migration Toolkit for Virtualization makes the following changes when it automatically generates a new VM name:
- Excluded characters are removed.
- Uppercase letters are switched to lowercase letters.
-
Any underscore (
_) is changed to a dash (-).
This feature allows a migration to proceed smoothly even if someone entered a VM name that does not follow the rules.
2.5. Red Hat Virtualization prerequisites
The following prerequisites apply to Red Hat Virtualization migrations:
-
To create a source provider, you must have at least the
UserRoleandReadOnlyAdminroles assigned to you. These are the minimum required permissions, however, any other administrator or superuser permissions will also work.
You must keep the UserRole and ReadOnlyAdmin roles until the virtual machines of the source provider have been migrated. Otherwise, the migration will fail.
To migrate virtual machines:
You must have one of the following:
- RHV admin permissions. These permissions allow you to migrate any virtual machine in the system.
-
DiskCreatorandUserVmManagerpermissions on every virtual machine you want to migrate.
- You must use a compatible version of Red Hat Virtualization.
You must have the Manager CA certificate, unless it was replaced by a third-party certificate, in which case, specify the Manager Apache CA certificate.
You can obtain the Manager CA certificate by navigating to https://<engine_host>/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA in a browser.
- If you are migrating a virtual machine with a direct LUN disk, ensure that the nodes in the OpenShift Virtualization destination cluster that the VM is expected to run on can access the backend storage.
- Unlike disk images that are copied from a source provider to a target provider, LUNs are detached, but not removed, from virtual machines in the source provider and then attached to the virtual machines (VMs) that are created in the target provider.
- LUNs are not removed from the source provider during the migration in case fallback to the source provider is required. However, before re-attaching the LUNs to VMs in the source provider, ensure that the LUNs are not used by VMs on the target environment at the same time, which might lead to data corruption.
2.6. OpenStack prerequisites
The following prerequisites apply to OpenStack migrations:
- You must use a compatible version of OpenStack.
2.6.1. Additional authentication methods for migrations with OpenStack source providers
MTV versions 2.6 and later support the following authentication methods for migrations with OpenStack source providers in addition to the standard username and password credential set:
- Token authentication
- Application credential authentication
You can use these methods to migrate virtual machines with OpenStack source providers using the CLI the same way you migrate other virtual machines, except for how you prepare the Secret manifest.
2.6.1.1. Using token authentication with an OpenStack source provider
You can use token authentication, instead of username and password authentication, when you create an OpenStack source provider.
MTV supports both of the following types of token authentication:
- Token with user ID
- Token with user name
For each type of token authentication, you need to use data from OpenStack to create a Secret manifest.
Prerequisites
Have an OpenStack account.
Procedure
- In the dashboard of the OpenStack web console, click Project > API Access.
Expand Download OpenStack RC file and click OpenStack RC file.
The file that is downloaded, referred to here as
<openstack_rc_file>, includes the following fields used for token authentication:OS_AUTH_URL OS_PROJECT_ID OS_PROJECT_NAME OS_DOMAIN_NAME OS_USERNAME
To get the data needed for token authentication, run the following command:
$ openstack token issue
The output, referred to here as
<openstack_token_output>, includes thetoken,userID, andprojectIDthat you need for authentication using a token with user ID.Create a
Secretmanifest similar to the following:For authentication using a token with user ID:
cat << EOF | oc apply -f - apiVersion: v1 kind: Secret metadata: name: openstack-secret-tokenid namespace: openshift-mtv labels: createdForProviderType: openstack type: Opaque stringData: authType: token token: <token_from_openstack_token_output> projectID: <projectID_from_openstack_token_output> userID: <userID_from_openstack_token_output> url: <OS_AUTH_URL_from_openstack_rc_file> EOFFor authentication using a token with user name:
cat << EOF | oc apply -f - apiVersion: v1 kind: Secret metadata: name: openstack-secret-tokenname namespace: openshift-mtv labels: createdForProviderType: openstack type: Opaque stringData: authType: token token: <token_from_openstack_token_output> domainName: <OS_DOMAIN_NAME_from_openstack_rc_file> projectName: <OS_PROJECT_NAME_from_openstack_rc_file> username: <OS_USERNAME_from_openstack_rc_file> url: <OS_AUTH_URL_from_openstack_rc_file> EOF
-
Continue migrating your virtual machine according to the procedure in Migrating virtual machines, starting with step 2, "Create a
Providermanifest for the source provider."
2.6.1.2. Using application credential authentication with an OpenStack source provider
You can use application credential authentication, instead of username and password authentication, when you create an OpenStack source provider.
MTV supports both of the following types of application credential authentication:
- Application credential ID
- Application credential name
For each type of application credential authentication, you need to use data from OpenStack to create a Secret manifest.
Prerequisites
You have an OpenStack account.
Procedure
- In the dashboard of the OpenStack web console, click Project > API Access.
Expand Download OpenStack RC file and click OpenStack RC file.
The file that is downloaded, referred to here as
<openstack_rc_file>, includes the following fields used for application credential authentication:OS_AUTH_URL OS_PROJECT_ID OS_PROJECT_NAME OS_DOMAIN_NAME OS_USERNAME
To get the data needed for application credential authentication, run the following command:
$ openstack application credential create --role member --role reader --secret redhat forklift
The output, referred to here as
<openstack_credential_output>, includes:-
The
idandsecretthat you need for authentication using an application credential ID -
The
nameandsecretthat you need for authentication using an application credential name
-
The
Create a
Secretmanifest similar to the following:For authentication using the application credential ID:
cat << EOF | oc apply -f - apiVersion: v1 kind: Secret metadata: name: openstack-secret-appid namespace: openshift-mtv labels: createdForProviderType: openstack type: Opaque stringData: authType: applicationcredential applicationCredentialID: <id_from_openstack_credential_output> applicationCredentialSecret: <secret_from_openstack_credential_output> url: <OS_AUTH_URL_from_openstack_rc_file> EOF
For authentication using the application credential name:
cat << EOF | oc apply -f - apiVersion: v1 kind: Secret metadata: name: openstack-secret-appname namespace: openshift-mtv labels: createdForProviderType: openstack type: Opaque stringData: authType: applicationcredential applicationCredentialName: <name_from_openstack_credential_output> applicationCredentialSecret: <secret_from_openstack_credential_output> domainName: <OS_DOMAIN_NAME_from_openstack_rc_file> username: <OS_USERNAME_from_openstack_rc_file> url: <OS_AUTH_URL_from_openstack_rc_file> EOF
-
Continue migrating your virtual machine according to the procedure in Migrating virtual machines, starting with step 2, "Create a
Providermanifest for the source provider."
2.7. VMware prerequisites
It is strongly recommended to create a VDDK image to accelerate migrations. For more information, see Creating a VDDK image.
The following prerequisites apply to VMware migrations:
- You must use a compatible version of VMware vSphere.
- You must be logged in as a user with at least the minimal set of VMware privileges.
- To access the virtual machine using a pre-migration hook, VMware Tools must be installed on the source virtual machine.
-
The VM operating system must be certified and supported for use as a guest operating system with OpenShift Virtualization and for conversion to KVM with
virt-v2v. - If you are running a warm migration, you must enable changed block tracking (CBT) on the VMs and on the VM disks.
- If you are migrating more than 10 VMs from an ESXi host in the same migration plan, you must increase the NFC service memory of the host.
- It is strongly recommended to disable hibernation because Migration Toolkit for Virtualization (MTV) does not support migrating hibernated VMs.
In the event of a power outage, data might be lost for a VM with disabled hibernation. However, if hibernation is not disabled, migration will fail
Neither MTV nor OpenShift Virtualization support conversion of Btrfs for migrating VMs from VMWare.
VMware privileges
The following minimal set of VMware privileges is required to migrate virtual machines to OpenShift Virtualization with the Migration Toolkit for Virtualization (MTV).
| Privilege | Description |
|---|---|
|
| |
|
| Allows powering off a powered-on virtual machine. This operation powers down the guest operating system. |
|
| Allows powering on a powered-off virtual machine and resuming a suspended virtual machine. |
|
Note
All | |
|
| Allows opening a disk on a virtual machine for random read and write access. Used mostly for remote disk mounting. |
|
| Allows operations on files associated with a virtual machine, including VMX, disks, logs, and NVRAM. |
|
| Allows opening a disk on a virtual machine for random read access. Used mostly for remote disk mounting. |
|
| Allows read operations on files associated with a virtual machine, including VMX, disks, logs, and NVRAM. |
|
| Allows write operations on files associated with a virtual machine, including VMX, disks, logs, and NVRAM. |
|
| Allows cloning of a template. |
|
| Allows cloning of an existing virtual machine and allocation of resources. |
|
| Allows creation of a new template from a virtual machine. |
|
| Allows customization of a virtual machine’s guest operating system without moving the virtual machine. |
|
| Allows deployment of a virtual machine from a template. |
|
| Allows marking an existing powered-off virtual machine as a template. |
|
| Allows marking an existing template as a virtual machine. |
|
| Allows creation, modification, or deletion of customization specifications. |
|
| Allows promote operations on a virtual machine’s disks. |
|
| Allows reading a customization specification. |
|
| |
|
| Allows creation of a snapshot from the virtual machine’s current state. |
|
| Allows removal of a snapshot from the snapshot history. |
2.7.1. Creating a VDDK image
The Migration Toolkit for Virtualization (MTV) uses the VMware Virtual Disk Development Kit (VDDK) SDK to accelerate transferring virtual disks from VMware vSphere. Therefore, creating a VDDK image, although optional, is highly recommended.
To make use of this feature, you download the VMware Virtual Disk Development Kit (VDDK), build a VDDK image, and push the VDDK image to your image registry.
The VDDK package contains symbolic links, therefore, the procedure of creating a VDDK image must be performed on a file system that preserves symbolic links (symlinks).
Storing the VDDK image in a public registry might violate the VMware license terms.
Prerequisites
- Red Hat OpenShift image registry.
-
podmaninstalled. - You are working on a file system that preserves symbolic links (symlinks).
- If you are using an external registry, OpenShift Virtualization must be able to access it.
Procedure
Create and navigate to a temporary directory:
$ mkdir /tmp/<dir_name> && cd /tmp/<dir_name>
- In a browser, navigate to the VMware VDDK version 8 download page.
- Select version 8.0.1 and click Download.
In order to migrate to OpenShift Virtualization 4.12, download VDDK version 7.0.3.2 from the VMware VDDK version 7 download page.
- Save the VDDK archive file in the temporary directory.
Extract the VDDK archive:
$ tar -xzf VMware-vix-disklib-<version>.x86_64.tar.gz
Create a
Dockerfile:$ cat > Dockerfile <<EOF FROM registry.access.redhat.com/ubi8/ubi-minimal USER 1001 COPY vmware-vix-disklib-distrib /vmware-vix-disklib-distrib RUN mkdir -p /opt ENTRYPOINT ["cp", "-r", "/vmware-vix-disklib-distrib", "/opt"] EOF
Build the VDDK image:
$ podman build . -t <registry_route_or_server_path>/vddk:<tag>
Push the VDDK image to the registry:
$ podman push <registry_route_or_server_path>/vddk:<tag>
- Ensure that the image is accessible to your OpenShift Virtualization environment.
2.7.2. Increasing the NFC service memory of an ESXi host
If you are migrating more than 10 VMs from an ESXi host in the same migration plan, you must increase the NFC service memory of the host. Otherwise, the migration will fail because the NFC service memory is limited to 10 parallel connections.
Procedure
- Log in to the ESXi host as root.
Change the value of
maxMemoryto1000000000in/etc/vmware/hostd/config.xml:... <nfcsvc> <path>libnfcsvc.so</path> <enabled>true</enabled> <maxMemory>1000000000</maxMemory> <maxStreamMemory>10485760</maxStreamMemory> </nfcsvc> ...Restart
hostd:# /etc/init.d/hostd restart
You do not need to reboot the host.
2.8. Open Virtual Appliance (OVA) prerequisites
The following prerequisites apply to Open Virtual Appliance (OVA) file migrations:
- All OVA files are created by VMware vSphere.
Migration of OVA files that were not created by VMware vSphere but are compatible with vSphere might succeed. However, migration of such files is not supported by MTV. MTV supports only OVA files created by VMware vSphere.
The OVA files are in one or more folders under an NFS shared directory in one of the following structures:
In one or more compressed Open Virtualization Format (OVF) packages that hold all the VM information.
The filename of each compressed package must have the
.ovaextension. Several compressed packages can be stored in the same folder.When this structure is used, MTV scans the root folder and the first-level subfolders for compressed packages.
For example, if the NFS share is,
/nfs, then:
The folder/nfsis scanned.
The folder/nfs/subfolder1is scanned.
But,/nfs/subfolder1/subfolder2is not scanned.In extracted OVF packages.
When this structure is used, MTV scans the root folder, first-level subfolders, and second-level subfolders for extracted OVF packages. However, there can be only one
.ovffile in a folder. Otherwise, the migration will fail.For example, if the NFS share is,
/nfs, then:
The OVF file/nfs/vm.ovfis scanned.
The OVF file/nfs/subfolder1/vm.ovfis scanned.
The OVF file/nfs/subfolder1/subfolder2/vm.ovfis scanned.
But, the OVF file/nfs/subfolder1/subfolder2/subfolder3/vm.ovfis not scanned.
2.9. Software compatibility guidelines
You must install compatible software versions.
| Migration Toolkit for Virtualization | Red Hat OpenShift | OpenShift Virtualization | VMware vSphere | Red Hat Virtualization | OpenStack |
|---|---|---|---|---|---|
| 2.6.2 | 4.14 or later | 4.14 or later | 6.5 or later | 4.4 SP1 or later | 16.1 or later |
MTV 2.6 was tested only with Red Hat Virtualization (RHV) 4.4 SP1. Migration from Red Hat Virtualization (RHV) 4.3 has not been tested with MTV 2.6. While not supported, basic migrations from RHV 4.3 are expected to work.
As RHV 4.3 lacks the improvements that were introduced in RHV 4.4 for MTV, and new features were not tested with RHV 4.3, migrations from RHV 4.3 may not function at the same level as migrations from RHV 4.4, with some functionality may be missing.
Therefore, it is recommended to upgrade RHV to the supported version above before the migration to OpenShift Virtualization.
However, migrations from RHV 4.3.11 were tested with MTV 2.3, and may work in practice in many environments using MTV 2.6. In this case, we advise upgrading Red Hat Virtualization Manager (RHVM) to the previously mentioned supported version before the migration to OpenShift Virtualization.
2.9.1. OpenShift Operator Life Cycles
For more information about the software maintenance Life Cycle classifications for Operators shipped by Red Hat for use with OpenShift Container Platform, see OpenShift Operator Life Cycles.
