Installing and using the Migration Toolkit for Virtualization

Procedure

1. Create and navigate to a temporary directory:

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

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

2. Extract the VDDK archive:

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

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

4. Build the VDDK image:

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

5. Push the VDDK image to the registry:

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

6. 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:

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

3. Restart hostd:

   # /etc/init.d/hostd restart

   You do not need to reboot the host.

Procedure

1. In the Red Hat OpenShift web console, click Plans for virtualization and then click Create Plan.

   The Create migration plan wizard opens to the Select source provider interface.

2. Select the source provider of the VMs you want to migrate.

   The Select virtual machines interface opens.

3. Select the VMs you want to migrate and click Next.

   The Create migration plan pane opens. It displays the source provider’s name and suggestions for a target provider and namespace, a network map, and a storage map.

4. Enter the Plan name.
5. Make any needed changes to the editable items.
6. Click Add mapping to edit a suggested network mapping or a storage mapping, or to add one or more additional mappings.

7. Click Create migration plan.

   MTV validates the migration plan and the Plan details page opens, indicating whether the plan is ready for use or contains an error. The details of the plan are listed, and you can edit the items you filled in on the previous page. If you make any changes, MTV validates the plan again.

8. VMware source providers only (All optional):

   • Preserving static IPs of VMs: By default, virtual network interface controllers (vNICs) change during the migration process. This results in vNICs that are set with a static IP in vSphere losing their IP. To avoid this by preserving static IPs of VMs, click the Edit icon next to Preserve static IPs and toggle the Whether to preserve the static IPs switch in the window that opens. Then click Save.

     MTV then issues a warning message about any VMs with a Windows operating system for which vNIC properties are missing. To retrieve any missing vNIC properties, run those VMs in vSphere in order for the vNIC properties to be reported to MTV.

   • Entering a list of decryption passphrases for disks encrypted using Linux Unified Key Setup (LUKS): To enter a list of decryption passphrases for LUKS-encrypted devices, in the Settings section, click the Edit icon next to Disk decryption passphrases, enter the passphrases, and then click Save. You do not need to enter the passphrases in a specific order - for each LUKS-encrypted device, MTV tries each passphrase until one unlocks the device.

   • Specifying a root device: Applies to multi-boot VM migrations only. By default, MTV uses the first bootable device detected as the root device.

     To specify a different root device, in the Settings section, click the Edit icon next to Root device and choose a device from the list of commonly-used options, or enter a device in the text box.

     MTV uses the following format for disk location: /dev/sd<disk_identifier><disk_partition>. For example, if the second disk is the root device and the operating system is on the disk’s second partition, the format would be: /dev/sdb2. After you enter the boot device, click Save.

     If the conversion fails because the boot device provided is incorrect, it is possible to get the correct information by looking at the conversion pod logs.

9. RHV source providers only (Optional):

   • Preserving the CPU model of VMs that are migrated from RHV: Generally, the CPU model (type) for RHV VMs is set at the cluster level, but it can be set at the VM level, which is called a custom CPU model. By default, MTV sets the CPU model on the destination cluster as follows: MTV preserves custom CPU settings for VMs that have them, but, for VMs without custom CPU settings, MTV does not set the CPU model. Instead, the CPU model is later set by OpenShift Virtualization.

     To preserve the cluster-level CPU model of your RHV VMs, in the Settings section, click the Edit icon next to Preserve CPU model. Toggle the Whether to preserve the CPU model switch, and then click Save.

10. If the plan is valid,

    1. You can run the plan now by clicking Start migration.
    2. You can run the plan later by selecting it on the Plans for virtualization page and following the procedure in Running a migration plan.

Procedure

1. In the Red Hat OpenShift web console, click Providers for virtualization.

2. In the row of the appropriate source provider, click VMs.

   The Virtual Machines tab opens.

3. Select the VMs you want to migrate and click Create migration plan.

   The Create migration plan pane opens. It displays the source provider’s name and suggestions for a target provider and namespace, a network map, and a storage map.

4. Enter the Plan name.
5. Make any needed changes to the editable items.
6. Click Add mapping to edit a suggested network mapping or a storage mapping, or to add one or more additional mappings.

7. Click Create migration plan.

   MTV validates the migration plan and the Plan details page opens, indicating whether the plan is ready for use or contains an error. The details of the plan are listed, and you can edit the items you filled in on the previous page. If you make any changes, MTV validates the plan again.

8. VMware source providers only (All optional):

   • Preserving static IPs of VMs: By default, virtual network interface controllers (vNICs) change during the migration process. This results in vNICs that are set with a static IP in vSphere losing their IP. To avoid this by preserving static IPs of VMs, click the Edit icon next to Preserve static IPs and toggle the Whether to preserve the static IPs switch in the window that opens. Then click Save.

     MTV then issues a warning message about any VMs with a Windows operating system for which vNIC properties are missing. To retrieve any missing vNIC properties, run those VMs in vSphere in order for the vNIC properties to be reported to MTV.

   • Entering a list of decryption passphrases for disks encrypted using Linux Unified Key Setup (LUKS): To enter a list of decryption passphrases for LUKS-encrypted devices, in the Settings section, click the Edit icon next to Disk decryption passphrases, enter the passphrases, and then click Save. You do not need to enter the passphrases in a specific order - for each LUKS-encrypted device, MTV tries each passphrase until one unlocks the device.

   • Specifying a root device: Applies to multi-boot VM migrations only. By default, MTV uses the first bootable device detected as the root device.

     To specify a different root device, in the Settings section, click the Edit icon next to Root device and choose a device from the list of commonly-used options, or enter a device in the text box.

     MTV uses the following format for disk location: /dev/sd<disk_identifier><disk_partition>. For example, if the second disk is the root device and the operating system is on the disk’s second partition, the format would be: /dev/sdb2. After you enter the boot device, click Save.

     If the conversion fails because the boot device provided is incorrect, it is possible to get the correct information by looking at the conversion pod logs.

9. RHV source providers only (Optional):

   • Preserving the CPU model of VMs that are migrated from RHV: Generally, the CPU model (type) for RHV VMs is set at the cluster level, but it can be set at the VM level, which is called a custom CPU model. By default, MTV sets the CPU model on the destination cluster as follows: MTV preserves custom CPU settings for VMs that have them, but, for VMs without custom CPU settings, MTV does not set the CPU model. Instead, the CPU model is later set by OpenShift Virtualization.

     To preserve the cluster-level CPU model of your RHV VMs, in the Settings section, click the Edit icon next to Preserve CPU model. Toggle the Whether to preserve the CPU model switch, and then click Save.

