Chapter 4. Migrating virtual machines by using the MTV web console

You can migrate virtual machines (VMs) to OpenShift Virtualization by using the MTV web console.

Important

You must ensure that all prerequisites are met.

4.1. Adding providers

You can add providers by using the MTV web console.

4.1.1. Adding a VMware source provider

You can add a VMware source provider by using the MTV web console.

Prerequisites

  • You must have VMware admin privileges.
  • vCenter SHA-1 fingerprint.
  • VMware Virtual Disk Development Kit (VDDK) image in a secure registry that is accessible to all clusters.

Procedure

  1. Add the VDDK image to the HyperConverged CR: 

    $ cat << EOF | oc apply -f -
apiVersion: hco.kubevirt.io/v1beta1
kind: HyperConverged
metadata:
  name: kubevirt-hyperconverged
  namespace: openshift-cnv
spec:
  vddkInitImage: <registry_route_or_server_path>/vddk:<tag> 1
EOF
    1
    Specify the VDDK image that you created.
  2. In the MTV web console, click Providers.
  3. Click Add provider.
  4. Select VMware from the Type list.

  5. Fill in the following fields:

    • Name: Name to display in the list of providers
    • Hostname or IP address: vCenter host name or IP address
    • Username: vCenter admin user, for example, administrator@vsphere.local
    • Password: vCenter admin password
    • SHA-1 fingerprint: vCenter SHA-1 fingerprint

  6. Click Add to add and save the provider.

    The source provider appears in the list of providers.

4.1.1.1. Selecting a migration network for a VMware source provider

You can select a migration network in the MTV web console for a VMware source provider to reduce risk to the source environment and to improve performance.

Using the default network for migration can result in poor performance because the network might not have sufficient bandwidth. This situation can have a negative effect on the source platform because the disk transfer operation might saturate the network.

Prerequisites

  • The migration network must have sufficient throughput, minimum speed of 10 Gbps, for disk transfer.

  • The migration network must be accessible to the OpenShift Virtualization nodes through the default gateway.

    Note

    The source virtual disks are copied by a pod that is connected to the pod network of the target namespace.

  • The migration network must have jumbo frames enabled.

Procedure

  1. In the MTV web console, click Providers
  2. Click the VMware tab.
  3. Click the host number in the Hosts column beside a provider to view a list of hosts.
  4. Select one or more hosts and click Select migration network.

  5. Select a Network.

    You can clear the selection by selecting the default network.

  6. If your source provider is VMware, complete the following fields:

    • ESXi host admin username: Specify the ESXi host admin user, for example, root.
    • ESXi host admin password: Specify the ESXi host admin password.

  7. If your source provider is Red Hat Virtualization, complete the following fields:

    • Username: Specify the Manager user.
    • Password: Specify the Manager password.
  8. Click Save.

  9. Verify that the status of each host is Ready.

    If a host status is not Ready, the host might be unreachable on the migration network or the credentials might be incorrect. You can modify the host configuration and save the changes.

4.1.2. Adding a Red Hat Virtualization source provider

You can add a Red Hat Virtualization source provider by using the MTV web console.

Prerequisites

  • CA certificate of the Manager.

Procedure

  1. In the MTV web console, click Providers.
  2. Click Add provider.
  3. Select Red Hat Virtualization from the Type list.

  4. Fill in the following fields:

    • Name: Name to display in the list of providers
    • Hostname or IP address: Manager host name or IP address
    • Username: Manager user
    • Password: Manager password
    • CA certificate: CA certificate of the Manager

  5. Click Add to add and save the provider.

    The source provider appears in the list of providers.

4.1.3. Adding an OpenShift Virtualization provider

You can add an OpenShift Virtualization provider to the MTV web console in addition to the default OpenShift Virtualization provider, which is the provider where you installed MTV.

Prerequisites

