Procedure

1. In the Red Hat OpenShift web console, click Migration > Plans for virtualization.

   The Plans list displays the source and target providers, the number of virtual machines (VMs) being migrated, the status, the date that the migration started, and the description of each plan.

2. Click Start beside a migration plan to start the migration.

3. Click Start in the confirmation window that opens.

   The plan’s Status changes to Running, and the migration’s progress is displayed.

   Warm migration only:

   • The precopy stage starts.

   • Click Cutover to complete the migration.

     Warning

     Do not take a snapshot of a VM after you start a migration. Taking a snaphot after a migration starts might cause the migration to fail.

4. Optional: Click the links in the migration’s Status to see its overall status and the status of each VM:

   • The link on the left indicates whether the migration failed, succeeded, or is ongoing. It also reports the number of VMs whose migration succeeded, failed, or was canceled.

   • The link on the right opens the Virtual Machines tab of the Plan Details page. For each VM, the tab displays the following data:

     • The name of the VM
     • The start and end times of the migration
     • The amount of data copied

     • A progress pipeline for the VM’s migration

       Warning

       vMotion, including svMotion, and relocation must be disabled for VMs that are being imported to avoid data corruption.

5. Optional: To view your migration’s logs, either as it is running or after it is completed, perform the following actions:

   1. Click the Virtual Machines tab.

   2. Click the arrow (>) to the left of the virtual machine whose migration progress you want to check.

      The VM’s details are displayed.

   3. In the Pods section, in the Pod links column, click the Logs link.

      The Logs tab opens.

      Note

      Logs are not always available. The following are common reasons for logs not being available:

      • The migration is from OpenShift Virtualization to OpenShift Virtualization. In this case, virt-v2v is not involved, so no pod is required.
      • No pod was created.
      • The pod was deleted.
      • The migration failed before running the pod.
   4. To see the raw logs, click the Raw link.
   5. To download the logs, click the Download link.

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, and 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, multus, and ignored. Use ignored to avoid attaching VMs to this network for this migration.

   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/kubev2v/hook-runner
     serviceAccount:<service account> 1
     playbook: |
       LS0tCi0gbm... 2
   EOF

   1

   Optional: Red Hat OpenShift service account. Use the serviceAccount parameter to modify any cluster resources.

   2

   Base64-encoded Ansible Playbook. If you specify a playbook, the image must include an ansible-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. Enter the following command to create the network attachment definition (NAD) of the transfer network used for MTV migrations.

   You use this definition to configure an IP address for the interface, either from the Dynamic Host Configuration Protocol (DHCP) or statically.

   Configuring the IP address enables the interface to reach the configured gateway.

   $ oc edit NetworkAttachmentDefinitions <name_of_the_NAD_to_edit>
   apiVersion: k8s.cni.cncf.io/v1
   kind: NetworkAttachmentDefinition
   metadata:
     name: <name_of_transfer_network>
     namespace: <namespace>
     annotations:
       forklift.konveyor.io/route: <IP_address>