10. If the plan is valid,

    1. You can run the plan now by clicking Start migration.
    2. You can run the plan later by selecting it on the Plans for virtualization page and following the procedure in Running a migration plan.

Procedure

1. Create a Secret manifest for the source provider credentials:

   $ cat << EOF | oc apply -f -
   apiVersion: v1
   kind: Secret
   metadata:
     name: <secret>
     namespace: <namespace>
     ownerReferences: 1
       - apiVersion: forklift.konveyor.io/v1beta1
         kind: Provider
         name: <provider_name>
         uid: <provider_uid>
     labels:
       createdForProviderType: vsphere
       createdForResourceType: providers
   type: Opaque
   stringData:
     user: <user> 2
     password: <password> 3
     insecureSkipVerify: <"true"/"false"> 4
     cacert: | 5
       <ca_certificate>
     url: <api_end_point> 6
   EOF

   1

   The ownerReferences section is optional.

   2

   Specify the vCenter user or the ESX/ESXi user.

   3

   Specify the password of the vCenter user or the ESX/ESXi user.

   4

   Specify "true" to skip certificate verification, specify "false" to verify the certificate. Defaults to "false" if not specified. Skipping certificate verification proceeds with an insecure migration and then the certificate is not required. Insecure migration means that the transferred data is sent over an insecure connection and potentially sensitive data could be exposed.

   5

   When this field is not set and skip certificate verification is disabled, MTV attempts to use the system CA.

   6

   Specify the API endpoint URL of the vCenter or the ESX/ESXi, for example, https://<vCenter_host>/sdk.

2. Create a Provider manifest for the source provider:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Provider
   metadata:
     name: <source_provider>
     namespace: <namespace>
   spec:
     type: vsphere
     url: <api_end_point> 1
     settings:
       vddkInitImage: <VDDK_image> 2
       sdkEndpoint: vcenter 3
     secret:
       name: <secret> 4
       namespace: <namespace>
   EOF

   1

   Specify the URL of the API endpoint, for example, https://<vCenter_host>/sdk.

   2

   Optional, but it is strongly recommended to create a VDDK image to accelerate migrations. Follow OpenShift documentation to specify the VDDK image you created.

   3

   Options: vcenter or esxi.

   4

   Specify the name of the provider Secret CR.

3. Create a Host manifest:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Host
   metadata:
     name: <vmware_host>
     namespace: <namespace>
   spec:
     provider:
       namespace: <namespace>
       name: <source_provider> 1
     id: <source_host_mor> 2
     ipAddress: <source_network_ip> 3
   EOF

   1

   Specify the name of the VMware vSphere Provider CR.

   2

   Specify the Managed Object Reference (moRef) of the VMware vSphere host. To retrieve the moRef, see Retrieving a VMware vSphere moRef.

   3

   Specify the IP address of the VMware vSphere migration network.

4. Create a NetworkMap 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: <namespace>
   spec:
     map:
       - destination:
           name: <network_name>
           type: pod 1
         source: 2
           id: <source_network_id>
           name: <source_network_name>
       - destination:
           name: <network_attachment_definition> 3
           namespace: <network_attachment_definition_namespace> 4
           type: multus
         source:
           id: <source_network_id>
           name: <source_network_name>
     provider:
       source:
         name: <source_provider>
         namespace: <namespace>
       destination:
         name: <destination_provider>
         namespace: <namespace>
   EOF

   1

   Allowed values are pod and multus.

   2

   You can use either the id or the name parameter to specify the source network. For id, specify the VMware vSphere network Managed Object Reference (moRef). To retrieve the moRef, see Retrieving a VMware vSphere moRef.

   3

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

   4

   Required only when type is multus. Specify the namespace of the OpenShift Virtualization network attachment definition.

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

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: StorageMap
   metadata:
     name: <storage_map>
     namespace: <namespace>
   spec:
     map:
       - destination:
           storageClass: <storage_class>
           accessMode: <access_mode> 1
         source:
           id: <source_datastore> 2
     provider:
       source:
         name: <source_provider>
         namespace: <namespace>
       destination:
         name: <destination_provider>
         namespace: <namespace>
   EOF

   1

   Allowed values are ReadWriteOnce and ReadWriteMany.

   2

   Specify the VMware vSphere datastore moRef. For example, f2737930-b567-451a-9ceb-2887f6207009. To retrieve the moRef, see Retrieving a VMware vSphere moRef.

6. Optional: Create a Hook 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: <namespace>
   spec:
     image: quay.io/konveyor/hook-runner
     playbook: |
       LS0tCi0gbmFtZTogTWFpbgogIGhvc3RzOiBsb2NhbGhvc3QKICB0YXNrczoKICAtIG5hbWU6IExv
       YWQgUGxhbgogICAgaW5jbHVkZV92YXJzOgogICAgICBmaWxlOiAiL3RtcC9ob29rL3BsYW4ueW1s
       IgogICAgICBuYW1lOiBwbGFuCiAgLSBuYW1lOiBMb2FkIFdvcmtsb2FkCiAgICBpbmNsdWRlX3Zh
       cnM6CiAgICAgIGZpbGU6ICIvdG1wL2hvb2svd29ya2xvYWQueW1sIgogICAgICBuYW1lOiB3b3Jr
       bG9hZAoK
   EOF

   where:

   playbook refers to an optional Base64-encoded Ansible Playbook. If you specify a playbook, the image must be hook-runner.

   Note

   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.

7. Create a Plan manifest for the migration:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Plan
   metadata:
     name: <plan> 1
     namespace: <namespace>
   spec:
     warm: false 2
     provider:
       source:
         name: <source_provider>
         namespace: <namespace>
       destination:
         name: <destination_provider>
         namespace: <namespace>
     map: 3
       network: 4
         name: <network_map> 5
         namespace: <namespace>
       storage: 6
         name: <storage_map> 7
         namespace: <namespace>
     targetNamespace: <target_namespace>
     vms: 8
       - id: <source_vm> 9
       - name: <source_vm>
         hooks: 10
           - hook:
               namespace: <namespace>
               name: <hook> 11
             step: <step> 12
   EOF

   1

   Specify the name of the Plan CR.

   2

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

   3

   Specify only one network map and one storage map per plan.

   4

   Specify a network mapping even if the VMs to be migrated are not assigned to a network. The mapping can be empty in this case.

   5

   Specify the name of the NetworkMap CR.

   6

   Specify a storage mapping even if the VMs to be migrated are not assigned with disk images. The mapping can be empty in this case.

   7

   Specify the name of the StorageMap CR.

   8

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

   9

   Specify the VMware vSphere VM moRef. To retrieve the moRef, see Retrieving a VMware vSphere moRef.

   10

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

   11

   Specify the name of the Hook CR.

   12

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

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

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Migration
   metadata:
     name: <name_of_migration_cr>
     namespace: <namespace>
   spec:
     plan:
       name: <name_of_plan_cr>
       namespace: <namespace>
     cutover: <optional_cutover_time>
   EOF

   Note

   If you specify a cutover time, use the ISO 8601 format with the UTC time offset, for example, 2024-04-04T01:23:45.678+09:00.

Procedure

1. Create a Secret manifest for the source provider credentials:

   $ cat << EOF | oc apply -f -
   apiVersion: v1
   kind: Secret
   metadata:
     name: <secret>
     namespace: <namespace>
     ownerReferences: 1
       - apiVersion: forklift.konveyor.io/v1beta1
         kind: Provider
         name: <provider_name>
         uid: <provider_uid>
     labels:
       createdForProviderType: ovirt
       createdForResourceType: providers
   type: Opaque
   stringData:
     user: <user> 2
     password: <password> 3
     insecureSkipVerify: <"true"/"false"> 4
     cacert: | 5
       <ca_certificate>
     url: <api_end_point> 6
   EOF

   1

   The ownerReferences section is optional.

   2

   Specify the RHV Manager user.

   3

   Specify the user password.

   4

   Specify "true" to skip certificate verification, specify "false" to verify the certificate. Defaults to "false" if not specified. Skipping certificate verification proceeds with an insecure migration and then the certificate is not required. Insecure migration means that the transferred data is sent over an insecure connection and potentially sensitive data could be exposed.

   5

   Enter the Manager CA certificate, unless it was replaced by a third-party certificate, in which case, enter the Manager Apache CA certificate. You can retrieve the Manager CA certificate at https://<engine_host>/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA.

   6

   Specify the API endpoint URL, for example, https://<engine_host>/ovirt-engine/api.

2. Create a Provider manifest for the source provider:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Provider
   metadata:
     name: <source_provider>
     namespace: <namespace>
   spec:
     type: ovirt
     url: <api_end_point> 1
     secret:
       name: <secret> 2
       namespace: <namespace>
   EOF

   1

   Specify the URL of the API endpoint, for example, https://<engine_host>/ovirt-engine/api.

   2

   Specify the name of provider Secret CR.

3. Create a NetworkMap 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: <namespace>
   spec:
     map:
       - destination:
           name: <network_name>
           type: pod 1
         source: 2
           id: <source_network_id>
           name: <source_network_name>
       - destination:
           name: <network_attachment_definition> 3
           namespace: <network_attachment_definition_namespace> 4
           type: multus
         source:
           id: <source_network_id>
           name: <source_network_name>
     provider:
       source:
         name: <source_provider>
         namespace: <namespace>
       destination:
         name: <destination_provider>
         namespace: <namespace>
   EOF

   1

   Allowed values are pod and multus.

   2

   You can use either the id or the name parameter to specify the source network. For id, specify the RHV network Universal Unique ID (UUID).

   3

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

   4

   Required only when type is multus. Specify the namespace of the OpenShift Virtualization network attachment definition.

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

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: StorageMap
   metadata:
     name: <storage_map>
     namespace: <namespace>
   spec:
     map:
       - destination:
           storageClass: <storage_class>
           accessMode: <access_mode> 1
         source:
           id: <source_storage_domain> 2
     provider:
       source:
         name: <source_provider>
         namespace: <namespace>
       destination:
         name: <destination_provider>
         namespace: <namespace>
   EOF

   1

   Allowed values are ReadWriteOnce and ReadWriteMany.

   2

   Specify the RHV storage domain UUID. For example, f2737930-b567-451a-9ceb-2887f6207009.

5. Optional: Create a Hook 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: <namespace>
   spec:
     image: quay.io/konveyor/hook-runner
     playbook: |
       LS0tCi0gbmFtZTogTWFpbgogIGhvc3RzOiBsb2NhbGhvc3QKICB0YXNrczoKICAtIG5hbWU6IExv
       YWQgUGxhbgogICAgaW5jbHVkZV92YXJzOgogICAgICBmaWxlOiAiL3RtcC9ob29rL3BsYW4ueW1s
       IgogICAgICBuYW1lOiBwbGFuCiAgLSBuYW1lOiBMb2FkIFdvcmtsb2FkCiAgICBpbmNsdWRlX3Zh
       cnM6CiAgICAgIGZpbGU6ICIvdG1wL2hvb2svd29ya2xvYWQueW1sIgogICAgICBuYW1lOiB3b3Jr
       bG9hZAoK
   EOF

   where:

   playbook refers to an optional Base64-encoded Ansible Playbook. If you specify a playbook, the image must be hook-runner.

   Note

   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.

6. Create a Plan manifest for the migration:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Plan
   metadata:
     name: <plan> 1
     namespace: <namespace>
     preserveClusterCpuModel: true 2
   spec:
     warm: false 3
     provider:
       source:
         name: <source_provider>
         namespace: <namespace>
       destination:
         name: <destination_provider>
         namespace: <namespace>
     map: 4
       network: 5
         name: <network_map> 6
         namespace: <namespace>
       storage: 7
         name: <storage_map> 8
         namespace: <namespace>
     targetNamespace: <target_namespace>
     vms: 9
       - id: <source_vm> 10
       - name: <source_vm>
         hooks: 11
           - hook:
               namespace: <namespace>
               name: <hook> 12
             step: <step> 13
   EOF

   1

   Specify the name of the Plan CR.

   2

   See note below.

   3

   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 manifest, only the precopy stage will run.

   4

   Specify only one network map and one storage map per plan.

   5

   Specify a network mapping even if the VMs to be migrated are not assigned to a network. The mapping can be empty in this case.

   6

   Specify the name of the NetworkMap CR.

   7

   Specify a storage mapping even if the VMs to be migrated are not assigned with disk images. The mapping can be empty in this case.

   8

   Specify the name of the StorageMap CR.

   9

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

   10

   Specify the RHV VM UUID.

   11

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

   12

   Specify the name of the Hook CR.

   13

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

   Note
   • If the migrated machines is set with a custom CPU model, it will be set with that CPU model in the destination cluster, regardless of the setting of preserveClusterCpuModel.

   • If the migrated machine is not set with a custom CPU model:

     • If preserveClusterCpuModel is set to 'true`, MTV checks the CPU model of the VM when it runs in RHV, based on the cluster’s configuration, and then sets the migrated VM with that CPU model.
     • If preserveClusterCpuModel is set to 'false`, MTV does not set a CPU type and the VM is set with the default CPU model of the destination cluster.

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

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Migration
   metadata:
     name: <name_of_migration_cr>
     namespace: <namespace>
   spec:
     plan:
       name: <name_of_plan_cr>
       namespace: <namespace>
     cutover: <optional_cutover_time>
   EOF

   Note

   If you specify a cutover time, use the ISO 8601 format with the UTC time offset, for example, 2024-04-04T01:23:45.678+09:00.

Procedure

1. Create a Secret manifest for the source provider credentials:

   $ cat << EOF | oc apply -f -
   apiVersion: v1
   kind: Secret
   metadata:
     name: <secret>
     namespace: <namespace>
     ownerReferences: 1
       - apiVersion: forklift.konveyor.io/v1beta1
         kind: Provider
         name: <provider_name>
         uid: <provider_uid>
     labels:
       createdForProviderType: openstack
       createdForResourceType: providers
   type: Opaque
   stringData:
     user: <user> 2
     password: <password> 3
     insecureSkipVerify: <"true"/"false"> 4
     domainName: <domain_name>
     projectName: <project_name>
     regionName: <region_name>
     cacert: | 5
       <ca_certificate>
     url: <api_end_point> 6
   EOF

   1

   The ownerReferences section is optional.

   2

   Specify the OpenStack user.

   3

   Specify the user OpenStack password.

   4

   Specify "true" to skip certificate verification, specify "false" to verify the certificate. Defaults to "false" if not specified. Skipping certificate verification proceeds with an insecure migration and then the certificate is not required. Insecure migration means that the transferred data is sent over an insecure connection and potentially sensitive data could be exposed.

   5

   When this field is not set and skip certificate verification is disabled, MTV attempts to use the system CA.

   6

   Specify the API endpoint URL, for example, https://<identity_service>/v3.

2. Create a Provider manifest for the source provider:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Provider
   metadata:
     name: <source_provider>
     namespace: <namespace>
   spec:
     type: openstack
     url: <api_end_point> 1
     secret:
       name: <secret> 2
       namespace: <namespace>
   EOF

   1

   Specify the URL of the API endpoint.

   2

   Specify the name of provider Secret CR.

3. Create a NetworkMap 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: <namespace>
   spec:
     map:
       - destination:
           name: <network_name>
           type: pod 1
         source:2
           id: <source_network_id>
           name: <source_network_name>
       - destination:
           name: <network_attachment_definition> 3
           namespace: <network_attachment_definition_namespace> 4
           type: multus
         source:
           id: <source_network_id>
           name: <source_network_name>
     provider:
       source:
         name: <source_provider>
         namespace: <namespace>
       destination:
         name: <destination_provider>
         namespace: <namespace>
   EOF

   1

   Allowed values are pod and multus.

   2

   You can use either the id or the name parameter to specify the source network. For id, specify the OpenStack network UUID.

   3

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

   4

   Required only when type is multus. Specify the namespace of the OpenShift Virtualization network attachment definition.

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

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: StorageMap
   metadata:
     name: <storage_map>
     namespace: <namespace>
   spec:
     map:
       - destination:
           storageClass: <storage_class>
           accessMode: <access_mode> 1
         source:
           id: <source_volume_type> 2
     provider:
       source:
         name: <source_provider>
         namespace: <namespace>
       destination:
         name: <destination_provider>
         namespace: <namespace>
   EOF

   1

   Allowed values are ReadWriteOnce and ReadWriteMany.

   2

   Specify the OpenStack volume_type UUID. For example, f2737930-b567-451a-9ceb-2887f6207009.

5. Optional: Create a Hook 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: <namespace>
   spec:
     image: quay.io/konveyor/hook-runner
     playbook: |
       LS0tCi0gbmFtZTogTWFpbgogIGhvc3RzOiBsb2NhbGhvc3QKICB0YXNrczoKICAtIG5hbWU6IExv
       YWQgUGxhbgogICAgaW5jbHVkZV92YXJzOgogICAgICBmaWxlOiAiL3RtcC9ob29rL3BsYW4ueW1s
       IgogICAgICBuYW1lOiBwbGFuCiAgLSBuYW1lOiBMb2FkIFdvcmtsb2FkCiAgICBpbmNsdWRlX3Zh
       cnM6CiAgICAgIGZpbGU6ICIvdG1wL2hvb2svd29ya2xvYWQueW1sIgogICAgICBuYW1lOiB3b3Jr
       bG9hZAoK
   EOF

   where:

   playbook refers to an optional Base64-encoded Ansible Playbook. If you specify a playbook, the image must be hook-runner.

   Note

   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.

6. Create a Plan manifest for the migration:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Plan
   metadata:
     name: <plan> 1
     namespace: <namespace>
   spec:
     provider:
       source:
         name: <source_provider>
         namespace: <namespace>
       destination:
         name: <destination_provider>
         namespace: <namespace>
     map: 2
       network: 3
         name: <network_map> 4
         namespace: <namespace>
       storage: 5
         name: <storage_map> 6
         namespace: <namespace>
     targetNamespace: <target_namespace>
     vms: 7
       - id: <source_vm> 8
       - name: <source_vm>
         hooks: 9
           - hook:
               namespace: <namespace>
               name: <hook> 10
             step: <step> 11
   EOF

   1

   Specify the name of the Plan CR.

   2

   Specify only one network map and one storage map per plan.

   3

   Specify a network mapping, even if the VMs to be migrated are not assigned to a network. The mapping can be empty in this case.

   4

   Specify the name of the NetworkMap CR.

   5

   Specify a storage mapping, even if the VMs to be migrated are not assigned with disk images. The mapping can be empty in this case.

   6

   Specify the name of the StorageMap CR.

   7

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

   8

   Specify the OpenStack VM UUID.

   9

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

   10

   Specify the name of the Hook CR.

   11

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

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

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Migration
   metadata:
     name: <name_of_migration_cr>
     namespace: <namespace>
   spec:
     plan:
       name: <name_of_plan_cr>
       namespace: <namespace>
     cutover: <optional_cutover_time>
   EOF

   Note

   If you specify a cutover time, use the ISO 8601 format with the UTC time offset, for example, 2024-04-04T01:23:45.678+09:00.

Procedure

1. Create a Secret manifest for the source provider credentials:

   $ cat << EOF | oc apply -f -
   apiVersion: v1
   kind: Secret
   metadata:
     name: <secret>
     namespace: <namespace>
     ownerReferences: 1
       - apiVersion: forklift.konveyor.io/v1beta1
         kind: Provider
         name: <provider_name>
         uid: <provider_uid>
     labels:
       createdForProviderType: ova
       createdForResourceType: providers
   type: Opaque
   stringData:
     url: <nfs_server:/nfs_path> 2
   EOF

   1

   The ownerReferences section is optional.

   2

   where: nfs_server is an IP or hostname of the server where the share was created and nfs_path is the path on the server where the OVA files are stored.

