vCHS APIs 101

calendar Sep 30, 2013 · 11 min read  ·
Share on: linkedin copy

When people think about vCHS they think about the vCHS portal. However we all know that an IaaS Cloud isn't (just) about a portal but rather about how you can consume it via APIs.

In this post I am going to give you a brief 101 overview of how you can consume vCHS via APIs.

Warning: the service will iterate quickly so some of these information can become obsolete fairly soon. This is how it works as of early October 2013.

Introduction

In this post I am not going to describe the overall architecture of vCHS. If you were at my vCHS Architecture and Consumption Principles breakout session at VMworld you may have (hopefully) a good enough background.

Suffice to say that, depending on what you subscribed to with the service, you may have access to one or more "virtual data centers". These are backed by one or more vCloud Director instances.

These instances can be dedicated to you or shared with other customers. I alluded to this concept of the cloud of clouds in this brief YouTube video. This is a topic that deserves an entire blog post of its own.

All in all this is what you may end up seeing when you login into your vCHS tenant:

This is me logged into the vCHS tenant my userid is part of. A tenant describes a client. A client could be Pepsi, Coke, Fiat or Pfizer. These brands are only used to describe what "a client" is, I am not implying they are vCHS customers. Maybe they are, I don't know.

My tenant has one virtual data center (5-37) that is coming from a shared multi-tenant vCD instance and the other virtual data centers are all built on the vCD instance dedicated to this tenant. My team (vCHS Technical Services Team) has been assigned a virtual data center we use for our own stuff. I am hiding all the other virtual data centers for confidentiality.

So far it's really all about the interface. There is no way, at the time of this writing, to connect via APIs to the root of the service and enumerate the virtual data centers the tenant has available.

When I click on my virtual data center I get into its context. This is what the UI will show:

Here I can navigate inside my virtual datacenter and I can explore things like resources Usage & Allocation, Virtual Machines, Gateways, Networks and Users (these are users entitled to consume this virtual data center).

This is also the place where the APIs journey can begin. Note in the right hand side of the screenshot above the coordinates to login into this virtual data center via APIs. In my case it is:

https://p1v14-vcd.vchs.vmware.com:443/cloud/org/TechServices/>

Essentially:

  • p1v14-vcd.vchs.vmware.com represents the public FQDN end-point of the vCD instance that is hosting this virtual data center

  • TechServices represents the vCD Organization that contains the virtual data center I want to access (in the TechServices organization there is the vCHS Technical Services Team virtual data center).

What APIs does vCHS exposes?

As hinted above we rely on vCloud Director to provide virtual data center services. The vCHS service exposes the standard vCD consumer APIs.

By consumer APIs I mean the vCD APIs available to vCD organization administrators. vCHS does not expose cloud administrator level APIs. The cloud administrator APIs fall in the scope of what VMware leverages to run the service and this part is not exposed to the vCHS customer.

At the time of this writing the vCHS service is based on vCD 5.1 but this will evolve as VMware will start deploying new versions of the software stack.

The vCHS APIs today map almost exactly the traditional vCD APIs, with minor exceptions. VMware is in the process of documenting these exceptions and I'll update this article when they become available.

In general these limitations gravitate around user management inside the vCD organization; this is because the vCHS service manages RBAC (Role Based Access Control) at a layer above the vCD organizations. This may have implications for applications (written against the vCD APIs) that require being able to manipulate users.

There are other minor and cosmetic limitations on how you can configure the vCD organization via APIs but these are less relevant as they are rarely used by applications written to consume the vCD APIs.

In the future, the vCHS APIs will continue to evolve to meet customers' requirements by both removing existing limitations as well as by ways of extensions to provide additional services above and beyond what the vCD out-of-the-box APIs provide.

vCHS API hands-on for dummies

That's it for the theory.

There are lots of official language bindings for the vCloud APIs (such as Java, PHP and .NET). There are also other bindings developed by the community (e.g. Ruby).

But if you want to start exploring what it means to connect via APIs to your virtual data center, a REST client may be an easier option. I usually use either the Chrome REST Console plugin or the Firefox RESTClient plugin. They work in a very similar way. Oh I have been suggested that Postman, another REST client plug-in for Chrome, is a good choice. I have never used it though.

I am going to use the Firefox plug-in to show you what you need to do. This is how you need to configure the client to login into your virtual data center:

***UPDATE - October 2nd 2013: When I posted this blog I used a deprecated API call to login in the organization. I have now updated text and screenshot accordingly to use the proper API calls.

The method to login must be set to POST.

You need to specify the FQDN of your vCD instance (depicted from the vCHS interface) with the /api/sessions additional path.

At this point you need to include a couple of headers.

The first one describes your credentials. This is how I configured mine by choosing Authentication -> Basic Authentication in the RESTClient menu:

The username is constructed using my vCHS login account (which will always be an email address) and then @. In my case my organization (again, depicted from the vCHS interface) is TechServices. The password is my vCHS login password. The system is smart enough to parse correctly the string with two "@". Shocked! 🙂