8. 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>
     preserveStaticIPs: 8
     networkNameTemplate: <network_interface_template> 9
     pvcNameTemplate: <pvc_name_template> 10
     pvcNameTemplateUseGenerateName: true 11
     skipGuestConversion: false 12
     targetNamespace: <target_namespace>
     useCompatibilityMode: true 13
     volumeNameTemplate: <volume_name_template> 14
     vms: 15
       - id: <source_vm1> 16
       - name: <source_vm2>
         networkNameTemplate: <network_interface_template_for_this_vm> 17
         pvcNameTemplate: <pvc_name_template_for_this_vm> 18
         volumeNameTemplate: <volume_name_template_for_this_vm> 19
         targetName: <target_name> 20
         hooks: 21
           - hook:
               namespace: <namespace>
               name: <hook> 22
             step: <step> 23
   
   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

   By default, virtual network interface controllers (vNICs) change during the migration process. As a result, vNICs that are configured with a static IP address linked to the interface name in the guest VM lose their IP address. To avoid this, set preserveStaticIPs to true. MTV issues a warning message about any VMs 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.

   9

   Optional. Specify a template for the network interface name for the VMs in your plan. The template follows the Go template syntax and has access to the following variables:

   • .NetworkName: If the target network is multus, add the name of the Multus Network Attachment Definition. Otherwise, leave this variable empty.
   • .NetworkNamespace: If the target network is multus, add the namespace where the Multus Network Attachment Definition is located.
   • .NetworkType: Specifies the network type. Options: multus or pod.

   • .NetworkIndex: Sequential index of the network interface (0-based).

     Examples

   • "net-{{.NetworkIndex}}"

   • {{if eq .NetworkType "pod"}}pod{{else}}multus-{{.NetworkIndex}}{{end}}"

     Variable names cannot exceed 63 characters. This rule applies to a network name network template, a PVC name template, a VM name template, and a volume name template.

   10

   Optional. Specify a template for the persistent volume claim (PVC) name for a plan. The template follows the Go template syntax and has access to the following variables:

   • .VmName: Name of the VM.
   • .PlanName: Name of the migration plan.
   • .DiskIndex: Initial volume index of the disk.
   • .RootDiskIndex: Index of the root disk.

   • .Shared: Options: true, for a shared volume, false, for a non-shared volume.

     Examples

   • "{{.VmName}}-disk-{{.DiskIndex}}"
   • "{{if eq .DiskIndex .RootDiskIndex}}root{{else}}data{{end}}-{{.DiskIndex}}"
   • "{{if .Shared}}shared-{{end}}{{.VmName}}-{{.DiskIndex}}"

   11

   Optional:

   • When set to true, MTV adds one or more randomly generated alphanumeric characters to the name of the PVC in order to ensure all PVCs have unique names.

   • When set to false, if you specify a pvcNameTemplate, MTV does not add such characters to the name of the PVC.

     Warning

     If you set pvcNameTemplateUseGenerateName to false, the generated PVC name might not be unique and might cause conflicts.

   12

   Determines whether VMs are converted before migration using the virt-v2v tool, which makes the VMs compatible with OpenShift Virtualization.

   • When set to false, the default value, MTV migrates VMs using virt-v2v.

   • When set to true, MTV migrates VMs using raw copy mode, which copies the VMs without converting them first.

     Raw copy mode copies VMs without converting them with virt-v2v. This allows for faster conversions, migrating VMs running a wider range of operating systems, as well as supporting migrating disks encrypted using Linux Unified Key Setup (LUKS) without needing keys. However, VMs migrated using raw copy mode might not function properly on OpenShift Virtualization. For more information on virt-v2v, see How MTV uses the virt-v2v tool.

   13

   Determines whether the migration uses VirtIO devices or compatibility devices (SATA bus, E1000E NIC) when skipGuestConversion is true, that is, when raw copy mode is used for the migration. The setting of useCompatibilityMode has no effect when skipGuestConversion is false, because virt-v2v conversion always uses VirtIO devices.

   • When set to true, the default setting, MTV uses compatibility devices (SATA bus, E1000E NIC) in the migration process to ensure that the VMs can be booted after migration.
   • When set to false, MTV uses high-performance VirtIO devices in the migration process, and virt-v2v ensures that the VMs can be booted after migration. Before using this option, verify that VirtIO drivers are already installed in the source VMs.

   14

   Optional: Specify a template for the volume interface name for the VMs in your plan. The template follows the Go template syntax and has access to the following variables:

   • .PVCName: Name of the PVC mounted to the VM using this volume.

   • .VolumeIndex: Sequential index of the volume interface (0-based).

     Examples

   • "disk-{{.VolumeIndex}}"
   • "pvc-{{.PVCName}}"

   15

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

   16

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

   17

   Optional: Specify a network interface name for the specific VM. Overrides the value set in spec:networkNameTemplate. Variables and examples as in callout 9.

   18

   Optional: Specify a PVC name for the specific VM. Overrides the value set in spec:pvcNameTemplate. Variables and examples as in callout 10.

   19

   Optional: Specify a volume name for the specific VM. Overrides the value set in spec:volumeNameTemplate. Variables and examples as in callout 14.

   20

   Optional: MTV automatically generates a name for the target VM. You can override this name by using this parameter and entering a new name. The name you enter must be unique, and it must be a valid Kubernetes subdomain. Otherwise, the migration fails automatically.

   21

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

   22

   Specify the name of the Hook CR.

   23

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

   Important

   When you migrate a VMware 7 VM to an OpenShift 4.13+ platform that uses CentOS 7.9, the name of the network interfaces changes and the static IP configuration for the VM no longer works.

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

   The Plans list displays the source and target providers, the number of virtual machines (VMs) being migrated, the status, the date that the migration started, and the description of each plan.

