Troubleshooting Failed DiskTransfer: Resolving VDDK Connection Errors During VMware to OpenShift Warm Migration

The Issue

Migrating virtual machines from VMware vSphere to Red Hat OpenShift Virtualization is generally a streamlined process using the Migration Toolkit for Virtualization (MTV). However, during warm migrations of Windows workloads, administrators may encounter a critical failure during the DiskTransfer phase.

The migration fails, and the logs from the MVT (Migration for Virtualization) tool or the controller pod display the following error:

“Warm migration fails on 'Disk transfer' phase with this message:

Unable to connect to vddk data source: disk xxxx.vmdk' is not present in VM hardware config or snapshot list"

This error prevents the synchronization of data, causing the migration plan to fail.

Root Cause Analysis: The Role of disk.EnableUUID

The root cause of this connectivity failure often lies in the VMware virtual machine configuration, specifically the advanced parameter disk.EnableUUID.

What is disk.EnableUUID?

In VMware vSphere, disk.EnableUUID is an advanced configuration parameter. When set to true, it exposes the virtual disk's unique identifier (UUID) to the Guest Operating System (Windows).

This setting is commonly enabled for:

1. Application-Consistent Backups: It allows Volume Shadow Copy Service (VSS) to uniquely identify disks to create consistent snapshots.

2. Application Requirements: certain database applications and monitoring tools require a unique serial number for every disk to function or cluster correctly.

Why does this cause the migration to fail?

The Migration Toolkit utilizes the Virtual Disk Development Kit (VDDK) to stream data from vSphere to OpenShift.

When disk.EnableUUID is set to true, the guest OS (Windows) maintains a stricter lock and identification mapping on the virtual disks to ensure VSS consistency. During a warm migration, the MTV tool attempts to establish a connection to the disk files (VMDKs) via the VDDK API.

The conflict arises because the VSS-aware configuration often interferes with the VDDK's ability to mount or read the disk snapshot stream required for the migration. The external VDDK connection is rejected or times out because the strict UUID presentation complicates the snapshot chain locking mechanism, resulting in the "Unable to connect" error.

The Solution

To resolve this issue, you must disable the UUID exposure on the source Virtual Machine.

Changing this parameter typically requires the Virtual Machine to be powered off to take effect. This may require a brief maintenance window, even for a planned "warm" migration.

Step-by-Step Workaround

   1. Log in to your VMware vSphere Client.

   2. Locate the source Windows Virtual Machine that is failing migration.

   3. Shut down the Virtual Machine.

   4. Right-click the VM and select Edit Settings.

   5. Navigate to the VM Options tab.

   6. Expand the Advanced section.

   7. Click on Edit Configuration... (Configuration Parameters).

   8. In the search bar, type disk.EnableUUID.

       * If the parameter exists: Change the value from true to false.

       * If the parameter does not exist: You generally do not need to add it, as the default is usually false, but ensure it is not present with a true value.

   9. Click OK to save the configuration parameters.

   10. Click OK to close the Edit Settings window.

   11. Power On the Virtual Machine.

   12. Restart the migration plan in the OpenShift console.

The DiskTransfer stage should now proceed without the VDDK connection error.