vRealize Automation and UCS Director Interaction via REST API – Part 1

You might ask yourself, “self, why do I care so much about automation?  Why so much fuss over APIs?”  The truth is the world is changing – this is true everywhere, and especially true in IT.  Automation and APIs are changing the game, allowing you to answer the question, “what can we do?” with “pretty much anything.”

There are a lot of references to VMware vRealize Automation/Orchestration (vRA/vRO) and Cisco UCS Director (UCSD) REST APIs from the vendors, but I thought I would post some findings and methodologies around rolling your own integrated solution.  I’m specifically going to work through calling a UCSD workflow with a vRA XaaS (a.k.a. vRO workflow) blueprint, but you can use this methodology to add any REST functionality through vRA for most anything.  APIs allow us the opportunity for endlessly integrated solutions…as long as you’ve got the time and patience to develop them!

I’ll lay out my methodology in 3 steps in this 3 part blog series (weird coincidence right?!).

  1. Perform an API call without using vRA to validate it
  2. Configure a workflow in vRO to execute it
  3. Configure an XaaS blueprint in vRA to offer up your workflow as  service to your user base

In this post we are going to cover actually accessing and validating the REST functionality outside of vRA, which should be your first step when developing a new workflow.  It goes without saying that there are some potential tradeoffs when you leverage other solutions outside of vRA.  For example, the workflow I’m calling in UCSD creates a single CentOS VM, using the defined compute/virtualization parameters for my vDC.  However, vRA only manages items that it directly creates.  So while vRA can tell UCSD to create this VM, it won’t be accessible through the Items pane in vRA and I won’t be able to do any day-2 actions with it without even more coding.  In other words, what I’m doing specifically doesn’t make a lot of sense but it should be used as a guide if you need to leverage outside interaction from another product.  Maybe you need some REST functionality to access an appliance that vRO doesn’t have a workflow set or plugin for.

At any rate, as a prerequisite you’ll need some kind of “thing” you want to do with UCSD.  That could be anything from adding a user or group to executing a workflow.  I’m not going to cover creating workflows here.

So, onward and upward!

Postman

The first thing you need in order to properly develop REST workflows is a REST client that you can execute API calls with.  This will basically let you ensure that you’ve got the right code, parameters, etc. with a working REST call before diving into vRO.

The best-est and free-est one I’ve found is Postman (https://www.getpostman.com/).  This is a great client that lets you develop your REST calls, does variable replacement, parameters, and you can save your workflows to bring them up later.  Heck you can use this thing for provisioning itself if you want!

You don’t have to use Postman but get yourself some kind of client to help you test out your calls initially.

UCSD REST Stuff

Here is a link to the master set of UCSD documentation:

http://www.cisco.com/c/en/us/support/servers-unified-computing/ucs-director/products-programming-reference-guides-list.html

And here is a link to the UCSD REST Getting Started Guide, which is very helpful.

http://www.cisco.com/c/en/us/td/docs/unified_computing/ucs/ucs-director/rest-api-getting-started-guide/6-0/b_REST_API_Getting_Started_Guide_60.html

And another good reference portal:

https://developer.cisco.com/site/ucs-dev-center/docs/

A nice thing about UCSD is that it is at least partially developed with REST in mind, so there are some handy things that you can find out using the UCSD GUI.

After logging in, select your username in the upper right hand corner.

ucsd_user_1

And go to the Advanced tab

ucsd_user_2

Two important things here.  First, the REST API Access key.  You’ll need this so copy it somewhere safe.  I’m not bothering to redact mine in this series because this is running in my closet in my basement air-gapped, and let’s be honest – if you’ve gotten that far then breaking into my UCSD instance is the least of our problems.  But keep in mind that this is effectively your credential key when accessing UCSD through the REST API!  It should not be shared any more than your username/password should be shared.

Second, notice the ticked box that says Enable Developer Menu.  You’ll want to enable this as it will relay some information to you from within the GUI that you can use for your REST calls.  Once enabled, log out and back in.

Now, browse to Policies > Orchestration and select REST API Browser up top.  Here you will see a ton of tasks that you can select.  You can fill out the details and hit the Generate XML button to see what the payload should look like.  Here is a screenshot of the Delete VM task where I’ve selected a specific VM and told it to generate the XML for the REST call.

xml

You can also run the task from here as well.

This is really cool to be able to sort of divine the REST stuff for you without having to paw through a lot of doc.  However, bad news now, at least for the workflow I’m using I don’t see any cool REST code inside the GUI to execute it.  So I did have to paw through doc.

Note that if you look at the Report Metadata for either the Catalog item or a Service Request, there is a REST URL at the bottom but this is for actually generating the report info and not for executing the service request.  Maybe it is hidden somewhere (which would be AWESOME) but I couldn’t find it.

So referencing the UCSD Cookbook, I see that the REST URL I care about looks something like this:

/app/api/rest?formatType=json&opName=userAPISubmitServiceRequest&opData={param0:"testCatalog",param1:"vdc1",param2:1,param3:-1,param4:1,param5:"provisioning vm"}

Sweet!  But what in the world does any of this mean.  “testCatalog” I can guess is the name of the workflow and vdc1 is probably the vDC.  But how about those parameters with numerical values?  In the API doc (on the developer site) I was able to track down the userAPISubmitServiceRequest doc and the parameters are as follows:

Parameters:

catalogName – : Catalog name. This is a mandatory parameter. Possible values {“testCat”,”cat_82″}

vdcName – : VDC name. This is a mandatory parameter. Possible values {“vdc82″,”vdc1”}

durationHours – : Duration of VM provisioning in hours. After the specified duration is complete, VM is automatically deprovisioned. Possible values {1,2,…,use -1 to set no duration}

beginTime – : Schedules the time at when you want to start provisioning a VM. Possible values { “January 1, 2014, 00:00:00 GMT”, Use 0 or -1 to start the VM}

qty – : Number of vms to be provisioned. Possible values {1,2,3…}

comments – : Contains comments for VM provision. This is an optional parameter.

OK now we are getting somewhere.  I can now see in that example call above that they are requesting a 1 hour duration, begin immediately, and provision 1 VM.  Good to know!

In my case, the URL is going to look like this:

https://ucsd_ip/app/api/rest?formatType=json&opName=userAPISubmitServiceRequest&opData={param0:"CreateVM",param1:"HomeLab",param2:1,param3:-1,param4:1,param5:"Provisioning VM from vRA"}

Again this post isn’t specifically about how to call my workflow, it is a general guide to how you can run anything RESTful from UCSD, or anything for that matter.  Having API references are absolutely necessary to be successful when developing.

Enough RESTing, Let’s Do This!

Alright let’s actually call this workflow.  Fire up Postman.  One thing you’ll want to likely change (at least I did in my cobbled up homelab) is turn SSL certificate verification off.  This is in Settings (wrench icon in upper right > settings > restart Postman).

Now, set up a POST request, use the complete URL (make sure there are no spaces in it), and add in a header variable of X-Cloupia-Request-Key as seen here.  Use your key from earlier.

postman1

This key is what allows you to make the request as admin (or whatever user you happen to be using).

Hit send and hopefully below you see something like this, indicating that the request was successful.

postman2

Back in UCSD

ucsd_complete

Under Service Requests you should see an in progress task with your ID from the Postman return.

Sweet, we have successfully made a REST API call to a workflow in UCSD!  In the next post we will see how to make this call from vRO instead of Postman, which will subsequently allow us to integrate it into vRA.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s