2. Click Start beside a migration plan to start the migration.

3. Click Start in the confirmation window that opens.

   The plan’s Status changes to Running, and the migration’s progress is displayed.

   Warm migration only:

   • The precopy stage starts.

   • Click Cutover to complete the migration.

     Warning

     Do not take a snapshot of a VM after you start a migration. Taking a snaphot after a migration starts might cause the migration to fail.

4. Optional: Click the links in the migration’s Status to see its overall status and the status of each VM:

   • The link on the left indicates whether the migration failed, succeeded, or is ongoing. It also reports the number of VMs whose migration succeeded, failed, or was canceled.

   • The link on the right opens the Virtual Machines tab of the Plan Details page. For each VM, the tab displays the following data:

     • The name of the VM
     • The start and end times of the migration
     • The amount of data copied

     • A progress pipeline for the VM’s migration

       Warning

       vMotion, including svMotion, and relocation must be disabled for VMs that are being imported to avoid data corruption.

5. Optional: To view your migration’s logs, either as it is running or after it is completed, perform the following actions:

   1. Click the Virtual Machines tab.

   2. Click the arrow (>) to the left of the virtual machine whose migration progress you want to check.

      The VM’s details are displayed.

   3. In the Pods section, in the Pod links column, click the Logs link.

      The Logs tab opens.

      Note

      Logs are not always available. The following are common reasons for logs not being available:

      • The migration is from OpenShift Virtualization to OpenShift Virtualization. In this case, virt-v2v is not involved, so no pod is required.
      • No pod was created.
      • The pod was deleted.
      • The migration failed before running the pod.
   4. To see the raw logs, click the Raw link.
   5. To download the logs, click the Download link.

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, and 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/kubev2v/hook-runner
     serviceAccount:<service account> 1
     playbook: |
       LS0tCi0gbm... 2
   EOF

   1

   Optional: Red Hat OpenShift service account. Use the serviceAccount parameter to modify any cluster resources.

   2

   Base64-encoded Ansible Playbook. If you specify a playbook, the image must include an ansible-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. Enter the following command to create the network attachment definition (NAD) of the transfer network used for MTV migrations.

   You use this definition to configure an IP address for the interface, either from the Dynamic Host Configuration Protocol (DHCP) or statically.

   Configuring the IP address enables the interface to reach the configured gateway.

   $ oc edit NetworkAttachmentDefinitions <name_of_the_NAD_to_edit>
   apiVersion: k8s.cni.cncf.io/v1
   kind: NetworkAttachmentDefinition
   metadata:
     name: <name_of_transfer_network>
     namespace: <namespace>
     annotations:
       forklift.konveyor.io/route: <IP_address>

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>
     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_vm1> 10
       - name: <source_vm2>
         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: 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 machine 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.

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

   The Plans list displays the source and target providers, the number of virtual machines (VMs) being migrated, the status, the date that the migration started, and the description of each plan.

2. Click Start beside a migration plan to start the migration.

3. Click Start in the confirmation window that opens.

   The plan’s Status changes to Running, and the migration’s progress is displayed.

   Warning

   Do not take a snapshot of a VM after you start a migration. Taking a snaphot after a migration starts might cause the migration to fail.

