Getting Started with the HCX Module for PowerCLI

Introduction

PowerCLI 11.2.0 introduced a brand-new module that allows us to easily automate VMware HCX. The VMware.VimAutomation.HCX module adds 20 new cmdlets to already existing count of well over 600 cmdlets contained in the entire set of PowerCLI modules. 

To give a quick overview, think of VMware HCX as a swiss army knife – a single tool with multiple options to move your workloads in and out of the cloud. Schedule migrations with HCX vMotion, take advantage of replication assisted vMotion for bulk migrations and even VMs with larger footprints, or simply protect your data with the available disaster recovery options. HCX is a powerful tool to easily manage the location of your workloads. 

Getting Started

The first time I use a module, I examine the cmdlets that are available. We can do that with the following code: 

We can see in the response that each of the cmdlets have a prefix, for the noun portion, of HCX. There’s the standard Connect-HCXServer and Disconnect-HCXServer cmdlets for authentication, along with the low-level Get-HCXService cmdlet so we can access the API directly. The other cmdlets are high-level, which have abstracted the available API calls and provided us with easy to understand names and parameters.

First, we need to authenticate to our HCX environment. We will connect directly to the on-premises HCX Manager using the Connect-HCXServer cmdlet.

Now that we’re connected, we can take a look at some of the appliances which have been deployed. We can use the Get-HCXAppliance cmdlet to do that.

We can see that we have 3 appliances deployed and the type for each of them. This falls in line with what you would see under the “HCX Components” tab of the Infrastructure Interconnect page in the HCX Management UI. 

Another piece of information on that particular page is the status of the Interconnect. We can receive that with the Get-HCXInterconnectStatus cmdlet.

We also want to know some site-based information. We can make use of the Get-HCXSite cmdlet to do this. However, we will be making use of two parameters to get the full picture. These two parameters are Source and Destination. If no parameter is used, we’ll receive the source site information by default.

There are also a handful of cmdlets to help us discover the what vSphere objects are available to the HCX environment. These include Get-HCXVM, Get-HCXDatastore, Get-HCXNetwork, and Get-HCXContainer. The first three should be fairly obvious, but the fourth cmdlet is a little more ambiguous. Get-HCXContainer returns back a list of multiple object types including clusters, datastores, folders, hosts, and resource pools. 

One item to take note of, by default each of these cmdlets only return objects for the source site. If you want to receive objects from some other site, you will need to specify that with the Site parameter. 

At this point, I think we’re fairly familiar with our environment so let’s take a look at performing an HCX migration.

HCX Migration

The HCX Migration service offers numerous ways to migrate our VMs between the available sites. There are five cmdlets to help us automate migrations. 

We can start off by using Get-HCXMigration to see a status on any existing migrations. In this case, there has been one previous migration and we can use the “Format-List” parameter to see the all the properties for the HCXMigration object.

Next, let’s perform an HCX Migration. We’ll need to populate a handful of parameters to create the migration with New-HCXMigration. This is quite similar to performing a standard vMotion between vCenters with Move-VM. One big caveat though, the New-HCXMigration cmdlet is looking for HCX objects and not the standard objects we receive from vCenter. Therefore, we’ll be using the HCX associated cmdlets to create variables for each of those parameters.

Here’s some example code based on my environment: 

Then, we can run our New-HCXMigration cmdlet. In my environment, I stored the output from the cmdlet into a variable since we will need to reference it later.

Example code: 

Our migration is created, but it hasn’t actually started yet. There’s one more step to perform before we start the migration, and that’s testing the migration!

Example code: 

Assuming a successful validation, we can now move onward to performing the migration with the Start-HCXMigration cmdlet. 

Putting the above altogether, it should look similar to the following: 

Summary

A module has been made available as part of PowerCLI 11.2.0 to automate VMware HCX. This module includes 20 cmdlets which can be used to discover HCX environments and automate the lifecycle of network extensions, migrations, and disaster recovery replication.