Chapter 4. Migrating virtual machines by using the Red Hat OpenShift web console

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

Important

You must ensure that all prerequisites are met.

VMware only: You must have the minimal set of VMware privileges.

VMware only: Creating a VMware Virtual Disk Development Kit (VDDK) image will increase migration speed.

4.1. The MTV user interface

The Migration Toolkit for Virtualization (MTV) user interface is integrated into the OpenShift web console.

In the left-hand panel, you can choose a page related to a component of the migration progress, for example, Providers for Migration, or, if you are an administrator, you can choose Overview, which contains information about migrations and lets you configure MTV settings.

Figure 4.1. MTV extension interface

MTV user interface

In pages related to components, you can click on the Projects list, which is in the upper-left portion of the page, and see which projects (namespaces) you are allowed to work with.

  • If you are an administrator, you can see all projects.
  • If you are a non-administrator, you can see only the projects that you have permissions to work with.

4.2. The MTV Overview page

The Migration Toolkit for Virtualization (MTV) Overview page displays system-wide information about migrations and a list of Settings you can change.

If you have Administrator privileges, you can access the Overview page by clicking MigrationOverview in the Red Hat OpenShift web console.

The Overview page displays the following information:

  • Migrations: The number of migrations performed using MTV:

    • Total
    • Running
    • Failed
    • Succeeded
    • Canceled
  • Virtual Machine Migrations: The number of VMs migrated using MTV:

    • Total
    • Running
    • Failed
    • Succeeded
    • Canceled
  • Operator: The namespace on which the MTV Operator is deployed and the status of the Operator.
  • Conditions: Status of the MTV Operator:

    • Failure: Last failure. False indicates no failure since deployment.
    • Running: Whether the Operator is currently running and waiting for the next reconciliation.
    • Successful: Last successful reconciliation.

4.3. Configuring MTV settings

If you have Administrator privileges, you can access the Overview page and change the following settings in it:

Table 4.1. MTV settings

SettingDescriptionDefault value

Max concurrent virtual machine migrations

The maximum number of VMs per plan that can be migrated simultaneously

20

Must gather cleanup after (hours)

The duration for retaining must gather reports before they are automatically deleted

Disabled

Controller main container CPU limit

The CPU limit allocated to the main controller container

500 m

Controller main container Memory limit

The memory limit allocated to the main controller container

800 Mi

Precopy internal (minutes)

The interval at which a new snapshot is requested before initiating a warm migration

60

Snapshot polling interval (seconds)

The frequency with which the system checks the status of snapshot creation or removal during a warm migration

10

Procedure

  1. In the Red Hat OpenShift web console, click MigrationOverview. The Settings list is on the right-hand side of the page.
  2. In the Settings list, click the Edit icon of the setting you want to change.
  3. Choose a setting from the list.
  4. Click Save.

4.4. Adding providers

You can add source providers and destination providers for a virtual machine migration by using the Red Hat OpenShift web console.

4.4.1. Adding source providers

You can use MTV to migrate VMs from the following source providers:

  • VMware vSphere
  • Red Hat Virtualization
  • OpenStack
  • Open Virtual Appliances (OVAs) that were created by VMware vSphere
  • OpenShift Virtualization

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

4.4.1.1. Adding a VMware vSphere source provider

You can add a VMware vSphere source provider by using the Red Hat OpenShift web console.

Important

EMS enforcement is disabled for migrations with VMware vSphere source providers in order to enable migrations from versions of vSphere that are supported by Migration Toolkit for Virtualization but do not comply with the 2023 FIPS requirements. Therefore, users should consider whether migrations from vSphere source providers risk their compliance with FIPS. Supported versions of vSphere are specified in Software compatibility guidelines.

Prerequisites

  • VMware Virtual Disk Development Kit (VDDK) image in a secure registry that is accessible to all clusters.

