Google Git
Sign in
apache / cloudstack-docs / 152589eb15ec87167472b3d1f340445d87e66a7a / . / rtd / source / dev.rst
blob: bdb6b3e843efd4e45e4ac2d580d4303b755f4fc3 [file] [log] [blame]
.. Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information#
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
Programmer Guide
================
This guide shows how to develop CloudStack, use the API for operation
and integration, access the usage data and use CloudStack specific tools
to ease development, testing and integration.
The CloudStack API
------------------
Getting Started
~~~~~~~~~~~~~~~
To get started using the CloudStack API, you should have the following:
- URL of the CloudStack server you wish to integrate with.
- Both the API Key and Secret Key for an account. This should have been
generated by the administrator of the cloud instance and given to
you.
- Familiarity with HTTP GET/POST and query strings.
- Knowledge of either XML or JSON.
- Knowledge of a programming language that can generate HTTP requests;
for example, Java or PHP.
Roles
~~~~~
The CloudStack API supports three access roles:
#. Root Admin. Access to all features of the cloud, including both
virtual and physical resource management.
#. Domain Admin. Access to only the virtual resources of the clouds that
belong to the administrator’s domain.
#. User. Access to only the features that allow management of the user’s
virtual instances, storage, and network.
API Reference Documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can find all the API reference documentation at the below site:
`http://cloudstack.apache.org/docs/api/
<http://cloudstack.apache.org/docs/api/>`__
Making API Requests
~~~~~~~~~~~~~~~~~~~~
All CloudStack API requests are submitted in the form of a HTTP GET/POST
with an associated command and any parameters. A request is composed of
the following whether in HTTP or HTTPS:
- CloudStack API URL: This is the web services API entry point(for
example, http://www.example.com:8080/client/api)
- Command: The web services command you wish to execute, such as start
a virtual machine or create a disk volume
- Parameters: Any additional required or optional parameters for the
command
A sample API GET request looks like the following:
.. sourcecode:: bash
http://localhost:8080/client/api?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
Or in a more readable format:
.. sourcecode:: bash
1. http://localhost:8080/client/api
2. ?command=deployVirtualMachine
3. &serviceOfferingId=1
4. &diskOfferingId=1
5. &templateId=2
6. &zoneId=4
7. &apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXqjB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ
8. &signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
The first line is the CloudStack API URL. This is the Cloud instance you
wish to interact with.
The second line refers to the command you wish to execute. In our
example, we are attempting to deploy a fresh new virtual machine. It is
preceded by a (?) to separate itself from the CloudStack API URL.
Lines 3-6 are the parameters for this given command. To see the command
and its request parameters, please refer to the appropriate section in
the CloudStack API documentation. Each parameter field-value pair
(field=value) is preceded by an ampersand character (&).
Line 7 is the user API Key that uniquely identifies the account. See
Signing API Requests on page 7.
Line 8 is the signature hash created to authenticate the user account
executing the API command.
Signing API Requests
~~~~~~~~~~~~~~~~~~~~
Whether you access the CloudStack API with HTTP or HTTPS, it must still
be signed so that CloudStack can verify the caller has been
authenticated and authorized to execute the command. Make sure that you
have both the API Key and Secret Key provided by the CloudStack
administrator for your account before proceeding with the signing
process.
To show how to sign a request, we will re-use the previous example.
.. sourcecode:: bash
http://http://localhost:8080/client/api?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
Breaking this down, we have several distinct parts to this URL.
- Base URL: This is the base URL to the CloudStack Management Server.
.. sourcecode:: bash
http://localhost:8080
- API Path: This is the path to the API Servlet that processes the
incoming requests.
.. sourcecode:: bash
/client/api?
- Command String: This part of the query string comprises of the
command, its parameters, and the API Key that identifies the account.
.. note::
As with all query string parameters of field-value pairs, the "field"
component is case insensitive while all "value" values are case
sensitive.
.. sourcecode: bash
command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ
- Signature: This is the signature of the command string that is
generated using a combination of the user’s Secret Key and the HMAC
SHA-1 hashing algorithm.
.. sourcecode:: bash
&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
Every API request has the format Base URL+API Path+Command
String+Signature.
To generate the signature.
#. For each field-value pair (as separated by a '&') in the Command
String, URL encode each value so that it can be safely sent via HTTP
GET.
.. note:: Make sure all spaces are encoded as "%20" rather than "+".
#. Lower case the entire Command String and sort it alphabetically via
the field for each field-value pair. The result of this step would
look like the following.
.. sourcecode:: bash
apikey=mivr6x7u6bn_sdahobpjnejpgest35exq-jb8cg20yi3yaxxcgpyuairmfi_ejtvwz0nukkjbpmy3y2bcikwfq&command=deployvirtualmachine&diskofferingid=1&serviceofferingid=1&templateid=2&zoneid=4
#. Take the sorted Command String and run it through the HMAC SHA-1
hashing algorithm (most programming languages offer a utility method
to do this) with the user’s Secret Key. Base64 encode the resulting
byte array in UTF-8 so that it can be safely transmitted via HTTP.
The final string produced after Base64 encoding should be
"Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D".
By reconstructing the final URL in the format Base URL+API
Path+Command String+Signature, the final URL should look like:
.. sourcecode:: bash
http://localhost:8080/client/api?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
How to sign an API call with Python
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To illustrate the procedure used to sign API calls we present a step by
step interactive session using Python.
First import the required modules:
.. sourcecode:: bash
$python
Python 2.7.3 (default, Nov 17 2012, 19:54:34)
[GCC 4.2.1 Compatible Apple Clang 4.1 ((tags/Apple/clang-421.11.66))] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import urllib2
>>> import urllib
>>> import hashlib
>>> import hmac
>>> import base64
Define the endpoint of the Cloud, the command that you want to execute
and the keys of the user.
.. sourcecode:: bash
>>> baseurl='http://localhost:8080/client/api?'
>>> request={}
>>> request['command']='listUsers'
>>> request['response']='json'
>>> request['apikey']='plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg'
>>> secretkey='VDaACYb0LV9eNjTetIOElcVQkvJck_J_QljX_FcHRj87ZKiy0z0ty0ZsYBkoXkY9b7eq1EhwJaw7FF3akA3KBQ'
Build the request string:
.. sourcecode:: bash
>>> request_str='&'.join(['='.join([k,urllib.quote_plus(request[k])]) for k in request.keys()])
>>> request_str
'apikey=plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg&command=listUsers&response=json'
.. note::
If you have API calls which contain * (asterisk) characters, you will need to add the option "safe = '*'" for the URL encoding.
The reason is that Python's urllib will encode * characters by default, while CloudStack's internal encoder does not encode them;
this results in an authentication failure for your API call. In the above you would replace "urllib.quote_plus(request[k])"
with "urllib.quote_plus(request[k], safe='*')".
Compute the signature with hmac, do a 64 bit encoding and a url
encoding:
.. sourcecode:: bash
>>> sig_str='&'.join(['='.join([k.lower(),urllib.quote_plus(request[k].lower().replace('+','%20'))])for k in sorted(request.iterkeys())])
>>> sig_str 'apikey=plgwjfzk4gys3momtvmjuvg-x-jlwlnfauj9gabbbf9edm-kaymmailqzzq1elzlyq_u38zcm0bewzgudp66mg&command=listusers&response=json'
>>> sig=hmac.new(secretkey,sig_str,hashlib.sha1)
>>> sig
<hmac.HMAC instance at 0x10d91d680>
>>> sig=hmac.new(secretkey,sig_str,hashlib.sha1).digest()
>>> sig
'M:]\x0e\xaf\xfb\x8f\xf2y\xf1p\x91\x1e\x89\x8a\xa1\x05\xc4A\xdb'
>>> sig=base64.encodestring(hmac.new(secretkey,sig_str,hashlib.sha1).digest())
>>> sig
'TTpdDq/7j/J58XCRHomKoQXEQds=\n'
>>> sig=base64.encodestring(hmac.new(secretkey,sig_str,hashlib.sha1).digest()).strip()
>>> sig
'TTpdDq/7j/J58XCRHomKoQXEQds='
>>> sig=urllib.quote_plus(base64.encodestring(hmac.new(secretkey,sig_str,hashlib.sha1).digest()).strip())
Finally, build the entire string and do an http GET:
.. sourcecode:: bash
>>> req=baseurl+request_str+'&signature='+sig
>>> req
'http://localhost:8080/client/api?apikey=plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg&command=listUsers&response=json&signature=TTpdDq%2F7j%2FJ58XCRHomKoQXEQds%3D'
>>> res=urllib2.urlopen(req)
>>> res.read()
'{ "listusersresponse" : { "count":3 ,"user" : [ {"id":"7ed6d5da-93b2-4545-a502-23d20b48ef2a","username":"admin","firstname":"admin","lastname":"cloud","created":"2012-07-05T12:18:27-0700","state":"enabled","account":"admin","accounttype":1,"domainid":"8a111e58-e155-4482-93ce-84efff3c7c77","domain":"ROOT","apikey":"plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg","secretkey":"VDaACYb0LV9eNjTetIOElcVQkvJck_J_QljX_FcHRj87ZKiy0z0ty0ZsYBkoXkY9b7eq1EhwJaw7FF3akA3KBQ","accountid":"7548ac03-af1d-4c1c-9064-2f3e2c0eda0d"}, {"id":"1fea6418-5576-4989-a21e-4790787bbee3","username":"runseb","firstname":"foobar","lastname":"goa","email":"joe@smith.com","created":"2013-04-10T16:52:06-0700","state":"enabled","account":"admin","accounttype":1,"domainid":"8a111e58-e155-4482-93ce-84efff3c7c77","domain":"ROOT","apikey":"Xhsb3MewjJQaXXMszRcLvQI9_NPy_UcbDj1QXikkVbDC9MDSPwWdtZ1bUY1H7JBEYTtDDLY3yuchCeW778GkBA","secretkey":"gIsgmi8C5YwxMHjX5o51pSe0kqs6JnKriw0jJBLceY5bgnfzKjL4aM6ctJX-i1ddQIHJLbLJDK9MRzsKk6xZ_w","accountid":"7548ac03-af1d-4c1c-9064-2f3e2c0eda0d"}, {"id":"52f65396-183c-4473-883f-a37e7bb93967","username":"toto","firstname":"john","lastname":"smith","email":"john@smith.com","created":"2013-04-23T04:27:22-0700","state":"enabled","account":"admin","accounttype":1,"domainid":"8a111e58-e155-4482-93ce-84efff3c7c77","domain":"ROOT","apikey":"THaA6fFWS_OmvU8od201omxFC8yKNL_Hc5ZCS77LFCJsRzSx48JyZucbUul6XYbEg-ZyXMl_wuEpECzK-wKnow","secretkey":"O5ywpqJorAsEBKR_5jEvrtGHfWL1Y_j1E4Z_iCr8OKCYcsPIOdVcfzjJQ8YqK0a5EzSpoRrjOFiLsG0hQrYnDA","accountid":"7548ac03-af1d-4c1c-9064-2f3e2c0eda0d"} ] } }'
Enabling API Call Expiration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can set an expiry timestamp on API calls to prevent replay attacks
over non-secure channels, such as HTTP. The server tracks the expiry
timestamp you have specified and rejects all the subsequent API requests
that come in after this validity period.
To enable this feature, add the following parameters to the API request:
- signatureVersion=3: If the signatureVersion parameter is missing or
is not equal to 3, the expires parameter is ignored in the API
request.
- expires=YYYY-MM-DDThh:mm:ssZ: Specifies the date and time at which
the signature included in the request is expired. The timestamp is
expressed in the YYYY-MM-DDThh:mm:ssZ format, as specified in the ISO
8601 standard.
For example:
.. sourcecode:: bash
expires=2011-10-10T12:00:00+0530
A sample API request with expiration is given below:
.. sourcecode:: bash
http://<IPAddress>:8080/client/api?command=listZones&signatureVersion=3&expires=2011-10-10T12:00:00+0530&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
Limiting the Rate of API Requests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can limit the rate at which API requests can be placed for each
account. This is useful to avoid malicious attacks on the Management
Server, prevent performance degradation, and provide fairness to all
accounts.
If the number of API calls exceeds the threshold, an error message is
returned for any additional API calls. The caller will have to retry
these API calls at another time.
Configuring the API Request Rate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To control the API request rate, use the following global configuration
settings:
- `api.throttling.enabled` - Enable/Disable API throttling. By default,
this setting is false, so API throttling is not enabled.
- `api.throttling.interval` (in seconds) - Time interval during which the
number of API requests is to be counted. When the interval has
passed, the API count is reset to 0.
- `api.throttling.max` - Maximum number of APIs that can be placed within
the `api.throttling.interval` period.
- `api.throttling.cachesize` - Cache size for storing API counters. Use a
value higher than the total number of accounts managed by the cloud.
One cache entry is needed for each account, to store the running API
total for that account.
Limitations on API Throttling
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following limitations exist in the current implementation of this
feature.
.. note::
Even with these limitations, CloudStack is still able to effectively use
API throttling to avoid malicious attacks causing denial of service.
- In a deployment with multiple Management Servers, the cache is not
synchronized across them. In this case, CloudStack might not be able
to ensure that only the exact desired number of API requests are
allowed. In the worst case, the number of API calls that might be
allowed is (number of Management Servers) \* (api.throttling.max).
- The API commands resetApiLimit and getApiLimit are limited to the
Management Server where the API is invoked.
API Responses
~~~~~~~~~~~~~
Response Formats: XML and JSON
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
CloudStack supports two formats as the response to an API call. The
default response is XML. If you would like the response to be in JSON,
add `&response=json` to the Command String.
The two response formats differ in how they handle blank fields. In
JSON, if there is no value for a response field, it will not appear in
the response. If all the fields were empty, there might be no response
at all. In XML, even if there is no value to be returned, an empty field
will be returned as a placeholder XML element.
Sample XML Response:
.. sourcecode:: bash
<listipaddressesresponse>
<allocatedipaddress>
<ipaddress>192.168.10.141</ipaddress>
<allocated>2009-09-18T13:16:10-0700</allocated>
<zoneid>4</zoneid>
<zonename>WC</zonename>
<issourcenat>true</issourcenat>
</allocatedipaddress>
</listipaddressesresponse>
Sample JSON Response:
.. sourcecode:: bash
{ "listipaddressesresponse" :
{ "allocatedipaddress" :
[
{
"ipaddress" : "192.168.10.141",
"allocated" : "2009-09-18T13:16:10-0700",
"zoneid" : "4",
"zonename" : "WC",
"issourcenat" : "true"
}
]
}
}
Maximum Result Pages Returned
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For each cloud, there is a default upper limit on the number of results
that any API command will return in a single page. This is to help
prevent overloading the cloud servers and prevent DOS attacks. For
example, if the page size limit is 500 and a command returns 10,000
results, the command will return 20 pages.
The default page size limit can be different for each cloud. It is set
in the global configuration parameter `default.page.size`. If your cloud
has many users with lots of VMs, you might need to increase the value of
this parameter. At the same time, be careful not to set it so high that
your site can be taken down by an enormous return from an API call. For
more information about how to set global configuration parameters, see
"Describe Your Deployment" in the Installation Guide.
To decrease the page size limit for an individual API command, override
the global setting with the page and pagesize parameters, which are
available in any list\* command (listCapabilities, listDiskOfferings,
etc.).
- Both parameters must be specified together.
- The value of the pagesize parameter must be smaller than the value of
default.page.size. That is, you can not increase the number of
possible items in a result page, only decrease it.
For syntax information on the list\* commands, see the API Reference.
Error Handling
~~~~~~~~~~~~~~
If an error occurs while processing an API request, the appropriate
response in the format specified is returned. Each error response
consists of an error code and an error text describing what possibly can
go wrong. Below is a list of possible error codes:
You can now find the CloudStack-specific error code in the exception
response for each type of exception. The following list of error codes
is added to the new class named CSExceptionErrorCode.
4250 : "com.cloud.utils.exception.CloudRuntimeException"
4255 : "com.cloud.utils.exception.ExceptionUtil"
4260 : "com.cloud.utils.exception.ExecutionException"
4265 : "com.cloud.utils.exception.HypervisorVersionChangedException"
4270 : "com.cloud.utils.exception.RuntimeCloudException"
4275 : "com.cloud.exception.CloudException"
4280 : "com.cloud.exception.AccountLimitException"
4285 : "com.cloud.exception.AgentUnavailableException"
4290 : "com.cloud.exception.CloudAuthenticationException"
4295 : "com.cloud.exception.CloudExecutionException"
4300 : "com.cloud.exception.ConcurrentOperationException"
4305 : "com.cloud.exception.ConflictingNetworkSettingsException"
4310 : "com.cloud.exception.DiscoveredWithErrorException"
4315 : "com.cloud.exception.HAStateException"
4320 : "com.cloud.exception.InsufficientAddressCapacityException"
4325 : "com.cloud.exception.InsufficientCapacityException"
4330 : "com.cloud.exception.InsufficientNetworkCapacityException"
4335 : "com.cloud.exception.InsufficientServerCapacityException"
4340 : "com.cloud.exception.InsufficientStorageCapacityException"
4345 : "com.cloud.exception.InternalErrorException"
4350 : "com.cloud.exception.InvalidParameterValueException"
4355 : "com.cloud.exception.ManagementServerException"
4360 : "com.cloud.exception.NetworkRuleConflictException"
4365 : "com.cloud.exception.PermissionDeniedException"
4370 : "com.cloud.exception.ResourceAllocationException"
4375 : "com.cloud.exception.ResourceInUseException"
4380 : "com.cloud.exception.ResourceUnavailableException"
4385 : "com.cloud.exception.StorageUnavailableException"
4390 : "com.cloud.exception.UnsupportedServiceException"
4395 : "com.cloud.exception.VirtualMachineMigrationException"
4400 : "com.cloud.exception.AccountLimitException"
4405 : "com.cloud.exception.AgentUnavailableException"
4410 : "com.cloud.exception.CloudAuthenticationException"
4415 : "com.cloud.exception.CloudException"
4420 : "com.cloud.exception.CloudExecutionException"
4425 : "com.cloud.exception.ConcurrentOperationException"
4430 : "com.cloud.exception.ConflictingNetworkSettingsException"
4435 : "com.cloud.exception.ConnectionException"
4440 : "com.cloud.exception.DiscoveredWithErrorException"
4445 : "com.cloud.exception.DiscoveryException"
4450 : "com.cloud.exception.HAStateException"
4455 : "com.cloud.exception.InsufficientAddressCapacityException"
4460 : "com.cloud.exception.InsufficientCapacityException"
4465 : "com.cloud.exception.InsufficientNetworkCapacityException"
4470 : "com.cloud.exception.InsufficientServerCapacityException"
4475 : "com.cloud.exception.InsufficientStorageCapacityException"
4480 : "com.cloud.exception.InsufficientVirtualNetworkCapcityException"
4485 : "com.cloud.exception.InternalErrorException"
4490 : "com.cloud.exception.InvalidParameterValueException"
4495 : "com.cloud.exception.ManagementServerException"
4500 : "com.cloud.exception.NetworkRuleConflictException"
4505 : "com.cloud.exception.PermissionDeniedException"
4510 : "com.cloud.exception.ResourceAllocationException"
4515 : "com.cloud.exception.ResourceInUseException"
4520 : "com.cloud.exception.ResourceUnavailableException"
4525 : "com.cloud.exception.StorageUnavailableException"
4530 : "com.cloud.exception.UnsupportedServiceException"
4535 : "com.cloud.exception.VirtualMachineMigrationException"
9999 : "org.apache.cloudstack.api.ServerApiException"
An HTTP error code of 401 is always returned if API request was rejected
due to bad signatures, missing API Keys, or the user simply did not have
the permissions to execute the command.
Asynchronous Commands
~~~~~~~~~~~~~~~~~~~~~
Asynchronous commands were introduced in CloudStack 2.x. Commands are
designated as asynchronous when they can potentially take a long period
of time to complete such as creating a snapshot or disk volume. They
differ from synchronous commands by the following:
- They are identified in the API Reference by an (A).
- They will immediately return a job ID to refer to the job that will
be responsible in processing the command.
- If executed as a "create" resource command, it will return the
resource ID as well as the job ID.
You can periodically check the status of the job by making a simple
API call to the command, `queryAsyncJobResult` and passing in the job
ID.
Job Status
~~~~~~~~~~
The key to using an asynchronous command is the job ID that is returned
immediately once the command has been executed. With the job ID, you can
periodically check the job status by making calls to queryAsyncJobResult
command. The command will return three possible job status integer
values:
- 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 "jobresultcode" tag
for failure reason code and "jobresult" for the failure reason.
Example
~~~~~~~
The following shows an example of using an asynchronous command. Assume
the API command:
.. sourcecode:: bash
command=deployVirtualMachine&zoneId=1&serviceOfferingId=1&diskOfferingId=1&templateId=1
CloudStack will immediately return a job ID and any other additional
data.
.. sourcecode:: bash
<deployvirtualmachineresponse>
<jobid>1</jobid>
<id>100</id>
</deployvirtualmachineresponse>
Using the job ID, you can periodically poll for the results by using the
queryAsyncJobResult command.
.. sourcecode:: bash
command=queryAsyncJobResult&jobId=1
Three possible results could come from this query.
Job is still pending:
.. sourcecode:: bash
<queryasyncjobresult>
<jobid>1</jobid>
<jobstatus>0</jobstatus>
<jobprocstatus>1</jobprocstatus>
</queryasyncjobresult>
Job has succeeded:
.. sourcecode:: bash
<queryasyncjobresultresponse cloud-stack-version="3.0.1.6">
<jobid>1</jobid>
<jobstatus>1</jobstatus>
<jobprocstatus>0</jobprocstatus>
<jobresultcode>0</jobresultcode>
<jobresulttype>object</jobresulttype>
<jobresult>
<virtualmachine>
<id>450</id>
<name>i-2-450-VM</name>
<displayname>i-2-450-VM</displayname>
<account>admin</account>
<domainid>1</domainid>
<domain>ROOT</domain>
<created>2011-03-10T18:20:25-0800</created>
<state>Running</state>
<haenable>false</haenable>
<zoneid>1</zoneid>
<zonename>San Jose 1</zonename>
<hostid>2</hostid>
<hostname>905-13.sjc.lab.vmops.com</hostname>
<templateid>1</templateid>
<templatename>CentOS 5.3 64bit LAMP</templatename>
<templatedisplaytext>CentOS 5.3 64bit LAMP</templatedisplaytext>
<passwordenabled>false</passwordenabled>
<serviceofferingid>1</serviceofferingid>
<serviceofferingname>Small Instance</serviceofferingname>
<cpunumber>1</cpunumber>
<cpuspeed>500</cpuspeed>
<memory>512</memory>
<guestosid>12</guestosid>
<rootdeviceid>0</rootdeviceid>
<rootdevicetype>NetworkFilesystem</rootdevicetype>
<nic>
<id>561</id>
<networkid>205</networkid>
<netmask>255.255.255.0</netmask>
<gateway>10.1.1.1</gateway>
<ipaddress>10.1.1.225</ipaddress>
<isolationuri>vlan://295</isolationuri>
<broadcasturi>vlan://295</broadcasturi>
<traffictype>Guest</traffictype>
<type>Virtual</type>
<isdefault>true</isdefault>
</nic>
<hypervisor>XenServer</hypervisor>
</virtualmachine>
</jobresult>
</queryasyncjobresultresponse>
Job has failed:
.. sourcecode:: bash
<queryasyncjobresult>
<jobid>1</jobid>
<jobstatus>2</jobstatus>
<jobprocstatus>0</jobprocstatus>
<jobresultcode>551</jobresultcode>
<jobresulttype>text</jobresulttype>
<jobresult>Unable to deploy virtual machine id = 100 due to not enough capacity</jobresult>
</queryasyncjobresult>
Event Types
-----------
.. cssclass:: table-striped table-bordered table-hover
+-------------------+--------------------------------------------------------+
| Types | Events |
+===================+========================================================+
| VM | VM.CREATE |
| | |
| | VM.DESTROY |
| | |
| | VM.START |
| | |
| | VM.STOP |
| | |
| | VM.REBOOT |
| | |
| | VM.UPDATE |
| | |
| | VM.UPGRADE |
| | |
| | VM.DYNAMIC.SCALE |
| | |
| | VM.RESETPASSWORD |
| | |
| | VM.RESETSSHKEY |
| | |
| | VM.MIGRATE |
| | |
| | VM.MOVE |
| | |
| | VM.RESTORE |
+-------------------+--------------------------------------------------------+
| Domain Router | ROUTER.CREATE |
| | |
| | ROUTER.DESTROY |
| | |
| | ROUTER.START |
| | |
| | ROUTER.STOP |
| | |
| | ROUTER.REBOOT |
| | |
| | ROUTER.HA |
| | |
| | ROUTER.UPGRADE |
+-------------------+--------------------------------------------------------+
| Console proxy | PROXY.CREATE |
| | |
| | PROXY.DESTROY |
| | |
| | PROXY.START |
| | |
| | PROXY.STOP |
| | |
| | PROXY.REBOOT |
| | |
| | PROXY.HA |
+-------------------+--------------------------------------------------------+
| VNC Console | VNC.CONNECT |
| Events | |
| | VNC.DISCONNECT |
+-------------------+--------------------------------------------------------+
| Network Events | NET.IPASSIGN |
| | |
| | NET.IPRELEASE |
| | |
| | PORTABLE.IPASSIGN |
| | |
| | PORTABLE.IPRELEASE |
| | |
| | NET.RULEADD |
| | |
| | NET.RULEDELETE |
| | |
| | NET.RULEMODIFY |
| | |
| | NETWORK.CREATE |
| | |
| | NETWORK.DELETE |
| | |
| | NETWORK.UPDATE |
| | |
| | FIREWALL.OPEN |
| | |
| | FIREWALL.CLOSE |
+-------------------+--------------------------------------------------------+
| NIC Events | NIC.CREATE |
| | |
| | NIC.DELETE |
| | |
| | NIC.UPDATE |
| | |
| | NIC.DETAIL.ADD |
| | |
| | NIC.DETAIL.UPDATE |
| | |
| | NIC.DETAIL.REMOVE |
+-------------------+--------------------------------------------------------+
| Load Balancers | LB.ASSIGN.TO.RULE |
| | |
| | LB.REMOVE.FROM.RULE |
| | |
| | LB.CREATE |
| | |
| | LB.DELETE |
| | |
| | LB.STICKINESSPOLICY.CREATE |
| | |
| | LB.STICKINESSPOLICY.DELETE |
| | |
| | LB.HEALTHCHECKPOLICY.CREATE |
| | |
| | LB.HEALTHCHECKPOLICY.DELETE |
| | |
| | LB.UPDATE |
+-------------------+--------------------------------------------------------+
| Global Load | GLOBAL.LB.ASSIGN |
| Balancer rules | |
| | GLOBAL.LB.REMOVE |
| | |
| | GLOBAL.LB.CREATE |
| | |
| | GLOBAL.LB.DELETE |
| | |
| | GLOBAL.LB.UPDATE |
+-------------------+--------------------------------------------------------+
| Account events | ACCOUNT.ENABLE |
| | |
| | ACCOUNT.DISABLE |
| | |
| | ACCOUNT.CREATE |
| | |
| | ACCOUNT.DELETE |
| | |
| | ACCOUNT.UPDATE |
| | |
| | ACCOUNT.MARK.DEFAULT.ZONE |
+-------------------+--------------------------------------------------------+
| UserVO Events | USER.LOGIN |
| | |
| | USER.LOGOUT |
| | |
| | USER.CREATE |
| | |
| | USER.DELETE |
| | |
| | USER.DISABLE |
| | |
| | USER.UPDATE |
| | |
| | USER.ENABLE |
| | |
| | USER.LOCK |
+-------------------+--------------------------------------------------------+
| Registering SSH | REGISTER.SSH.KEYPAIR |
| keypair events | |
+-------------------+--------------------------------------------------------+
| Register for user | REGISTER.USER.KEY |
| API and secret | |
| keys | |
+-------------------+--------------------------------------------------------+
| Template Events | TEMPLATE.CREATE |
| | |
| | TEMPLATE.DELETE |
| | |
| | TEMPLATE.UPDATE |
| | |
| | TEMPLATE.DOWNLOAD.START |
| | |
| | TEMPLATE.DOWNLOAD.SUCCESS |
| | |
| | TEMPLATE.DOWNLOAD.FAILED |
| | |
| | TEMPLATE.COPY |
| | |
| | TEMPLATE.EXTRACT |
| | |
| | TEMPLATE.UPLOAD |
| | |
| | TEMPLATE.CLEANUP |
+-------------------+--------------------------------------------------------+
| Volume Events | VOLUME.CREATE |
| | |
| | VOLUME.DELETE |
| | |
| | VOLUME.ATTACH |
| | |
| | VOLUME.DETACH |
| | |
| | VOLUME.EXTRACT |
| | |
| | VOLUME.UPLOAD |
| | |
| | VOLUME.MIGRATE |
| | |
| | VOLUME.RESIZE |
| | |
| | VOLUME.DETAIL.UPDATE |
| | |
| | VOLUME.DETAIL.ADD |
| | |
| | VOLUME.DETAIL.REMOVE |
+-------------------+--------------------------------------------------------+
| Domains | DOMAIN.CREATE |
| | |
| | DOMAIN.DELETE |
| | |
| | DOMAIN.UPDATE |
+-------------------+--------------------------------------------------------+
| Snapshots | SNAPSHOT.CREATE |
| | |
| | SNAPSHOT.DELETE |
| | |
| | SNAPSHOTPOLICY.CREATE |
| | |
| | SNAPSHOTPOLICY.UPDATE |
| | |
| | SNAPSHOTPOLICY.DELETE |
+-------------------+--------------------------------------------------------+
| ISO | ISO.CREATE |
| | |
| | ISO.DELETE |
| | |
| | ISO.COPY |
| | |
| | ISO.ATTACH |
| | |
| | ISO.DETACH |
| | |
| | ISO.EXTRACT |
| | |
| | ISO.UPLOAD |
+-------------------+--------------------------------------------------------+
| SSVM | SSVM.CREATE |
| | |
| | SSVM.DESTROY |
| | |
| | SSVM.START |
| | |
| | SSVM.STOP |
| | |
| | SSVM.REBOOT |
| | |
| | SSVM.HA |
+-------------------+--------------------------------------------------------+
| Service Offerings | SERVICE.OFFERING.CREATE |
| | |
| | SERVICE.OFFERING.EDIT |
| | |
| | SERVICE.OFFERING.DELETE |
+-------------------+--------------------------------------------------------+
| Disk Offerings | DISK.OFFERING.CREATE |
| | |
| | DISK.OFFERING.EDIT |
| | |
| | DISK.OFFERING.DELETE |
+-------------------+--------------------------------------------------------+
| Network offerings | NETWORK.OFFERING.CREATE |
| | |
| | NETWORK.OFFERING.ASSIGN |
| | |
| | NETWORK.OFFERING.EDIT |
| | |
| | NETWORK.OFFERING.REMOVE |
| | |
| | NETWORK.OFFERING.DELETE |
+-------------------+--------------------------------------------------------+
| Pods | POD.CREATE |
| | |
| | POD.EDIT |
| | |
| | POD.DELETE |
+-------------------+--------------------------------------------------------+
| Zones | ZONE.CREATE |
| | |
| | ZONE.EDIT |
| | |
| | ZONE.DELETE |
+-------------------+--------------------------------------------------------+
| VLANs/IP ranges | VLAN.IP.RANGE.CREATE |
| | |
| | VLAN.IP.RANGE.DELETE |
| | |
| | VLAN.IP.RANGE.DEDICATE |
| | |
| | VLAN.IP.RANGE.RELEASE |
| | |
| | STORAGE.IP.RANGE.CREATE |
| | |
| | STORAGE.IP.RANGE.DELETE |
| | |
| | STORAGE.IP.RANGE.UPDATE |
+-------------------+--------------------------------------------------------+
| Configuration | CONFIGURATION.VALUE.EDIT |
| Table | |
+-------------------+--------------------------------------------------------+
| Security Groups | SG.AUTH.INGRESS |
| | |
| | SG.REVOKE.INGRESS |
| | |
| | SG.AUTH.EGRESS |
| | |
| | SG.REVOKE.EGRESS |
| | |
| | SG.CREATE |
| | |
| | SG.DELETE |
| | |
| | SG.ASSIGN |
| | |
| | SG.REMOVE |
+-------------------+--------------------------------------------------------+
| Host | HOST.RECONNECT |
+-------------------+--------------------------------------------------------+
| Maintenance | MAINT.CANCEL |
| | |
| | MAINT.CANCEL.PS |
| | |
| | MAINT.PREPARE |
| | |
| | MAINT.PREPARE.PS |
+-------------------+--------------------------------------------------------+
| VPN | VPN.REMOTE.ACCESS.CREATE |
| | |
| | VPN.REMOTE.ACCESS.DESTROY |
| | |
| | VPN.USER.ADD |
| | |
| | VPN.USER.REMOVE |
| | |
| | VPN.S2S.VPN.GATEWAY.CREATE |
| | |
| | VPN.S2S.VPN.GATEWAY.DELETE |
| | |
| | VPN.S2S.CUSTOMER.GATEWAY.CREATE |
| | |
| | VPN.S2S.CUSTOMER.GATEWAY.DELETE |
| | |
| | VPN.S2S.CUSTOMER.GATEWAY.UPDATE |
| | |
| | VPN.S2S.CONNECTION.CREATE |
| | |
| | VPN.S2S.CONNECTION.DELETE |
| | |
| | VPN.S2S.CONNECTION.RESET |
+-------------------+--------------------------------------------------------+
| Network | NETWORK.RESTART |
+-------------------+--------------------------------------------------------+
| Custom | UPLOAD.CUSTOM.CERTIFICATE |
| certificates | |
+-------------------+--------------------------------------------------------+
| OneToOnenat | STATICNAT.ENABLE |
| | |
| | STATICNAT.DISABLE |
| | |
| | ZONE.VLAN.ASSIGN |
| | |
| | ZONE.VLAN.RELEASE |
+-------------------+--------------------------------------------------------+
| Projects | PROJECT.CREATE |
| | |
| | PROJECT.UPDATE |
| | |
| | PROJECT.DELETE |
| | |
| | PROJECT.ACTIVATE |
| | |
| | PROJECT.SUSPEND |
| | |
| | PROJECT.ACCOUNT.ADD |
| | |
| | PROJECT.INVITATION.UPDATE |
| | |
| | PROJECT.INVITATION.REMOVE |
| | |
| | PROJECT.ACCOUNT.REMOVE |
+-------------------+--------------------------------------------------------+
| Network as a | NETWORK.ELEMENT.CONFIGURE |
| Service | |
+-------------------+--------------------------------------------------------+
| Physical Network | PHYSICAL.NETWORK.CREATE |
| Events | |
| | PHYSICAL.NETWORK.DELETE |
| | |
| | PHYSICAL.NETWORK.UPDATE |
+-------------------+--------------------------------------------------------+
| Physical Network | SERVICE.PROVIDER.CREATE |
| Service Provider | |
| Events | SERVICE.PROVIDER.DELETE |
| | |
| | SERVICE.PROVIDER.UPDATE |
+-------------------+--------------------------------------------------------+
| Physical Network | TRAFFIC.TYPE.CREATE |
| Traffic Type | |
| Events | TRAFFIC.TYPE.DELETE |
| | |
| | TRAFFIC.TYPE.UPDATE |
+-------------------+--------------------------------------------------------+
| External network | PHYSICAL.LOADBALANCER.ADD |
| device events | |
| | PHYSICAL.LOADBALANCER.DELETE |
| | |
| | PHYSICAL.LOADBALANCER.CONFIGURE |
+-------------------+--------------------------------------------------------+
| External switch | SWITCH.MGMT.ADD |
| management device | |
| events | SWITCH.MGMT.DELETE |
| | |
| For example: | SWITCH.MGMT.CONFIGURE |
| Cisco Nexus 1000v | |
| Virtual | SWITCH.MGMT.ENABLE |
| Supervisor | |
| Module. | SWITCH.MGMT.DISABLE |
| | |
| | PHYSICAL.FIREWALL.ADD |
| | |
| | PHYSICAL.FIREWALL.DELETE |
| | |
| | PHYSICAL.FIREWALL.CONFIGURE |
+-------------------+--------------------------------------------------------+
| VPC | VPC.CREATE |
| | |
| | VPC.UPDATE |
| | |
| | VPC.DELETE |
| | |
| | VPC.RESTART |
+-------------------+--------------------------------------------------------+
| Network ACL | NETWORK.ACL.CREATE |
| | |
| | NETWORK.ACL.DELETE |
| | |
| | NETWORK.ACL.REPLACE |
| | |
| | NETWORK.ACL.ITEM.CREATE |
| | |
| | NETWORK.ACL.ITEM.UPDATE |
| | |
| | NETWORK.ACL.ITEM.DELETE |
+-------------------+--------------------------------------------------------+
| VPC offerings | VPC.OFFERING.CREATE |
| | |
| | VPC.OFFERING.UPDATE |
| | |
| | VPC.OFFERING.DELETE |
+-------------------+--------------------------------------------------------+
| Private gateway | PRIVATE.GATEWAY.CREATE |
| | |
| | PRIVATE.GATEWAY.DELETE |
+-------------------+--------------------------------------------------------+
| Static routes | STATIC.ROUTE.CREATE |
| | |
| | STATIC.ROUTE.DELETE |
+-------------------+--------------------------------------------------------+
| Tag-related | CREATE\_TAGS |
| events | |
| | DELETE\_TAGS |
+-------------------+--------------------------------------------------------+
| Meta data-related | CREATE\_RESOURCE\_DETAILS |
| events | |
| | DELETE\_RESOURCE\_DETAILS |
+-------------------+--------------------------------------------------------+
| VM snapshot | VMSNAPSHOT.CREATE |
| events | |
| | VMSNAPSHOT.DELETE |
| | |
| | VMSNAPSHOT.REVERTTO |
+-------------------+--------------------------------------------------------+
| External network | PHYSICAL.NVPCONTROLLER.ADD |
| device events | |
| | PHYSICAL.NVPCONTROLLER.DELETE |
| | |
| | PHYSICAL.NVPCONTROLLER.CONFIGURE |
+-------------------+--------------------------------------------------------+
| AutoScale | COUNTER.CREATE |
| | |
| | COUNTER.DELETE |
| | |
| | CONDITION.CREATE |
| | |
| | CONDITION.DELETE |
| | |
| | AUTOSCALEPOLICY.CREATE |
| | |
| | AUTOSCALEPOLICY.UPDATE |
| | |
| | AUTOSCALEPOLICY.DELETE |
| | |
| | AUTOSCALEVMPROFILE.CREATE |
| | |
| | AUTOSCALEVMPROFILE.DELETE |
| | |
| | AUTOSCALEVMPROFILE.UPDATE |
| | |
| | AUTOSCALEVMGROUP.CREATE |
| | |
| | AUTOSCALEVMGROUP.DELETE |
| | |
| | AUTOSCALEVMGROUP.UPDATE |
| | |
| | AUTOSCALEVMGROUP.ENABLE |
| | |
| | AUTOSCALEVMGROUP.DISABLE |
| | |
| | PHYSICAL.DHCP.ADD |
| | |
| | PHYSICAL.DHCP.DELETE |
| | |
| | PHYSICAL.PXE.ADD |
| | |
| | PHYSICAL.PXE.DELETE |
| | |
| | AG.CREATE |
| | |
| | AG.DELETE |
| | |
| | AG.ASSIGN |
| | |
| | AG.REMOVE |
| | |
| | VM.AG.UPDATE |
| | |
| | INTERNALLBVM.START |
| | |
| | INTERNALLBVM.STOP |
| | |
| | HOST.RESERVATION.RELEASE |
+-------------------+--------------------------------------------------------+
| Dedicated guest | GUESTVLANRANGE.DEDICATE |
| vlan range | |
| | GUESTVLANRANGE.RELEASE |
| | |
| | PORTABLE.IP.RANGE.CREATE |
| | |
| | PORTABLE.IP.RANGE.DELETE |
| | |
| | PORTABLE.IP.TRANSFER |
+-------------------+--------------------------------------------------------+
| Dedicated | DEDICATE.RESOURCE |
| Resources | |
| | DEDICATE.RESOURCE.RELEASE |
| | |
| | VM.RESERVATION.CLEANUP |
| | |
| | UCS.ASSOCIATEPROFILE |
| | |
| | UCS.DISASSOCIATEPROFILE |
+-------------------+--------------------------------------------------------+
Time Zones
----------
The following time zone identifiers are accepted by PRODUCT. There are
several places that have a time zone as a required or optional
parameter. These include scheduling recurring snapshots, creating a
user, and specifying the usage time zone in the Configuration table.
.. cssclass:: table-striped table-bordered table-hover
+-----------------------------------+-----------------------+------------------------+
| Etc/GMT+12 | Etc/GMT+11 | Pacific/Samoa |
+-----------------------------------+-----------------------+------------------------+
| Pacific/Honolulu | US/Alaska | America/Los\_Angeles |
+-----------------------------------+-----------------------+------------------------+
| Mexico/BajaNorte | US/Arizona | US/Mountain |
+-----------------------------------+-----------------------+------------------------+
| America/Chihuahua | America/Chicago | America/Costa\_Rica |
+-----------------------------------+-----------------------+------------------------+
| America/Mexico\_City | Canada/Saskatchewan | America/Bogota |
+-----------------------------------+-----------------------+------------------------+
| America/New\_York | America/Caracas | America/Asuncion |
+-----------------------------------+-----------------------+------------------------+
| America/Cuiaba | America/Halifax | America/La\_Paz |
+-----------------------------------+-----------------------+------------------------+
| America/Santiago | America/St\_Johns | America/Araguaina |
+-----------------------------------+-----------------------+------------------------+
| America/Argentina/Buenos\_Aires | America/Cayenne | America/Godthab |
+-----------------------------------+-----------------------+------------------------+
| America/Montevideo | Etc/GMT+2 | Atlantic/Azores |
+-----------------------------------+-----------------------+------------------------+
| Atlantic/Cape\_Verde | Africa/Casablanca | Etc/UTC |
+-----------------------------------+-----------------------+------------------------+
| Atlantic/Reykjavik | Europe/London | CET |
+-----------------------------------+-----------------------+------------------------+
| Europe/Bucharest | Africa/Johannesburg | Asia/Beirut |
+-----------------------------------+-----------------------+------------------------+
| Africa/Cairo | Asia/Jerusalem | Europe/Minsk |
+-----------------------------------+-----------------------+------------------------+
| Europe/Moscow | Africa/Nairobi | Asia/Karachi |
+-----------------------------------+-----------------------+------------------------+
| Asia/Kolkata | Asia/Bangkok | Asia/Shanghai |
+-----------------------------------+-----------------------+------------------------+
| Asia/Kuala\_Lumpur | Australia/Perth | Asia/Taipei |
+-----------------------------------+-----------------------+------------------------+
| Asia/Tokyo | Asia/Seoul | Australia/Adelaide |
+-----------------------------------+-----------------------+------------------------+
| Australia/Darwin | Australia/Brisbane | Australia/Canberra |
+-----------------------------------+-----------------------+------------------------+
| Pacific/Guam | Pacific/Auckland | |
+-----------------------------------+-----------------------+------------------------+