Exploring the vCloud REST API Part 2

In the previous article, we looked at some of the basic fundamentals required to use the vCloud API and walked through a sample login/logout to vCloud Director using two freely available tools: RESTClient Firefox Plugin and cURL.

In this article, we will step through a more complex scenario as a tenant user in vCloud Director and we will be using the Hello vCloud: A Simplified RESTful Workflow as an example which is available in the vCloud API Programming Guide. If this is your first time using the vCloud API, be sure to take a look at the previous article before you get started. You also will need access to an account with access to a catalog with at least one vApp template to deploy from as mentioned in the documentation. We will be using curl for all examples, but you may opt for the RESTClient Firefox Pluing if you wish.

The workflow that we will walk through is logging into a vCloud Director instance as a tenant user, identify a catalog with a specific vAppTemplate and deploy a new vApp from that vAppTemplate. After the deployment, we will power on the vApp and acquire a session ticket for viewing the remote console and then finally un-provisioning the vApp for deletion.

1. Login

Highlighted is the vCloud authorization token that is returned after you login and it is used for all subsequent calls within this session. You will also see several links, one of which is “org” which provides you a list of all organizations you have access to.

The selected catalog item is a vAppTemplate also called “AppServer“, if you wish to deploy from a specific vAppTemplate, make a note of the href property which we will use a little bit later. You can also get the list of available vAppTemplate when we look at the vDC.

If we want to get more details on the vAppTemplate, we can further explore it’s composition. For this example, the vAppTemplate is composed of just one VM called “AppServer-VM“. The above is just a partial screenshot of the configuration for the VM, there is much more info. If you wish to change the network configuration as part of the deployment such as adding an organization network to the VM, you need to make a note of the VM’s network name.

Now that we have identified the vAppTemplate we wish to deploy from, we need to find an Org vDC within our organization to perform the actual deployment and any additional information we may need for customizing our vApp. If you recall earlier when we perform a GET operation on our Foo organization, there is a link to Org vDC called Foo-Org-vDC, you will need it’s href to get more information about the vDC.

To deploy from the vAppTemplate we identified earlier, we will need to call the instantiateVAppTemplate vCloud API which accepts InstantiateVAppTemplateParams and there is a link for this operation as part of the Org vDC which is highlighted above. If you wish to add/modify the network, you will need VM’s network name that’s currently configured which we looked at earlier in the vAppTemplate. In the vDC you will also see a list of available networks which is highlighted in the above screenshot.

In our example, the vAppTemplate is already configured on the proper network and we do not need to make any additional changes. Per the vCloud API documentation, we have to create a file that contains the InstantiateVAppTemplateParams which includes the following: href of the vAppTemplate that will deploy from, name of the vApp to deploy, deploy method, powerOn and description as highlighted below.

If you would like to modify the network, here is an example with a single VM with a network called “App-Network-1” and we will be associating that with an organization network called “Foo-Stage-Org-Network“. In addition to the information above, you will need to also include InstantiationParams which contains the name of the vApp networks, the href to network you wish to connect and also the fencemode. For more details, you can refer to vCloud Programming Guide Create a vApp from Template.

From the previous step, we created a file called deploy-request which includes the deployment params which is then specified as part of our instantiateVAppTemplate by using the -d option from curl. We also need to specify the proper Content-Type for this operation which is documented in the vCloud API.

If the POST request was successful, we should receive back the new vApp that we just deployed including an href to that vApp. We can then perform a GET operation on our new vApp to see the actions that are available to us.

Note: Depending on the size of your vApp, this may take sometime before your vApp is ready.

When we perform a GET operation on our new vApp, we will see several actions available to us, one of which is the powerOn action. We will go ahead and power on our vApp by performing a POST to that action URL.

You should see status set to “success” if the vApp is completely powered on. Once the vApp is powered on, we can perform another GET operation on the vApp’s href and we should see some new actions that are available for individual VMs within the vApp such as acquireTicket which is used to get access to VMRC of a specific VM.

Note: All operations going forward can be discovered by just using the GET operation on the vApp’s href.

Per the vCloud API documentation, when you perform the POST operation, you will be returned with a VM screenticket which that then be used with the VMRC API to access the remote console of a VM. Take a look at this article for more details.

Once you are done with your vApp and no longer have use for it, the next logical step is to of course stop the vApp and then delete the vApp. Just like in the vCloud UI, you can perform the “stop” operation using the undeploy vCloud REST API action. This will de-allocate the cpu, memory and networking resources and also allows you to specify how to stop the VMs within the vApp such as powering off, shutdown or suspending.

Similar to the instantiatevAppTemplate API call, we will need to create a file that contains the expected input for the undeploy operation. From the vCloud API, we just need to specify the UndeployPowerAction and in this example, we will be powering off the VMs.

15. Logout

When you logout, you will receive a 204 response code which means the request was completed but response does not contain any content.

Though this was a simplified example, hopefully this gives you a better understanding of how you can use the vCloud API to perform various operations in vCloud Director. For more examples of other types of operations, be sure to check out the vCloud API Programming Guide.

Get notification of new blog postings and more by following lamw on Twitter: @lamw

SK

@Chad,
You can interact with the REST API over HTTP/HTTPs, and cURL is just one of many tools that you could use to interact with a URL, in this case we’re using it to interact with vCloud REST API.

SK

August 27th, 2012

How to list all vApps and/or VMs of an organization?

ViRtUaLBoB

October 30th, 2012

…I’m not certain if this is particular to my environment, or, the version of the cURL executable (curl_728_0_ssl) I am using, but in my experience, “double quotes” are required when specifying the -u option, and not single quotes as illustrated above

Ashutosh Mohle

October 21st, 2013

Thankyou so much for the excellent explanation.

Ashutosh Mohle

October 21st, 2013

We would like to mention a problem in login here:
when we tried
$ curl -i -k -H “Accept:application/*+xml;version=1.5″ -u ‘foo-user@Foo:MySuperPassword123′ -X POST https://10.20.181.101/api/sessions
with out server we got some error and couldn’t login.
For resolving this we added -A “Mozilla/5.0” in the command to proxy the client as “Mozilla” agent. and this worked for us.

ben

November 6th, 2013

William: Great blog. I do have a question:
Assume that I have a single VM in a vApp template that is already preconfigured with the necessary network details. How do I create differently named vApp from the same vApp template and deployed them?.
That is vApp1, vApp2, vApp3,…,vAppn from the same vApp template with same networking.
Q1: Do I need also to renamed the VM contained within each vApp1,vApp2,…?
Q2: Do I need also to renamed the “Computer Name” contained within each vApp1,vApp2,… to avoid network collision?
That is I just want a set of vApp from the same base vApp templated created and deployed.

Albert Fader

June 5th, 2015

Hi I am pretty new trying to use the API. I am using this on a windows machine with CURL so that I can script what I want to do. The issue I am running into is that I have to use the value returned by x-vcloud-authorization for all commands past the session command. This means that my scripts have to change every time I log on. Is there any way around this such as forcing the value returned by the login into a variable that I can use for the next commands?