Discussion on the state of cloud computing and open source software that helps build, manage, and deliver everything-as-a-service.
Beginners guide to interacting with the CloudStack API
CloudStack has a nice (and ever improving) UI, and sometimes the robust API gets ignored. I recently had to help another open source project that wants to interact with CloudStack via the API and figured I'd post some of that experience here. I should note that there is also CloudBridge which permits you to use the EC2 API to interface with CloudStack, so you can make use of the ec2 and euca client tools to interface with CloudStack, but this post talks only about the native CloudStack API
Lets first talk about access - there are two API interfaces. The first is unauthenticated and listens on port 8096. This is really designed to be called from localhost, and if you aren't using it we advise ensuring that it stays firewalled off or is disabled. It is pretty simple to query
So you can for instance run the following from your management server:
$ curl http://localhost:8096/?command=listHosts
The above will return a list of physical compute nodes. You'll notice I used curl in this example and in the ones to follow to call the API, you could do this equally well with wget or even a web browser.
The second, more 'public' interface that runs on the same port as the UI, which is port 8080 for most people. This requires authentication, and is a 'bit' more work to generate requests. The additional work comes from the fact that you must specify your API key, and you must 'sign' your request using your Secret Key. We'll talk more about that in a bit when we talk about forming requests, but here is what the above request would like on the authenticated interface:
$ curl http://davidsmanagementserver.cloustack.org:8080/client/api?apikey=4uWlbYbxSYedp8NQC46RAi4rdnZ277X7TAj1jWp1aGEDRDpZQnVq4zZiX5PNXuxw9oJSrFVR6QAO1sqXq9a8jw&command=listhosts&signature=wcnVSNI/4EVDnGnXS0y0lo/qgy4=
If you tried the above requests you likely saw an XML response, which is pretty useful, but many prefer JSON, so you can append &response=json to your command and it will provide you with a response in JSON
The above examples has been pretty simple, listing all the hosts. Well that makes for a simplistic view of getting information out, but there are plenty of things that can be done from the API, we'll initially stick with a few examples of getting information but we'll add some examples of making CloudStack do work as well. We'll be doing this using the local unauthenticated API interface till we discuss more properly forming the requests.
$ curl http://localhost:8096/?command=listCapacity
The above will tell you about the capacity of your cloud, certainly interesting, but rather generic.
$ curl http://localhost:8096/?command=listVirtualMachines&domainId=1&account=admin
This shows all of the VM instances owned by the Admin user.
Lets move on to making CloudStack do something.
$ curl http://localhost:8096/?command=stopVirtualMachine&id=6
The above stops one of the virtual machines I listed earlier. If you try this you'll notice the response is a bit different. That's because this is an asynchronous call. It will give you the job id, but because the response might actually take a few seconds or even a few minutes it provides an immediate response with the job id. For me it provided job id 33, so I can use the following to check on the status:
$ curl http://localhost:8096/?command=queryAsyncJobResult&jobid=33
This is going to provide a set of result codes, which are pretty simple and as follows:
0 - Job is still in progress. Continue to periodically poll for any status changes.
1 - Job has successfully completed. The job will return any successful response values associated with command that was originally executed.
2 - Job has failed to complete. Please check the
$ curl http://localhost:8096/?command=deployVirtualMachine&serviceofferingid=1&zoneid=1&templateid=4
The above deploys a virtual machine in my first zone. I can of course specify a veritable plethora of other configuration items. The API is pretty robust.
Now as promised I said we'd talk about sending API requests to the 'public' API interface. I could describe the process of generating these requests, but figure you could read the official documentation if you are really interested in the mechanics. Instead I'll get you up and firing off API requests in short order.
You'll need to acquire two pieces of information from the UI, and that's the API and Secret Key for the user you are wanting to use. I should add in here, that all of these commands have assumed that the user is an admin - domain admins and users have fewer permissions, and smaller default scopes. You can find the your keys by going to Accounts, locating your account, click on the Users tab, find your user and you should see fields for API key and Secret Key. If these aren't populated, click on 'Generate Keys' from the Actions drop down menu.
For the purpose of this documentation, the API key is:
and the Secret key is:
I tend to be a bit lazy, and found a nice perl script from shugonumano on github that makes this process a bit easier (and to be fair, there's some java code in CloudStack's API documentation, but this is a bit smaller and easier to use, in my opinion) You can grab a copy of that script at: https://github.com/snumano/CloudStack-API
So I provide the inputs that generate-url.pl requests:
Usage:generate-url.pl -u "command=
$ generate-url.pl -u "command=listcapacity"
A couple of things that you should note, the command isn't using camelcase or studly caps, instead it's all lowercase.
That spits out the url:
You'll note that this doesn't work, you'll need to reintroduce the appropriate caps into the command like:
And that's really all there is to it, which makes it relatively easy to integrate CloudStack with your monitoring system, configuration management, etc. You'll certainly want to make CloudStack's API documentation readily available: