Tag Archives: API

If you’re working with vRealize Orhcestrator you are probably spending a lot of time in the API explorer. I find myself using it all the time. But it has some flaws and the functionality is limited. Two of my colleagues recognized that and decided to build their own vRO API Explorer. And they didn’t stop there… it is now available online for everyboy to use: vroapi.com

Recently I have done some work on automating vRA (vCAC) using vRO (vCO). This meant I had to dive into the vCAC APIs. The bad news is that this felt like diving into a pool of dark muddy water. The good news is that I’m still alive, my headache is gone and I’ll try to capture some of the things I learned on this blog.

Split brain

In this post I’ll start out with an introduction to the vCAC APIs. Yes, plural. Not just one API.

vCAC ahem… VRA is actually not just one product, it’s two products which are loosely coupled and sold as one. The first product is the vRA Appliance also known as CAFE. This is a new product that was introduced with vCAC verion 6.0. It is developed in Java (springsource), runs on linux, uses postgres as a data persistence layer, seems to use a micro services architecture , supports multi-tenancy and provides a REST API.

But there also is the old product that was originally developed at CreditSuise, spun off as DynamicOps and then acquired by VMware. It was sold as vCAC 5.x, is developed in .net, uses an MS SQL back-end, runs .net workflows, has no notion of multi-tenancy and provides an OData API. This part is usually called the Iaas Part.

The two products are also reflected in two separate vCO ahem… vRO Plugins. Although you download and install just one package there are really two plugins installed. One is called VCAC and has the description “vCloud Automation Center Infrastructure Administration plug-in for vCenter Orchestrator” the other one is called CAFE and is described as “vCloud Automation Center plug-in for vCenter Orchestrator”.

Confusing. Right? So let’s clear things up:

CAFE is the virtual appliance. All new features are developed in CAFE. So anything that was added since 6.0 runs on the appliance and can be used from the REST API. On top of that some functionality was moved to the appliance. Functionality running in CAFE in version 6.1 includes:

Business Groups and Tenants

Advanced Service Designer

The Catalog

Resource Actions

Approval policies

Notifications

So if you want to automate anything regarding any of these features you’ll need the CAFE plugin which talks to the REST API running on the virtual appliance.

IaaS is the name of everything that’s not on the appliance. It is the reason you need a windows server to run vRA, not just the appliance. This windows server (or multiple servers) runs the old DynamicOps Software with some modifications. Features provided by this part of vRA include:

Virtual Machine Blueprints

Machine Prefixes

Provisioning Groups (Maps to Business Groups in CAFE, GUI only knows Business Groups in the current version)

Reservations

VirtualMachines (vCAC VM objects which map to vSphere/vCloud VMs or even physical machines)

If you want to automate any of the above you’ll need to use the vCAC plugin or the Odata API. If you’re note familiar with Odata APIs there is something you should know: It’s not an actual API. It’s just a representation of the database. There is no application logic behind it, just database constraints. This means that creating new things (called entities) is rather difficult. You have to figure out all the links between different database tables yourself. I’ll try to dive into this deeper in another blog post.

There another peculiarity I want to point out: there is no multi-tenency in the IaaS part. This means that a lot of items from the IaaS part (for example: machine prefixes) are shown to all tenants!

Touchpoints

The fact that vRA basically has a split brain provides some challenges when automation things in vRA. For Example: You’ll have to create a blueprint in the IaaS part but when you want to publish it you have to create a catalog item in the CAFE part of the product. Which brings me to the last part of this post.

As I said before the two product are loosely coupled. The actual touchpoints are not documented. Or at least I couldn’t find anything. But after spending a lot of hour trying to find out how to autmate the publishing of blueprint I found these touchpoints between both APIs:

The Business Group ID in CAFE is identical to the Provisioning Group ID in IaaS. If you create a Business Group in the REST API then vRA also creates the ProvisioningGroup in IaaS for you.

The catalog actually consists of three catalogs. More on this later. One of the catalogs is the provider catalog. Each provider manages its own provider catalog. IaaS is on of the providers. Somehow CAFE knows where to find certain provides IDs. Not sure where to find or set that mapping.

Every Catalog Item has a providerBinding attribute. This contains the bindingId. This binding ID is the blueprint ID (virtualMachineTemplateID) from the IaaS Part. This is how vRA figures out which blueprint to deploy when you request a catalog Item.

A Resource Operation has bindingId which maps the CAFE action to the IaaS action (like powerOn a VM for example)

I recently posted an article about the automate-it robotic arm. I promised to go into more detail on the brain of the Automate-IT robot so time to awake you inner geek because here is a write up about the controller hardware and software that brings the thing to life.

Controller Hardware

The hardware for the controller is an Arduino Yun microcontroller. In case you’re not familiar with Arduino according to the their website: “Arduino is an open-source electronics platform based on easy-to-use hardware and software. It’s intended for anyone making interactive projects”. There are different Arduino compatible boards available. The Yun is a special one because it combines an AVR ATmega 32u4 chip with a System on a Chip running Linux on the same board. Both are connected via a serial bus. A bridge library provides an API which enables a developers to integrate the Linux SoC into Arduino projects. The SoC part of the board provides WLAN, Ethernet, MicroSD card slot and USB Connectivity. The SoC is running an openWRT linux distribution which runs a webserver and some other services. The webserver can be manipulated from the Arduino code. This makes it very easy to build an http API on your Arduino powered device.

The board can provide about 50mA of power. All servo motors combined can draw up to 3Amps so I needed something a little bit more powerful. I choose the LM123K voltage regulator which gets its juice from a 12v brick type power supply. The voltage regulator magically converts it into 5v. I put the LM123K on a piece of perf board and added headers to connect the servos. Male headers on the bottom of the board turn it into a very simple Arduino shield. It doesn’t look pretty but it works fine.

Voltage regulator on top of Arduino Yun

Controller Software

The roboticArm library

The arm is programmed by recording the exact position of all the joints step by step. With each step the time it takes to execute the step is stored as well. Putting the arm to work is just a matter of playing back the recorded sequences. My roboticArm library implements this logic and presents it as a single class. The object instantiated from the class represents the robotic arm and stores a pointer to a recorded or empty sequence. The object can be in recording mode or in playback mode. When in recording mode the current position in the sequence can be selected and the positions of the servos can be set. It’s also possible to add or delete steps from the sequence.

In playback mode the step number will be automatically increased when the recorded duration for a step is expired. At the end of a sequence the playback will be stopped until the step counter is reset to 0.

My library uses the Arduino servo library so there is did not develop any servo control code. But since this isn’t a dedicated Arduino or development blog I won’t go into too much detail about the actual code. If you’re interested feel free to download the RoboticArm library.

Using the library

Below is an excerpt from my controller code. I did not actually test the code below and it is not very usefull since it doesn’t include any code to program a sequence. But at least the servos should come to life and go to the position configured in the defaults sequences.

Arduino

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

#include <Servo.h>

#include <RoboticArm.h>

#define numSequences 4

#define numSequenceSteps 16

////default Sequences

seqstep_tSequences[numSequences][numSequenceSteps]=

{

{

{90,90,90,90,130,25}

},

{

{90,90,90,90,130,25}

},

{

{90,90,90,90,130,25}

},

{

{90,90,90,90,130,25}

}

};

uint8_tsequenceSizes[numSequences]={1,1,1,1};

uint8_tselectedSequence=0;

uint8_tnextSelectedSequence=0;//Start at 0 so arm moves to default position. File load after this

The REST API

The controller presents a REST API via the linux part of the Yun. The beauty of the Yun is that you can actually code this API in the Arduino code. Unfortunately this also means there is no framework available that makes creating a REST API easier. And even if there was I doubt it would fit in the Atmega’s RAM or Flash. The first thing to tackle when creating a REST API is the routing. Routing basically means figuring out what we need to do when a certain URL is requested. You could read the request and use a huge switch case contruction to figure out where to go. but this uses up valuable program storage and ram in a microcontroller. On top of that I find it cumbersome to program in that way. So I used a slightly different approach. I use a URL structure that looks like this: http://RESThost/category/command/parameter. Based on that I wrote the code below:

To figure out which function to run my code uses 3 arrays. The first is an array of strings (or technically a two dimensional array of characters) which defines the categories we have. The second array is a three dimensional array of characters which defines the commands available for each category. The last array is a two dimensional array of function pointers. When a request comes in the code looks for the corresponding element in the first array. Then it know the index number of the category so it starts looking for the element matching the command in the second array. When the command is found the code knows both the index number for the category and the command and uses these index number to find the pointer to the right function in the third array and runs the function. If the function need any parameters the rest of the URL is read and used as parameter. For example: http://roboticarm/status/record will start the function statusRecordCommand() which toggles the recording mode flag of the roboticArm object.

Putting it all together

I made the whole project available for download. You can find it here: robotic_arm. Don’t forget to also download the RoboticArm library and put it somewhere the arduini IDE can find it. The download also includes the AJAX Gui to program the arm. This was my first time building such a gui so it doesn’t like very nice and the code can probably be optimized. So feel free to modify the code and send me the results :).

Disclaimer: The code was only tested on Arduino Yun. The library will run fine on any other Arduino as long as you configure the correct pin numbers. The REST API and Ajax Gui will not work on any other Arduino board currently available.

Recent Posts

Automate-IT Archive

Chris already works with virtualization products since 2004 and since this time he developed into a real expert. Chris works for ITQ and one of his passions is to share his knowledge and use all of his experience to find the best solution for his customers.