Procedure

  1. In the Red Hat OpenShift web console, click MigrationProviders for virtualization.
  2. Click Create Provider.
  3. Click vSphere.
  4. Specify the following fields:

    • Provider resource name: Name of the source provider.
    • URL: URL of the SDK endpoint of the vCenter on which the source VM is mounted. Ensure that the URL includes the sdk path, usually /sdk. For example, https://vCenter-host-example.com/sdk. If a certificate for FQDN is specified, the value of this field needs to match the FQDN in the certificate.
    • VDDK init image: VDDKInitImage path. It is strongly recommended to create a VDDK init image to accelerate migrations. For more information, see Creating a VDDK image.
    • Username: vCenter user. For example, user@vsphere.local.
    • Password: vCenter user password.
    • SHA-1 fingerprint: The provider currently requires the SHA-1 fingerprint of the vCenter Server’s TLS certificate in all circumstances. vSphere calls this the server’s thumbprint.
  5. Choose one of the following options for validating CA certificates:

    • Skip certificate validation : Migrate without validating a CA certificate.
    • Use the system CA certificates: Migrate after validating the system CA certificates.

      1. To skip certificate validation, select the Skip certificate validation check box.
      2. To validate the system CA certificates, leave the Skip certificate validation check box cleared.
  6. Click Create to add and save the provider.

    The provider appears in the list of providers.

4.4.1.1.1. Selecting a migration network for a VMware source provider

You can select a migration network in the Red Hat OpenShift web console for a 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 Red Hat OpenShift web console, click MigrationProviders for virtualization.
  2. Click the host number in the Hosts column beside a provider to view a list of hosts.
  3. Select one or more hosts and click Select migration network.
  4. Specify the following fields:

    • Network: Network name
    • ESXi host admin username: For example, root
    • ESXi host admin password: Password
  5. Click Save.
  6. 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.4.1.2. Adding a Red Hat Virtualization source provider

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

Prerequisites

  • Manager CA certificate, unless it was replaced by a third-party certificate, in which case, specify the Manager Apache CA certificate

Procedure

  1. In the Red Hat OpenShift web console, click MigrationProviders for virtualization.
  2. Click Create Provider.
  3. Click Red Hat Virtualization
  4. Specify the following fields:

    • Provider resource name: Name of the source provider.
    • URL: URL of the API endpoint of the Red Hat Virtualization Manager (RHVM) on which the source VM is mounted. Ensure that the URL includes the path leading to the RHVM API server, usually /ovirt-engine/api. For example, https://rhv-host-example.com/ovirt-engine/api.
    • Username: Username.
    • Password: Password.
  5. Choose one of the following options for validating CA certificates:

    • Skip certificate validation : Migrate without validating a CA certificate.
    • Use a custom CA certificate: Migrate after validating a custom CA certificate.

      1. To skip certificate validation, select the Skip certificate validation check box.
      2. To validate a custom CA certificate, leave the Skip certificate validation check box cleared and either drag the CA certificate to the text box or browse for it and click Select.
  6. Click Create to add and save the provider.

    The provider appears in the list of providers.

4.4.1.3. Adding an OpenStack source provider

You can add an OpenStack source provider by using the Red Hat OpenShift web console.

Note

Migration using OpenStack source providers only supports VMs that use only Cinder volumes.

Procedure

  1. In the Red Hat OpenShift web console, click MigrationProviders for virtualization.
  2. Click Create Provider.
  3. Click OpenStack.
  4. Specify the following fields:

    • Provider resource name: Name of the source provider.
    • URL: URL of the OpenStack Identity (Keystone) endpoint. For example, http://controller:5000/v3.
    • Authentication type: Choose one of the following methods of authentication and supply the information related to your choice. For example, if you choose Application credential ID as the authentication type, the Application credential ID and the Application credential secret fields become active, and you need to supply the ID and the secret.

      • Application credential ID

      • Application credential name

        • Application credential name: OpenStack application credential name
        • Application credential secret: : OpenStack application credential Secret
        • Username: OpenStack username
        • Domain: OpenStack domain name
      • Token with user ID

        • Token: OpenStack token
        • User ID: OpenStack user ID
        • Project ID: OpenStack project ID
      • Token with user Name

        • Token: OpenStack token
        • Username: OpenStack username
        • Project: OpenStack project
        • Domain name: OpenStack domain name
      • Password

        • Username: OpenStack username
        • Password: OpenStack password
        • Project: OpenStack project
        • Domain: OpenStack domain name
  5. Choose one of the following options for validating CA certificates:

    • Skip certificate validation : Migrate without validating a CA certificate.
    • Use a custom CA certificate: Migrate after validating a custom CA certificate.

      1. To skip certificate validation, select the Skip certificate validation check box.
      2. To validate a custom CA certificate, leave the Skip certificate validation check box cleared and either drag the CA certificate to the text box or browse for it and click Select.
  6. Click Create to add and save the provider.

    The provider appears in the list of providers.

