The HCX module for PowerCLI provides an automated way to perform seamless migration of hundreds of VMs, bi-directionally, which includes options to schedule, cancel or use seed VMs at the target side. This post discusses the best practices on how to use migration modules in HCX PowerCLI to iterate over the workload and perform network mapping operations in a way that ensures workload VMs will attach to the correct set of networks at the target site, post successful migration.

Related Resources

• Automating HCX (hcx.design)
• PowerCLI Blog: Getting Started with the HCX Module

Network Mappings for Workload Migration

Let’s take a look at the New-HCXMigration cmdlet which creates an HCX migration request that one can use to first test and then start a migration:

New-HCXMigration Cmdlet

New-HCXMigration [-ForcePowerOffVm <Boolean>] [-UpgradeHardware <Boolean>] [-UpgradeVMTools <Boolean>] [-RetainMac <Boolean>] [-RemoveSnapshots <Boolean>] [-ReplicateSecurityTags <Boolean>] [-MigrateCustomAttributes <Boolean>] [-RemoveISOs <Boolean>] [-EnableSeedCheckpoint <Boolean>] -NetworkMapping <HCXNetworkMapping[]> -SourceSite <HCXSite> -DestinationSite <HCXSite> -TargetDatastore <HCXDatastore> [-TargetStorageProfile <HCXStorageProfile>] -VM <HCXVM> [-ScheduleStartTime <DateTime>] [-ScheduleEndTime <DateTime>] -MigrationType <MigrationType> [-TargetComputeContainer <HCXComputeContainer>] [-DiskProvisionType <DiskProvisionType>] [-Folder <HCXFolderContainer>] [-memory <int>] [-vcpus <int>] [-Server <HcxServer[]>] [-WhatIf] [-Confirm] [<CommonParameters>]

As observed from the cmdlet definition and its params, we need to provide a few target site details for placing the VM which includes, among others, the following:

TargetDatastore
TargetComputeContainer
TargetStorageProfile
TargetFolder
NetworkMapping

The first of the four target site placement details are straightforward and can be obtained by providing the target values as shown below:

Obtaining Target-Side Objects

$targetDatastore = Get-HCXDatastore -Site $targetSite -Name $targetDatastoreName -Server $hcxSourceServer
 
$targetContainer = Get-HCXContainer -Site $targetSite -Name $targetComputeContainerName -Type $targetComputeContainerType -Server $hcxSourceServer
 
$targetFolder = Get-HCXContainer -Site $targetSite -Type Folder -Name $targetFolderName -Server $hcxSourceServer
 
$targetStorageProfile = Get-HCXStorageProfile -Site $targetSite -Name $targetStorageProfileName -Server $hcxSourceServer

“NetworkMapping” is an array that expects an object of type “HCXNetworkMapping”, which is nothing but a collection of Source and Target Network names/types/values. The source network is a property of the Virtual Machine and hence should be derived from the VM object itself.

Before proceeding with the PCLI cmdlet, let us look at how HCX UI obtains the source network info from the Virtual Machine object. When the migration wizard is opened from the HCX Migration dashboard, the response payload from the underlying Virtual Machine API call includes the “network” section. This network section provides the source networks along with their type and value as shown below for an NSX-T (CVDS) configured source site:

Network Section in Virtual Machine API Response Payload

"network": [ {

    "type": "DistributedVirtualPortgroup",

    "value": "dvportgroup-45",

    "@xsi:type": "ManagedObjectReference",

    "serverGuid": "803be4b6-9262-4068-afbf-b8c166e9aaac",

    "id": "dvportgroup-45",

    "name": "stretch3000",

    "key": "dvportgroup-45",

    "isVxlanBacked": false,

    "displayName": "stretch3000"

  }

This network section derives its values from the information as configured in VC MOB configuration for the virtual machine:

The migration network mapping workflow tries to map the VM NIC config (obtained from VC) to the source network provided in the definition and finally to the target network provided by the user. This is to recreate the VM config on target – ‘Network adapter 1’ should correctly map to network adapter 1 on target VM, ‘Network adapter 2’ should map to network adapter 2 on target VM and so on. This implies that the source network object should always be derived from the VM config as obtained from the vCenter Server.

So, here is the recommended HCX PCLI snippet to derive the source network for performing the network mapping operation while iterating over the entire list of workload VMs to be migrated:

Deriving Source Network in PCLI

for($i = 0; $i -le ($vmsToMigrateList.Count - 1); $i += 1)
{
$targetNetworkMapping = @()
## Get HCX VM Object
$vm = Get-HCXVM -Name $vmsToMigrateList[$i] -Site $sourceSite -Server $hcxSourceServer
## Get the list of VM NIC Adapters
$networkAdapterList = Get-VM -Name $vmsToMigrateList[$i] -Server $sourceVIServer | get-networkadapter
Write-Host "No of Networks attached to the source VM -> " $networkAdapterList.Count
Write-Host "Networks attached to the source VM -> " $vm.Network
for($j = 0; $j -le ($networkAdapterList.Count -1); $j++)
{
$sourceNetwork = $vm.Network[$j]
...
<Target Network Mapping Logic goes here>
...
}

Target Network Mapping Operation:

Once the source VM network object has been derived, the next step is to map it to a target network for the VM to connect to, after successful migration. If any of the source networks attached to the VM is extended using the HCX Network Extension feature, then the HCX migration UI pre-populates the target network in the wizard. Considering the fact that more often than not, the workload VM networks are extended to the target site in order to avoid disrupting the VM communication, it makes sense to have a PCLI way also to perform the target network mapping using the NE appliance:

Performing Target Network Mapping

for($i = 0; $i -le ($vmsToMigrateList.Count - 1); $i += 1)
{
$targetNetworkMapping = @()

## Get HCX VM Object
$vm = Get-HCXVM -Name $vmsToMigrateList[$i] -Site $sourceSite -Server $hcxSourceServer

## Get the list of VM NIC Adapters
$networkAdapterList = Get-VM -Name $vmsToMigrateList[$i] -Server $sourceVIServer | get-networkadapter

for($j = 0; $j -le ($networkAdapterList.Count -1); $j++)
{
## Get the source VM network
$sourceNetwork = $vm.Network[$j]
 
##Check if this VM network is part of any network extension
$networkExtension = Get-HCXNetworkExtension |where -Property Network -like $vm.Network[$j].DisplayName | Select -First 1
 
if(($null -ne $networkExtension))     ## If there is a NE appliance match, let it pre-populate the target network automatically
{
$destinationNetwork = Get-HCXNetwork -Name $networkExtension.DestinationNetwork -Site $targetSite -Type $networkExtension.DestinationNetwork.Type -Server $hcxSourceServer
}
else             ## If this source network is not extended, then provide the target network values manually as input
{
$destinationNetwork = Get-HCXNetwork -Name <TargetNetworkName> -Site $targetSite -Type <TargetNetworkType> -Server $hcxSourceServer
}
 
## Create the network mapping object by appending it to the list
$targetNetworkMapping += New-HCXNetworkMapping -SourceNetwork $sourceNetwork -DestinationNetwork $destinationNetwork
 
Write-Host "Network Mapping -> $targetNetworkMapping"
}

}

P.S: The code snippets provided here for deriving the source network and the target network mapping are provided as a sample. Scripts should be tailored to the target environments and tested before using in a production environment.