mirror of
https://github.com/apache/cloudstack.git
synced 2025-10-26 08:42:29 +01:00
276 lines
11 KiB
HTML
276 lines
11 KiB
HTML
<HTML>
|
|
<!--
|
|
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.
|
|
-->
|
|
<HEAD>
|
|
<TITLE>Cloud.com's EC2 API User's Guide</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
<H1>Cloud.com's EC2 API User's Guide</H1>
|
|
4/17/2010
|
|
<H2>Table of Contents</H2>
|
|
<UL>
|
|
<LI><A href="#part1">Part 1. Cloud.com's Specific Implementation Details</A></LI>
|
|
<UL>
|
|
<LI><A href="#registration">1. User Registration</A></LI>
|
|
<UL>
|
|
<LI><A href="#cloudkeys">1.1 Setting Cloud.com API Keys</A></LI>
|
|
<LI><A href="#certifiates">1.2 Setting a User's X509 Certificate</A></LI>
|
|
</UL>
|
|
<LI><A href="#endpoints">2. Endpoints</LI>
|
|
<LI><A href="#differences">3. Differences between Amazon's and Cloud.com's EC2 Implementations</A></LI>
|
|
<LI><A href="#misc">4. Miscellaneous</A><P></LI>
|
|
</UL>
|
|
<LI><A href="#part2">Part 2. Generic EC2 Details</A></LI>
|
|
<UL>
|
|
<LI><A href="#functions">List of EC2 Functions Implemented</A></LI>
|
|
<LI><A href="#wsdl">Supported WSDL Version</A><P></LI>
|
|
</UL>
|
|
<LI><A href="#refs">References</A></LI>
|
|
</UL>
|
|
<P></BR>
|
|
<H2 id="part1">Part 1. Cloud.com's Specific Implementation Details</H2>
|
|
<H3 id="registration">1. User Registration</H3>
|
|
To access Cloud.com's EC2 service via REST follow the instructions in Section 1.1.
|
|
To access Cloud.com's EC2 service via SOAP follow instructions in both Section 1.1 and 1.2 below.
|
|
<P>
|
|
<H3 id="cloudkeys">1.1 Setting Cloud.com API Keys</H3>
|
|
The EC2 service needs to be given the user's Cloud.com API access and secret keys <A href="#ref2">[2]</A> so that it
|
|
can make Cloud.com API calls on the user's behalf. This is done by the following REST command.
|
|
|
|
<pre>
|
|
http://<fqdn-or-ip>:<port>/bridge/rest/AmazonEC2?Action=SetUserKeys&accesskey=<key>&secretkey=<key>
|
|
</pre>
|
|
SetUserKeys is an <I>unauthorized</I> REST call.</br>
|
|
A HTTP 200 result code is returned on success and a 401 on failure.
|
|
<P>
|
|
<H3 id="certifiates">1.2 Setting a User's X509 Certificate</H3>
|
|
EC2 uses WS-Security <A href="#ref4">[4]</A> for authentication on SOAP access. WS-Security signs the entire SOAP request
|
|
using a public/private key pair. The user of Cloud.com's EC2 service must
|
|
generate a public/private key pair with the public key defined in an X509
|
|
certificate. The private key is used by a SOAP client in generating
|
|
the WS-Security signature of a SOAP request. The matching public key is stored on
|
|
a server and is used to verify the signature on each request.
|
|
<P>
|
|
The following REST command must be used by a Cloud.com's EC2 service user to
|
|
load their certificate into the service. No access via the SOAP API is
|
|
possible until this step is performed. Also for this REST command to be
|
|
successful the instructions in Section 1.1 must be performed first.
|
|
|
|
<pre>
|
|
http://<fqdn-or-ip>:<port>/bridge/rest/AmazonEC2?Action=SetCertificate&AWSAccessKeyId=<Cloud.com API AccessKey>&cert=<pem encoded cert>
|
|
</pre>
|
|
SetCertificate is an <I>authenticated</I> REST call using the same authentication scheme as all other EC2 REST calls.
|
|
This means that the following standard EC2 REST paramters must also be part of the request: Signature, SignatureMethod, Version,
|
|
SignatureVersion, and Expires <A href="#ref3">[3]</A>.</br>
|
|
A HTTP 200 result code is returned on success and a 404 on failure.
|
|
<P>
|
|
An example of a PEM encoded X509 Certificate is <A href="#ref5">[5]</A>:
|
|
<pre>
|
|
-----BEGIN CERTIFICATE-----
|
|
MIICdzCCAeCgAwIBAgIGAPCRHu3UMA0GCSqGSIb3DQEBBQUAMFMxCzAJBgNVBAYT
|
|
AlVTMRMwEQYDVQQKEwpBbWF6b24uY29tMQwwCgYDVQQLEwNBV1MxITAfBgNVBAMT
|
|
GEFXUyBMaW1pdGVkLUFzc3VyYW5jZSBDQTAeFw0xMDA2MjMxODE4MTZaFw0xMTA2
|
|
MjMxODE4MTZaMFIxCzAJBgNVBAYTAlVTMRMwEQYDVQQKEwpBbWF6b24uY29tMRcw
|
|
FQYDVQQLEw5BV1MtRGV2ZWxvcGVyczEVMBMGA1UEAxMMZWZieDQ0eXF1d3E2MIGf
|
|
MA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCw+RO1QV7t5EbluyAAD11SoZ4ats5t
|
|
DBSta/QB3G9T0y3p2gURrYMDYVJ1BZmyel/DuMANx6UG6Vw+0o0SXOS3mH8Yu/lO
|
|
OOH9WxWiXulGMIrpPCiUpnWMrWhIlHu8mqLLhBx+5k4I92plMfH97BySunbv9zaf
|
|
ZRKXX3cXIYbUMwIDAQABo1cwVTAOBgNVHQ8BAf8EBAMCBaAwFgYDVR0lAQH/BAww
|
|
CgYIKwYBBQUHAwIwDAYDVR0TAQH/BAIwADAdBgNVHQ4EFgQUCzKwCQvocPYFki/9
|
|
NORZFTsjcZ8wDQYJKoZIhvcNAQEFBQADgYEAXmIe6+XsNHYIiLGQO6dh8nvHHzDw
|
|
3sltNa7z6BSdNr7WDxpJg9oFUcddQVca1LZsjsqx6dIc1WxQUjPE9oOfSYqQZuMD
|
|
/GOpWyXMb/oJ2MLI1Vp1ABKhHoHUJmPOrIou4UbCifMeD7MFZkezkKDqqH3jQMjA
|
|
4YDNkSWLnJ9xba8=
|
|
-----END CERTIFICATE-----
|
|
</pre>
|
|
<P>
|
|
To remove a previously loaded certificate the user can simply execute
|
|
the following REST command.
|
|
<pre>
|
|
http://<fqdn-or-ip>:<port>/bridge/rest/AmazonEC2?Action=DeleteCertificate&AWSAccessKeyId=<Cloud.com API AccessKey>
|
|
where the same value for the 'AWSAccessKeyId' parameter as was used in a previous call to SetCertificate.
|
|
</pre>
|
|
DeleteCertificate is an <I>authenticated</I> REST call using the same authentication scheme (and having all the same
|
|
required parameters) as all other EC2 REST calls.</br>
|
|
A HTTP 200 result code is returned on success and a 404 on failure.
|
|
<P>
|
|
<H3 id="endpoints">2. Endpoints</H3>
|
|
For SOAP access the endpoint is:
|
|
<pre>http://<fqdn-or-ip>:<port>/bridge/services/AmazonEC2</pre>
|
|
For REST access the endpoint is:
|
|
<pre>http://<fqdn-or-ip>:<port>/bridge/rest/AmazonEC2</pre>
|
|
<P>
|
|
|
|
<H3 id="differences">3. Differences between Amazon's and Cloud.com's EC2 Implementations</H3>
|
|
<font size=+1><I>EC2's RegisterImage Function</I></font>
|
|
<P>
|
|
This function maps to the Cloud.com's API "registerTemplate" function <A href="#ref2">[2]</A>. However the registerTemplate function
|
|
requires the following additional parameters that are not present in the RegisterImage function:
|
|
<pre>
|
|
format - the format for the template. Possible values include QCOW2, RAW, and VHD.</br>
|
|
osTypeId - the ID of the OS Type that best represents the OS of this template.</br>
|
|
zoneId - the ID of the zone the template is to be hosted on.</br>
|
|
</pre>
|
|
These parameters must be provided for a successful registerTemplate call and thus a RegsiterImage call.
|
|
To accomidate these values we have redefined the "architecture" parameter defined for RegisterImage.
|
|
The Amazon defined valid values are: "i386 | x86_64" and it is of type xsd:string. Neither of these
|
|
defined values has any meaning in the context of the Cloud.com API.
|
|
|
|
The new definition of the architecture field is a three part value of the form:
|
|
"<format>:<zoneName>:<osTypeName>", where ":" is the field delimitor. A valid example
|
|
would be: "VHD:ZONE1:Centos 4.5". Cloud.com's EC2 code translates the "zoneName" value into a valid zoneId,
|
|
and the "osTypeName" value into a matching osTypeId. In addition, whereas the architecture field
|
|
is optional in Amazon's definition of RegisterImage, it is required in Cloud.com's modified version.
|
|
<P>
|
|
Another difference for the RegisterImage function concerns the use of the "imageLocation" parameter.
|
|
As defined by Amazon <A href="#ref3">[3]</A>:
|
|
<pre>
|
|
imageLocation - a full path to your AMI manifest in Amazon S3 storage.
|
|
</pre>
|
|
As defined for Cloud.com's EC2 implementation:
|
|
<pre>
|
|
imageLocation - is a URL of where the template is hosted. Possible URL include http:// and https://
|
|
</pre>
|
|
<P>
|
|
<font size=+1><I>EC2's DescribeInstances Function</I></font>
|
|
<P>
|
|
Only the following list of filters are currently supported:
|
|
<pre>
|
|
availability-zone
|
|
hypervisor
|
|
image-id
|
|
instance-id
|
|
instance-type
|
|
instance-state-code
|
|
instance-state-name
|
|
ip-address
|
|
owner-id
|
|
root-device-name
|
|
</pre>
|
|
<P>
|
|
<font size=+1><I>EC2's DescribeVolumes Function</I></font>
|
|
<P>
|
|
Only the following list of filters are currently supported:
|
|
<pre>
|
|
attachment.attach-time
|
|
attachment.device
|
|
attachment.instance-id
|
|
availability-zone
|
|
create-time
|
|
size
|
|
snapshot-id
|
|
status
|
|
volume-id
|
|
</pre>
|
|
<P>
|
|
<font size=+1><I>EC2's DescribeSnapshots Function</I></font>
|
|
<P>
|
|
Only the following list of filters are currently supported:
|
|
<pre>
|
|
owner-alias
|
|
owner-id (here its the CloudStack API key)
|
|
snapshot-id
|
|
start-time
|
|
status
|
|
volume-id
|
|
volume-size
|
|
</pre>
|
|
<P>
|
|
<P>
|
|
<font size=+1><I>EC2's DescribeSecurityGroups Function</I></font>
|
|
<P>
|
|
Only the following list of filters are currently supported:
|
|
<pre>
|
|
description
|
|
group-id
|
|
group-name
|
|
ip-permission.cidr
|
|
ip-permission.from-port
|
|
ip-permission.to-port
|
|
ip-permission.protocol
|
|
owner-id
|
|
</pre>
|
|
<P>
|
|
<H3 id="misc">4. Miscellaneous</H3>
|
|
The EC2 service provides a Cloud.com extension to obtain the release version of the EC2 software.
|
|
|
|
<pre>
|
|
http://<fqdn-or-ip>:<port>/bridge/rest/AmazonEC2?Action=CloudEC2Version
|
|
</pre>
|
|
CloudEC2Version is an <I>unauthorized</I> REST call.</br>
|
|
An example of a valid response from this function is:
|
|
<pre>
|
|
<CloudEC2Version>1.01</CloudEC2Version>
|
|
</pre>
|
|
<P></BR>
|
|
<H2 id="part2">Part 2. Generic EC2 Details</H2>
|
|
<H3 id="functions">List of EC2 Functions Implemented</H3>
|
|
Refer to the Amazon EC2 documentation <A href="#ref3">[3]</A> for a description of each function.
|
|
Also see Part1, section 3 above, for differences between Amazon's and Cloud.com's EC2 implementations.
|
|
<pre>
|
|
AllocateAddress
|
|
AssociateAddress
|
|
AttachVolume
|
|
AuthorizeSecurityGroupIngress
|
|
CreateImage
|
|
CreateSecurityGroup
|
|
CreateSnapshot
|
|
CreateVolume
|
|
DeleteSecurityGroup
|
|
DeleteSnapshot
|
|
DeleteVolume
|
|
DeregisterImage
|
|
DescribeAvailabilityZones
|
|
DescribeImageAttribute
|
|
DescribeImages
|
|
DescribeInstanceAttribute
|
|
DescribeInstances
|
|
DescribeSecurityGroups
|
|
DescribeSnapshots
|
|
DescribeVolumes
|
|
DetachVolume
|
|
DisassociateAddress
|
|
ModifyImageAttribute
|
|
RebootInstances
|
|
ReleaseAddress
|
|
RegisterImage
|
|
RevokeSecurityGroupIngress
|
|
ResetImageAttribute
|
|
RunInstances
|
|
StartInstances
|
|
StopInstances
|
|
TerminateInstances
|
|
</pre>
|
|
<P>
|
|
<H3 id="wsdl">Supported WSDL Version</H3>
|
|
<A href="http://ec2.amazonaws.com/doc/2010-08-31/">http://ec2.amazonaws.com/doc/2010-08-31/</A></BR>
|
|
Amazon EC2 Command Line Tool used for testing was version 1.3-57419.
|
|
<P>
|
|
</BR>
|
|
<H2 id="refs">References</H2>
|
|
<OL>
|
|
<LI id="ref1"><A href="http://en.wikipedia.org/wiki/Public_Key_Cryptography">Public-key cryptograph</A></LI>
|
|
<LI id="ref2"><A href="http://cloud.com/community/kb">Cloud.com's Developer API</A></LI>
|
|
<LI id="ref3"><A href="http://aws.amazon.com/documentation/ec2/">Amazon's EC2 API</A></LI>
|
|
<LI id="ref4"><A href="http://en.wikipedia.org/wiki/WS-Security">WS-Security</A></LI>
|
|
<LI id="ref5"><A href="http://en.wikipedia.org/wiki/X.509">X.509 Certificates</A></LI>
|
|
</OL>
|
|
</BODY>
|
|
</HTML>
|