4.4.1.4. Adding an Open Virtual Appliance (OVA) source provider

You can add Open Virtual Appliance (OVA) files that were created by VMware vSphere as a source provider by using the Red Hat OpenShift web console.

Migration using one or more Open Virtual Appliance (OVA) files as a source provider is a Technology Preview.

Important

Migration using one or more Open Virtual Appliance (OVA) files as a source provider is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/.

Procedure

  1. In the Red Hat OpenShift web console, click MigrationProviders for virtualization.
  2. Click Create Provider.
  3. Click Open Virtual Appliance (OVA).
  4. Specify the following fields:

    • Provider resource name: Name of the source provider
    • URL: URL of the NFS file share that serves the OVA
  5. Click Create to add and save the provider.

    The provider appears in the list of providers.

    Note

    An error message might appear that states that an error has occurred. You can ignore this message.

4.4.1.5. Adding a Red Hat OpenShift Virtualization source provider

You can use a Red Hat OpenShift Virtualization provider as both a source provider and destination provider.

Specifically, the host cluster that is automatically added as a OpenShift Virtualization provider can be used as both a source provider and a destination provider.

You can migrate VMs from the cluster that MTV is deployed on to another cluster, or from a remote cluster to the cluster that MTV is deployed on.

Procedure

  1. In the Red Hat OpenShift web console, click MigrationProviders for virtualization.
  2. Click Create Provider.
  3. Click OpenShift Virtualization.
  4. Specify the following fields:

    • Provider resource name: Name of the source provider
    • URL: URL of the endpoint of the API server
    • Service account bearer token: Token for a service account with cluster-admin privileges

      If both URL and Service account bearer token are left blank, the local OpenShift cluster is used.

  5. Click Create to add and save the provider.

    The provider appears in the list of providers.

4.4.2. Adding destination providers

You can add a OpenShift Virtualization destination provider by using the Red Hat OpenShift web console.

4.4.2.1. Adding an OpenShift Virtualization destination provider

You can use a Red Hat OpenShift Virtualization provider as both a source provider and destination provider.

Specifically, the host cluster that is automatically added as a OpenShift Virtualization provider can be used as both a source provider and a destination provider.

You can also add another OpenShift Virtualization destination provider to the Red Hat OpenShift web console in addition to the default OpenShift Virtualization destination provider, which is the cluster where you installed MTV.

You can migrate VMs from the cluster that MTV is deployed on to another cluster, or from a remote cluster to the cluster that MTV is deployed on.

Prerequisites

Procedure

  1. In the Red Hat OpenShift web console, click MigrationProviders for virtualization.
  2. Click Create Provider.
  3. Click OpenShift Virtualization.
  4. Specify the following fields:

    • Provider resource name: Name of the source provider
    • URL: URL of the endpoint of the API server
    • Service account bearer token: Token for a service account with cluster-admin privileges

      If both URL and Service account bearer token are left blank, the local OpenShift cluster is used.

  5. Click Create to add and save the provider.

    The provider appears in the list of providers.

4.4.2.2. Selecting a migration network for an OpenShift Virtualization provider

You can select a default migration network for an OpenShift Virtualization provider in the Red Hat OpenShift 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 Red Hat OpenShift web console, click MigrationProviders for virtualization.
  2. On the right side of the provider, select Select migration network from the Options menu kebab .
  3. Select a network from the list of available networks and click Select.

4.5. Creating a network mapping

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

Prerequisites

  • Source and target providers added to the Red Hat OpenShift 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. In the Red Hat OpenShift web console, click MigrationNetworkMaps for virtualization.
  2. Click Create NetworkMap.
  3. Specify 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.
  4. Select a Source network and a Target namespace/network.
  5. Optional: Click Add to create additional network mappings or to map multiple source networks to a single target network.
  6. If you create an additional network mapping, select the network attachment definition as the target network.
  7. Click Create.

    The network mapping is displayed on the NetworkMaps screen.

4.6. Creating a storage mapping

