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