Getting started with the Hybrid Cloud Extension (HCX) APIs

VMware Hybrid Cloud Extension (HCX) is the de facto VMware solution when it comes to Enterprise scale workload migration whether that is from onPrem to onPrem or from onPrem to Cloud, including our VMware Cloud on AWS (VMC) offering. In fact, one of the most popular use cases for HCX right now is datacenter evacuation/consolidation and customers are migrating their workloads to VMC because they want to get out of the business of running datacenters and get back to running their core business. This is especially attractive for customers wanting to expand to new markets without requiring the need of new datacenters. This makes a ton of sense, especially when you go beyond the initial CapEx, its the on-going OpEx costs that folks may not always be thinking about immediately and being able to easily scale up or down is not always possible for most onPrem environments.

HCX already provides a rich UI interface within the vSphere Client for scheduling migrations including the new Cloud Motion with vSphere Replication feature which was announced at VMworld US 2018.

However, it should come as no surprise that our customers are also interested in Automation, especially as it can help expedite migrations and remove potential user error, especially around mapping the destination networks which can be quite daunting for a large number of migrations. The good news is that HCX provides a Restful API that allows customers to automate all aspects of HCX including the HCX VAMI UI for initial configuration as well as consuming the HCX services which are exposed in the vSphere UI.

HCX API Documentation

The nice thing about the HCX API documentation is that it is included as part of deploying the HCX Enterprise (HCX Manager) and can be accessed by opening a browser to the following URL: https://<HCX-Manager>/hybridity/docs In fact, the documentation is also an interactive API Explorer, similiar to vCenter Server's API Explorer where you can login with your credentials and you can execute some of the APIs directly from this interface.

To begin, you will need to select "HCX Enterprise" from the drop down and you should see the following categories of HCX APIs as shown in the screenshot below.

There are two primary HCX APIs:

• Functionality found in the HCX VAMI UI, which can be accessed by going to https://<HCX-Manager>:9443 and logging in with admin and the password that you had configured when setting up the appliance.
• Functionality found in the HCX plugin when using the vSphere UI such as Migrations, Network Extensions, etc, which can be accessed by simply logging into your onPrem vSphere UI.

This will be more apparent in the sample code below, but there are two different authentication mechanism that you should be aware of depending on the specific HCX API you wish to consume.

• To use the HCX VAMI API, you need to provide basic auth header which encodes the username (admin) and the password and include that in all requests related to the VAMI API, which has a base URL endpoint of https://<HCX-Manager>:9443/api
• To use the HCX API, you need to first login by performing a POST https://<HCX-Server>/hybridity/api/sessions with the username and password of the vSphere User/Group that you have authorized access to HCX. Once you have that, you will get back a token called x-hm-authorization which needs to be included in all HCX API calls, which has a base URL endpoint of https://<HCX-Manager>/hybridity/api

To help demonstrate the HCX APIs, I have created an HCX PowerShell Module (Install-Module VMware.HCX) that contains a number of functions which directly invokes the HCX REST API, which can be useful if you wish to consume the API using other SDK/languages.

HCX VAMI API Example

First, we need to use the Connect-HcxVAMI function which requires the HCX Manager Hostname/IP, Username and Password (credentials of the admin user) and it will create a global variable called $global:hcxVAMIConnection which will contain the based HCX VAMI URL along with the encoded basic authentication token which can then be used in subsequent API requests.

Next, we can use the Get-HcxVAMIVCConfig cmdlet exercises one of the VAMI APIs that returns the onPrem vCenter Server that has been associated with the HCX Manager. As you can see from the output, you will get the hostname, Version, Build and UUIDs for the vCenter Server.

HCX API Example

Now onto the main HCX API which has a different endpoint than the VAMI API and you will need to use the Connect-HcxServer cmdlet. If successfully logged in, HCX Manager will return an authorization token which you will need to use in subsequent API calls. Simliar to the VAMI connect cmdlet, I create a global variable called $global:hcxConnection which will contain the base HCX API URL along with the authorization header information, making it easy to re-use.

To exercise one of the HCX API, I will be retrieving the HCX Cloud information that is registred with your HCX Manager. Simply use the Get-HcxCloudConfig cmdlet to do so as shown in the screenshot below.

The two samples above are fairly simple to give you an idea of how the two different HCX API endpoints functions. You can refer to the HCX documentation for more information.

Automating the new Cloud Motion with vSphere Replication

Lastly, I had mentioned at the start of this article that you could automate a number of things including the new Cloud Motion feature and I do not think it would be fair to talk about it without showing some proof ... As many of you know, I am all about simplicity and trying to make the consumption of our products whether its UI or API, simply amazing. I have been working on building a nice little PowerShell function which I will be sharing in the very near future that will allow you to easily initiate a bulk Cloud Motion migration with very minimal user input.

Below is a sneak peek at how the function will work which simply accepts your onPrem and VMC vCenter Server connection, list of VMs you wish to migrate, the networks to map from onPrem to VMC as well as start and end time for the switch over. You will get back a list of migration IDs, which you can then use to track progress and there is another function that will help retrieve that information, just like you would see in the HCX UI.