You can create a storage mapping by using the Red Hat OpenShift web console to map source disk storages to OpenShift Virtualization storage classes.

Prerequisites

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

Procedure

  1. In the Red Hat OpenShift web console, click MigrationStorageMaps for virtualization.
  2. Click Create StorageMap.
  3. Specify the following fields:

    • Name: Enter a name to display in the storage mappings list.
    • Source provider: Select a source provider.
    • Target provider: Select a target provider.
  4. To create a storage mapping, click Add and map storage sources to target storage classes as follows:

    1. If your source provider is VMware vSphere, select a Source datastore and a Target storage class.
    2. If your source provider is Red Hat Virtualization, select a Source storage domain and a Target storage class.
    3. If your source provider is OpenStack, select a Source volume type and a Target storage class.
    4. If your source provider is a set of one or more OVA files, select a Source and a Target storage class for the dummy storage that applies to all virtual disks within the OVA files.
    5. If your storage provider is OpenShift Virtualization. select a Source storage class and a Target storage class.
    6. Optional: Click Add to create additional storage mappings, including mapping multiple storage sources to a single target storage class.
  5. Click Create.

    The mapping is displayed on the StorageMaps page.

4.7. Creating a migration plan

You can create a migration plan by using the Red Hat OpenShift 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 Red Hat OpenShift web console, click MigrationPlans for virtualization.
  2. Click Create plan.
  3. Specify 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: Do one of the following:

      • Select a target namespace from the list
      • Create a target namespace by typing its name in the text box, and then clicking create "<the_name_you_entered>"
    • You can change the migration transfer network for this plan by clicking Select a different network, selecting a network from the list, and then clicking Select.

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

  4. Click Next.
  5. Select options to filter the list of source VMs and click Next.
  6. Select the VMs to migrate and then click Next.
  7. Select an existing network mapping or create a new network mapping.
  8. . Optional: Click Add to add an additional network mapping.

    To create a new network mapping:

    • Select a target network for each source network.
    • Optional: Select Save current mapping as a template and enter a name for the network mapping.
  9. Click Next.
  10. Select an existing storage mapping, which you can modify, or create a new storage mapping.

    To create a new storage mapping:

    1. If your source provider is VMware, select a Source datastore and a Target storage class.
    2. If your source provider is Red Hat Virtualization, select a Source storage domain and a Target storage class.
    3. If your source provider is OpenStack, select a Source volume type and a Target storage class.
  11. Optional: Select Save current mapping as a template and enter a name for the storage mapping.
  12. Click Next.
  13. 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.

      Note

      Warm migration is supported only from vSphere and Red Hat Virtualization.

  14. Click Next.
  15. 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 be run: pre-migration or post-migration.
    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 Red Hat OpenShift cluster.

  16. Click Next.
  17. Review your migration plan and click Finish.

    The migration plan is saved on the Plans page.

    You can click the Options menu kebab of the migration plan and select View details to verify the migration plan details.

4.8. Running a migration plan

You can run a migration plan and view its progress in the Red Hat OpenShift web console.

Prerequisites

  • Valid migration plan.

Procedure

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

    The Plans list displays the source and target providers, the number of virtual machines (VMs) being migrated, the status, 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 Migration details by VM screen opens, displaying the migration’s progress

    Warm migration only:

    • The precopy stage starts.
    • Click Cutover to complete the migration.
  4. If the migration fails:

    1. Click Get logs to retrieve the migration logs.
    2. Click Get logs in the confirmation window that opens.
    3. Wait until Get logs changes to Download logs and then click the button to download the logs.
  5. Click a migration’s Status, whether it failed or succeeded or is still ongoing, to view the details of the migration.

    The Migration details by VM screen opens, displaying the start and end times of the migration, the amount of data copied, and a progress pipeline for each VM being migrated.

  6. Expand an individual VM to view its steps and the elapsed time and state of each step.

4.9. Migration plan options

On the Plans for virtualization page of the Red Hat OpenShift web console, you can click the Options menu kebab beside a migration plan to access the following options:

  • Get logs: Retrieves the logs of a migration. When you click Get logs, a confirmation window opens. After you click Get logs in the window, wait until Get logs changes to Download logs and then click the button to download the logs.
  • 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.10. 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 Red Hat OpenShift web console.

Procedure

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