posted by C.J. Taylor
In my last article I covered enough material to do an authentication handshake with the vCloud API and retrieve some of the most common items. Of course, the API isn’t just used to get information on vCloud objects. Today I’m going to cover a few simple set commands giving you a few easy examples to replicate. The tasks are on the shallow end of the pool with one small wade out toward the deep end.
Some set commands, especially when it comes to Virtual Machines, can become complex quickly. vCloud API development also requires some decent knowledge of VMWare’s virtual machine properties, what they mean and how they’re related. The API becomes very granular quickly, with the upside being control and precision. Just understand that using it isn’t like rubbing a lamp, making a wish, and suddenly having a re-sized hard drive (a single subject worthy of its own article).
A Few Assumptions
Before proceeding, have a firm grip on how to set and successfully instantiate SDK objects. This was covered in my previous article.
To avoid redundancy, I’ll be making reference to some methods I created in my past article. So some methods defined below are simply building on the vCloudWrap class I began in Part 1.
Your API User
Creating an API user is a good practice. Once you have the user from vCloud, you have the same permissions in the API as you would through the console. Whether you’re administering a full instance of vCloud or an individual organization, the available commands are limited to the permissions of that user’s role. In addition to automation, you can limit other user’s permissions directly through the vCloud console, but allow logically controlled tasks through API calls.
The following examples are subject to the permissions you have open and available to the user via the API. For the examples provided below to work, the user must be able to modify vApps and VMs.
Simple Walkthrough: Powering vApps On and Off
When reviewing the SDK documention, it’s an easy pitfall to assume that powerOn() and powerOff() do indeed power on and off objects. In reality this will leave VMs in a state of “partially powered off”, a feature I’ve yet to replicate with the power button on my PC at home. There’s a legitimate explanation to this that can be found here in an article written by William Lamm. This goes back to my earlier statement about having equal knowledge of vCloud’s user interface functionality as well as the commands you send to the API.
Generally when you send the command to power off, you expect that to become the state of the object you’re controlling. Let’s start with the task of power control, which is done with the methods deploy() and undeploy().
Assuming your VApp is currently running, we’re going to call the service SDK object, create an SDK object for the vApp, and then run the undeploy() command. $href is the prefetched href string value of the vApp we’re controlling. Also, (un)deploy() requires a special object type as noted in the documentation: VMware_VCloud_API_UndeployeVAppParamsType. It’s an object that allows us to adjust parameters before passing it to the SDK’s method. This one is fairly simple and many modification calls have one. Become familiar with this workflow and you will have less trouble coming up with other more complex operations you may wish to develop.
Below we’re telling vCloud to undeploy (power off) a vApp using its default settings for this action.
Now to power it back on. We don’t use the same API object as we did for undeploying. The methods/properties are customized for this action.
Powering VMs On and Off In Sequence
We’re going to do a similar action this time with a single Virtual Machine rather than the entire vApp. We’re going to chain an undeploy and a deploy back to back. Basically we’re going to turn the VM off and then back on immediately after that. However, there’s a trick to this. Tasks get queued in vCloud. When we send a request to the server, it throws it in a queue to start the task immediately and then returns a response. When we get a response, that does not mean the task is complete!
Because of PHP’s synchronous behavior, the moment we get back a response to our code it immediately moves on to the next process. This leads to telling vCloud to turn on a VM that’s already on, although it currently has a task queued that will shut it off. The result isn’t a submission of a new task. An error is returned telling us there are tasks pending on that object and the call fails.
The solution? We wait. This is done by a method on the service SDK called waitForTask(). During this time the script sleeps until the task on the top of vCloud’s “task stack” for this item has been completed. This routine can become so common that we’re going to create a method specifically for this on vCloudWrap:
Take note in the code below that we must retrieve a refreshed version of the object in its current state before requesting to wait on its tasks or anything else. Now let’s turn off and back on our VM. Note: Practically we would call the sdk method reboot(). However, what we’re doing here is for academic purposes.
Now that you’re familiar with the API param type objects and how they’re set and passed to an sdk object, I want to focus in a bit more. It’s key to understanding the process for modifying when using the SDK methods. As I mentioned before, this can become involved. Some API parameter types require an assembly of multiple parameter objects to send a single configuration command to vCloud. I’m going to scrape the surface of how this works here.
The next example modifies a VM’s RAM. To do that we need the object VMware_VCloud_API_OVF_RASD_Type passed to the VM’s sdk method modifyVirtualMemory(). Many times building these parameter types from scratch is no simple task. But thankfully on an existing VM it’s rarely necessary. We’re going to retrieve the current configuration from the VM, which already contains these other pre-constructed objects reflecting that. We then simply have the task of modifying them and sending it back to vCloud. Here’s an example.
Hopefully this article helps in understanding the root concept of how the SDK handles modifying objects on vCloud. It’s most certainly not limited to VApps and VMs alone. Not only does the API cover everything that a user can do in vCloud Director, but even a bit more where it comes to VM configuration. Any object the API user is granted permissions to modify can be done in the API, and the workflow is usually the same. That is, an SDK method is called with either a simple value for a parameter or an object that defines all the complexity of the related configuration request.
In the next article we’ll go up a level to the VDC and explore how to create new vApps and VMs. Until then, I hope this was helpful! Feel free to ask questions in the comments!CJ