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
      }
   }