4. Optional: Click the links in the migration’s Status to see its overall status and the status of each VM:

   • The link on the left indicates whether the migration failed, succeeded, or is ongoing. It also reports the number of VMs whose migration succeeded, failed, or was canceled.

   • The link on the right opens the Virtual Machines tab of the Plan Details page. For each VM, the tab displays the following data:

     • The name of the VM
     • The start and end times of the migration
     • The amount of data copied

     • A progress pipeline for the VM’s migration

       Warning

       vMotion, including svMotion, and relocation must be disabled for VMs that are being imported to avoid data corruption.

5. Optional: To view your migration’s logs, either as it is running or after it is completed, perform the following actions:

   1. Click the Virtual Machines tab.

   2. Click the arrow (>) to the left of the virtual machine whose migration progress you want to check.

      The VM’s details are displayed.

   3. In the Pods section, in the Pod links column, click the Logs link.

      The Logs tab opens.

      Note

      Logs are not always available. The following are common reasons for logs not being available:

      • The migration is from OpenShift Virtualization to OpenShift Virtualization. In this case, virt-v2v is not involved, so no pod is required.
      • No pod was created.
      • The pod was deleted.
      • The migration failed before running the pod.
   4. To see the raw logs, click the Raw link.
   5. To download the logs, click the Download link.

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, and 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/kubev2v/hook-runner
     serviceAccount:<service account> 1
     playbook: |
       LS0tCi0gbm... 2
   EOF

   1

   Optional: Red Hat OpenShift service account. Use the serviceAccount parameter to modify any cluster resources.

   2

   Base64-encoded Ansible Playbook. If you specify a playbook, the image must include an ansible-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. Enter the following command to create the network attachment definition (NAD) of the transfer network used for MTV migrations.

   You use this definition to configure an IP address for the interface, either from the Dynamic Host Configuration Protocol (DHCP) or statically.

   Configuring the IP address enables the interface to reach the configured gateway.

   $ oc edit NetworkAttachmentDefinitions <name_of_the_NAD_to_edit>
   apiVersion: k8s.cni.cncf.io/v1
   kind: NetworkAttachmentDefinition
   metadata:
     name: <name_of_transfer_network>
     namespace: <namespace>
     annotations:
       forklift.konveyor.io/route: <IP_address>

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:
     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_vm1> 8
       - name: <source_vm2>
         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: 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.

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

   The Plans list displays the source and target providers, the number of virtual machines (VMs) being migrated, the status, the date that the migration started, and the description of each plan.

2. Click Start beside a migration plan to start the migration.

3. Click Start in the confirmation window that opens.

   The plan’s Status changes to Running, and the migration’s progress is displayed.

   Warning

   Do not take a snapshot of a VM after you start a migration. Taking a snaphot after a migration starts might cause the migration to fail.

4. Optional: Click the links in the migration’s Status to see its overall status and the status of each VM:

   • The link on the left indicates whether the migration failed, succeeded, or is ongoing. It also reports the number of VMs whose migration succeeded, failed, or was canceled.

   • The link on the right opens the Virtual Machines tab of the Plan Details page. For each VM, the tab displays the following data:

     • The name of the VM
     • The start and end times of the migration
     • The amount of data copied

     • A progress pipeline for the VM’s migration

       Warning

       vMotion, including svMotion, and relocation must be disabled for VMs that are being imported to avoid data corruption.