2. Create a Provider manifest for the source provider:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Provider
   metadata:
     name: <source_provider>
     namespace: <namespace>
   spec:
     type: ova
     url:  <nfs_server:/nfs_path> 1
     secret:
       name: <secret> 2
       namespace: <namespace>
   EOF

   1

   where: nfs_server is an IP or hostname of the server where the share was created and nfs_path is the path on the server where the OVA files are stored.

   2

   Specify the name of provider Secret CR.

3. Create a NetworkMap 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: <namespace>
   spec:
     map:
       - destination:
           name: <network_name>
           type: pod 1
         source:
           id: <source_network_id> 2
       - destination:
           name: <network_attachment_definition> 3
           namespace: <network_attachment_definition_namespace> 4
           type: multus
         source:
           id: <source_network_id>
     provider:
       source:
         name: <source_provider>
         namespace: <namespace>
       destination:
         name: <destination_provider>
         namespace: <namespace>
   EOF

   1

   Allowed values are pod and multus.

   2

   Specify the OVA network Universal Unique ID (UUID).

   3

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

   4

   Required only when type is multus. Specify the namespace of the OpenShift Virtualization network attachment definition.

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

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: StorageMap
   metadata:
     name: <storage_map>
     namespace: <namespace>
   spec:
     map:
       - destination:
           storageClass: <storage_class>
           accessMode: <access_mode> 1
         source:
           name:  Dummy storage for source provider <provider_name> 2
     provider:
       source:
         name: <source_provider>
         namespace: <namespace>
       destination:
         name: <destination_provider>
         namespace: <namespace>
   EOF

   1

   Allowed values are ReadWriteOnce and ReadWriteMany.

   2

   For OVA, the StorageMap can map only a single storage, which all the disks from the OVA are associated with, to a storage class at the destination. For this reason, the storage is referred to in the UI as "Dummy storage for source provider <provider_name>". In the YAML, write the phrase as it appears above, without the quotation marks and replacing <provider_name> with the actual name of the provider.

5. Optional: Create a Hook 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: <namespace>
   spec:
     image: quay.io/konveyor/hook-runner
     playbook: |
       LS0tCi0gbmFtZTogTWFpbgogIGhvc3RzOiBsb2NhbGhvc3QKICB0YXNrczoKICAtIG5hbWU6IExv
       YWQgUGxhbgogICAgaW5jbHVkZV92YXJzOgogICAgICBmaWxlOiAiL3RtcC9ob29rL3BsYW4ueW1s
       IgogICAgICBuYW1lOiBwbGFuCiAgLSBuYW1lOiBMb2FkIFdvcmtsb2FkCiAgICBpbmNsdWRlX3Zh
       cnM6CiAgICAgIGZpbGU6ICIvdG1wL2hvb2svd29ya2xvYWQueW1sIgogICAgICBuYW1lOiB3b3Jr
       bG9hZAoK
   EOF

   where:

   playbook refers to an optional Base64-encoded Ansible Playbook. If you specify a playbook, the image must be hook-runner.

   Note

   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.

6. Create a Plan manifest for the migration:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Plan
   metadata:
     name: <plan> 1
     namespace: <namespace>
   spec:
     provider:
       source:
         name: <source_provider>
         namespace: <namespace>
       destination:
         name: <destination_provider>
         namespace: <namespace>
     map: 2
       network: 3
         name: <network_map> 4
         namespace: <namespace>
       storage: 5
         name: <storage_map> 6
         namespace: <namespace>
     targetNamespace: <target_namespace>
     vms: 7
       - id: <source_vm> 8
       - name: <source_vm>
         hooks: 9
           - hook:
               namespace: <namespace>
               name: <hook> 10
             step: <step> 11
   EOF

   1

   Specify the name of the Plan CR.

   2

   Specify only one network map and one storage map per plan.

   3

   Specify a network mapping, even if the VMs to be migrated are not assigned to a network. The mapping can be empty in this case.

   4

   Specify the name of the NetworkMap CR.

   5

   Specify a storage mapping even if the VMs to be migrated are not assigned with disk images. The mapping can be empty in this case.

   6

   Specify the name of the StorageMap CR.

   7

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

   8

   Specify the OVA VM UUID.

   9

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

   10

   Specify the name of the Hook CR.

   11

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

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

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Migration
   metadata:
     name: <name_of_migration_cr>
     namespace: <namespace>
   spec:
     plan:
       name: <name_of_plan_cr>
       namespace: <namespace>
     cutover: <optional_cutover_time>
   EOF

   Note

   If you specify a cutover time, use the ISO 8601 format with the UTC time offset, for example, 2024-04-04T01:23:45.678+09:00.

Procedure

1. Create a Secret manifest for the source provider credentials:

   $ cat << EOF | oc apply -f -
   apiVersion: v1
   kind: Secret
   metadata:
     name: <secret>
     namespace: <namespace>
     ownerReferences: 1
       - apiVersion: forklift.konveyor.io/v1beta1
         kind: Provider
         name: <provider_name>
         uid: <provider_uid>
     labels:
       createdForProviderType: openshift
       createdForResourceType: providers
   type: Opaque
   stringData:
     token: <token> 2
     password: <password> 3
     insecureSkipVerify: <"true"/"false"> 4
     cacert: | 5
       <ca_certificate>
     url: <api_end_point> 6
   EOF

   1

   The ownerReferences section is optional.

   2

   Specify a token for a service account with cluster-admin privileges. If both token and url are left blank, the local OpenShift cluster is used.

   3

   Specify the user password.

   4

   Specify "true" to skip certificate verification, specify "false" to verify the certificate. Defaults to "false" if not specified. Skipping certificate verification proceeds with an insecure migration and then the certificate is not required. Insecure migration means that the transferred data is sent over an insecure connection and potentially sensitive data could be exposed.

   5

   When this field is not set and skip certificate verification is disabled, MTV attempts to use the system CA.

   6

   Specify the URL of the endpoint of the API server.

2. Create a Provider manifest for the source provider:

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

   1

   Specify the URL of the endpoint of the API server.

   2

   Specify the name of provider Secret CR.

