Installing and using the Migration Toolkit for Virtualization

Procedure

1. Create and navigate to a temporary directory:

   Copy to Clipboard Toggle word wrap

   $ mkdir /tmp/<dir_name> && cd /tmp/<dir_name>

2. In a browser, navigate to the VMware VDDK version 8 download page.

3. Select version 8.0.1 and click Download.

   Note

   In order to migrate to OpenShift Virtualization 4.12 or earlier, download VDDK version 7.0.3.2 from VMware VDDK version 7 download page.

4. Save the VDDK archive file in the temporary directory.

5. Extract the VDDK archive:

   Copy to Clipboard Toggle word wrap

   $ tar -xzf VMware-vix-disklib-<version>.x86_64.tar.gz

6. Create a Dockerfile:

   Copy to Clipboard Toggle word wrap

   $ 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

7. Build the VDDK image:

   Copy to Clipboard Toggle word wrap

   $ podman build . -t <registry_route_or_server_path>/vddk:<tag>

8. Push the VDDK image to the registry:

   Copy to Clipboard Toggle word wrap

   $ podman push <registry_route_or_server_path>/vddk:<tag>

9. Ensure that the image is accessible to your OpenShift Virtualization environment.

Procedure

1. Log in to the ESXi host as root.

2. Change the value of maxMemory to 1000000000 in /etc/vmware/hostd/config.xml:

   Copy to Clipboard Toggle word wrap

   ...
         <nfcsvc>
            <path>libnfcsvc.so</path>
            <enabled>true</enabled>
            <maxMemory>1000000000</maxMemory>
            <maxStreamMemory>10485760</maxStreamMemory>
         </nfcsvc>
   ...

3. Restart hostd:

   Copy to Clipboard Toggle word wrap

   # /etc/init.d/hostd restart

   You do not need to reboot the host.

Procedure

1. Connect to the terminal of the Validation pod:

   Copy to Clipboard Toggle word wrap

   $ oc rsh <validation_pod>

2. Go to the OPA policies directory for your provider:

   Copy to Clipboard Toggle word wrap

   $ cd /usr/share/opa/policies/io/konveyor/forklift/<provider> 

   1

   1

   Specify vmware or ovirt.

3. Search for the default policies:

   Copy to Clipboard Toggle word wrap

   $ grep -R "default" *

Procedure

1. Retrieve the routes for the project:

   Copy to Clipboard Toggle word wrap

   oc get route -n openshift-mtv

2. Retrieve the Inventory service route:

   Copy to Clipboard Toggle word wrap

   $ oc get route <inventory_service> -n openshift-mtv

3. Retrieve the access token:

   Copy to Clipboard Toggle word wrap

   $ TOKEN=$(oc whoami -t)

4. Trigger an HTTP GET request (for example, using Curl):

   Copy to Clipboard Toggle word wrap

   $ curl -H "Authorization: Bearer $TOKEN" https://<inventory_service_route>/providers -k

5. Retrieve the UUID of a provider:

   Copy to Clipboard Toggle word wrap

   $ curl -H "Authorization: Bearer $TOKEN"  https://<inventory_service_route>/providers/<provider> -k 

   1

   1

   Allowed values for the provider are vsphere, ovirt, and openstack.

6. Retrieve the VMs of a provider:

   Copy to Clipboard Toggle word wrap

   $ curl -H "Authorization: Bearer $TOKEN"  https://<inventory_service_route>/providers/<provider>/<UUID>/vms -k

