Tag Archives: Api

vCloud API sample

This sample code shows step–by-step  how to use the vCloud API to deploy a new vApp from a template.  Our template vApp in this example contains a single linux (CentOS) virtual machine.

We are going to be making calls to the API directly using ‘curl’. Please note that VMware provide language specific wrappers for the API which simplify the process of using it. Wrappers are available for Java, PHP and .net.

This example is working with the StratoGen UK cloud. The organization name is called ‘test’ and I have a user called ‘user1’ with a password of ‘password’.

Let’s get started…

Step 1

The first thing we need to do is login and get our ‘authentication token’. The username and password are passed in the format user@organization:password.

curl -i -k -H "Accept:application/*+xml;version=5.1" -u "user1@test:password" -X POST  https://mycloud.stratogen.net/api/sessions

1 login

The authentication token is found in the first response header. We need to use this authentication token as a header in all our subsequent API calls.

Step 2

The response body contains links that provide access to our org. We are going to use the link provided as a http GET as follows:

curl -i -k -H "Accept:application/*+xml;version=5.1" -H "x-vcloud-authorization: 2cdWzuFRvuyZVnpD9GFRn5GSIosmfRzRgqNjZKT5+mw=" -X GET https://mycloud.stratogen.net/api/org/45410774-1e62-40bb-9832-8980b54644fa

2 get org

The response provides links to various attributes and actions to do with the org.

Step 3

The first thing we will need to do is find the ID of our template vapp. This is achieved by locating the catalog first and then the vApp template within it. We need the ID of the template as it is used when we deploy our new vApp later in this guide.

Our catalog is called “testcatalog” so we use the appropriate link from the previous step.

curl -i -k -H "Accept:application/*+xml;version=5.1" -H "x-vcloud-authorization: 2cdWzuFRvuyZVnpD9GFRn5GSIosmfRzRgqNjZKT5+mw=" -X GET https://mycloud.stratogen.net/api/catalog/fc227f0d-7440-4c84-a1c5-42c1e20e035e

3 get catalog

The output lists the items within the catalog.

Step 4

The catalog item that we are going to use in this example is “centostemplate” listed as https://mycloud.stratogen.net/api/catalogItem/5fe25d90-d941-44c8-bcc9-c474e3e54b39

curl -i -k -H "Accept:application/*+xml;version=5.1" -H "x-vcloud-authorization: 2cdWzuFRvuyZVnpD9GFRn5GSIosmfRzRgqNjZKT5+mw=" -X GET https://mycloud.stratogen.net/api/catalogItem/5fe25d90-d941-44c8-bcc9-c474e3e54b39

3b get vapp template

The vApp template we are going to use is thus https://mycloud.stratogen.net/api/vAppTemplate/vappTemplate-04207cb9-9e34-4e2c-b163-72f8028b4e8c

Make a note of the reference as we will use it in the following steps.

Step 5

We are now ready to deploy a new vApp based on our template. The action to deploy a vApp from a template can be found in the virtual datacenter (vDC). The link to the vDC can be found in the response to our ORG query in Step 2.

curl -i -k -H "Accept:application/*+xml;version=5.1" -H "x-vcloud-authorization: 2cdWzuFRvuyZVnpD9GFRn5GSIosmfRzRgqNjZKT5+mw=" -X GET https://mycloud.stratogen.net/api/vdc/58c49b3e-f228-4cdf-a031-bec4c218d6c4

4 get vdc

The response lists various actions that are available to us. The one we will be using is called instantiateVAppTemplate.

Step 6

We need to pass some parameters regarding the vApp we want to create. In the API these are known as InstantiateVAppTemplateParams.

 name="new one"
 <Description>New vApp</Description>
 href="https://mycloud.stratogen.net/api/vAppTemplate/vappTemplate-04207cb9-9e34-4e2c-b163-72f8028b4e8c" />