Procedure

  1. In the MTV web console, click Providers.
  2. Click Add provider.
  3. Select OpenShift Virtualization from the Type list.

  4. Complete the following fields:

    • Cluster name: Specify the cluster name to display in the list of target providers.
    • URL: Specify the API endpoint of the cluster.
    • Service account token: Specify the cluster-admin service account token.
  5. Click Check connection to verify the credentials.

  6. Click Add.

    The provider appears in the list of providers.

4.1.3.1. Selecting a migration network for an OpenShift Virtualization provider

You can select a default migration network for an OpenShift Virtualization provider in the MTV web console to improve performance. The default migration network is used to transfer disks to the namespaces in which it is configured.

If you do not select a migration network, the default migration network is the pod network, which might not be optimal for disk transfer.

Note

You can override the default migration network of the provider by selecting a different network when you create a migration plan.

Procedure

  1. In the MTV web console, click Providers.
  2. Click the OpenShift Virtualization tab.
  3. Select a provider and click Select migration network.
  4. Select a network from the list of available networks and click Select.
  5. Click the network number in the Networks column beside the provider to verify that the selected network is the default migration network.

4.2. Creating a network mapping

You can create one or more network mappings by using the MTV web console to map source networks to OpenShift Virtualization networks.

Prerequisites

  • Source and target providers added to the web console.
  • If you map more than one source and target network, each additional OpenShift Virtualization network requires its own network attachment definition.

Procedure

  1. Click Mappings.
  2. Click the Network tab and then click Create mapping.

  3. Complete the following fields:

    • Name: Enter a name to display in the network mappings list.
    • Source provider: Select a source provider.
    • Target provider: Select a target provider.
    • Source networks: Select a source network.
    • Target namespaces/networks: Select a target network.
  4. Optional: Click Add to create additional network mappings or to map multiple source networks to a single target network.
  5. If you create an additional network mapping, select the network attachment definition as the target network.

  6. Click Create.

    The network mapping is displayed on the Network mappings screen.

4.3. Creating a storage mapping

You can create a storage mapping by using the MTV web console to map source data stores to OpenShift Virtualization storage classes.

Prerequisites

  • Source and target providers added to the web console.
  • Local and shared persistent storage that support VM migration.

Procedure

  1. Click Mappings.
  2. Click the Storage tab and then click Create mapping.
  3. Enter the Name of the storage mapping.
  4. Select a Source provider and a Target provider.
  5. If your source provider is VMware, select a Source datastore and a Target storage class.
  6. If your source provider is Red Hat Virtualization, select a Source storage domain and a Target storage class.
  7. Optional: Click Add to create additional storage mappings or to map multiple source data stores or storage domains to a single storage class.

  8. Click Create.

    The mapping is displayed on the Storage mappings page.

4.4. Creating a migration plan

You can create a migration plan by using the MTV web console.

A migration plan allows you to group virtual machines to be migrated together or with the same migration parameters, for example, a percentage of the members of a cluster or a complete application.

You can configure a hook to run an Ansible playbook or custom container image during a specified stage of the migration plan.

Prerequisites

  • If MTV is not installed on the target cluster, you must add a target provider on the Providers page of the web console.