3. Create a NetworkMap 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: <namespace>
   spec:
     map:
       - destination:
           name: <network_name>
           type: pod 1
         source:
           name: <network_name>
           type: pod
       - destination:
           name: <network_attachment_definition> 2
           namespace: <network_attachment_definition_namespace> 3
           type: multus
         source:
           name: <network_attachment_definition>
           namespace: <network_attachment_definition_namespace>
           type: multus
     provider:
       source:
         name: <source_provider>
         namespace: <namespace>
       destination:
         name: <destination_provider>
         namespace: <namespace>
   EOF

   1

   Allowed values are pod and multus.

   2

   Specify a network attachment definition for each additional OpenShift Virtualization network. Specify the namespace either by using the namespace property or with a name built as follows: <network_namespace>/<network_name>.

   3

   Required only when type is multus. Specify the namespace of the OpenShift Virtualization network attachment definition.

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

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: StorageMap
   metadata:
     name: <storage_map>
     namespace: <namespace>
   spec:
     map:
       - destination:
           storageClass: <storage_class>
           accessMode: <access_mode> 1
         source:
           name: <storage_class>
     provider:
       source:
         name: <source_provider>
         namespace: <namespace>
       destination:
         name: <destination_provider>
         namespace: <namespace>
   EOF

   1

   Allowed values are ReadWriteOnce and ReadWriteMany.

5. Optional: Create a Hook 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: <namespace>
   spec:
     image: quay.io/konveyor/hook-runner
     playbook: |
       LS0tCi0gbmFtZTogTWFpbgogIGhvc3RzOiBsb2NhbGhvc3QKICB0YXNrczoKICAtIG5hbWU6IExv
       YWQgUGxhbgogICAgaW5jbHVkZV92YXJzOgogICAgICBmaWxlOiAiL3RtcC9ob29rL3BsYW4ueW1s
       IgogICAgICBuYW1lOiBwbGFuCiAgLSBuYW1lOiBMb2FkIFdvcmtsb2FkCiAgICBpbmNsdWRlX3Zh
       cnM6CiAgICAgIGZpbGU6ICIvdG1wL2hvb2svd29ya2xvYWQueW1sIgogICAgICBuYW1lOiB3b3Jr
       bG9hZAoK
   EOF

   where:

   playbook refers to an optional Base64-encoded Ansible Playbook. If you specify a playbook, the image must be hook-runner.

   Note

   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.

6. Create a Plan manifest for the migration:

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Plan
   metadata:
     name: <plan> 1
     namespace: <namespace>
   spec:
     provider:
       source:
         name: <source_provider>
         namespace: <namespace>
       destination:
         name: <destination_provider>
         namespace: <namespace>
     map: 2
       network: 3
         name: <network_map> 4
         namespace: <namespace>
       storage: 5
         name: <storage_map> 6
         namespace: <namespace>
     targetNamespace: <target_namespace>
     vms:
       - name: <source_vm>
         namespace: <namespace>
         hooks: 7
           - hook:
               namespace: <namespace>
               name: <hook> 8
             step: <step> 9
   EOF

   1

   Specify the name of the Plan CR.

   2

   Specify only one network map and one storage map per plan.

   3

   Specify a network mapping, even if the VMs to be migrated are not assigned to a network. The mapping can be empty in this case.

   4

   Specify the name of the NetworkMap CR.

   5

   Specify a storage mapping, even if the VMs to be migrated are not assigned with disk images. The mapping can be empty in this case.

   6

   Specify the name of the StorageMap CR.

   7

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

   8

   Specify the name of the Hook CR.

   9

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

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

   $ cat << EOF | oc apply -f -
   apiVersion: forklift.konveyor.io/v1beta1
   kind: Migration
   metadata:
     name: <name_of_migration_cr>
     namespace: <namespace>
   spec:
     plan:
       name: <name_of_plan_cr>
       namespace: <namespace>
     cutover: <optional_cutover_time>
   EOF

   Note

   If you specify a cutover time, use the ISO 8601 format with the UTC time offset, for example, 2024-04-04T01:23:45.678+09:00.

Procedure

1. Connect to the terminal of the Validation pod:

   $ oc rsh <validation_pod>

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

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

   1

   Specify vmware or ovirt.

3. Search for the default policies:

   $ grep -R "default" *

Procedure

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

   $ 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:

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

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

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

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

   $ 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:

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

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

   $ 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:

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

   Example output

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

2. Connect to the terminal of the Validation pod:

   $ 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:

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

   Example output

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

Procedure