7. Retrieve the details of a VM:

   Copy to Clipboard Toggle word wrap

   $ curl -H "Authorization: Bearer $TOKEN"  https://<inventory_service_route>/providers/<provider>/<UUID>/workloads/<vm> -k

   Example output

   Copy to Clipboard Toggle word wrap

   {
       "input": {
           "selfLink": "providers/vsphere/c872d364-d62b-46f0-bd42-16799f40324e/workloads/vm-431",
           "id": "vm-431",
           "parent": {
               "kind": "Folder",
               "id": "group-v22"
           },
           "revision": 1,
           "name": "iscsi-target",
           "revisionValidated": 1,
           "isTemplate": false,
           "networks": [
               {
                   "kind": "Network",
                   "id": "network-31"
               },
               {
                   "kind": "Network",
                   "id": "network-33"
               }
           ],
           "disks": [
               {
                   "key": 2000,
                   "file": "[iSCSI_Datastore] iscsi-target/iscsi-target-000001.vmdk",
                   "datastore": {
                       "kind": "Datastore",
                       "id": "datastore-63"
                   },
                   "capacity": 17179869184,
                   "shared": false,
                   "rdm": false
               },
               {
                   "key": 2001,
                   "file": "[iSCSI_Datastore] iscsi-target/iscsi-target_1-000001.vmdk",
                   "datastore": {
                       "kind": "Datastore",
                       "id": "datastore-63"
                   },
                   "capacity": 10737418240,
                   "shared": false,
                   "rdm": false
               }
           ],
           "concerns": [],
           "policyVersion": 5,
           "uuid": "42256329-8c3a-2a82-54fd-01d845a8bf49",
           "firmware": "bios",
           "powerState": "poweredOn",
           "connectionState": "connected",
           "snapshot": {
               "kind": "VirtualMachineSnapshot",
               "id": "snapshot-3034"
           },
           "changeTrackingEnabled": false,
           "cpuAffinity": [
               0,
               2
           ],
           "cpuHotAddEnabled": true,
           "cpuHotRemoveEnabled": false,
           "memoryHotAddEnabled": false,
           "faultToleranceEnabled": false,
           "cpuCount": 2,
           "coresPerSocket": 1,
           "memoryMB": 2048,
           "guestName": "Red Hat Enterprise Linux 7 (64-bit)",
           "balloonedMemory": 0,
           "ipAddress": "10.19.2.96",
           "storageUsed": 30436770129,
           "numaNodeAffinity": [
               "0",
               "1"
           ],
           "devices": [
               {
                   "kind": "RealUSBController"
               }
           ],
           "host": {
               "id": "host-29",
               "parent": {
                   "kind": "Cluster",
                   "id": "domain-c26"
               },
               "revision": 1,
               "name": "IP address or host name of the vCenter host or RHV Engine host",
               "selfLink": "providers/vsphere/c872d364-d62b-46f0-bd42-16799f40324e/hosts/host-29",
               "status": "green",
               "inMaintenance": false,
               "managementServerIp": "10.19.2.96",
               "thumbprint": <thumbprint>,
               "timezone": "UTC",
               "cpuSockets": 2,
               "cpuCores": 16,
               "productName": "VMware ESXi",
               "productVersion": "6.5.0",
               "networking": {
                   "pNICs": [
                       {
                           "key": "key-vim.host.PhysicalNic-vmnic0",
                           "linkSpeed": 10000
                       },
                       {
                           "key": "key-vim.host.PhysicalNic-vmnic1",
                           "linkSpeed": 10000
                       },
                       {
                           "key": "key-vim.host.PhysicalNic-vmnic2",
                           "linkSpeed": 10000
                       },
                       {
                           "key": "key-vim.host.PhysicalNic-vmnic3",
                           "linkSpeed": 10000
                       }
                   ],
                   "vNICs": [
                       {
                           "key": "key-vim.host.VirtualNic-vmk2",
                           "portGroup": "VM_Migration",
                           "dPortGroup": "",
                           "ipAddress": "192.168.79.13",
                           "subnetMask": "255.255.255.0",
                           "mtu": 9000
                       },
                       {
                           "key": "key-vim.host.VirtualNic-vmk0",
                           "portGroup": "Management Network",
                           "dPortGroup": "",
                           "ipAddress": "10.19.2.13",
                           "subnetMask": "255.255.255.128",
                           "mtu": 1500
                       },
                       {
                           "key": "key-vim.host.VirtualNic-vmk1",
                           "portGroup": "Storage Network",
                           "dPortGroup": "",
                           "ipAddress": "172.31.2.13",
                           "subnetMask": "255.255.0.0",
                           "mtu": 1500
                       },
                       {
                           "key": "key-vim.host.VirtualNic-vmk3",
                           "portGroup": "",
                           "dPortGroup": "dvportgroup-48",
                           "ipAddress": "192.168.61.13",
                           "subnetMask": "255.255.255.0",
                           "mtu": 1500
                       },
                       {
                           "key": "key-vim.host.VirtualNic-vmk4",
                           "portGroup": "VM_DHCP_Network",
                           "dPortGroup": "",
                           "ipAddress": "10.19.2.231",
                           "subnetMask": "255.255.255.128",
                           "mtu": 1500
                       }
                   ],
                   "portGroups": [
                       {
                           "key": "key-vim.host.PortGroup-VM Network",
                           "name": "VM Network",
                           "vSwitch": "key-vim.host.VirtualSwitch-vSwitch0"
                       },
                       {
                           "key": "key-vim.host.PortGroup-Management Network",
                           "name": "Management Network",
                           "vSwitch": "key-vim.host.VirtualSwitch-vSwitch0"
                       },
                       {
                           "key": "key-vim.host.PortGroup-VM_10G_Network",
                           "name": "VM_10G_Network",
                           "vSwitch": "key-vim.host.VirtualSwitch-vSwitch1"
                       },
                       {
                           "key": "key-vim.host.PortGroup-VM_Storage",
                           "name": "VM_Storage",
                           "vSwitch": "key-vim.host.VirtualSwitch-vSwitch1"
                       },
                       {
                           "key": "key-vim.host.PortGroup-VM_DHCP_Network",
                           "name": "VM_DHCP_Network",
                           "vSwitch": "key-vim.host.VirtualSwitch-vSwitch1"
                       },
                       {
                           "key": "key-vim.host.PortGroup-Storage Network",
                           "name": "Storage Network",
                           "vSwitch": "key-vim.host.VirtualSwitch-vSwitch1"
                       },
                       {
                           "key": "key-vim.host.PortGroup-VM_Isolated_67",
                           "name": "VM_Isolated_67",
                           "vSwitch": "key-vim.host.VirtualSwitch-vSwitch2"
                       },
                       {
                           "key": "key-vim.host.PortGroup-VM_Migration",
                           "name": "VM_Migration",
                           "vSwitch": "key-vim.host.VirtualSwitch-vSwitch2"
                       }
                   ],
                   "switches": [
                       {
                           "key": "key-vim.host.VirtualSwitch-vSwitch0",
                           "name": "vSwitch0",
                           "portGroups": [
                               "key-vim.host.PortGroup-VM Network",
                               "key-vim.host.PortGroup-Management Network"
                           ],
                           "pNICs": [
                               "key-vim.host.PhysicalNic-vmnic4"
                           ]
                       },
                       {
                           "key": "key-vim.host.VirtualSwitch-vSwitch1",
                           "name": "vSwitch1",
                           "portGroups": [
                               "key-vim.host.PortGroup-VM_10G_Network",
                               "key-vim.host.PortGroup-VM_Storage",
                               "key-vim.host.PortGroup-VM_DHCP_Network",
                               "key-vim.host.PortGroup-Storage Network"
                           ],
                           "pNICs": [
                               "key-vim.host.PhysicalNic-vmnic2",
                               "key-vim.host.PhysicalNic-vmnic0"
                           ]
                       },
                       {
                           "key": "key-vim.host.VirtualSwitch-vSwitch2",
                           "name": "vSwitch2",
                           "portGroups": [
                               "key-vim.host.PortGroup-VM_Isolated_67",
                               "key-vim.host.PortGroup-VM_Migration"
                           ],
                           "pNICs": [
                               "key-vim.host.PhysicalNic-vmnic3",
                               "key-vim.host.PhysicalNic-vmnic1"
                           ]
                       }
                   ]
               },
               "networks": [
                   {
                       "kind": "Network",
                       "id": "network-31"
                   },
                   {
                       "kind": "Network",
                       "id": "network-34"
                   },
                   {
                       "kind": "Network",
                       "id": "network-57"
                   },
                   {
                       "kind": "Network",
                       "id": "network-33"
                   },
                   {
                       "kind": "Network",
                       "id": "dvportgroup-47"
                   }
               ],
               "datastores": [
                   {
                       "kind": "Datastore",
                       "id": "datastore-35"
                   },
                   {
                       "kind": "Datastore",
                       "id": "datastore-63"
                   }
               ],
               "vms": null,
               "networkAdapters": [],
               "cluster": {
                   "id": "domain-c26",
                   "parent": {
                       "kind": "Folder",
                       "id": "group-h23"
                   },
                   "revision": 1,
                   "name": "mycluster",
                   "selfLink": "providers/vsphere/c872d364-d62b-46f0-bd42-16799f40324e/clusters/domain-c26",
                   "folder": "group-h23",
                   "networks": [
                       {
                           "kind": "Network",
                           "id": "network-31"
                       },
                       {
                           "kind": "Network",
                           "id": "network-34"
                       },
                       {
                           "kind": "Network",
                           "id": "network-57"
                       },
                       {
                           "kind": "Network",
                           "id": "network-33"
                       },
                       {
                           "kind": "Network",
                           "id": "dvportgroup-47"
                       }
                   ],
                   "datastores": [
                       {
                           "kind": "Datastore",
                           "id": "datastore-35"
                       },
                       {
                           "kind": "Datastore",
                           "id": "datastore-63"
                       }
                   ],
                   "hosts": [
                       {
                           "kind": "Host",
                           "id": "host-44"
                       },
                       {
                           "kind": "Host",
                           "id": "host-29"
                       }
                   ],
                   "dasEnabled": false,
                   "dasVms": [],
                   "drsEnabled": true,
                   "drsBehavior": "fullyAutomated",
                   "drsVms": [],
                   "datacenter": null
               }
           }
       }
   }

