Migrating ESXi Hosts to a New Domain (Changing FQDN)
Article ID: 444720
Updated On:
Products
Issue/Introduction
To provide the supported procedure for migrating a standalone ESXi hosts to a new domain (changing its Fully Qualified Domain Name) without causing network lockouts or storage errors.
Symptoms / Use Case:
You need to transition ESXi hosts to a new domain infrastructure (e.g., migrating from
legacy.localtonew.local).Removing old DNS entries before properly removing the host from vCenter causes the host to become "Unresponsive" or "Disconnected."
Attempts to remove and re-add hosts without proper network preparation result in storage, virtual machine, or Distributed Switch (vDS) configuration errors.
Environment
VMware vSphere 7.x
VMware vSphere 8.x
VMware vSphere 9.x
Cause
vCenter Server continuously polls ESXi hosts using the specific FQDN and IP address recorded when the host was initially added to the inventory. Deleting the legacy DNS records while the host is actively connected breaks this management polling mechanism. Additionally, removing a host while its management interface is bound to a static vSphere Distributed Switch (vDS) port group can cause binding conflicts when attempting to re-add the host.
Important Prerequisites & Warnings:
VCF Environments: If your infrastructure is deployed and managed by VMware Cloud Foundation (SDDC Manager), changing the hostname or domain of an ESXi host after deployment is unsupported.
vSAN Environments: Do not use this procedure for hosts participating in a vSAN cluster. vSAN nodes are highly sensitive to cluster UUIDs and unicast agent lists and require a specialized workflow.
DNS: Ensure the forward (A) and reverse (PTR) DNS records for the host's new FQDN are created and fully propagated across your network before beginning this process.
Resolution
Phase 1: Network Preparation If the ESXi host's management network (vmk0) resides on a vSphere Distributed Switch (vDS), you must migrate it before removing the host from inventory. Failing to do so can result in vCenter database mismatches and network lockouts.
In vCenter Server, migrate the host's management VMkernel adapter to a vSphere Standard Switch (vSS) or an ephemeral port group on the vDS.
Verify management connectivity to the host via its IP address.
Phase 2: Removing the Host from Inventory (Note: Removing an ESXi host from the vCenter inventory safely unregisters its virtual machines from vCenter. It does not delete the VMs, their VMDKs, or the datastores. They will automatically repopulate when the host is re-added.)
Place the ESXi host into Maintenance Mode. Ensure all running VMs are evacuated or powered off.
If the host is part of a cluster, drag and drop the host outside of the cluster to a standalone Datacenter or Folder level.
Right-click the ESXi host and select Connection > Disconnect. Wait for the task to complete.
Right-click the disconnected host and select Remove from Inventory.
Phase 3: Renaming the Host
Log directly into the ESXi host via SSH or the ESXi Host Client (UI).
Execute the following command to update the host's FQDN to the new domain:
esxcli system hostname set --fqdn=<new_hostname>.<new_domain.local>Verify the change was successful by running:
esxcli system hostname get
Phase 4: Re-adding the Host and Cleanup
In the vCenter Server UI, right-click your Datacenter or Cluster and select Add Host.
Enter the new FQDN of the host. Ensure vCenter can resolve the new FQDN.
Complete the Add Host wizard, accepting the host's certificate thumbprint.
Once the host is successfully re-added to vCenter, migrate the management VMkernel adapter back to its original static port group on the vSphere Distributed Switch (vDS) if applicable.
Right-click the ESXi host and select Maintenance Mode > Exit Maintenance Mode.
Additional Information
Feedback
