Migrate VMware VMs with HCX Automation by using PowerCLI
Created by Giri Nadiminty (AWS), Hassan Adekoya (AWS), and Naveen Deshwal
Environment: Production | Source: On-premises or cloud-based VMware vCenter or SDDC | Target: VMware Cloud on AWS |
R Type: Rehost | Workload: All other workloads | Technologies: Migration; Hybrid cloud |
AWS services: VMware Cloud on AWS |
Summary
Notice: As of April 30, 2024, VMware Cloud on AWS is no longer resold by AWS or its channel partners. The service will continue to be available through Broadcom. We encourage you to reach out to your AWS representative for details. |
This pattern describes how to migrate VMware on-premises virtual machines (VMs) to VMware Cloud on AWS by using VMware Hybrid Cloud Extension (HCX) Automation powered by VMware PowerCLI scripts. PowerCLI
You can adapt this pattern for migration between any combination of vCenters, software-defined data centers (SDDCs), and cloud environments. The PowerCLI scripts included with this pattern use automation instead of mouse clicks for all VM configuration and scheduling tasks, so they provide time savings in migration activities and help reduce the risk of human error.
Prerequisites and limitations
Prerequisites
A VMware Cloud on AWS account with SDDC
An existing on-premises or cloud-based vCenter or SDDC
A user account with the necessary permissions for source and destination vCenters or SDDCs
HCX Site Pairing
with HCX Network Extension (HCX-NE) configured between source and destination vCenters or SDDCs VMware PowerCLI
installed on your server of choice
Limitations
If the source vCenter uses cross-vCenter NSX, the PowerCLI module will not work. Use a scripting method (such as Python) with the HCX API instead of PowerCLI.
If the migrated VMs need new names or IP addresses, use a scripting method (such as Python) with the HCX API.
This pattern doesn’t populate the .csv file, which is required. You can populate the file by using VMware vRealize Network Insight (vRNI) or some other method.
Product versions
VMware vSphere version 5 or later
VMware HCX version 4.4 or later
VMware PowerCLI version 12.7 or later
Architecture
Source technology stack
On-premises or cloud-based VMware
Target technology stack
VMware Cloud on AWS
Target architecture
![Migrating VMs to AWS with HCX Automation and PowerCLI](/images/prescriptive-guidance/latest/patterns/images/pattern-img/744c7937-c625-40d8-a858-e8fdcc2f6600/images/c4ffe8b3-d905-4bd6-8538-ecd57d01b8a7.png)
Tools
AWS services
VMware Cloud on AWS
is a service jointly designed by AWS and VMware to help you migrate and extend your on-premises VMware vSphere-based environments to the AWS Cloud.
Other tools
VMware Hybrid Cloud Extension (HCX
) is a utility for migrating workloads from your on-premises VMware environment to VMware Cloud on AWS without changing the underlying platform. Note: This product was formerly known as Hybrid Cloud Extension and NSX Hybrid Connect. This pattern uses HCX for VM migration. VMware PowerCLI
is a command-line tool for automating VMware vSphere and vCloud management. You run PowerCLI commands in Windows PowerShell by using PowerShell cmdlets. This pattern uses PowerCLI to run migration commands.
Code
Simple, self-contained script
We recommend that you use this single-machine script for initial testing, to verify that configuration options are accepted and behave as expected. For instructions, see the Epics section.
<# Manual Variables #> $HcxServer = "[enterValue]" $SrcNetworkName = "[enterValue]" $DstNetworkName = "[enterValue]" $DstComputeName = "[enterValue]" $DstDSName = "[enterValue]" $DstFolderName = "[enterValue]" $vmName = "[enterValue]" <# Environment Setup #> Connect-HCXServer -Server $HcxServer $HcxDstSite = Get-HCXSite -Destination $HcxSrcSite = Get-HCXSite -Source $SrcNetwork = Get-HCXNetwork -Name $SrcNetworkName -Type VirtualWire -Site $HcxSrcSite $DstNetwork = Get-HCXNetwork -Name $DstNetworkName -Type NsxtSegment -Site $HcxDstSite $DstCompute = Get-HCXContainer -Name $DstComputeName -Site $HcxDstSite $DstDS = Get-HCXDatastore -Name $DstDSName -Site $HcxDstSite $DstFolder = Get-HCXContainer -name $DstFolderName -Site $HcxDstSite $vm = Get-HCXVM -Name $vmName <# Migration #> $NetworkMapping = New-HCXNetworkMapping -SourceNetwork $SrcNetwork -DestinationNetwork $DstNetwork $NewMigration = New-HCXMigration -VM $vm -MigrationType vMotion -SourceSite $HcxSrcSite -DestinationSite $HcxDstSite -Folder $DstFolder -TargetComputeContainer $DstCompute -TargetDatastore $DstDS -NetworkMapping $NetworkMapping -DiskProvisionType Thin -UpgradeVMTools $True -RemoveISOs $True -ForcePowerOffVm $True -RetainMac $True -UpgradeHardware $True -RemoveSnapshots $True
Full-featured, .csv-based script
After testing is complete, you can use the following script in your production environments. For instructions, see the Epics section.
<# Schedule #> write-host("Getting Time for Scheduling") $startTime = [DateTime]::Now.AddDays(12) $endTime = [DateTime]::Now.AddDays(15) <# Migration #> Connect-HCXServer -Server [enterValue] write-host("Getting Source Site") $HcxSrcSite = Get-HCXSite write-host("Getting Target Site") $HcxDstSite = Get-HCXSite -Destination $HCXVMS = Import-CSV .\Import_VM_list.csv ForEach ($HCXVM in $HCXVMS) { $DstFolder = Get-HCXContainer $HCXVM.DESTINATION_VM_FOLDER -Site $HcxDstSite $DstCompute = Get-HCXContainer $HCXVM.DESTINATION_COMPUTE -Site $HcxDstSite $DstDatastore = Get-HCXDatastore $HCXVM.DESTINATION_DATASTORE -Site $HcxDstSite $SrcNetwork = Get-HCXNetwork $HCXVM.SOURCE_NETWORK -Type VirtualWire -Site $HcxSrcSite $DstNetwork = Get-HCXNetwork $HCXVM.DESTINATION_NETWORK -Type NsxtSegment -Site $HcxDstSite $NetworkMapping = New-HCXNetworkMapping -SourceNetwork $SrcNetwork -DestinationNetwork $DstNetwork $NewMigration = New-HCXMigration -VM (Get-HCXVM $HCXVM.VM_NAME) -MigrationType Bulk -SourceSite $HcxSrcSite -DestinationSite $HcxDstSite -Folder $DstFolder -TargetComputeContainer $DstCompute -TargetDatastore $DstDatastore -NetworkMapping $NetworkMapping -DiskProvisionType Thin -UpgradeVMTools $True -RemoveISOs $True -ForcePowerOffVm $True -RetainMac $True -UpgradeHardware $True -RemoveSnapshots $True -ScheduleStartTime $startTime -ScheduleEndTime $endTime Start-HCXMigration -Migration $NewMigration -Confirm:$false }
Epics
Task | Description | Skills required |
---|---|---|
Find the source and destination vCenter and SDDC server names. | PowerCLI scripts require the variables described in this epic. You can gather this information in advance for ease of script use. In the HCX section of the vSphere console, choose Infrastructure, Site Pairing. Make a note of the source and destination server names that are displayed. | Cloud architect |
Find the source and destination HCX names. | In the HCX section of the vSphere console, choose System, Administration. Make a note of the source and destination HCX names that are displayed. | Cloud architect |
Find the source and destination network names. | In the HCX section of the vSphere console, choose System, Network Extension. Make a note of the source and destination network names. Note: As an alternative, you can get the source and destination network names by using the PowerCLI Get-HCXNetwork and Get-HCXNetwork-Destination commands after you connect to the HCX server. | Cloud architect |
Gather additional information from the vSphere console. | On the vSphere console, collect the following information:
| Cloud architect |
Task | Description | Skills required |
---|---|---|
Determine migration options. | Determine the following:
For more Information about each option, see the VMware developer documentation | Cloud architect |
Task | Description | Skills required |
---|---|---|
Copy the script. | The simple version of the script is self-contained in a single file. You can use it to test the migration of a single machine. Copy the first script from the Code section of this pattern and store it on the computer that has the VMware PowerCLI module installed. (To install PowerCLI, follow the instructions in the VMware documentation | Cloud architect |
Set script variables. | Set all the variables in the | Cloud architect |
Set migration variables. | Set all the | Cloud architect |
Specify sites. | (Optional) If the source or destination has multiple sites, specify the sites manually in the If the source and destination have single sites, the script will automatically look the information up. | Cloud architect |
Run the script. | On the server where PowerCLI is installed, from an elevated PowerShell window, run the script, and enter your credentials when prompted. | Cloud architect |
Validate the script. | Confirm that VM migration has been initiated. | Cloud architect |
Task | Description | Skills required |
---|---|---|
Create and populate the .csv file. | Create a .csv file called
Replace each Note: You can populate the .csv file by using VMware vRealize Network Insight (vRNI) or some other method. | Cloud architect |
Copy the script. | The full-featured version of the script uses information from an external .csv file to automatically migrate multiple VMs. Copy the second script from the Code section of this pattern and store it on the computer that has the VMware PowerCLI module installed, in the same folder as the .csv file. | Cloud architect |
Modify the script. | Edit the script to make the following changes:
| Cloud architect |
Run the script. | On the server where PowerCLI is installed, from an elevated PowerShell window, run the script, and enter your credentials when prompted. | Cloud architect |
Validate the script. | Confirm that VM migration has been initiated. | Cloud architect |
Troubleshooting
Issue | Solution |
---|---|
The script fails with the error message: “All source networks are not mapped to target!” | If the source vCenter uses cross-vCenter NSX, the PowerCLI module will not work. Use a scripting method (such as Python) with the HCX API instead of PowerCLI. This is a known limitation of the PowerCLI script. |
The script fails with the error message: “Connect-HCXServer Error: Unauthorized” | The credentials you entered don’t provide the necessary permissions. |
Related resources
Migrating Workloads to VMware Cloud on AWS with Hybrid Cloud Extension (HCX)
(AWS blog post) Choosing a migration approach for relocating your VMware applications and workloads to the AWS Cloud (AWS Prescriptive Guidance)
Migrate VMware SDDC to VMware Cloud on AWS using VMware HCX (AWS Prescriptive Guidance)
Getting Started with the HCX Module
(VMware blog post)