mirror of
https://github.com/apache/cloudstack.git
synced 2025-10-26 08:42:29 +01:00
165 lines
8.6 KiB
HTML
165 lines
8.6 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 Implementation Guide</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
<H1>Cloud.com's EC2 API Implementation Guide</H1>
|
|
3/24/2011
|
|
<H2>Table of Contents</H2>
|
|
<UL>
|
|
<LI><A href="#conf">1. Configuration Parameters</A></LI>
|
|
<LI><A href="#party">2. Required 3rd Party Software</A></LI>
|
|
<LI><A href="#maintenace">3. Maintenance</A></LI>
|
|
<LI><A href="#install">4. Installation Instructions</A></LI>
|
|
<LI><A href="#refs">5. References</A></LI>
|
|
</UL>
|
|
<P>
|
|
<H2 id="conf">1. Configuration Parameters</H2>
|
|
Several configuration parameters are required to make Cloud.com's EC2 service work properly.
|
|
The following parameters are defined in the file:</BR> <install directory>"/apache-tomcat-6.0.18/conf/ec2-service.properties":
|
|
<pre>
|
|
managementServer=192.168.154.36
|
|
cloudAPIPort=8080
|
|
WSDLVersion=2010-08-31
|
|
keystore=xes.keystore
|
|
keystorePass=apache
|
|
dbName=cloudsbridge
|
|
dbUser=root
|
|
dbPassword=
|
|
pollInterval1=100
|
|
pollInterval2=100
|
|
pollInterval3=100
|
|
pollInterval4=1000
|
|
pollInterval5=100
|
|
pollInterval6=100
|
|
</pre>
|
|
<I>managementServer</I> - FQDN or IP address of a Cloud.com management server. This is the address that
|
|
the EC2 service makes Cloud.com REST API calls against.</BR>
|
|
<I>cloudAPIPort</I> - The TCP port that the CloudStack, User API is running on. If this property is not defined,
|
|
then no port is used by the EC2 service when it queries the CloudStack.</BR>
|
|
<I>WSDLVersion</I> - The string that defines the WSDL used by the SOAP API which the REST API also implements.
|
|
This string is compared to the "Version=" parameter on each and every authorized REST request.</BR>
|
|
<I>keystore</I> - The file name of the keystore used by EC2 which must be placed at the directory:
|
|
"../apache-tomcat-6.0.18/webapps/bridge/WEB-INF/classes"</BR>
|
|
<I>keystorePass</I> - The password to the EC2 keystore specified by the "keystore" parameter.</BR>
|
|
<I>dbName</I> - The MySql database name holding the EC2 service's required tables.</BR>
|
|
<I>dbUser=</I> - The user name used to access the "dbName" MySql database.</BR>
|
|
<I>dbPassword</I> - The password (if any) the "dbUser" needs to access the EC2 MySql database.</BR>
|
|
<I>pollInterval1</I> - Time in milliseconds between asynchronous job completion polling for the following Cloud.com
|
|
API call: createTemplate. Default value is 100.</BR>
|
|
<I>pollInterval2</I> - Time in milliseconds between asynchronous job completion polling for the following Cloud.com
|
|
API call: deployVirtualMachine. Default value is 100.</BR>
|
|
<I>pollInterval3</I> - Time in milliseconds between asynchronous job completion polling for the following Cloud.com
|
|
API call: createVolume. Default value is 100.</BR>
|
|
<I>pollInterval4</I> - Time in milliseconds between asynchronous job completion polling for the following Cloud.com
|
|
API call: createSnapshot. Default value is 1000.</BR>
|
|
<I>pollInterval5</I> - Time in milliseconds between asynchronous job completion polling for the following Cloud.com
|
|
API calls: deleteSnapshot, deleteTemplate, deleteVolume, attachVolume, detachVolume, disassociateIpAddress, enableStaticNat, disableStaticNat. Default value is 100.</BR>
|
|
<I>pollInterval6</I> - Time in milliseconds between asynchronous job completion polling for the following Cloud.com
|
|
API calls: startVirtualMachine, destroyVirtualMachine, stopVirtualMachine. Default value is 100.</BR>
|
|
<P>
|
|
<BR>
|
|
The following REST calls are used to configure a mapping between Amazon's instance types and CloudStack service offerings:
|
|
<P>
|
|
http://<fqdn-or-ip>:<port>/bridge/rest/AmazonEC2?Action=SetOfferMapping&amazonoffer=m1.large&cloudoffer=1<BR>
|
|
<P>
|
|
The 'amazonoffer' parameter defines the standard Amazon instance types while the 'cloudoffer' parameter defines its associated
|
|
CloudStack service offering identifer. The result of this REST call is to save the defined relationship. A second call with the
|
|
same value for amazonoffer but with a different cloudoffer value will overwrite a previously saved setting.
|
|
<BR>
|
|
SetOfferMapping is an authenticated 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 HTTP 200 result code is returned on success and a 404 on failure.
|
|
<P>
|
|
http://<fqdn-or-ip>:<port>/bridge/rest/AmazonEC2?Action=DeleteOfferMapping&amazonoffer=m1.large<BR>
|
|
<P>
|
|
The result of this REST call is to delete any relationship previously defined by a call to the SetOfferMapping call for the
|
|
value passed in the 'amazonoffer' parameter.<BR>
|
|
DeleteOfferMapping is an authenticated 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 HTTP 200 result code is returned on success and a 404 on failure.
|
|
<P>
|
|
Examples of other Amazon instance types are:
|
|
{ "m1.small", "m1.large", "m1.xlarge", "c1.medium", "c1.xlarge", "m2.xlarge", "m2.2xlarge", "m2.4xlarge" }.</BR>
|
|
Service offering IDs can be obtained from the following Cloud.com API calls: listServiceOfferings.
|
|
Cloud.com's service offerings are configurable and thus can be different per installation, and they
|
|
can also be viewed from the Cloud.com's Admin UI.
|
|
<P>
|
|
<H2 id="party">2. Required 3rd Party Software</H2>
|
|
Cloud.com's EC2 service has been built and tested on the following set of 3rd party software:
|
|
<pre>
|
|
MySql
|
|
apache-tomcat 6.0.18
|
|
axis2 1.5.1
|
|
rampart 1.5 (installed into axis2 for WS-Security)
|
|
used for testing: ec2-api-tools-1.3-53907
|
|
</pre>
|
|
<P>
|
|
<H2 id="maintenace">3. Maintenance</H2>
|
|
As a result of the SetCertificate REST call <A href="#ref1">[1]</A>, X509 Certificates used for SOAP authentication are
|
|
stored in the following keystore:
|
|
<pre>
|
|
<install directory>/apache-tomcat-6.0.18/webapps/bridge/WEB-INF/classes/xes.keystore
|
|
</pre>
|
|
The keytool <A href="#ref2">[2]</A> command line tool can be used to delete certificates no longer in use.
|
|
<P>
|
|
As a result of the SetUserKeys REST call <A href="#ref1">[1]</A>, entries are inserted into
|
|
the "usercredentials" table of the "cloudbridge" MySql database.
|
|
The MySql command line client can be used to delete usercredentials entries no longer in use.
|
|
<P>
|
|
<H2 id="install">4. Installation Instructions</H2>
|
|
<P>
|
|
On the very first install an EC2/S3 MySql database is created by running the following
|
|
scripts in the given order: cloudsbridge_db.sql, cloudsbridge_schema.sql, cloudbridge_index.sql
|
|
<P>
|
|
After a successful installation the following directory and file structure should exist:
|
|
<pre>
|
|
<install directory>
|
|
apache-tomcat-6.0.18
|
|
conf
|
|
ec2-service.properties (EC2 service's configuration parameters)
|
|
server.xml
|
|
lib
|
|
<many axis2 jar files>
|
|
webapps
|
|
bridge
|
|
WEB-INF
|
|
classes
|
|
crypto.properties
|
|
xes.keystore (holds X509 certificates for SOAP authentication)
|
|
modules
|
|
cloud-auth-ec2.mar
|
|
rampart-1.5.mar
|
|
rahas-1.5.mar
|
|
addressing-1.5.1.mar
|
|
services
|
|
cloud-ec2.aar (the Axis2 EC2 service)
|
|
</pre>
|
|
The "../modules/cloud-auth-ec2.mar" module performs a mapping from an X509 certificate appearing in a SOAP
|
|
request (since its signed via WS-Security) to a matching user's Cloud.com API access and secret keys. This association
|
|
is first created via the SetUserKeys and SetCertificate REST calls [1].
|
|
<P>
|
|
<H2 id="refs">5. References</H2>
|
|
<OL>
|
|
<LI id="ref1">Cloud.com's EC2 API User's Guide, 7/15/2010</LI>
|
|
<LI id="ref2"><A href="http://download.oracle.com/docs/cd/E17476_01/javase/1.4.2/docs/tooldocs/windows/keytool.html">keytool - Key and Certificate Management Tool</A></LI>
|
|
</OL>
|
|
</BODY>
|
|
</HTML>
|