Home > Blogs > VMware vSphere Blog


Exploring the vCloud REST API Part 2

By William Lam, Sr. Technical Marketing Engineer

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

$ curl -i -k -H “Accept:application/*+xml;version=1.5″ -u ‘foo-user@Foo:MySuperPassword123′ -X POST https://10.20.181.101/api/sessions

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.

2. List All Organizations

$ curl -i -k -H “Accept:application/*+xml;version=1.5″ -H “x-vcloud-authorization: SkqSCI//xE4Q6geIXMpnp7CVXwuJXlR+poUUTRjMTHM=” -X GET https://10.20.181.101/api/org

2.listOrg

In this example, we have only one organization called “Foo” and to get more information we can perform a GET operation on it’s href which is highlighted.

3. Get Specific Organization

$ curl -i -k -H “Accept:application/*+xml;version=1.5″ -H “x-vcloud-authorization: SkqSCI//xE4Q6geIXMpnp7CVXwuJXlR+poUUTRjMTHM=” -X GET https://10.20.181.101/api/org/0d020a29-90de-4000-a0ec-c8a630e65c61

3.listSpecificOrg

We can see the Org vDC’s that this organization has access to and also the catalogs. In this example, we have one catalog called “Development-Catalog“. Let’s take a look and see what’s in the catalog

4. Get Catalog

$ curl -i -k -H “Accept:application/*+xml;version=1.5″ -H “x-vcloud-authorization: SkqSCI//xE4Q6geIXMpnp7CVXwuJXlR+poUUTRjMTHM=” -X GET https://10.20.181.101/api/catalog/4b98e02f-6405-43cc-a04a-c406e93a2eac

4.listCatalog

In this example, we have two items in the catalog. We will select the “AppServer” catalog item to further explore as we are interested in deploying a new vApp from this template.

5. Get Catalog Item

$ curl -i -k -H “Accept:application/*+xml;version=1.5″ -H “x-vcloud-authorization: SkqSCI//xE4Q6geIXMpnp7CVXwuJXlR+poUUTRjMTHM=” -X GET https://10.20.181.101/api/catalogItem/37abb7bc-bf4a-41f0-8561-017711814fff

5.getCatalogItem

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.

6. Get vAppTemplate

$ curl -i -k -H “Accept:application/*+xml;version=1.5″ -H “x-vcloud-authorization: SkqSCI//xE4Q6geIXMpnp7CVXwuJXlR+poUUTRjMTHM=” -X GET https://10.20.181.101/api/vAppTemplate/vappTemplate-fdea59a3-10cb-489f-8402-3a480fccc71c

6.listvAppTemplate

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.

7. List Org vDC

$ curl -i -k -H “Accept:application/*+xml;version=1.5″ -H “x-vcloud-authorization: SkqSCI//xE4Q6geIXMpnp7CVXwuJXlR+poUUTRjMTHM=” -X GET https://10.20.181.101/api/vdc/d0ef82ad-c677-41bb-bcfc-c2a5abe8e927

7.listvDC

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.

$ cat deploy-request
<InstantiateVAppTemplateParams
   xmlns=”http://www.vmware.com/vcloud/v1.5″
   xmlns:ovf=”http://schemas.dmtf.org/ovf/envelope/1″
   name=”AppServer-TESTING”
   deploy=”false”
   powerOn=”false”>
   <Description>Testing AppServer</Description>
   <Source
      href=”https://10.20.181.101/api/vAppTemplate/vappTemplate-fdea59a3-10cb-489f-8402-3a480fccc71c” />
</InstantiateVAppTemplateParams>

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.

$ cat deploy-request
<InstantiateVAppTemplateParams
xmlns=”http://www.vmware.com/vcloud/v1.5″
xmlns:ovf=”http://schemas.dmtf.org/ovf/envelope/1″
name=”AppServer-TESTING”
deploy=”false”
powerOn=”false”>
<Description>Testing AppServer</Description>
<InstantiationParams>
<NetworkConfigSection>
<ovf:Info>Configuration parameters for logical networks</ovf:Info>
<NetworkConfig
networkName=”App-Network-1“>
<Configuration>
<ParentNetwork
href=”https://10.20.181.101/api/network/0caf1136-ba51-4ca4-8c08-208dea9f1324” />
<FenceMode>isolated</FenceMode>
</Configuration>
</NetworkConfig>
</NetworkConfigSection>
</InstantiationParams>
<Source
href=”https://10.20.181.101/api/vAppTemplate/vappTemplate-fdea59a3-10cb-489f-8402-3a480fccc71c” />
</InstantiateVAppTemplateParams>

8. Instantiate from vAppTemplate

$ curl -i -k -H “Accept:application/*+xml;version=1.5″ -H “x-vcloud-authorization: SkqSCI//xE4Q6geIXMpnp7CVXwuJXlR+poUUTRjMTHM=” -H “Content-Type:application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml” -X POST https://10.20.181.101/api/vdc/d0ef82ad-c677-41bb-bcfc-c2a5abe8e927/action/instantiateVAppTemplate -d @deploy-request

8.deployvAppTemplate

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.

9. Get Newly Deployed vApp

$ curl -i -k -H “Accept:application/*+xml;version=1.5″ -H “x-vcloud-authorization: SkqSCI//xE4Q6geIXMpnp7CVXwuJXlR+poUUTRjMTHM=” -X GET https://10.20.181.101/api/vApp/vapp-fc611c57-ba91-44e2-87ab-42bb913f45cf

9.getDeployedvApp

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.

10. Power On vApp

$ curl -i -k -H “Accept:application/*+xml;version=1.5″ -H “x-vcloud-authorization: SkqSCI//xE4Q6geIXMpnp7CVXwuJXlR+poUUTRjMTHM=” -X POST https://10.20.181.101/api/vApp/vapp-fc611c57-ba91-44e2-87ab-42bb913f45cf/power/action/powerOn

10.powerOn

If the operation was succesful, you will get back a vCloud task which you can monitor the progress by performing a GET operation on the task href and checking the “status” attribute.

11. Get vApp PowerOn Task

$ curl -i -k -H “Accept:application/*+xml;version=1.5″ -H “x-vcloud-authorization: SkqSCI//xE4Q6geIXMpnp7CVXwuJXlR+poUUTRjMTHM=” -X GET https://10.20.181.101/api/task/fa749dcb-c1d8-49f6-95db-8d2692cb07c9

11.getPowerOnTask

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.

12. Get vApp ScreenTicket

$ curl -i -k -H “Accept:application/*+xml;version=1.5″ -H “x-vcloud-authorization: SkqSCI//xE4Q6geIXMpnp7CVXwuJXlR+poUUTRjMTHM=” -X POST https://10.20.181.101/api/vApp/vm-928cb8f8-81ec-4503-9d22-306b2afa3149/screen/action/acquireTicket

12.getScreenTicket

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.

$ cat undeploy-request
<UndeployVAppParams xmlns=”http://www.vmware.com/vcloud/v1.5″>
<UndeployPowerAction>powerOff</UndeployPowerAction>
</UndeployVAppParams>

13. Undeploy vApp

$ curl -i -k -H “Accept:application/*+xml;version=1.5″ -H “x-vcloud-authorization: SkqSCI//xE4Q6geIXMpnp7CVXwuJXlR+poUUTRjMTHM=” -H “Content-Type:application/vnd.vmware.vcloud.undeployVAppParams+xml” -X POST https://10.20.181.101/api/vApp/vapp-fc611c57-ba91-44e2-87ab-42bb913f45cf/action/undeploy -d @undeploy-request

13.undeploy

As with the powerOn operation, we can perform a GET operation on the vCloud task to see when the operation has completed before moving to the next step of un-provisioning our vApp.

14. Delete vApp

$ curl -i -k -H “Accept:application/*+xml;version=1.5″ -H “x-vcloud-authorization: SkqSCI//xE4Q6geIXMpnp7CVXwuJXlR+poUUTRjMTHM=” -X DELETE https://10.20.181.101/api/vApp/vapp-fc611c57-ba91-44e2-87ab-42bb913f45cf

14.delete

Once you verified the vApp has been deleted, the last step is to logout of vCloud Director.

15. Logout

$ curl -i -k -H “Accept:application/*+xml;version=1.5″ -H “x-vcloud-authorization: SkqSCI//xE4Q6geIXMpnp7CVXwuJXlR+poUUTRjMTHM=” -X DELETE https://10.20.181.101/api/session
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

13 thoughts on “Exploring the vCloud REST API Part 2

  1. Chad King

    I don’t understand why cURL come into play? I thought this was using rest?
    is cURL a type of rest client?

    1. SK

      Yes, cURL is a rest client automatially available in many (all?) distributions. Just type curl and you will the help for cURL.

  2. VMware Automation

    @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.

  3. ViRtUaLBoB

    …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

    curl -i -k -H “Accept:application/*+xml;version=5.1″ -u ‘username@org:password’ -X POST https://vcloud.example.com/api/sessions

    HTTP/1.1 401 Unauthorized

    curl -i -k -H “Accept:application/*+xml;version=5.1″ -u “username@org:password” -X POST https://vcloud.example.com/api/sessions

    HTTP/1.1 200 OK

  4. JCDelgado

    Hi, when i create new vApp from vAppTemplate, the network appears disconnected from the VM. Why? How can i connect this?

  5. Patrick Hurley

    I am using Google Rest Console 4.0.2. Can you please tell me where to put the information into the Rest Console for an example such as:

    2. List All Organizations

    $ curl -i -k -H “Accept:application/*+xml;version=1.5″ -H “x-vcloud-authorization: SkqSCI//xE4Q6geIXMpnp7CVXwuJXlR+poUUTRjMTHM=” -X GET https://10.20.181.101/api/org

  6. Ashutosh Mohle

    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.

    More over for getting the IP of created VMs we can use this command

    $ curl -i -k -H “Accept:application/*+xml;version=1.5″ -H “x-vcloud-authorization: SkqSCI//xE4Q6geIXMpnp7CVXwuJXlR+poUUTRjMTHM=” -X GET https://10.20.181.101/api/vApp/vm-928cb8f8-81ec-4503-9d22-306b2afa3149

  7. ben

    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.

  8. Pingback: Getting started with the vCloud Director API with Python | virtual devops

Comments are closed.