1. If needed, create a secret with an SSH private key for the VM. You can either use an existing key or generate a key pair, install the public key on the VM, and base64 encode the private key in the secret.

   apiVersion: v1
   data:
     key: VGhpcyB3YXMgZ2VuZXJhdGVkIHdpdGggc3NoLWtleWdlbiBwdXJlbHkgZm9yIHRoaXMgZXhhbXBsZS4KSXQgaXMgbm90IHVzZWQgYW55d2hlcmUuCi0tLS0tQkVHSU4gT1BFTlNTSCBQUklWQVRFIEtFWS0tLS0tCmIzQmxibk56YUMxclpYa3RkakVBQUFBQUJHNXZibVVBQUFBRWJtOXVaUUFBQUFBQUFBQUJBQUFCbHdBQUFBZHpjMmd0Y24KTmhBQUFBQXdFQUFRQUFBWUVBMzVTTFRReDBFVjdPTWJQR0FqcEsxK2JhQURTTVFuK1NBU2pyTGZLNWM5NGpHdzhDbnA4LwovRHErZHFBR1pxQkg2ZnAxYmVJM1BZZzVWVDk0RVdWQ2RrTjgwY3dEcEo0Z1R0NHFUQ1gzZUYvY2x5VXQyUC9zaTNjcnQ0CjBQdi9wVnZXU1U2TlhHaDJIZC93V0MwcGh5Z0RQOVc5SHRQSUF0OFpnZmV2ZnUwZHpraVl6OHNVaElWU2ZsRGpaNUFqcUcKUjV2TVVUaGlrczEvZVlCeTdiMkFFSEdzYU8xN3NFbWNiYUlHUHZuUFVwWmQrdjkyYU1JdWZoYjhLZkFSbzZ3Ty9ISW1VbQovdDdHWFBJUmxBMUhSV0p1U05odTQzZS9DY3ZYd3Z6RnZrdE9kYXlEQzBMTklHMkpVaURlNWd0UUQ1WHZXc1p3MHQvbEs1CklacjFrZXZRNUJsYWNISmViV1ZNYUQvdllpdFdhSFo4OEF1Y0czaGh2bjkrOGNSTGhNVExiVlFSMWh2UVpBL1JtQXN3eE0KT3VJSmRaUmtxTThLZlF4Z28zQThRNGJhQW1VbnpvM3Zwa0FWdC9uaGtIOTRaRE5rV2U2RlRhdThONStyYTJCZkdjZVA4VApvbjFEeTBLRlpaUlpCREVVRVc0eHdTYUVOYXQ3c2RDNnhpL1d5OURaQUFBRm1NRFBXeDdBejFzZUFBQUFCM056YUMxeWMyCkVBQUFHQkFOK1VpMDBNZEJGZXpqR3p4Z0k2U3RmbTJnQTBqRUova2dFbzZ5M3l1WFBlSXhzUEFwNmZQL3c2dm5hZ0JtYWcKUituNmRXM2lOejJJT1ZVL2VCRmxRblpEZk5ITUE2U2VJRTdlS2t3bDkzaGYzSmNsTGRqLzdJdDNLN2VORDcvNlZiMWtsTwpqVnhvZGgzZjhGZ3RLWWNvQXovVnZSN1R5QUxmR1lIM3IzN3RIYzVJbU0vTEZJU0ZVbjVRNDJlUUk2aGtlYnpGRTRZcExOCmYzbUFjdTI5Z0JCeHJHanRlN0JKbkcyaUJqNzV6MUtXWGZyL2RtakNMbjRXL0Nud0VhT3NEdnh5SmxKdjdleGx6eUVaUU4KUjBWaWJrallidU4zdnduTDE4TDh4YjVMVG5Xc2d3dEN6U0J0aVZJZzN1WUxVQStWNzFyR2NOTGY1U3VTR2E5WkhyME9RWgpXbkJ5WG0xbFRHZy83MklyVm1oMmZQQUxuQnQ0WWI1L2Z2SEVTNFRFeTIxVUVkWWIwR1FQMFpnTE1NVERyaUNYV1VaS2pQCkNuME1ZS053UEVPRzJnSmxKODZONzZaQUZiZjU0WkIvZUdRelpGbnVoVTJydkRlZnEydGdYeG5Iai9FNko5UTh0Q2hXV1UKV1FReEZCRnVNY0VtaERXcmU3SFF1c1l2MXN2UTJRQUFBQU1CQUFFQUFBR0JBSlZtZklNNjdDQmpXcU9KdnFua2EvakRrUwo4TDdpSE5mekg1TnRZWVdPWmRMTlk2L0lRa1pDeFcwTWtSKzlUK0M3QUZKZzBNV2Q5ck5PeUxJZDkxNjZoOVJsNG0xdFJjCnViZ1o2dWZCZ3hGVDlXS21mSEdCNm4zelh5b2pQOEFJTnR6ODVpaUVHVXFFRWtVRVdMd0RGSmdvcFllQ3l1VmZ2ZE92MUgKRm1WWmEwNVo0b3NQNkNENXVmc2djQ1RYQTR6VnZ5ZHVCYkxqdHN5RjdYZjNUdjZUQ1QxU0swZHErQk1OOXRvb0RZaXpwagpzbDh6NzlybXp3eUFyWFlVcnFUUkpsNmpwRkNrWHJLcy9LeG96MHhhbXlMY2RORk9hWE51LzlnTkpjRERsV2hPcFRqNHk4CkpkNXBuV1Jueis1RHJLRFdhY0loUW1CMUxVd2ZLWmQwbVFxaUpzMUMxcXZVUmlKOGExaThKUTI4bHFuWTFRRk9wbk13emcKWEpla2FndThpT1ExRFJlQkhaM0NkcVJUYnY3bVJZSGxramx0dXJmZGc4M3hvM0ErZ1JSR001eUVOcW5xSkplQjhJQVB5UwptMFp0dGdqbHNqNTJ2K1B1NmExMHoxZndKK1VML2N6dTRKeEpOYlp6WTFIMnpLODJBaVI1T3JYNmx2aUEvSWFSRVcwUUFBCkFNQndVeUJpcUc5bEZCUnltL2UvU1VORVMzdHpicUZNdTdIcy84WTV5SnAxKzR6OXUxNGtJR2ttV0Y5eE5HT3hrY3V0cWwKeHVUcndMbjFUaFNQTHQrTjUwTGhVdzR4ZjBhNUxqemdPbklPU0FRbm5HY1Nxa0dTRDlMR21obGE2WmpydFBHY29lQ3JHdAo5M1Vvcmx5YkxNRzFFRFAxWmpKS1RaZzl6OUMwdDlTTGd3ei9DbFhydW9UNXNQVUdKWnUrbHlIZXpSTDRtcHl6OEZMcnlOCkdNci9leVM5bWdISjNVVkZEYjNIZ3BaK1E1SUdBRU5rZVZEcHIwMGhCZXZndGd6YWtBQUFEQkFQVXQ1RitoMnBVby94V1YKenRkcVQvMzA4dFB5MXVMMU1lWFoydEJPQmRwSDJyd0JzdWt0aTIySGtWZUZXQjJFdUlFUXppMzY3MGc1UGdxR1p4Vng4dQpobEE0Rkg4ZXN1NTNQckZqVW9EeFJhb3d3WXBFcFh5Y2pnNUE1MStwR1VQcWljWjB0YjliaWlhc3BWWXZhWW5sdGlnVG5iClN0UExMY29nemNiL0dGcVYyaXlzc3lwTlMwKzBNRTUxcEtxWGNaS2swbi8vVHpZWWs4TW8vZzRsQ3pmUEZQUlZrVVM5blIKWU1pQzRlcEk0TERmbVdnM0xLQ2N1Zk85all3aWgwYlFBQUFNRUE2WEtldDhEMHNvc0puZVh5WFZGd0dyVyszNlhBVGRQTwpMWDdjaStjYzFoOGV1eHdYQWx3aTJJNFhxSmJBVjBsVEhuVGEycXN3Uy9RQlpJUUJWSkZlVjVyS1daZTc4R2F3d1pWTFZNCldETmNwdFFyRTFaM2pGNS9TdUVzdlVxSDE0Tkc5RUFXWG1iUkNzelE0Vlk3NzQrSi9sTFkvMnlDT1diNzlLYTJ5OGxvYUoKVXczWWVtSld3blp2R3hKNldsL3BmQ2xYN3lEVXlXUktLdGl0cWNjbmpCWVkyRE1tZURwdURDYy9ZdDZDc3dLRmRkMkJ1UwpGZGt5cDlZY3VMaDlLZEFBQUFIR3BoYzI5dVFFRlVMVGd3TWxVdWJXOXVkR3hsYjI0dWFXNTBjbUVCQWdNRUJRWT0KLS0tLS1FTkQgT1BFTlNTSCBQUklWQVRFIEtFWS0tLS0tCgo=
   kind: Secret
   metadata:
     name: ssh-credentials
     namespace: konveyor-forklift
   type: Opaque

2. Encode your playbook by conncatenating a file and piping it for base64, for example:

   $ cat playbook.yml | base64 -w0

   Note

   You can also use a here document to encode a playbook:

   $ cat << EOF | base64 -w0
   - hosts: localhost
     tasks:
     - debug:
         msg: test
   EOF