Procedure

1. Create a config map CR according to the following example:

   Copy to Clipboard Toggle word wrap

   $ cat << EOF | oc apply -f -
   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: <forklift-validation-config>
     namespace: openshift-mtv
   data:
     vmware_multiple_disks.rego: |-
       package <provider_package> 

   1

   
   
       has_multiple_disks { 

   2

   
         count(input.disks) > 1
       }
   
       concerns[flag] {
         has_multiple_disks 

   3

   
           flag := {
             "category": "<Information>", 

   4

   
             "label": "Multiple disks detected",
             "assessment": "Multiple disks detected on this VM."
           }
       }
   EOF

   1

   Specify the provider package name. Allowed values are io.konveyor.forklift.vmware for VMware and io.konveyor.forklift.ovirt for Red Hat Virtualization.

   2

   Specify the concerns name and Rego query.

   3

   Specify the concerns name and flag parameter values.

   4

   Allowed values are Critical, Warning, and Information.

2. Stop the Validation pod by scaling the forklift-controller deployment to 0:

   Copy to Clipboard Toggle word wrap

   $ oc scale -n openshift-mtv --replicas=0 deployment/forklift-controller

3. Start the Validation pod by scaling the forklift-controller deployment to 1:

   Copy to Clipboard Toggle word wrap

   $ oc scale -n openshift-mtv --replicas=1 deployment/forklift-controller

