Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 9. Understanding MTV migration

Understand the Migration Toolkit for Virtualization (MTV) custom resources, services, and workflows that enable virtual machine migration to OpenShift Virtualization.

9.1. MTV custom resources and services
Copy link

The MTV Operator is provided as a Red Hat OpenShift Operator. It creates and manages the following custom resources (CRs) and services.

9.1.1. MTV custom resources
Copy link

  • Provider CR stores attributes that enable MTV to connect to and interact with the source and target providers.
  • NetworkMapping CR maps the networks of the source and target providers.
  • StorageMapping CR maps the storage of the source and target providers.
  • Plan CR contains a list of VMs with the same migration parameters and associated network and storage mappings.

  • Migration CR runs a migration plan.

    Only one Migration CR per migration plan can run at a given time. You can create multiple Migration CRs for a single Plan CR.

9.1.2. MTV services
Copy link

  • The Inventory service performs the following actions:

    • Connects to the source and target providers.
    • Maintains a local inventory for mappings and plans.
    • Stores VM configurations.
    • Runs the Validation service if a VM configuration change is detected.
  • The Validation service checks the suitability of a VM for migration by applying rules.

  • The Migration Controller service orchestrates migrations.

    When you create a migration plan, the Migration Controller service validates the plan and adds a status label. If the plan fails validation, the plan status is Not ready and the plan cannot be used to perform a migration. If the plan passes validation, the plan status is Ready and it can be used to perform a migration. After a successful migration, the Migration Controller service changes the plan status to Completed.

  • The Populator Controller service orchestrates disk transfers using Volume Populators.
  • The Kubevirt Controller and Containerized Data Import (CDI) Controller services handle most technical operations.

9.2. High-level migration workflow
Copy link

The high-level workflow shows the migration process from the point of view of the user:

  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.

9.2.1. Detailed migration workflows
Copy link

You can use the detailed migration workflows to troubleshoot a failed migration.

Warm migration or migration to a remote OpenShift cluster:

  1. When you create the Migration custom resource (CR) to run a migration plan, the Migration Controller service creates a DataVolume CR for each source VM disk.

    For each VM disk:

  2. The Containerized Data Importer (CDI) Controller service creates a persistent volume claim (PVC) based on the parameters specified in the DataVolume CR.
  3. If the StorageClass has a dynamic provisioner, the persistent volume (PV) is dynamically provisioned by the StorageClass provisioner.
  4. The CDI Controller service creates an importer pod.

  5. The importer pod streams the VM disk to the PV.

    After the VM disks are transferred:

  6. The Migration Controller service creates a conversion pod with the PVCs attached to it when importing from VMware.

    The conversion pod runs virt-v2v, which installs and configures device drivers on the PVCs of the target VM.

  7. The Migration Controller service creates a VirtualMachine CR for each source virtual machine (VM), connected to the PVCs.

  8. If the VM ran on the source environment, the Migration Controller powers on the VM, the KubeVirt Controller service creates a virt-launcher pod and a VirtualMachineInstance CR.

    The virt-launcher pod runs QEMU-KVM with the PVCs attached as VM disks.

Cold migration from Red Hat Virtualization or OpenStack to the local OpenShift cluster:

  1. When you create a Migration custom resource (CR) to run a migration plan, the Migration Controller service creates for each source VM disk a PersistentVolumeClaim CR, and an OvirtVolumePopulator when the source is RHV, or an OpenstackVolumePopulator CR when the source is OpenStack.

    For each VM disk:

  2. The Populator Controller service creates a temporarily persistent volume claim (PVC).

  3. If the StorageClass has a dynamic provisioner, the persistent volume (PV) is dynamically provisioned by the StorageClass provisioner.

    • The Migration Controller service creates a dummy pod to bind all PVCs. The name of the pod contains pvcinit.
  4. The Populator Controller service creates a populator pod.

  5. The populator pod transfers the disk data to the PV.

    After the VM disks are transferred:

  6. The temporary PVC is deleted, and the initial PVC points to the PV with the data.
  7. The Migration Controller service creates a VirtualMachine CR for each source virtual machine (VM), connected to the PVCs.

  8. If the VM ran on the source environment, the Migration Controller powers on the VM, the KubeVirt Controller service creates a virt-launcher pod and a VirtualMachineInstance CR.

    The virt-launcher pod runs QEMU-KVM with the PVCs attached as VM disks.

Cold migration from VMware to the local OpenShift cluster:

  1. When you create a Migration custom resource (CR) to run a migration plan, the Migration Controller service creates a DataVolume CR for each source VM disk.

    For each VM disk:

  2. The Containerized Data Importer (CDI) Controller service creates a blank persistent volume claim (PVC) based on the parameters specified in the DataVolume CR.

  3. If the StorageClass has a dynamic provisioner, the persistent volume (PV) is dynamically provisioned by the StorageClass provisioner.

    For all VM disks:

  4. The Migration Controller service creates a dummy pod to bind all PVCs. The name of the pod contains pvcinit.
  5. The Migration Controller service creates a conversion pod for all PVCs.

  6. The conversion pod runs virt-v2v, which converts the VM to the KVM hypervisor and transfers the disks' data to their corresponding PVs.

    After the VM disks are transferred:

  7. The Migration Controller service creates a VirtualMachine CR for each source virtual machine (VM), connected to the PVCs.

  8. If the VM ran on the source environment, the Migration Controller powers on the VM, the KubeVirt Controller service creates a virt-launcher pod and a VirtualMachineInstance CR.

    The virt-launcher pod runs QEMU-KVM with the PVCs attached as VM disks.