5. Optional: To view your migration’s logs, either as it is running or after it is completed, perform the following actions:

   1. Click the Virtual Machines tab.

   2. Click the arrow (>) to the left of the virtual machine whose migration progress you want to check.

      The VM’s details are displayed.

   3. In the Pods section, in the Pod links column, click the Logs link.

      The Logs tab opens.

      Note

      Logs are not always available. The following are common reasons for logs not being available:

      • The migration is from OpenShift Virtualization to OpenShift Virtualization. In this case, virt-v2v is not involved, so no pod is required.
      • No pod was created.
      • The pod was deleted.
      • The migration failed before running the pod.
   4. To see the raw logs, click the Raw link.
   5. To download the logs, click the Download link.

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/kubev2v/hook-runner
     serviceAccount:<service account> 1
     playbook: |
       LS0tCi0gbm... 2
   EOF

   1

   Optional: Red Hat OpenShift service account. Use the serviceAccount parameter to modify any cluster resources.

   2

   Base64-encoded Ansible Playbook. If you specify a playbook, the image must include an ansible-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. Enter the following command to create the network attachment definition (NAD) of the transfer network used for MTV migrations.

   You use this definition to configure an IP address for the interface, either from the Dynamic Host Configuration Protocol (DHCP) or statically.

   Configuring the IP address enables the interface to reach the configured gateway.

   $ oc edit NetworkAttachmentDefinitions <name_of_the_NAD_to_edit>
   apiVersion: k8s.cni.cncf.io/v1
   kind: NetworkAttachmentDefinition
   metadata:
     name: <name_of_transfer_network>
     namespace: <namespace>
     annotations:
       forklift.konveyor.io/route: <IP_address>

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:
     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_vm1> 8
       - name: <source_vm2>
         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.

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

   The Plans list displays the source and target providers, the number of virtual machines (VMs) being migrated, the status, the date that the migration started, and the description of each plan.

2. Click Start beside a migration plan to start the migration.

3. Click Start in the confirmation window that opens.

   The plan’s Status changes to Running, and the migration’s progress is displayed.

   Warning

   Do not take a snapshot of a VM after you start a migration. Taking a snaphot after a migration starts might cause the migration to fail.

4. Optional: Click the links in the migration’s Status to see its overall status and the status of each VM:

   • The link on the left indicates whether the migration failed, succeeded, or is ongoing. It also reports the number of VMs whose migration succeeded, failed, or was canceled.

   • The link on the right opens the Virtual Machines tab of the Plan Details page. For each VM, the tab displays the following data:

     • The name of the VM
     • The start and end times of the migration
     • The amount of data copied

     • A progress pipeline for the VM’s migration

       Warning

       vMotion, including svMotion, and relocation must be disabled for VMs that are being imported to avoid data corruption.

5. Optional: To view your migration’s logs, either as it is running or after it is completed, perform the following actions:

   1. Click the Virtual Machines tab.

   2. Click the arrow (>) to the left of the virtual machine whose migration progress you want to check.

      The VM’s details are displayed.

   3. In the Pods section, in the Pod links column, click the Logs link.

      The Logs tab opens.

      Note

      Logs are not always available. The following are common reasons for logs not being available:

      • The migration is from OpenShift Virtualization to OpenShift Virtualization. In this case, virt-v2v is not involved, so no pod is required.
      • No pod was created.
      • The pod was deleted.
      • The migration failed before running the pod.
   4. To see the raw logs, click the Raw link.
   5. To download the logs, click the Download link.

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, and 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, ignored, and multus.

   2

   Specify the network name. When the type is multus, use the OpenShift Virtualization network attachment definition name.

   3

   Required only when the 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/kubev2v/hook-runner
     serviceAccount:<service account> 1
     playbook: |
       LS0tCi0gbm... 2
   EOF

   1

   Optional: Red Hat OpenShift service account. Use the serviceAccount parameter to modify any cluster resources.

   2

   Base64-encoded Ansible Playbook. If you specify a playbook, the image must include an ansible-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. Enter the following command to create the network attachment definition (NAD) of the transfer network used for MTV migrations.

   You use this definition to configure an IP address for the interface, either from the Dynamic Host Configuration Protocol (DHCP) or statically.

   Configuring the IP address enables the interface to reach the configured gateway.

   $ oc edit NetworkAttachmentDefinitions <name_of_the_NAD_to_edit>
   apiVersion: k8s.cni.cncf.io/v1
   kind: NetworkAttachmentDefinition
   metadata:
     name: <name_of_transfer_network>
     namespace: <namespace>
     annotations:
       forklift.konveyor.io/route: <IP_address>

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

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. In the Red Hat OpenShift web console, click Operators → Installed Operators → Migration Toolkit for Virtualization Operator → Subscription.

