Using vCAC 6.0 REST APIs – Part 1

vCloud Automation Center 6.x has a very extensive API that can allow you to automate everything done with your cloud. This ranges from auto creating new tenants, to auto generating catalog items & services. One could even ask to request a catalog item on behalf of another user defined in vCloud Automation Center. The thing is, is at the moment these API’s are considered in a beta state this is due to the fact that they are still under development in 6.0.x and that not all of the functionalities (as you’ll see soon) are still available.

Recently, VMware has released a vCO Plugin for vCAC, which consists of two parts:
– The IaaS ODATA API workflow interface
– A vCAC Appliance API workflow interface.

Interacting with vCAC API

For the purpose of this post, we will learn how to utilize the vCAC-VA APIs, which are the MAIN set of API’s exposed from vCAC to users. Thing is, in order to authenticate we will have to use the vCO Server + vCAC 6.x vCO Plugin , since the natural authentication mechanism isn’t yet exposed (remember? BETA APIs)

vco-vcac-rest

 

In this first of two-part series, i’ll demonstrate how to capture, and make sense of the JSON request generated by the vCAC UI. Next post, will discuss on how to utilize vCO and this JSON code, to generate new automated requests via REST calls.

Capturing the API Call


The first step here is to understand the JSON construct vCAC 6.0 requests (I’m assuming API usage of vCAC would be for using it to consume services like IaaS / ASD)

We’ll begin by downloading Firefox, and FireBug plugin. What firebug does, is to get in between the actual UI click and the HTTP REST call that the browser make. We can leverage this to easily poke around, and re-create some of the REST API calls! So lets dive deeper in the rabbit hole. We will open up our vCAC catalog , and request an item:
Requesting Deb6
We’ll need to enable firebug, and then click the submit button:
FIREBUGON
Once we do that, we’ll see the HTTP responses , GET and POST operations.

HTTP REST Requests

If we click the plus sign and open it, we will get the JSON code posted:

PostMakeRequest

Analyzing the Request’s JSON Code

if we grab the text and format it, we can make some sense out of it. I’ll put the formatted code here, in case you want to take a look, and analyze what we can do further down. An explanation on how to utilize this using vCO will follow.

[code lang=”js” collapse=”true” title=”Click to see full Item Request JSON Code (warning: it׳s a LONG one)”]
"@type": "CatalogItemRequest",
"catalogItemRef": {
"id": "e783893b-3068-498d-b5cc-3be78cf4742d",
"label": "Debian 6"
},
"organization": {
"tenantRef": "vmdemo",
"tenantLabel": "vmdemo.local",
"subtenantRef": "a88b5eb5-210f-4f25-b074-95475f599018",
"subtenantLabel": "Lab-BG"
},
"quote": {
"leasePeriod": null,
"leaseRate": {
"type": "moneyTimeRate",
"cost": {
"type": "money",
"currencyCode": null,
"amount": 177
},
"basis": {
"type": "timeSpan",
"unit": "DAYS",
"amount": 1
}
},
"totalLeaseCost": null
},
"requestedFor": "kushmaro@vmdemo.local",
"requestedBy": "kushmaro@vmdemo.local",
"requestorEntitlementId": "e2117850-88ed-4564-a8e8-6fff77e8fede",
"state": "SUBMITTED",
"requestData": {"entries": [
{
"key": "provider-Cafe.Shim.VirtualMachine.Description",
"value": {
"type": "string",
"value": ""
}
},
{
"key": "provider-blueprintId",
"value": {
"type": "string",
"value": "e0f0b0d0-681d-45ee-9dfe-5b3466b161ef"
}
},
{
"key": "provider-Cafe.Shim.VirtualMachine.Reason",
"value": {
"type": "string",
"value": ""
}
},
{
"key": "provider-Cafe.Shim.VirtualMachine.MaxCost",
"value": {
"type": "string",
"value": "177.0000"
}
},
{
"key": "provider-VirtualMachine.CPU.Count",
"value": {
"type": "integer",
"value": 1
}
},
{
"key": "provider-Cafe.Shim.VirtualMachine.NumberOfInstances",
"value": {
"type": "integer",
"value": 1
}
},
{
"key": "provider-Cafe.Shim.VirtualMachine.TotalStorageSize",
"value": {
"type": "decimal",
"value": 0
}
},
{
"key": "provider-__Notes",
"value": {
"type": "string",
"value": ""
}
},
{
"key": "provider-provisioningGroupId",
"value": {
"type": "string",
"value": "a88b5eb5-210f-4f25-b074-95475f599018"
}
},
{
"key": "provider-Cafe.Shim.VirtualMachine.MinCost",
"value": {
"type": "string",
"value": "177.0000"
}
},
{
"key": "provider-VirtualMachine.Disk0.Size",
"value": {
"type": "string",
"value": "16"
}
},
{
"key": "provider-Cafe.Shim.VirtualMachine.AssignToUser",
"value": {
"type": "string",
"value": "kushmaro@vmdemo.local"
}
},
{
"key": "provider-VirtualMachine.LeaseDays",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "provider-VirtualMachine.Memory.Size",
"value": {
"type": "integer",
"value": 1024
}
}
]},
"preApprovalId": null,
"postApprovalId": null,
"retriesRemaining": 3
}
[/code]

