Chapter 5. Migrating virtual machines from the command line interface

Procedure

1. VMware only: Add the VDDK image to the HyperConverged CR:

   $ cat << EOF | oc apply -f -
   apiVersion: hco.kubevirt.io/v1beta1
   kind: HyperConverged
   metadata:
     name: kubevirt-hyperconverged
     namespace: openshift-cnv
   spec:
     vddkInitImage: <registry_route_or_server_path>/vddk:<tag> 1
   EOF

   1

   Specify the VDDK image that you created.

2. Create a Secret CR manifest for the source provider credentials:

   $ cat << EOF | oc apply -f -
   apiVersion: v1
   kind: Secret
   metadata:
     name: <secret>
     namespace: openshift-mtv
   type: Opaque
   stringData:
     user: <user> 1
     password: <password> 2
     cacert: <RHV_ca_certificate> 3
     thumbprint: <vcenter_fingerprint> 4
   EOF

   1

   Specify the base64-encoded vCenter admin user or the RHV Manager user.

   2

   Specify the base64-encoded password.

   3

   RHV only: Specify the base64-encoded CA certificate of the Manager. You can retrieve it at https://<www.example.com>/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA.

   4

   VMware only: Specify the vCenter SHA-1 fingerprint.

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

   $ 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 and vsphere.

   2

   Specify the API end point URL, for example, https://<www.example.com>/sdk for vSphere or https://<www.example.com>/ovirt-engine/api/ for RHV.

   3

   Specify the name of provider Secret CR.

4. VMware only: Create a Host CR manifest:

   $ 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

   1

   Specify the name of the VMware Provider CR.

   2

   Specify the managed object reference (MOR) 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:
           name: <pod>
           namespace: openshift-mtv
           type: pod 1
         source: 2
           id: <source_network_id> 3
           name: <source_network_name>
       - destination:
           name: <network_attachment_definition> 4
           namespace: <network_attachment_definition_namespace> 5
           type: multus
         source:
           id: <source_network_id>
           name: <source_network_name>
     provider:
       source:
         name: <source_provider>
         namespace: openshift-mtv
       destination:
         name: <destination_cluster>
         namespace: openshift-mtv
   EOF

   1

   Allowed values are pod and multus.

   2

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

   3

   Specify the VMware network MOR or RHV network UUID.

   4

   Specify a network attachment definition for each additional OpenShift Virtualization network.

   5

   Specify the namespace of the OpenShift Virtualization network attachment definition.

6. Create a StorageMap CR manifest to map source and destination storage:

   $ 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>
           accessMode: <access_mode> 1
         source:
           id: <source_datastore> 2
       - destination:
           storageClass: <storage_class>
           accessMode: <access_mode>
         source:
           id: <source_datastore>
     provider:
       source:
         name: <source_provider>
         namespace: openshift-mtv
       destination:
         name: <destination_cluster>
         namespace: openshift-mtv
   EOF

   1

   Allowed values are ReadWriteOnce and ReadWriteMany.

   2

   Specify the VMware data storage MOR or RHV storage domain UUID, for example, f2737930-b567-451a-9ceb-2887f6207009.

7. Optional: Create a Hook CR manifest to run custom code on a VM during the phase specified in the Plan CR:

   $  cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Hook
   metadata:
     name: <hook>
     namespace: openshift-mtv
   spec:
     image: quay.io/konveyor/hook-runner 1
     playbook: | 2
       LS0tCi0gbmFtZTogTWFpbgogIGhvc3RzOiBsb2NhbGhvc3QKICB0YXNrczoKICAtIG5hbWU6IExv
       YWQgUGxhbgogICAgaW5jbHVkZV92YXJzOgogICAgICBmaWxlOiAiL3RtcC9ob29rL3BsYW4ueW1s
       IgogICAgICBuYW1lOiBwbGFuCiAgLSBuYW1lOiBMb2FkIFdvcmtsb2FkCiAgICBpbmNsdWRlX3Zh
       cnM6CiAgICAgIGZpbGU6ICIvdG1wL2hvb2svd29ya2xvYWQueW1sIgogICAgICBuYW1lOiB3b3Jr
       bG9hZAoK
   EOF

   1

   You can use the default hook-runner image or specify a custom image. If you specify a custom image, you do not have to specify a playbook.

   2

   Optional: Base64-encoded Ansible playbook. If you specify a playbook, the image must be hook-runner.

8. 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:
     warm: true 2
     provider:
       source:
         name: <source_provider>
         namespace: openshift-mtv
       destination:
         name: <destination_cluster>
         namespace: openshift-mtv
     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> 7
       - name: <source_vm>
         hooks: 8
           - hook:
               namespace: openshift-mtv
               name: <hook> 9
             step: <step> 10
   EOF

   1

   Specify the name of the Plan CR.

   2

   VMware only: 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. Warm migration is not supported for RHV.

   3

   You can add multiple network mappings.

   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 VMware VM MOR or RHV VM UUID.

   8

   Optional: You can specify up to two hooks for a VM. Each hook must run during a separate migration step.

   9

   Specify the name of the Hook CR.

   10

   Allowed values are PreHook, before the migation plan starts, or PostHook, after the migration is complete.

9. Optional, for VMware only: 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

   1

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

10. 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

    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.

    You can associate multiple Migration CRs with a single Plan CR. If a migration does not complete, you can create a new Migration CR, without changing the Plan CR, to migrate the remaining VMs.

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

    $ oc get pods -n openshift-mtv

Canceling the migration of individual VMs

1. Add the individual VMs to the Migration CR manifest:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Migration
   metadata:
     name: <migration>
     namespace: openshift-mtv
   ...
   spec:
     cancel: 1
     - id: vm-102 2
     - id: vm-203
     - name: rhel8-vm
   EOF

   1 1

   You can specify the canceled VMs by using either the id or the name.

   2

   VMware VM managed object reference or RHV VM UUID.

2. View the VirtualMachineImport pods to monitor the progress of the remaining VMs:

   $ oc get pods -n openshift-mtv