Installing and using the Migration Toolkit for Virtualization

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

2. You create a migration plan that includes the following resources:

   • Source provider
   • Target provider
   • Network mapping
   • Storage mapping
   • One or more VMs
3. You run a migration plan by creating a Migration CR that references the migration plan. If a migration is incomplete, you can run a migration plan multiple times until all VMs are migrated.
4. For each VM in the migration plan, the Migration Controller creates a VirtualMachineImport CR and monitors its status. When all VMs have been migrated, the Migration Controller sets the status of the migration plan to Completed. The power state of a source VM is maintained after migration.

1. When you run a migration plan, the Migration Controller creates a VirtualMachineImport custom resource (CR) for each source VM.
2. The Virtual Machine Import Controller validates the VirtualMachineImport CR and generates a VirtualMachine CR.

3. The Virtual Machine Import Controller retrieves the VM configuration, including network, storage, and metadata, linked in the VirtualMachineImport CR.



   For each VM disk:

4. The Virtual Machine Import Controller creates a DataVolume CR as a wrapper for a Persistent Volume Claim (PVC) and annotations.


5. The Containerized Data Importer (CDI) Controller creates a PVC. The Persistent Volume (PV) is dynamically provisioned by the StorageClass provisioner.


6. The CDI Controller creates an Importer pod.

7. The Importer pod connects to the VM disk by using the VMware Virtual Disk Development Kit (VDDK) SDK and streams the VM disk to the PV.

   After the VM disks are transferred:

8. The Virtual Machine Import Controller creates a Conversion pod with the PVCs attached to it.

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

9. The Virtual Machine Import Controller creates a VirtualMachineInstance CR.

10. When the target VM is powered on, the KubeVirt Controller creates a VM pod.

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

Procedure

1. Create and navigate to a temporary directory:

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

   Copy to Clipboard Toggle word wrap
2. In a browser, navigate to the VMware VDDK download page.
3. Select the latest VDDK version and click Download.
4. Save the VDDK archive file in the temporary directory.

5. Extract the VDDK archive:

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

   Copy to Clipboard Toggle word wrap

6. Create a Dockerfile:

   $ cat > Dockerfile <<EOF
   FROM registry.access.redhat.com/ubi8/ubi-minimal
   COPY vmware-vix-disklib-distrib /vmware-vix-disklib-distrib
   RUN mkdir -p /opt
   ENTRYPOINT ["cp", "-r", "/vmware-vix-disklib-distrib", "/opt"]
   EOF

   Copy to Clipboard Toggle word wrap

7. Build the VDDK image:

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

   Copy to Clipboard Toggle word wrap

8. Push the VDDK image to the registry:

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

   Copy to Clipboard Toggle word wrap
9. Ensure that the image is accessible to your OpenShift Virtualization environment.

10. Edit the HyperConverged CR in the openshift-cnv project:

    $ oc edit hco -n openshift-cnv kubevirt-hyperconverged

    Copy to Clipboard Toggle word wrap

11. Add the vddkInitImage parameter to the spec stanza:

    apiVersion: hco.kubevirt.io/v1beta1
    kind: HyperConverged
    metadata:
      name: kubevirt-hyperconverged
      namespace: openshift-cnv
    spec:
      vddkInitImage: <registry_route_or_server_path>/vddk:<tag>

    Copy to Clipboard Toggle word wrap

Procedure

1. Obtain the vCenter SHA-1 fingerprint:

   $ openssl s_client \
       -connect <www.example.com>:443 \ 

   1

   
       < /dev/null 2>/dev/null \
       | openssl x509 -fingerprint -noout -in /dev/stdin \
       | cut -d '=' -f 2

   Copy to Clipboard Toggle word wrap

   1

   Specify the vCenter name.

   Example output

   01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67

   Copy to Clipboard Toggle word wrap

2. Create a Secret CR manifest for the VMware provider:

   $ cat << EOF | oc apply -f -
   apiVersion: v1
   kind: Secret
   metadata:
     name: <vmware_secret>
     namespace: openshift-mtv
   type: Opaque
   stringData:
     user: <vcenter_user> 

   1

   
     password: <vcenter_password> 

   2

   
     thumbprint: <vcenter_fingerprint> 

   3

   
   EOF

   Copy to Clipboard Toggle word wrap

   1

   Specify the vCenter administrator account, for example, administrator@vsphere.local.

   2

   Specify the vCenter password.

   3

   Specify the vCenter SHA-1 fingerprint.

3. Create a Provider CR manifest for the VMware provider:

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

   1

   
     secret:
       name: <vmware_secret> 

   2

   
       namespace: openshift-mtv
   EOF

   Copy to Clipboard Toggle word wrap

   1

   Specify the vSphere API end point, for example, https://<vcenter.host.com>/sdk.

   2

   Specify the name of the VMware Secret CR.

4. Create a Host CR manifest for the VMware host:

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

   1

   
     id: <source_host_mor> 

   2

   
     ipAddress: <source_network_ip> 

   3

   
   EOF

   Copy to Clipboard Toggle word wrap

   1

   Specify the name of the VMware Provider CR.

   2

   Specify the managed object reference of the VMware host.

   3

   Specify the IP address of the VMware migration network.