The second header tells the RESTClient to specify the vCloud API version you want to use. I have stolen (and adapted) a lot of these information from an old blog post by William Lam.

This is how I configured my header by choosing Headers -> Custom Header in the RESTClient menu:

Done.

Hit the Send button next to the URL in the RESTClient and you should see the status code : 200 ok at the bottom of the page.

What do I do next? I usually move to the Response Body (Preview) tab at the bottom of the RESTClient. This is what I see after the login:

I connected to the Org whose name is TechServices and, in fact, there is an href to it.

If you click on that hyperlink the URL of the RESTClient will change. If you click Send on that hyperlink (make sure you change the method to GET at this point) you will get a list of the objects inside the organization. One of those objects is the virtual data center:

Click on that href to change the REST client URL, click Send and you'll see all objects inside the virtual data center. This includes the vApps:

These vApps are the same vApps you see from the vCHS portal.

Here they are inside the vCHS portal:

At the end of the day, the portal uses these APIs to interact with the vCHS cloud service.

So far I have navigated inside the structure. You can also manipulate objects, such as creating VMs and controlling their power state. This requires slightly more sophisticated REST calls that I am not going to cover in this blog post.

The virtual data center API structure

Are you lost? If it can help, here is a high level overview (with lots of missing details!) of how you can navigate inside the virtual data center structure:

As you can see the API structure deviates a bit from the "virtual data center centric user interface view". In particular, in the UI, the virtual data center is the center piece where everything lives. This includes the private catalog, the Edge Gateway(s) and the layer 2 networks.

In the APIs some of these objects live outside of the context of the virtual data center (albeit some of them can be referenced inside of it).

In theory a vCD organization, which is supposed to describe the characteristics of a tenant, is less relevant in vCHS because tenant management, like RBAC, is done at a higher layer in the back-end. So, from this perspective, the vCD organization object could be seen as a ghost construct that is technically required only as a container for the virtual data center.

However, in reality, the vCD organization contains, at its root level, a lot of objects that we consider part of the vCHS virtual data center (as seen in the vCHS portal). So, from this perspective, a vCD organization can be seen as actually mapping the vCHS virtual data center construct in the UI.

I am sure this will evolve over time but this is how it works at the date of this writing.

Some of you may be attempting to do serious things with the vCHS APIs and not just navigating through the structure of the virtual data center (per the above). If that's the case you may find handy using the vCD query service that, regardless of the structure described above, could be used to search for objects at an abstracted level without having to know the path to it.

There are packaged queries available out of the box or you can build your own custom queries. Check them out.

Products consuming the vCHS APIs

The vCHS APIs are the means by which VMware allows other VMware products, ISVs or customers custom tools to interact with the cloud in a programmatic way.

Examples of VMware products that can talk to the vCHS APIs include, but are not limited to, VMware vCloud Connector, VMware vCenter Orchestrator and VMware vFabric Application Director.

The following picture shows how you can configure VMware AppDirector to connect to vCHS as a cloud end-point:

Note how we keep using the same login information we have used before. The data you need are always:

  • the FQDN of the vCloud instance hosting the virtual data center (depicted from the vCHS interface)
  • the organization name hosting the virtual data center (depicted from the vCHS interface)
  • the vCHS login credentials (userid and password)

There are also third party products and services that integrate with vCHS via APIs. One that I have been testing and playing with lately is ScaleXtreme. They announced at VMworld 2013 Full Support for VMware vCloud Hybrid Service.

In general, all products written against the vCloud APIs will work with vCHS (granted they don't use the API calls mentioned above that we do not yet support).

Last but not least customers and end-users can leverage these APIs to build their own monitoring, automation and consumption tools. This is, for example, what Andrea and I did a few months ago when we wrote the LiquidDC tool.

You may also want to have a look at this new RAS (REST API Shell) fling which would fall into the category of a custom tool (that VMware happened to turn into a fling). I haven't tried it myself so I can't comment on how it works.

Conclusions

In summary, in this article I have described how to:

  • identify the virtual data center APIs end-point through the vCHS interface
  • describe the nature of the vCHS APIs
  • connect to the virtual data center via APIs leveraging browser REST plug-ins
  • provide examples of how to consume those APIs for production use

If I was to look at vCHS from a pure API only perspective this is how I would picture it in my mind: the virtual data center in the middle of the picture exposing APIs to external components.

These components include the vCHS portal (that you can also see as the uber-aggregator of one or more virtual data centers your tenant has access to) and a number of other tools that can consume the virtual data center as an atomic resource.

Something like this, if you will:

At the time of this writing the vCHS Portal is required (and it's the first step for API consumption) because it is the only means by which you can get the information (FQDN and organization name) you need to connect to your discrete virtual data center via APIs.

Also, as you can depict from the picture above, if you need to connect to another virtual datacenter available in your tenant, you need to login into it following the same procedure we have described. In other words, at the time of this writing, there is no way to change virtual data center context with a single login operation.

Massimo.