HCX Bulk Migration – DNS Customization Not Applied Post-Migration

Products

• VMware HCX

Issue/Introduction

When performing an HCX Bulk Migration with Guest OS Customization enabled, the virtual machine (VM) powers on at the destination with incomplete network settings.

• IP address, subnet mask, and gateway are applied successfully.
• DNS server configurations are NOT applied, and the VM retains its original (source) DNS settings or has no DNS configured.
• The issue is observed for  Windows Servers.
• VMware Tools are confirmed to be installed and up to date.
• The "Primary NIC" flag is correctly enabled in Network Mappings.

Environment

VMware HCX

Cause

This behavior typically occurs due to missing DNS Metadata: The migration task was submitted without a DNS Suffix or complete DNS paths in the HCX Migration Wizard.

The customization engine requires the suffix to successfully commit the DNS server changes to the Guest OS.

Resolution

• Verify Migration Wizard Configuration
  Before starting the migration, navigate to the Extended Options section of the HCX Migration wizard.
  Ensure Guest Customization is selected.
  Explicitly populate the Primary DNS, Secondary DNS, and DNS Suffix fields. Note: The customization may fail to trigger if the suffix is omitted.
• Validate Environment Constraints
  Single vCenter Migrations: Ensure the "Retain MAC" option is unchecked. This allows the customization engine to correctly map the new network settings to the generated MAC address of the target VM.
  Check OS Compatibility: Verify if the Guest OS is on the supported list for HCX Bulk Migration customization. If using RHEL 8 or Windows 2022, manual configuration post-migration may be required.
• Review Guest OS Logs
  If the issue persists, log in to the migrated VM and review the following logs for errors such as "NICs are not ready" or "enable-custom-scripts UNSET":
  Windows: C:\Windows\TEMP\vmware-imc\guestcust.log
  Linux: /var/log/vmware-imc/toolsDeployPkg.log or /var/log/cloud-init.log
•  

Workaround
For workloads where customization fails to apply automatically, manually update the DNS settings within the Guest OS or apply a vCenter Guest Customization Specification directly through the vSphere Client after the migration has reached the "Ready for Cutover" or "Completed" state.