5. Create a NetworkMap CR manifest to map the source and destination networks:

   $  cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: NetworkMap
   metadata:
     name: <network_map>
     namespace: openshift-mtv
   spec:
     map:
       - destination:
           type: pod 

   1

   
         source:
           id: <source_network_mor> 

   2

   
       - destination:
           type: multus
           name: <network_attachment_definition> 

   3

   
           namespace: <network_attachment_definition_namespace> 

   4

   
         source:
           id: <source_network_mor>
     provider:
       source:
         name: <vmware_provider>
         namespace: openshift-mtv
       destination:
         name: <destination_cluster>
         namespace: openshift-mtv
   EOF

   Copy to Clipboard Toggle word wrap

   1

   Allowed values are pod and multus.

   2

   Specify the managed object reference of the VMware network.

   3

   Specify the network attachment definition for each additional destination network.

   4

   Specify the namespace of the network attachment definition.

6. Create a StorageMap CR manifest:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: StorageMap
   metadata:
     name: <storage_map>
     namespace: openshift-mtv
   spec:
     map:
       - destination:
           storageClass: <storage_class>
         source:
           id: <source_datastore_mor> 

   1

   
     provider:
       source:
         name: <vmware_provider>
         namespace: openshift-mtv
       destination:
         name: <destination_cluster>
         namespace: openshift-mtv
   EOF

   Copy to Clipboard Toggle word wrap

   1

   Specify the managed object reference of the VMware data storage.

7. Create a Plan CR manifest for the migration:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Plan
   metadata:
     name: <plan> 

   1

   
     namespace: openshift-mtv
   spec:
     provider:
       source:
         name: <vmware_provider>
         namespace: openshift-mtv
       destination:
         name: <destination_cluster>
         namespace: openshift-mtv
     warm: true 

   2

   
     map:
       network: 

   3

   
         name: <network_map> 

   4

   
         namespace: openshift-mtv
       storage:
         name: <storage_map> 

   5

   
         namespace: openshift-mtv
     targetNamespace: openshift-mtv
     vms: 

   6

   
       - id: <source_vm_mor> 

   7

   
       - name: <source_vm>
   EOF

   Copy to Clipboard Toggle word wrap

   1

   Specify the name of the Plan CR.

   2

   Specify whether the migration is warm or cold. If you specify a warm migration without specifying a value for the cutover parameter in the Migration CR manifest, only the precopy stage will run.

   3

   You can create multiple network mappings for source and destination networks.

   4

   Specify the name of the NetworkMap CR.

   5

   Specify the name of the StorageMap CR.

   6

   You can use either the id or the name parameter to specify the source VMs.

   7

   Specify the managed object reference of the VMware VM.

8. Optional: To change the time interval between the CBT snapshots for warm migration, patch the vm-import-controller-config config map:

   $ oc patch configmap/vm-import-controller-config \
     -n openshift-cnv -p '{"data": \
     {"warmImport.intervalMinutes": "<interval>"}}' 

   1

   Copy to Clipboard Toggle word wrap

   1

   Specify the time interval in minutes. The default value is 60.

9. Create a Migration CR manifest to run the Plan CR:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Migration
   metadata:
     name: <migration> 

   1

   
     namespace: openshift-mtv
   spec:
     plan:
       name: <plan> 

   2

   
       namespace: openshift-mtv
     cutover: <cutover_time> 

   3

   
   EOF

   Copy to Clipboard Toggle word wrap

   1

   Specify the name of the Migration CR.

   2

   Specify the name of the Plan CR that you are running. The Migration CR creates a VirtualMachineImport CR for each VM that is migrated.

   3

   Optional: Specify a cutover time according to the ISO 8601 format with the UTC time offset, for example, 2021-04-04T01:23:45.678+09:00.

10. View the VirtualMachineImport pods to monitor the progress of the migration:

    $ oc get pods -n openshift-mtv

    Copy to Clipboard Toggle word wrap

Procedure

1. Click Home → Projects.
2. Enter rhmtv in the Search field to locate the openshift-mtv project.
3. On the right side of the project, select Delete Project from the Options menu .
4. In the Delete Project pane, enter the project name and click Delete.
5. Click Administration → CustomResourceDefinitions.
6. Enter forklift in the Search field to locate the CRDs in the forklift.konveyor.io group.
7. On the right side of each CRD, select Delete CustomResourceDefinition from the Options menu .

Procedure

1. Delete the project:

   $ oc delete project openshift-mtv

   Copy to Clipboard Toggle word wrap

2. Delete the CRDs:

   $ oc get crd -o name | grep 'forklift' | xargs oc delete

   Copy to Clipboard Toggle word wrap

3. Delete the OAuthClient:

   $ oc delete oauthclient/forklift-ui

   Copy to Clipboard Toggle word wrap

Collecting logs and CR information

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

2. Run the oc adm must-gather command:

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

   Copy to Clipboard Toggle word wrap

   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.