The important bit here is the Source field which was found in step 4. The name and Description fields should be what you wish to call your new vApp. I have set deploy and powerOn to “true” which means the vApp will be powered on as soon as it is deployed.

I have created a small text file called “instantiate-params” so that we can pass this information using curl.

5 instant params


Step 7

We are now ready to deploy our new vApp. We use the POST method to call the API and pass our “instantiate-params” file using the –d option. Note that we include a Content-Type header.

curl -i -k -H "Accept:application/*+xml;version=5.1" -H "x-vcloud-authorization: 2cdWzuFRvuyZVnpD9GFRn5GSIosmfRzRgqNjZKT5+mw="  -H "Content-Type:application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml" -X POST https://mycloud.stratogen.net/api/vdc/58c49b3e-f228-4cdf-a031-bec4c218d6c4/action/instantiateVAppTemplate -d @instantiate-params

6 deploy vapp

Step 8

The response shows us that the vApp is being deployed. We can use the <task> link to check when the process has completed but in the case of the StratoGen cloud this is usually just a couple of seconds.

If we log on to vCloud Director at this point we can see the vApp being created.

portal creating

The response from the API call also passes us a link to the newly created vApp. Using this we can get information such as IPs of VM:

curl -i -k -H "Accept:application/*+xml;version=5.1" -H "x-vcloud-authorization: 2cdWzuFRvuyZVnpD9GFRn5GSIosmfRzRgqNjZKT5+mw=" -X GET https://mycloud.stratogen.net/api/vApp/vapp-e7d299ed-b3b0-411d-b59e-8bebe8c1aafc

There is a lot of information in this response. A snippet showing the IP address of the new VM is shown here:

7 response

A final look at vCloud Director shows our new vApp has been deployed and is running.

portal deployed

At this stage we can log on to the virtual machine and start using it.

How to Offer Software Trials with StratoGen VMware Hosting & vCloud Director

StratoGen has recently been approcached by a number of ISVs looking for ways to offer cost effective trials of their server based software applications.  We all know that the best way to get prospects hooked on your product or VMware Hosting 7 Day Free Trialservice is to let them try it, preferably for free.  Once they have experienced your product first hand, they are much more likely to convert into a paying customer.  But we also know that conducting these trials can be expensive and in these tough times we all need to minimise our cost of sale.

So the team at StratoGen set about thinking of new & innovative ways to do this with the platform and tools that we already have in place.  Here’s where StratoGen VMware Hosting with vCloud Director comes in.

The most recent requirement was to be able to automatically spin up a trial VM instance with the ISV application on it, and for the trial to automatically expire after a defined period.

The solution was this:

  1. Create a ‘Pay As You Go’ (PAYG) Virtual Datacentre on the StratoGen VMware Hosting platform – PAYG customers pay for resources by the hour as they are consumed.
  2. Set the Runtime & Storage leases to the required software trial length, as defined by the ISV (this can be set to as short as 1 hour)
  3. Create a vApp template containing a Virtual Machine pre loaded with the ISV application
  4. Call on the vCloud API to deploy the trial machine from the vApp Template (eg from a web signup form)
  5. Pull IP address information for the deployed VM out of the vCloud API and pass this back to the trialist so they can access the VM with the trial software on it

With the Runtime & Storage leases set to the required trial length, the trial VM will automatically power off and be deleted when the lease expires, thus minimising the cost of the trial for the ISV.

In this particular scenario, a trial VM needed 2 x vCPU, 4GB RAM and 50GB storage.  The ISV wanted their trial to last for 2 hours just to give their customers a taste.

The cost of the infrastructure for this trial – just over US$1!

A neat solution requiring little or no custom integration, other than a little development into the vCloud API.

If you like the sound of this, there is plenty of documentation on the vCloud API which you can find on VMware’s website here

And of course if you want to test vCloud API integration you can do so with a StratoGen VMware Hosting 7 Day Free Trial