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. Table 2.1. Default volume and access modes 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 Note If the OpenShift Virtualization storage does not support dynamic provisioning , you must apply the following settings: Filesystem volume mode Filesystem volume mode is slower than Block volume mode. ReadWriteOnce access mode ReadWriteOnce access mode does not support live virtual machine migration. See Enabling a statically-provisioned storage class for details on editing the storage profile. Note 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. Note 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: Table 2.2. Network ports required for migrating from VMware vSphere 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 Table 2.3. Network ports required for migrating from Red Hat Virtualization 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. Note Migration 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 UserRole and ReadOnlyAdmin roles assigned to you. These are the minimum required permissions, however, any other administrator or superuser permissions will also work. Important 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. DiskCreator and UserVmManager permissions 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. Note 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: USD openstack token issue The output, referred to here as <openstack_token_output> , includes the token , userID , and projectID that you need for authentication using a token with user ID. Create a Secret manifest 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> EOF For 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 Provider manifest 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: USD openstack application credential create --role member --role reader --secret redhat forklift The output, referred to here as <openstack_credential_output> , includes: The id and secret that you need for authentication using an application credential ID The name and secret that you need for authentication using an application credential name Create a Secret manifest 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 Provider manifest 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. Important 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 Note 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). Table 2.4. VMware privileges Privilege Description Virtual machine.Interaction privileges: Virtual machine.Interaction.Power Off Allows powering off a powered-on virtual machine. This operation powers down the guest operating system. Virtual machine.Interaction.Power On Allows powering on a powered-off virtual machine and resuming a suspended virtual machine. Virtual machine.Guest operating system management by VIX API Allows managing a virtual machine by the VMware VIX API. Virtual machine.Provisioning privileges: Note All Virtual machine.Provisioning privileges are required. Virtual machine.Provisioning.Allow disk access Allows opening a disk on a virtual machine for random read and write access. Used mostly for remote disk mounting. Virtual machine.Provisioning.Allow file access Allows operations on files associated with a virtual machine, including VMX, disks, logs, and NVRAM. Virtual machine.Provisioning.Allow read-only disk access Allows opening a disk on a virtual machine for random read access. Used mostly for remote disk mounting. Virtual machine.Provisioning.Allow virtual machine download Allows read operations on files associated with a virtual machine, including VMX, disks, logs, and NVRAM. Virtual machine.Provisioning.Allow virtual machine files upload Allows write operations on files associated with a virtual machine, including VMX, disks, logs, and NVRAM. Virtual machine.Provisioning.Clone template Allows cloning of a template. Virtual machine.Provisioning.Clone virtual machine Allows cloning of an existing virtual machine and allocation of resources. Virtual machine.Provisioning.Create template from virtual machine Allows creation of a new template from a virtual machine. Virtual machine.Provisioning.Customize guest Allows customization of a virtual machine's guest operating system without moving the virtual machine. Virtual machine.Provisioning.Deploy template Allows deployment of a virtual machine from a template. Virtual machine.Provisioning.Mark as template Allows marking an existing powered-off virtual machine as a template. Virtual machine.Provisioning.Mark as virtual machine Allows marking an existing template as a virtual machine. Virtual machine.Provisioning.Modify customization specification Allows creation, modification, or deletion of customization specifications. Virtual machine.Provisioning.Promote disks Allows promote operations on a virtual machine's disks. Virtual machine.Provisioning.Read customization specifications Allows reading a customization specification. Virtual machine.Snapshot management privileges: Virtual machine.Snapshot management.Create snapshot Allows creation of a snapshot from the virtual machine's current state. Virtual machine.Snapshot management.Remove Snapshot Allows removal of a snapshot from the snapshot history. Datastore privileges: Datastore.Browse datastore Allows exploring the contents of a datastore. Datastore.Low level file operations Allows performing low-level file operations - read, write, delete, and rename - in a datastore. Sessions privileges: Sessions.Validate session Allows verification of the validity of a session. Cryptographic privileges: Cryptographic.Decrypt Allows decryption of an encrypted virtual machine. Cryptographic.Direct access Allows access to encrypted resources. 2.7.1. Creating a VDDK image The Migration Toolkit for Virtualization (MTV) can use the VMware Virtual Disk Development Kit (VDDK) SDK to accelerate transferring virtual disks from VMware vSphere. Note 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). Note Storing the VDDK image in a public registry might violate the VMware license terms. Prerequisites Red Hat OpenShift image registry . podman installed. 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: USD 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 . Note 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: USD tar -xzf VMware-vix-disklib-<version>.x86_64.tar.gz Create a Dockerfile : USD 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: USD podman build . -t <registry_route_or_server_path>/vddk:<tag> Push the VDDK image to the registry: USD 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 maxMemory to 1000000000 in /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. Note 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 .ova extension. 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 /nfs is scanned. The folder /nfs/subfolder1 is scanned. But, /nfs/subfolder1/subfolder2 is 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 .ovf file in a folder. Otherwise, the migration will fail. For example, if the NFS share is, /nfs , then: The OVF file /nfs/vm.ovf is scanned. The OVF file /nfs/subfolder1/vm.ovf is scanned. The OVF file /nfs/subfolder1/subfolder2/vm.ovf is scanned. But, the OVF file /nfs/subfolder1/subfolder2/subfolder3/vm.ovf is not scanned. 2.9. Software compatibility guidelines You must install compatible software versions. Table 2.5. Compatible software versions Migration Toolkit for Virtualization Red Hat OpenShift OpenShift Virtualization VMware vSphere Red Hat Virtualization OpenStack 2.6.7 4.14 or later 4.14 or later 6.5 or later 4.4 SP1 or later 16.1 or later Migration from Red Hat Virtualization 4.3 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 .

Commands:
OS_AUTH_URL OS_PROJECT_ID OS_PROJECT_NAME OS_DOMAIN_NAME OS_USERNAME
openstack token issue
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> EOF
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
OS_AUTH_URL OS_PROJECT_ID OS_PROJECT_NAME OS_DOMAIN_NAME OS_USERNAME
openstack application credential create --role member --role reader --secret redhat forklift
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
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
mkdir /tmp/<dir_name> && cd /tmp/<dir_name>
tar -xzf VMware-vix-disklib-<version>.x86_64.tar.gz
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
podman build . -t <registry_route_or_server_path>/vddk:<tag>
podman push <registry_route_or_server_path>/vddk:<tag>
<nfcsvc> <path>libnfcsvc.so</path> <enabled>true</enabled> <maxMemory>1000000000</maxMemory> <maxStreamMemory>10485760</maxStreamMemory> </nfcsvc>
/etc/init.d/hostd restart