9.3. How MTV uses the virt-v2v tool
Copy link

The Migration Toolkit for Virtualization (MTV) uses the virt-v2v tool to convert the disk image of a virtual machine (VM) into a format compatible with OpenShift Virtualization. The tool makes migrations easier because it automatically performs the tasks needed to make your VMs work with OpenShift Virtualization. For example, enabling paravirtualized VirtIO drivers in the converted VM, if possible, and installing the QEMU guest agent.

virt-v2v is included in Red Hat Enterprise Linux (RHEL) versions 7 and later.

During migration, MTV uses virt-v2v to collect metadata about VMs, make necessary changes to VM disks, and copy the disks containing the VMs to OpenShift Virtualization.

virt-v2v makes the following changes to VM disks to prepare them for migration:

  • Additions:

    • Injection of VirtIO drivers, for example, network or disk drivers.
    • Preparation of hypervisor-specific tools or agents, for example, a QEMU guest agent installation.
    • Modification of boot configuration, for example, updated boot loader or boot entries.

  • Removals:

    • Unnecessary or former hypervisor-specific files, for example, VMware tools or VirtualBox additions.
    • Old network driver configurations, for example, removing VMware-specific NIC drivers.
    • Configuration settings that are incompatible with the target system, for example, old boot settings.

If you are migrating from VMware or from Open Virtual Appliances (OVA) files, virt-v2v also sets their IP addresses either during the migration or during the first reboot of the VMs after migration.

Note

You can also run predefined Ansible hooks before or after a migration using MTV. For more information, see the "Additional resources" section.

These hooks do not necessarily use virt-v2v.

9.3.2. Customizing, removing, and installing files
Copy link

MTV uses virt-v2v to perform additional guest customizations during the conversion, such as the following actions:

  • Customization to preserve IP addresses
  • Customization to preserve drive letters
Note

For Red Hat Enterprise Linux (RHEL)-based guests, virt-v2v attempts to install the guest agent from the Red Hat registry. If the migration is run in a detached environment, the installation program fails, and you must use hooks or other automation to install the guest agent.

9.3.3. Permissions and virt-v2v
Copy link

virt-v2v does not require permissions or access credentials for the guest operating system itself because virt-v2v is not run against a running VM, but only against the disks of a VM.

9.4. Raw copy mode
Copy link

In regular cold and warm migrations, Migration Toolkit for Virtualization (MTV) uses a program called virt-v2v to convert the disk image of virtual machines (VMs) into a format compatible with OpenShift Virtualization after the VMs have been copied from their source provider.

Although virt-v2v is compatible with major operating systems such as recent versions of Red Hat Enterprise Linux, Windows, and Windows Server, it is not compatible with macOS and some other operating systems.

As a workaround for migrating VMs that use an operating system that virt-v2v does not support, MTV includes a feature called raw copy mode. Raw copy mode copies VMs without conversion for use with OpenShift Virtualization. The migrated VMs use emulated devices.

This enables more robust migrations, enabling a wider range of operating systems and configurations. Examples are VMs with uncommon file systems, VMs with uncommon encryption technologies or without access to keys.

However, VMs migrated using raw copy mode might not boot on OpenShift Virtualization or perform as well as VMs migrated in the regular way.

Therefore, using raw copy mode is a tradeoff between being a more versatile migration option compared to increasing the risk of problems following migration.

Because of this risk, users are asked to request that Red Hat support perform raw copy mode migrations.

When you use raw copy mode, you can configure which device types MTV uses for migrated VMs through the Use compatibility mode setting.

Compatibility devices (default)

By default, when you enable raw copy mode, MTV uses compatibility devices to ensure VMs can boot on OpenShift Virtualization:

  • SATA bus for disk controllers
  • E1000E NICs for network interfaces

  • USB controllers

    These emulated devices work without requiring additional drivers in the guest operating system, ensuring maximum bootability for migrated VMs.

VirtIO devices

For source VMs that already have VirtIO drivers installed, you can disable compatibility mode to use VirtIO devices instead. VirtIO devices provide better performance:

  • VirtIO disk bus provides higher I/O throughput than SATA

  • VirtIO network interface provides better network performance than E1000E

    Important

    The Use compatibility mode setting only applies when you enable raw copy mode. When you disable raw copy mode (standard V2V conversion), MTV always uses VirtIO devices regardless of this setting.

    Warning

    Before you disable compatibility mode, verify that VirtIO drivers are installed in the source VM. VMs without VirtIO drivers do not boot on OpenShift Virtualization if you disable compatibility mode.

When to disable compatibility mode

Consider disabling compatibility mode when:

  • Your source VMs are running modern operating systems with VirtIO drivers pre-installed, for example, recent versions of Red Hat Enterprise Linux or Windows with VirtIO drivers
  • Maximum performance is required for your workload
  • You have verified VirtIO driver presence in the source VM before migration
Configuring compatibility mode
You can configure the compatibility mode setting when you create a migration plan.
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Legal Notice

Theme

© 2026 Red HatBack to top