4. Check the Validation pod log to verify that the pod started:

   Copy to Clipboard Toggle word wrap

   $ oc logs -f <validation_pod>

   If the custom rule conflicts with a default rule, the Validation pod will not start.

5. Remove the source provider:

   Copy to Clipboard Toggle word wrap

   $ oc delete provider <provider> -n openshift-mtv

6. Add the source provider to apply the new rule:

   Copy to Clipboard Toggle word wrap

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Provider
   metadata:
     name: <provider>
     namespace: openshift-mtv
   spec:
     type: <provider_type> 

   1

   
     url: <api_end_point> 

   2

   
     secret:
       name: <secret> 

   3

   
       namespace: openshift-mtv
   EOF

   1

   Allowed values are ovirt, vsphere, and openstack.

   2

   Specify the API end point URL, for example, https://<vCenter_host>/sdk for vSphere, https://<engine_host>/ovirt-engine/api/ for RHV, or https://<identity_service>/v3 for OpenStack.

   3

   Specify the name of the provider Secret CR.

Procedure

1. Retrieve the current rules version:

   Copy to Clipboard Toggle word wrap

   $ GET https://forklift-validation/v1/data/io/konveyor/forklift/<provider>/rules_version 

   1

   Example output

   Copy to Clipboard Toggle word wrap

   {
      "result": {
          "rules_version": 5
      }
   }