Procedure

  1. In the web console, click Migration plans and then click Create migration plan.

  2. Complete the following fields:

    • Plan name: Enter a migration plan name to display in the migration plan list.
    • Plan description: Optional: Brief description of the migration plan.
    • Source provider: Select a source provider.
    • Target provider: Select a target provider.
    • Target namespace: You can type to search for an existing target namespace or create a new namespace.

    • You can change the migration transfer network for this plan by clicking Select a different network, selecting a network from the list, and clicking Select.

      If you defined a migration transfer network for the OpenShift Virtualization provider and if the network is in the target namespace, that network is the default network for all migration plans. Otherwise, the pod network is used.

  3. Click Next.
  4. Select options to filter the list of source VMs and click Next.
  5. Select the VMs to migrate and then click Next.

  6. Select an existing network mapping or create a new network mapping.

    To create a new network mapping:

    • Select a target network for each source network.
    • Optional: Select Save mapping to use again and enter a network mapping name.
  7. Click Next.

  8. Select an existing storage mapping or create a new storage mapping.

    To create a new storage mapping:

    • Select a target storage class for each VMware data store or Red Hat Virtualization storage domain.
    • Optional: Select Save mapping to use again and enter a storage mapping name.
  9. Click Next.

  10. Select a migration type and click Next.

    • Cold migration: The source VMs are stopped while the data is copied.
    • Warm migration: The source VMs run while the data is copied incrementally. Later, you will run the cutover, which stops the VMs and copies the remaining VM data and metadata. Warm migration is not supported for Red Hat Virtualization.

  11. Optional: You can create a migration hook to run an Ansible playbook before or after migration:

    1. Click Add hook.
    2. Select the step when the hook will run.

    3. Select a hook definition:

      • Ansible playbook: Browse to the Ansible playbook or paste it into the field.

      • Custom container image: If you do not want to use the default hook-runner image, enter the image path: <registry_path>/<image_name>:<tag>.

        Note

        The registry must be accessible to your OpenShift Container Platform cluster.

  12. Click Next.

  13. Review your migration plan and click Finish.

    The migration plan is saved in the migration plan list.

  14. Click the Options menu kebab of the migration plan and select View details to verify the migration plan details.

4.5. Running a migration plan

You can run a migration plan and view its progress in the MTV web console.

Prerequisites

  • Valid migration plan.

Procedure

  1. Click Migration plans.

    The Migration plans list displays the source and target providers, the number of virtual machines (VMs) being migrated, and the status of the plan.

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

    Warm migration only:

    • The precopy stage starts.
    • Click Cutover to complete the migration.

  3. Expand a migration plan to view the migration details.

    The migration details screen displays the migration start and end time, the amount of data copied, and a progress pipeline for each VM being migrated.

  4. Expand a VM to view the migration steps, elapsed time of each step, and its state.

4.6. Migration plan options

On the Migration plans page of the MTV web console, you can click the Options menu kebab beside a migration plan to access the following options:

  • Edit: Edit the details of a migration plan. You cannot edit a migration plan while it is running or after it has completed successfully.

  • Duplicate: Create a new migration plan with the same virtual machines (VMs), parameters, mappings, and hooks as an existing plan. You can use this feature for the following tasks:

    • Migrate VMs to a different namespace.
    • Edit an archived migration plan.
    • Edit a migration plan with a different status, for example, failed, canceled, running, critical, or ready.

  • Archive: Delete the logs, history, and metadata of a migration plan. The plan cannot be edited or restarted. It can only be viewed.

    Note

    The Archive option is irreversible. However, you can duplicate an archived plan.

  • Delete: Permanently remove a migration plan. You cannot delete a running migration plan.

    Note

    The Delete option is irreversible.

    Deleting a migration plan does not remove temporary resources such as importer pods, conversion pods, config maps, secrets, failed VMs, and data volumes. (BZ#2018974) You must archive a migration plan before deleting it in order to clean up the temporary resources.

  • View details: Display the details of a migration plan.
  • Restart: Restart a failed or canceled migration plan.
  • Cancel scheduled cutover: Cancel a scheduled cutover migration for a warm migration plan.

4.7. Canceling a migration

You can cancel the migration of some or all virtual machines (VMs) while a migration plan is in progress by using the MTV web console.

Procedure

  1. Click Migration Plans.
  2. Click the name of a running migration plan to view the migration details.
  3. Select one or more VMs and click Cancel.

  4. Click Yes, cancel to confirm the cancellation.

    In the Migration details by VM list, the status of the canceled VMs is Canceled. The unmigrated and the migrated virtual machines are not affected.

You can restart a canceled migration by clicking Restart beside the migration plan on the Migration plans page.