3. Create a Hook CR:

   apiVersion: forklift.konveyor.io/v1beta1
   kind: Hook
   metadata:
     name: playbook
     namespace: konveyor-forklift
   spec:
     image: registry.redhat.io/rhmtc/openshift-migration-hook-runner-rhel8:v1.8.2-2
     playbook: LSBuYW1lOiBNYWluCiAgaG9zdHM6IGxvY2FsaG9zdAogIHRhc2tzOgogIC0gbmFtZTogTG9hZCBQbGFuCiAgICBpbmNsdWRlX3ZhcnM6CiAgICAgIGZpbGU6IHBsYW4ueW1sCiAgICAgIG5hbWU6IHBsYW4KCiAgLSBuYW1lOiBMb2FkIFdvcmtsb2FkCiAgICBpbmNsdWRlX3ZhcnM6CiAgICAgIGZpbGU6IHdvcmtsb2FkLnltbAogICAgICBuYW1lOiB3b3JrbG9hZAoKICAtIG5hbWU6IAogICAgZ2V0ZW50OgogICAgICBkYXRhYmFzZTogcGFzc3dkCiAgICAgIGtleTogInt7IGFuc2libGVfdXNlcl9pZCB9fSIKICAgICAgc3BsaXQ6ICc6JwoKICAtIG5hbWU6IEVuc3VyZSBTU0ggZGlyZWN0b3J5IGV4aXN0cwogICAgZmlsZToKICAgICAgcGF0aDogfi8uc3NoCiAgICAgIHN0YXRlOiBkaXJlY3RvcnkKICAgICAgbW9kZTogMDc1MAogICAgZW52aXJvbm1lbnQ6CiAgICAgIEhPTUU6ICJ7eyBhbnNpYmxlX2ZhY3RzLmdldGVudF9wYXNzd2RbYW5zaWJsZV91c2VyX2lkXVs0XSB9fSIKCiAgLSBrOHNfaW5mbzoKICAgICAgYXBpX3ZlcnNpb246IHYxCiAgICAgIGtpbmQ6IFNlY3JldAogICAgICBuYW1lOiBzc2gtY3JlZGVudGlhbHMKICAgICAgbmFtZXNwYWNlOiBrb252ZXlvci1mb3JrbGlmdAogICAgcmVnaXN0ZXI6IHNzaF9jcmVkZW50aWFscwoKICAtIG5hbWU6IENyZWF0ZSBTU0gga2V5CiAgICBjb3B5OgogICAgICBkZXN0OiB+Ly5zc2gvaWRfcnNhCiAgICAgIGNvbnRlbnQ6ICJ7eyBzc2hfY3JlZGVudGlhbHMucmVzb3VyY2VzWzBdLmRhdGEua2V5IHwgYjY0ZGVjb2RlIH19IgogICAgICBtb2RlOiAwNjAwCgogIC0gYWRkX2hvc3Q6CiAgICAgIG5hbWU6ICJ7eyB3b3JrbG9hZC52bS5pcGFkZHJlc3MgfX0iCiAgICAgIGFuc2libGVfdXNlcjogcm9vdAogICAgICBncm91cHM6IHZtcwoKLSBob3N0czogdm1zCiAgdGFza3M6CiAgLSBuYW1lOiBJbnN0YWxsIGNsb3VkLWluaXQKICAgIGRuZjoKICAgICAgbmFtZToKICAgICAgLSBjbG91ZC1pbml0CiAgICAgIHN0YXRlOiBsYXRlc3QKCiAgLSBuYW1lOiBDcmVhdGUgVGVzdCBGaWxlCiAgICBjb3B5OgogICAgICBkZXN0OiAvdGVzdC50eHQKICAgICAgY29udGVudDogIkhlbGxvIFdvcmxkIgogICAgICBtb2RlOiAwNjQ0Cg==
     serviceAccount: forklift-controller 1

   1

   Specify a serviceAccount to run the hook with in order to control access to resources on the cluster.

   Note

   To decode an attached playbook retrieve the resource with custom output and pipe it to base64. For example:

    oc get -n konveyor-forklift hook playbook -o \
      go-template='{{ .spec.playbook }}' | base64 -d

   The playbook encoded here runs the following:

   - name: Main
     hosts: localhost
     tasks:
     - name: Load Plan
       include_vars:
         file: plan.yml
         name: plan
   
     - name: Load Workload
       include_vars:
         file: workload.yml
         name: workload
   
     - name:
       getent:
         database: passwd
         key: "{{ ansible_user_id }}"
         split: ':'
   
     - name: Ensure SSH directory exists
       file:
         path: ~/.ssh
         state: directory
         mode: 0750
       environment:
         HOME: "{{ ansible_facts.getent_passwd[ansible_user_id][4] }}"
   
     - k8s_info:
         api_version: v1
         kind: Secret
         name: ssh-credentials
         namespace: konveyor-forklift
       register: ssh_credentials
   
     - name: Create SSH key
       copy:
         dest: ~/.ssh/id_rsa
         content: "{{ ssh_credentials.resources[0].data.key | b64decode }}"
         mode: 0600
   
     - add_host:
         name: "{{ workload.vm.ipaddress }}"
         ansible_user: root
         groups: vms
   
   - hosts: vms
     tasks:
     - name: Install cloud-init
       dnf:
         name:
         - cloud-init
         state: latest
   
     - name: Create Test File
       copy:
         dest: /test.txt
         content: "Hello World"
         mode: 0644

4. Create a Plan CR using the hook:

   kind: Plan
   apiVersion: forklift.konveyor.io/v1beta1
   metadata:
     name: test
     namespace: konveyor-forklift
   spec:
     map:
       network:
         namespace: "konveyor-forklift"
         name: "network"
       storage:
         namespace: "konveyor-forklift"
         name: "storage"
     provider:
       source:
         namespace: "konveyor-forklift"
         name: "boston"
       destination:
         namespace: "konveyor-forklift"
         name: host
     targetNamespace: "konveyor-forklift"
     vms:
       - id: vm-2861
         hooks:
           - hook:
               namespace: konveyor-forklift
               name: playbook
             step: PreHook 1

   1

   Options are PreHook, to run the hook before the migration, and PostHook, to run the hook after the migration.

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 Red Hat OpenShift web console, click Migration → Plans for virtualization.
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:

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

   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:

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

   • Migration plan:

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

   • Virtual machine:

     $ oc adm must-gather --image=registry.redhat.io/migration-toolkit-virtualization/mtv-must-gather-rhel8:2.6.7 \
       -- 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.