Migrate VMware VMs with HCX Automation by using PowerCLI - AWS Prescriptive Guidance
SummaryPrerequisites and limitationsArchitectureToolsEpicsTroubleshootingRelated resources

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 is a command-line tool that’s built on Windows PowerShell. It helps you manage VMware software, and automates infrastructure and migration tasks.

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

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

TaskDescriptionSkills 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:

  • Names of VMs that you want to migrate

  • Destination compute environment (cluster/host)

  • Destination datastore

  • Destination VM folder name

Cloud architect
TaskDescriptionSkills required

Determine migration options.

Determine the following:

  • MigrationType – The HCX-assisted migration types are vMotion, bulk, cold, and RAV. Your choice depends on your downtime requirements, network bandwidth, migration time frame, and workload type. For more information, see the AWS blog post Migrating Workloads to VMware Cloud on AWS with Hybrid Cloud Extension (HCX).

  • DiskProvisionType (Thin, Thick)

  • UpgradeVMTools ($True, $False)

  • RemoveISOs ($True, $False)

  • ForcePowerOffVm ($True, $False)

  • RetainMac ($True, $False)

  • UpgradeHardware ($True, $False)

  • RemoveSnapshots ($True, $False)

For more Information about each option, see the VMware developer documentation.

Cloud architect
TaskDescriptionSkills 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 Manual Variables section of the script.

Cloud architect

Set migration variables.

Set all the New-HCXMigration settings in the Migration section of the script.

Cloud architect

Specify sites.

(Optional) If the source or destination has multiple sites, specify the sites manually in the Environment Setup section of the script.

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
TaskDescriptionSkills required

Create and populate the .csv file.

Create a .csv file called Import_VM_list.csv on your computer and populate it with the following sample content:

VM_NAME,DESTINATION_VM_FOLDER,DESTINATION_COMPUTE,DESTINATION_DATASTORE,SOURCE_NETWORK,DESTINATION_NETWORK
[enterValue],[enterValue],[enterValue],[enterValue],[enterValue],[enterValue]

Replace each [enterValue] in the .csv file with the information you collected earlier.

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:

  • Line 7: Set the HCX server variable (Connect-HCXServer).

  • Line 12: (Optional) If you set the .csv filename differently, update it.

  • Lines 3-4: (Optional) Set the schedule.

  • Line 20: (Optional) Specify the New-HCXMigration settings in the Migration section.

  • Lines 9 and 11: (Optional) If the source or destination includes multiple sites, specify the desired sites manually.

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

IssueSolution

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