Provisioning and Managing VMware Cloud on AWS Using vRealize Orchestrator

By Sam Walker, Sr. Partner Solutions Architect – AWS

VMware vRealize Orchestrator (vRO) is a part of VMware’s vRealize Suite and tied in closely with VMware vRealize Automation (vRA). It acts as the orchestration tool for anything that sits outside of the control of vRA, which enables vRA customers to create workflows to perform additional steps during the provisioning of a virtual machine (VM). This includes managing backup policies, updating a content management database (CMDB), and emailing users a server’s login credentials.

Additionally, vRA can leverage vRO workflows to perform provisioning requests on anything that can be managed by vRO; in the case of VMware Cloud on AWS, by using the REST API. This is referred to as “anything-as-a-service,” or XaaS.

Customers have made significant investments in automation projects which control their on-premises VMware environments, and nearly all of these leverage vRealize Orchestrator. Many VMware administrators are comfortable using vRO workflows to automate tasks and schedule recurring tasks such as removal of snapshots.

This post shows another method of automating VMware Cloud on AWS and helps vRO admins get started using vRO to manage VMware Cloud on AWS environments. The sample code can be found in this GitHub page and follows the VMware Cloud on AWS API guide from VMware.

Overview

The first step when using the VMware Cloud on AWS API is to create an API token through the VMware Cloud portal. Instructions for this can be found in the API guide mentioned above.

Once you have this API token, it must be exchanged for an access token which you can use to perform subsequent API operations on VMware Cloud on AWS. This includes creating or deleting a software-defined data center (SDDC), managing credentials and subscriptions, and monitoring or updating tasks happening in the environment.

There are two API endpoints involved in managing VMware Cloud on AWS environments. The first is used to exchange the API token for an access token, and the second is used to perform subsequent operations. These can be added as REST Host endpoints in vRO using this VMware documentation:

https://console.cloud.vmware.com/csp/gateway – used for authentication
https://vmc.vmware.com/vmc – used for subsequent operations

I have named these “vmc-auth” and “vmc,” respectively, for the API endpoints in the sample workflows.

Figure 1 – vRealize Orchestrator plug-ins.