2. Connect to the terminal of the Validation pod:

   Copy to Clipboard Toggle word wrap

   $ oc rsh <validation_pod>

3. Update the rules version in the /usr/share/opa/policies/io/konveyor/forklift/<provider>/rules_version.rego file.
4. Log out of the Validation pod terminal.

5. Verify the updated rules version:

   Copy to Clipboard Toggle word wrap

   $ GET https://forklift-validation/v1/data/io/konveyor/forklift/<provider>/rules_version 

   1

   Example output

   Copy to Clipboard Toggle word wrap

   {
      "result": {
          "rules_version": 6
      }
   }

1. You create a source provider, a target provider, a network mapping, and a storage mapping.

2. You create a Plan custom resource (CR) that includes the following resources:

   • Source provider
   • Target provider, if MTV is not installed on the target cluster
   • Network mapping
   • Storage mapping
   • One or more virtual machines (VMs)

3. You run a migration plan by creating a Migration CR that references the Plan CR.

   If you cannot migrate all the VMs for any reason, you can create multiple Migration CRs for the same Plan CR until all VMs are migrated.

4. For each VM in the Plan CR, the Migration Controller service records the VM migration progress in the Migration CR.

5. Once the data transfer for each VM in the Plan CR completes, the Migration Controller service creates a VirtualMachine CR.

   When all VMs have been migrated, the Migration Controller service updates the status of the Plan CR to Completed. The power state of each source VM is maintained after migration.

1. When you create the Migration custom resource (CR) to run a migration plan, the Migration Controller service creates a DataVolume CR for each source VM disk.

   For each VM disk:

2. The Containerized Data Importer (CDI) Controller service creates a persistent volume claim (PVC) based on the parameters specified in the DataVolume CR.


3. If the StorageClass has a dynamic provisioner, the persistent volume (PV) is dynamically provisioned by the StorageClass provisioner.
4. The CDI Controller service creates an importer pod.

5. The importer pod streams the VM disk to the PV.

   After the VM disks are transferred:

6. The Migration Controller service creates a conversion pod with the PVCs attached to it when importing from VMWare.

   The conversion pod runs virt-v2v, which installs and configures device drivers on the PVCs of the target VM.

7. The Migration Controller service creates a VirtualMachine CR for each source virtual machine (VM), connected to the PVCs.

8. If the VM ran on the source environment, the Migration Controller powers on the VM, the KubeVirt Controller service creates a virt-launcher pod and a VirtualMachineInstance CR.

   The virt-launcher pod runs QEMU-KVM with the PVCs attached as VM disks.

1. When you create a Migration custom resource (CR) to run a migration plan, the Migration Controller service creates for each source VM disk a PersistentVolumeClaim CR, and an OvirtVolumePopulator when the source is RHV, or an OpenstackVolumePopulator CR when the source is OpenStack.

   For each VM disk:

2. The Populator Controller service creates a temporarily persistent volume claim (PVC).

3. If the StorageClass has a dynamic provisioner, the persistent volume (PV) is dynamically provisioned by the StorageClass provisioner.

   • The Migration Controller service creates a dummy pod to bind all PVCs. The name of the pod contains pvcinit.
4. The Populator Controller service creates a populator pod.

5. The populator pod transfers the disk data to the PV.

   After the VM disks are transferred:

6. The temporary PVC is deleted, and the initial PVC points to the PV with the data.
7. The Migration Controller service creates a VirtualMachine CR for each source virtual machine (VM), connected to the PVCs.

8. If the VM ran on the source environment, the Migration Controller powers on the VM, the KubeVirt Controller service creates a virt-launcher pod and a VirtualMachineInstance CR.

   The virt-launcher pod runs QEMU-KVM with the PVCs attached as VM disks.

1. When you create a Migration custom resource (CR) to run a migration plan, the Migration Controller service creates a DataVolume CR for each source VM disk.

   For each VM disk:

2. The Containerized Data Importer (CDI) Controller service creates a blank persistent volume claim (PVC) based on the parameters specified in the DataVolume CR.


3. If the StorageClass has a dynamic provisioner, the persistent volume (PV) is dynamically provisioned by the StorageClass provisioner.

1. The Migration Controller service creates a dummy pod to bind all PVCs. The name of the pod contains pvcinit.
2. The Migration Controller service creates a conversion pod for all PVCs.

3. The conversion pod runs virt-v2v, which converts the VM to the KVM hypervisor and transfers the disks' data to their corresponding PVs.

   After the VM disks are transferred:

4. The Migration Controller service creates a VirtualMachine CR for each source virtual machine (VM), connected to the PVCs.

5. If the VM ran on the source environment, the Migration Controller powers on the VM, the KubeVirt Controller service creates a virt-launcher pod and a VirtualMachineInstance CR.

   The virt-launcher pod runs QEMU-KVM with the PVCs attached as VM disks.

Procedure

1. In the web console, click Migration plans.
2. Click Get logs beside a migration plan name.

3. In the Get logs window, click Get logs.

   The logs are collected. A Log collection complete message is displayed.

4. Click Download logs to download the archive file.
5. To download logs for a migrated VM, click a migration plan name and then click Get logs beside the VM.

Procedure

1. Navigate to the directory where you want to store the must-gather data.

2. Run the oc adm must-gather command:

   Copy to Clipboard Toggle word wrap

   $ oc adm must-gather --image=registry.redhat.io/migration-toolkit-virtualization/mtv-must-gather-rhel8:2.4.3

   The data is saved as /must-gather/must-gather.tar.gz. You can upload this file to a support case on the Red Hat Customer Portal.

3. Optional: Run the oc adm must-gather command with the following options to gather filtered data:

   • Namespace:

     Copy to Clipboard Toggle word wrap

     $ oc adm must-gather --image=registry.redhat.io/migration-toolkit-virtualization/mtv-must-gather-rhel8:2.4.3 \
       -- NS=<namespace> /usr/bin/targeted

   • Migration plan:

     Copy to Clipboard Toggle word wrap

     $ oc adm must-gather --image=registry.redhat.io/migration-toolkit-virtualization/mtv-must-gather-rhel8:2.4.3 \
       -- PLAN=<migration_plan> /usr/bin/targeted

   • Virtual machine:

     Copy to Clipboard Toggle word wrap

     $ oc adm must-gather --image=registry.redhat.io/migration-toolkit-virtualization/mtv-must-gather-rhel8:2.4.3 \
       -- VM=<vm_name> NS=<namespace> /usr/bin/targeted 

     1

     1

     You must specify the VM name, not the VM ID, as it appears in the Plan CR.