2. Change the update channel to the correct release.

   See Changing update channel in the Red Hat OpenShift documentation.

3. Confirm that Upgrade status changes from Up to date to Upgrade available. If it does not, restart the CatalogSource pod:

   1. Note the catalog source, for example, redhat-operators.

   2. From the command line, retrieve the catalog source pod:

      $ oc get pod -n openshift-marketplace | grep <catalog_source>

   3. Delete the pod:

      $ oc delete pod -n openshift-marketplace <catalog_source_pod>

      Upgrade status changes from Up to date to Upgrade available.

      If you set Update approval on the Subscriptions tab to Automatic, the upgrade starts automatically.

4. If you set Update approval on the Subscriptions tab to Manual, approve the upgrade.

   See Manually approving a pending upgrade in the Red Hat OpenShift documentation.

5. If you are upgrading from MTV 2.2 and have defined VMware source providers, edit the VMware provider by adding a VDDK init image. Otherwise, the update will change the state of any VMware providers to Critical. For more information, see Adding a VMSphere source provider.
6. If you mapped to NFS on the Red Hat OpenShift destination provider in MTV 2.2, edit the AccessModes and VolumeMode parameters in the NFS storage profile. Otherwise, the upgrade will invalidate the NFS mapping. For more information, see Customizing the storage profile.

Procedure

1. In the Red Hat OpenShift web console, click Operators > Installed Operators.

2. Click Migration Toolkit for Virtualization Operator.

   The Operator Details page opens in the Details tab.

3. Click the ForkliftController tab.

4. Click Actions and select Delete ForkLiftController.

   A confirmation window opens.

5. Click Delete.

   The controller is removed.

6. Open the Details tab.

   The Create ForkliftController button appears instead of the controller you deleted. There is no need to click it.

7. On the upper-right side of the page, click Actions and select Uninstall Operator.

   A confirmation window opens, displaying any operand instances.

8. To delete all instances, select the Delete all operand instances for this operator checkbox. By default, the checkbox is cleared.

   Important

   If your Operator configured off-cluster resources, these will continue to run and will require manual cleanup.

9. Click Uninstall.

   The Installed Operators page opens, and the Migration Toolkit for Virtualization Operator is removed from the list of installed Operators.

10. Click Home > Overview.

11. In the Status section of the page, click Dynamic Plugins.

    The Dynamic Plugins pop-up opens, listing forklift-console-plugin as a failed plugin. If the forklift-console-plugin does not appear as a failed plugin, refresh the web console.

12. Click forklift-console-plugin.

    The ConsolePlugin details page opens in the Details tab.

13. On the upper right side of the page, click Actions and select Delete ConsolePlugin from the list.

    A confirmation window opens.

14. Click Delete.

    The plugin is removed from the list of Dynamic plugins on the Overview page. If the plugin still appears, restart the Overview page.

Procedure

1. Delete the forklift controller by running the following command:

   $ oc delete ForkliftController --all -n openshift-mtv

2. Delete the subscription to the MTV Operator by running the following command:

   $ oc get subscription -o name|grep 'mtv-operator'| xargs oc delete

3. Delete the clusterserviceversion for the MTV Operator by running the following command:

   $ oc get clusterserviceversion -o name|grep 'mtv-operator'| xargs oc delete

4. Delete the plugin console CR by running the following command:

   $ oc delete ConsolePlugin forklift-console-plugin

5. Optional: Delete the custom resource definitions (CRDs) by running the following command:

   oc get crd -o name | grep 'forklift.konveyor.io' | xargs oc delete

6. Optional: Perform cleanup by deleting the MTV project by running the following command:

   oc delete project openshift-mtv

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

   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.10.0 \
       -- NS=<namespace> /usr/bin/targeted

   • Migration plan:

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

   • Virtual machine:

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

     1

     Specify the VM ID as it appears in the Plan CR.

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.