Although the Add REST Host workflow should install a certificate automatically (or prompt the user to accept the certificate), you may need to manually install these. This can be done by browsing to the Control Center (https://vro-address/vco-controlcenter/config) and logging in using the “root” account.

Once logged in, select Certificates > Import from URL and import the certificate from the two URLs provided above.

Figure 2 – Importing a certificate through the Control Center.

These REST API endpoints should be used in your workflows to reflect the correct API endpoints once you have added them into vRO.

Use a workflow to return an access token. The following code has been provided as a sample. Pass the input variables of apiKey and resthost which should be the authentication endpoint. The output will be accessToken.

//Build Request
var encodeURI = encodeURI ("refresh_token=" + apiKey)
var request = resthost.createRequest("POST","/am/api/auth/api-tokens/authorize?" + encodeURI);

//Set Headers
request.contentType = "application/json";
request.setHeader("Content-Type: application/x-www-form-urlencoded")

//Execute Request & get status
var response = request.execute();
var statusCode = response.statusCode;
System.debug ("API status code is " + statusCode);

//Get Content as string and extract access token
var contentAsString = response.contentAsString;
var jsonobj = JSON.parse(contentAsString);
accessToken = jsonobj.access_token;

Once you have managed to successfully create an access token, you can use this workflow at the beginning of all subsequent workflows to generate the access token from your API key every time.

At this point, the first thing to test is something basic like getting the organizations available to the API user. To do this, create a workflow which takes the input of the access token generated from the previous workflow and outputs an array of organizations.

I used the following code with the accessToken and resthost as inputs:

//Build Request
var request = resthost.createRequest("GET","/api/orgs");
//Set Headers
request.contentType = "application/json";
request.setHeader("Accept","application/json")
request.setHeader("Content-Type","application/json")
request.setHeader("csp-auth-token", accessToken )

//Execute Request & get status code
var response = request.execute();
var statusCode = response.statusCode;
System.log ("API status code is " + statusCode);

//Get Content as string & log output
var contentAsString = response.contentAsString;
var jsonobj = JSON.parse(contentAsString)
for each (var obj in jsonobj) {
    System.log (“Found organisation “ + obj.display_name + " - " + obj.id)
}

From this point on, you can adapt the code to perform actions you need to do; either something you can host using vRealize Automation XaaS, or actions you want to orchestrate to be able to schedule, minimize manual clicks, or just remove human error. Some other examples I have used vRO with are listed in the following section.

Examples

Where customers want to self-service the creation of a full SDDC, they can do so by using a POST command on https://vmc.vmware.com/vmc/api/orgs/{org}/sddcs. This needs to have a JSON body built up and attached to the API call. The minimum content of the JSON with an example is listed below:

{ 
    "region": “US_WEST_2”,
    "name": “vRO Demo”,
    "num_hosts": 2,
    "provider": "AWS"
 }

This can be taken as input variables on a vRO form, so the user is prompted for variables.

Figure 3 – vRealize Orchestrator SDDC request form example.

The JSON can be modified to include additional parameters such as management subnet, AWS account ID, Microsoft licensing, single sign-on (SSO) domain, default network address, and host instance type. The result is an SDDC is created programmatically.

Figure 4 – VMware Cloud on AWS deployment.

Another place where the API can be used is to highlight what accounts are connected and then subsequently remove unused account IDs. Use a GET API call to https://vmc.vmware.com/vmc/api/orgs/{org}/account-link/connected-accounts to return a JSON of all connected accounts, and use a DELETE API call to https://vmc.vmware.com/vmc/api/orgs/{org}/account-link/connected-accounts/{linkedAccountPathId} to remove unused accounts.

Below is the JSON returned from one of the linked accounts; this can be used to identify owners and what accounts have been configured for an organization already.

Figure 5 – JSON returned from a linked account API call.

This can be performed on a weekly schedule to identify what AWS CloudFormation stacks created during VMware Cloud on AWS provisioning are still deployed in AWS environments which may be a compliancy requirement.

A vRealize Orchestrator workflow can also be used to quickly validate what SDDCs have add-on features enabled. This can be performed by using the GET API call on https://vmc.vmware.com/vmc/api/orgs/{org}/sddcs/{sddc}/enablements, which returns a JSON string of enabled add-ons:

[{"name":"hcx","enabled":true},{"name":"draas","enabled":true},{"name":"skynet","enabled":true},{"name":"default","enabled":false}]

You can also use a POST API call to enable add-ons by calling https://vmc.vmware.com/vmc/api/orgs/{org}/sddcs/{sddc}/enablements/{enablement} but replacing the variables, including the {enablement} variable with the required add-on, for example “hcx” or “draas.”

Next Steps

Once you have built out basic workflows, this can be modified and combined to create larger and more complex workflows. For example, the workflow below will only delete certain SDDCs which we use during customer training events.

Figure 6 – Delete SDDC workflow example.

Recommendations

The following are provided as guidelines on using the VMware Cloud on AWS API with vRO, although you should consult VMware vRealize Orchestrator and VMware Cloud on AWS API documentation to gather more information about the API and best practices.

Create an API key per-user; do not share between users.
Store API keys using a secrets management tool such as AWS Secrets Manager to avoid hardcoding the API key; ensure that if vRO is used by multiple users, the per-user API key is used.
Practice role-based access control (RBAC) and give only the required permissions; don’t assume your API key needs the same permissions as the user interface (UI) user.
Regularly recreate your API key and avoid keys that last indefinitely.
When creating workflows, before performing a POST or DELETE operation, perform an action like a System.log(…) to ensure your workflow performs as expected and you don’t inadvertently delete a production SDDC.

Conclusion

This post highlighted how you can use vRealize Orchestrator to deploy and manage VMware Cloud on AWS environments. As with all automation projects, ensure you are clear on what it is you’re trying to automate and that it’s well documented before trying to use an API to control it.

Please connect with the VMware Cloud on AWS team for more information.

AWS Partner Network (APN) Blog