I’ll review some of the JSON Code above.
If we’ll look at the two first lines, we are able to see what type this JSON request is.

[code lang=”js”]
"@type": "CatalogItemRequest",
  "catalogItemRef":   {
    "id": "e783893b-3068-498d-b5cc-3be78cf4742d",
    "label": "Debian 6"
  },
 [/code]

As mentioned, this specific request is a catalog item request, referencing the specific id and name of the catalog item requested.
By changing these two parameters , and assuming we have multiple catalog items that look the same (in terms of request fields / input params) , we are able to easily shift our request from one item to the other. Like requesting a Red Hat VM or a Windows VM , all according to specific needs.

Next part of the code, depicts which BG & Tenant the request was made for:

[code lang=”js”]
"organization": {
"tenantRef": "vmdemo",
"tenantLabel": "vmdemo.local",
"subtenantRef": "a88b5eb5-210f-4f25-b074-95475f599018",
"subtenantLabel": "Lab-BG"
},
[/code]

The subtenantRef value is actually the Business group UUID within vCAC , and the tenantRef is the UUID kept for the tenant. vCAC keeps tenants by name, which represent a single UUID for the tenant.
Next comes an interesting part, specifying who is this requested for, and by whom:

[code lang=”js”]
"requestedFor": "kushmaro@vmdemo.local",
"requestedBy": "kushmaro@vmdemo.local",
"requestorEntitlementId": "e2117850-88ed-4564-a8e8-6fff77e8fede",
"state": "SUBMITTED",
[/code]

another part of the code determines who is the assigned user for the VM, its owner:

[code lang=”js”]
"key": "provider-Cafe.Shim.VirtualMachine.AssignToUser",
"value": {
"type": "string",
"value": "kushmaro@vmdemo.local"
[/code]

The ‘RequestedFor’ and ‘AssignToUser’ fields, indicates the user that this request is done on behalf of. This opens up some very nice possibilities, in automating requests for other users.
Lets say you want to perform a mass request automatically for new groups or users who joined the organization, or maybe a QA environment for each of your QE team’s members (hint: vCAC Devops Post), so that when they come to work, they have a new build ready for testing.
If you want the API Requested VM to be requested and assigned for a different user, you’ll have to change the ‘AssignToUser’ and ‘Requested For’ parameters for a user of your choice (having the proper entitlement).

Another interesting thing to notice here is the request state. A new request is tagged as submitted, while a request that’s been done is marked as completed.
This allows for tracking of the request, also with the help of a ‘phase’ field, that is non-existing at time of submitting the request.

Lastly comes the request details.
This part of the request details all of the item’s specific details, whether its customer properties, CPUs, Memory etc. For ASD requests , this would hold the ASD form values filled in by the user.

By modifying parameters below, we can easily set the CPU / Memory numbers for the specific request.

[code lang=”js”]
{
"key": "provider-VirtualMachine.Memory.Size",
"value": {
"type": "integer",
"value": 1024
}
{
"key": "provider-VirtualMachine.CPU.Count",
"value": {
"type": "integer",
"value": 1
}
[/code]

This concludes the first part of the vCAC6 REST API series, in the next part (coming soon!) i’ll demonstrate how to use vCO to regenerate a new API request, and help you automate vCAC for different purposes.
As always – Leave your comments below!


Comments
Harvey Specter
Posted at 10:35 pm January 14, 2015
chad
Reply
Author

Why do you refer to the tenantRef as a UUID, when it is a name?
“tenantRef”: “vmdemo”

    Harvey Specter
    Posted at 12:01 pm January 18, 2015
    Kushmaro
    Reply
    Author

    The tenant UUiD is actually its name :)
    there can only be 1 unique tenant name per instance.
    (e.g can’t have 2 tenants named/url’d as ‘DemoTenant’ for example)

Harvey Specter
Posted at 12:33 pm January 20, 2015
Dan
Reply
Author

Hi Kushmaro. Very useful Post.
How is the authentication done here?
Have you ever tried to authenticate via REST API by request a baerer token via POST operation through vco?
I can not figure out how to do this.

    Harvey Specter
    Posted at 9:52 pm March 8, 2015
    Kushmaro
    Reply
    Author

    Hi!
    First i’ll say I didn’t see your comment for a long time for some reason :(
    Second, in this article, since it refers to 6.0 where the APIs were beta and there was no API to get a token, the auth is done through the vCO plugin which utilizes the Internal SDK to gain access to the system.

    Third, in vRA 6.1 and up, you won’t need vCO to authenticate via REST. You can simply do a POST method to the vRA VA.
    You can find a simple example here: http://grantorchard.com/vcac/concepts/vcac-6-1-api-authentication/

Harvey Specter
Posted at 5:13 pm March 8, 2016
shah
Reply
Author

Just a question regarding asd workflows. Can a subtenantRef be set as an input to the action requestCatalogItemOnBehalfOf so that new machine is built in the correct business group ?

Leave a Reply

Navigation