incubator-cloudstack-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ahu...@apache.org
Subject [6/32] git commit: Improvements to AWS installation, configuration and use in installation guide
Date Fri, 11 Jan 2013 00:01:22 GMT
Improvements to AWS installation, configuration and use in installation guide


Project: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/commit/09b68ce1
Tree: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/tree/09b68ce1
Diff: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/diff/09b68ce1

Branch: refs/heads/javelin
Commit: 09b68ce13fa85702417fbce090379e3e94fecc94
Parents: 999ecb6
Author: Sebastien Goasguen <runseb@gmail.com>
Authored: Mon Dec 17 16:34:25 2012 +0100
Committer: Joe Brockmeier <jzb@zonker.net>
Committed: Wed Jan 9 13:56:24 2013 -0600

----------------------------------------------------------------------
 docs/en-US/aws-api-examples.xml                 |  145 ++++++++++++++++++
 docs/en-US/aws-ec2-configuration.xml            |  104 ++++++++++---
 docs/en-US/aws-ec2-introduction.xml             |   13 +-
 docs/en-US/aws-ec2-requirements.xml             |    9 +-
 docs/en-US/aws-ec2-supported-commands.xml       |    2 +-
 docs/en-US/aws-ec2-timeouts.xml                 |    5 +-
 docs/en-US/aws-ec2-user-setup.xml               |  108 +++++++------
 docs/en-US/aws-interface-compatibility.xml      |    3 +-
 docs/en-US/images/compute-service-offerings.png |  Bin 0 -> 75482 bytes
 9 files changed, 306 insertions(+), 83 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/09b68ce1/docs/en-US/aws-api-examples.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/aws-api-examples.xml b/docs/en-US/aws-api-examples.xml
new file mode 100644
index 0000000..ee3b44a
--- /dev/null
+++ b/docs/en-US/aws-api-examples.xml
@@ -0,0 +1,145 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
[
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- 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.
+-->
+
+<section id="aws-api-examples">
+    <title>Examples</title>
+    <para>There are many tools available to interface with a AWS compatible API. In
this section we provide
+    a few examples that users of &PRODUCT; can build upon.</para>
+
+    <section id="aws-api-boto-examples">
+        <title>Boto Examples</title>
+        <para>Boto is one of them. It is a Python package available at https://github.com/boto/boto.
+        In this section we provide two examples of Python scripts that use Boto and have
been tested with the
+        &PRODUCT; AWS API Interface.</para>
+        <para>First is an EC2 example. Replace the Access and Secret Keys with your
own and
+        update the endpoint.</para>
+        <para>
+            <example>
+                <title>An EC2 Boto example</title>
+                <programlisting>#!/usr/bin/env python
+
+import sys
+import os
+import boto
+import boto.ec2
+
+region = boto.ec2.regioninfo.RegionInfo(name="ROOT",endpoint="localhost")
+apikey='GwNnpUPrO6KgIdZu01z_ZhhZnKjtSdRwuYd4DvpzvFpyxGMvrzno2q05MB0ViBoFYtdqKd'
+secretkey='t4eXLEYWw7chBhDlaKf38adCMSHx_wlds6JfSx3z9fSpSOm0AbP9Moj0oGIzy2LSC8iw'
+
+def main():
+	'''Establish connection to EC2 cloud'''
+        conn =boto.connect_ec2(aws_access_key_id=apikey,
+                       aws_secret_access_key=secretkey,
+                       is_secure=False,
+                       region=region,
+                       port=7080,
+                       path="/awsapi",
+                       api_version="2010-11-15")
+
+        '''Get list of images that I own'''
+	images = conn.get_all_images()
+	print images
+	myimage = images[0]
+	'''Pick an instance type'''
+	vm_type='m1.small'
+	reservation = myimage.run(instance_type=vm_type,security_groups=['default'])
+
+if __name__ == '__main__':
+	main()
+                </programlisting>
+            </example>
+        </para>
+        <para>Second is an S3 example. Replace the Access and Secret keys with your
own,
+            as well as the endpoint of the service. Be sure to also update the file paths
to something
+            that exists on your machine.</para>
+        <para>
+            <example>
+                <title>An S3 Boto Example</title>
+                <programlisting>#!/usr/bin/env python
+
+import sys
+import os
+from boto.s3.key import Key
+from boto.s3.connection import S3Connection
+from boto.s3.connection import OrdinaryCallingFormat
+
+apikey='ChOw-pwdcCFy6fpeyv6kUaR0NnhzmG3tE7HLN2z3OB_s-ogF5HjZtN4rnzKnq2UjtnHeg_yLA5gOw'
+secretkey='IMY8R7CJQiSGFk4cHwfXXN3DUFXz07cCiU80eM3MCmfLs7kusgyOfm0g9qzXRXhoAPCH-IRxXc3w'
+
+cf=OrdinaryCallingFormat()
+
+def main():	
+	'''Establish connection to S3 service'''
+        conn =S3Connection(aws_access_key_id=apikey,aws_secret_access_key=secretkey, \
+                          is_secure=False, \
+                          host='localhost', \
+                          port=7080, \
+                          calling_format=cf, \
+                          path="/awsapi/rest/AmazonS3")
+
+        try:
+            bucket=conn.create_bucket('cloudstack')
+            k = Key(bucket)
+            k.key = 'test'
+            try:
+               k.set_contents_from_filename('/Users/runseb/Desktop/s3cs.py')
+            except:
+               print 'could not write file'
+               pass
+        except:
+            bucket = conn.get_bucket('cloudstack')
+            k = Key(bucket)
+            k.key = 'test'
+            try:
+               k.get_contents_to_filename('/Users/runseb/Desktop/foobar')
+            except:
+               print 'Could not get file'
+               pass
+
+        try:
+           bucket1=conn.create_bucket('teststring')
+           k=Key(bucket1)
+           k.key('foobar')
+           k.set_contents_from_string('This is my silly test')
+        except:
+           bucket1=conn.get_bucket('teststring')
+           k = Key(bucket1)
+           k.key='foobar'
+           k.get_contents_as_string()
+	
+if __name__ == '__main__':
+	main()
+
+                </programlisting>
+            </example>
+        </para>
+    </section>
+
+    <section id="aws-api-jclouds-examples">
+        <title>JClouds Examples</title>
+        <para></para>
+    </section>
+
+ </section>

http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/09b68ce1/docs/en-US/aws-ec2-configuration.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/aws-ec2-configuration.xml b/docs/en-US/aws-ec2-configuration.xml
index d6c4066..7d26027 100644
--- a/docs/en-US/aws-ec2-configuration.xml
+++ b/docs/en-US/aws-ec2-configuration.xml
@@ -23,26 +23,88 @@
 -->
 
 <section id="aws-ec2-configuration">
-  <title>Enabling the AWS API Compatible Interface</title>
-  <para>
-    The software that provides AWS API compatibility is installed along with &PRODUCT;.
However, you must enable the feature and perform some setup steps.
-  </para>
-  <orderedlist>
-    <listitem><para>Set the global configuration parameter enable.ec2.api to
true. See <xref linkend="global-config" />.</para></listitem>
-    <listitem><para>Create a set of &PRODUCT; service offerings with names
that match the Amazon service offerings.
-      You can do this through the &PRODUCT; UI as described in the Administration Guide.</para>
-      <warning><para>Be sure you have included the Amazon default service offering,
m1.small.</para></warning></listitem>
-    <listitem><para>If you did not already do so when you set the configuration
parameter in step 1, restart the Management Server.</para>
-    <programlisting># service cloud-management restart</programlisting></listitem>
-    <listitem><para>(Optional) The AWS API listens for requests on port 7080.
If you prefer AWS API to listen on another port, you can change it as follows:</para>
-      <orderedlist numeration="loweralpha">
-        <listitem><para>Edit the files /etc/cloud/management/server.xml, /etc/cloud/management/server-nonssl.xml,
and /etc/cloud/management/server-ssl.xml.</para></listitem>
-        <listitem><para>In each file, find the tag &lt;Service name="Catalina7080"&gt;.
Under this tag, locate &lt;Connector executor="tomcatThreadPool-internal" port= ....&lt;.</para></listitem>
-        <listitem><para>Change the port to whatever port you want to use, then
save the files.</para></listitem>
-        <listitem><para>Restart the Management Server.</para>
-        <note><para>If you re-install CloudStack, you will have to make these
changes again.</para></note>
+    <title>Enabling the EC2 and S3 Compatible Interface</title>
+
+    <para>The software that provides AWS API compatibility is installed along with
&PRODUCT;. You must enable the services and perform some setup steps prior to using it.
+    </para>
+    <orderedlist>
+        <listitem><para>Set the global configuration parameters for each service
to true. 
+                  See <xref linkend="global-config" />.</para></listitem>
+        <listitem><para>Create a set of &PRODUCT; service offerings with
names that match the Amazon service offerings.
+                  You can do this through the &PRODUCT; UI as described in the Administration
Guide.</para>
+                  <warning><para>Be sure you have included the Amazon default
service offering, m1.small. As well as any EC2 instance types that you will use.</para></warning>
+        </listitem>
+        <listitem><para>If you did not already do so when you set the configuration
parameter in step 1,
+                  restart the Management Server.</para>
+                  <programlisting># service cloud-management restart</programlisting>
         </listitem>
-      </orderedlist>
-    </listitem>
-  </orderedlist>
+    </orderedlist>
+    <para>The following sections provides details to perform these steps</para>
+
+    <section id="aws-api-settings">
+        <title>Enabling the Services</title>
+        <para>To enable the EC2 and S3 compatible services you need to set the configuration
variables <emphasis>enable.ec2.api</emphasis>
+        and <emphasis>enable.s3.api</emphasis> to true. You do not have to enable
both at the same time. Enable the ones you need.
+        This can be done via the &PRODUCT; GUI by going in <emphasis>Global Settings</emphasis>
or via the API.</para>
+        <para>The snapshot below shows you how to use the GUI to enable these services</para>
+
+        <para>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="./images/ec2-s3-configuration.png"/>
+            </imageobject>
+            <textobject>
+                <phrase>Use the GUI to set the configuration variable to <emphasis>true</emphasis></phrase>
+            </textobject>
+        </mediaobject>
+        </para>
+
+        <para>Using the &PRODUCT; API, the easiest is to use the so-called integration
port on which you can make 
+        unauthenticated calls. In Global Settings set the port to 8096 and subsequently call
the <emphasis>updateConfiguration</emphasis> method.
+        The following urls shows you how:</para>
+    
+        <para>
+            <programlisting>
+            http://localhost:8096/client/api?command=updateConfiguration&amp;name=enable.ec2.api&amp;value=true
+            http://localhost:8096/client/api?command=updateConfiguration&amp;name=enable.ec2.api&amp;value=true
+            </programlisting>
+        </para>
+
+        <para>Once you have enabled the services, restart the server.</para>
+    </section>
+
+    <section id="aws-ec2-service-offerings">
+        <title>Creating EC2 Compatible Service Offerings</title>
+        <para>You will also need to define compute service offerings with names compatible
with the <ulink url="http://aws.amazon.com/ec2/instance-types/">
+              Amazon EC2 instance types</ulink> API names (e.g m1.small,m1.large).
This can be done via the &PRODUCT; GUI.
+              Go under <emphasis>Service Offerings</emphasis> select <emphasis>Compute
offering</emphasis> and either create
+              a new compute offering or modify an existing one, ensuring that the name matches
an EC2 instance type API name. The snapshot below shows you how:</para>
+        <para>
+            <mediaobject>
+                <imageobject>
+                    <imagedata fileref="./images/compute-service-offerings.png"/>
+                </imageobject>
+                <textobject>
+                    <phrase>Use the GUI to set the name of a compute service offering
to an EC2 instance
+                    type API name.</phrase>
+                </textobject>
+            </mediaobject>
+        </para>
+    </section>
+    <section id="aws-api-port-change">
+        <title>Modifying the AWS API Port</title>
+        <note>
+            <para>(Optional) The AWS API listens for requests on port 7080. If you
prefer AWS API to listen on another port, you can change it as follows:</para>
+            <orderedlist numeration="loweralpha">
+                <listitem><para>Edit the files /etc/cloud/management/server.xml,
/etc/cloud/management/server-nonssl.xml,
+                          and /etc/cloud/management/server-ssl.xml.</para></listitem>
+                <listitem><para>In each file, find the tag &lt;Service name="Catalina7080"&gt;.
Under this tag,
+                          locate &lt;Connector executor="tomcatThreadPool-internal" port=
....&lt;.</para></listitem>
+                <listitem><para>Change the port to whatever port you want to
use, then save the files.</para></listitem>
+                <listitem><para>Restart the Management Server.</para></listitem>
+            </orderedlist>
+            <para>If you re-install &PRODUCT;, you will have to re-enable the services
and if need be update the port.</para>
+        </note>
+    </section> 
+
  </section>

http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/09b68ce1/docs/en-US/aws-ec2-introduction.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/aws-ec2-introduction.xml b/docs/en-US/aws-ec2-introduction.xml
index a4df086..538c09d 100644
--- a/docs/en-US/aws-ec2-introduction.xml
+++ b/docs/en-US/aws-ec2-introduction.xml
@@ -23,16 +23,19 @@
 -->
 
 <section id="aws-ec2-introduction">
-  <title>Amazon Web Services EC2 Compatible Interface</title>
+  <title>Amazon Web Services Compatible Interface</title>
     <para>&PRODUCT; can translate Amazon Web Services (AWS) API calls to native
&PRODUCT; API calls
     so that users can continue using existing AWS-compatible tools. This translation service
runs as
     a separate web application in the same tomcat server as the management server of &PRODUCT;,
-    listening on the same port. This Amazon EC2-compatible API is accessible through a SOAP
web
-    service.</para> 
+    listening on a different port. The Amazon Web Services (AWS) compatible interface provides
the
+    EC2 SOAP and Query APIs as well as the S3 REST API.</para> 
     <note>
       <para>This service was previously enabled by separate software called CloudBridge.
It is now
       fully integrated with the &PRODUCT; management server. </para>
     </note>
+    <warning>
+      <para>The compatible interface for the EC2 Query API and the S3 API are Work
In Progress. The S3 compatible API offers a way to store data on the management server file
system, it is not an implementation of the S3 backend.</para>
+    </warning>
     <para>Limitations</para>
     <itemizedlist>
       <listitem>
@@ -42,7 +45,9 @@
         <para>Available in fresh installations of &PRODUCT;. Not available through
upgrade of previous versions.</para>
       </listitem>
       <listitem>
-        <para>If you need to support features such as elastic IP, set up a Citrix NetScaler
to provide this service. The commands such as ec2-associate-address will not work without
EIP setup. Users running VMs in this zone will be using the NetScaler-enabled network offering
(DefaultSharedNetscalerEIP and ELBNetworkOffering).</para>
+        <para>Features such as Elastic IP (EIP) and Elastic Load Balacing (ELB) are
only available in an infrastructure
+        with a Citrix NetScaler device. Users accessing a Zone with a NetScaler device will
need to use a 
+        NetScaler-enabled network offering (DefaultSharedNetscalerEIP and ELBNetworkOffering).</para>
       </listitem>
     </itemizedlist>
 </section>

http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/09b68ce1/docs/en-US/aws-ec2-requirements.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/aws-ec2-requirements.xml b/docs/en-US/aws-ec2-requirements.xml
index 59fb5b6..62e94b1 100644
--- a/docs/en-US/aws-ec2-requirements.xml
+++ b/docs/en-US/aws-ec2-requirements.xml
@@ -23,13 +23,14 @@
 -->
 
 <section id="aws-ec2-requirements">
-    <title>System Requirements</title>
+    <title>Supported API Version</title>
     <itemizedlist>
-        <listitem><para>This interface complies with Amazon's WDSL version dated
November 15, 2010, available at
+        <listitem><para>The EC2 interface complies with Amazon's WDSL version
dated November 15, 2010, available at
             <ulink url="http://ec2.amazonaws.com/doc/2010-11-15/">http://ec2.amazonaws.com/doc/2010-11-15/</ulink>.</para></listitem>
-        <listitem><para>Compatible with the EC2 command-line
+        <listitem><para>The interface is compatible with the EC2 command-line
             tools <emphasis>EC2 tools v. 1.3.6230</emphasis>, which can be downloaded
at <ulink
             url="http://s3.amazonaws.com/ec2-downloads/ec2-api-tools-1.3-62308.zip">http://s3.amazonaws.com/ec2-downloads/ec2-api-tools-1.3-62308.zip</ulink>.</para>
         </listitem>
     </itemizedlist>
-</section>
\ No newline at end of file
+    <note><para>Work is underway to support a more recent version of the EC2
API</para></note>
+</section>

http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/09b68ce1/docs/en-US/aws-ec2-supported-commands.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/aws-ec2-supported-commands.xml b/docs/en-US/aws-ec2-supported-commands.xml
index 9494218..7cdbcad 100644
--- a/docs/en-US/aws-ec2-supported-commands.xml
+++ b/docs/en-US/aws-ec2-supported-commands.xml
@@ -24,7 +24,7 @@
 
 <section id="aws-ec2-supported-commands">
   <title>Supported AWS API Calls</title>
-    <para>The following Amazon EC2 commands are supported by &PRODUCT; when the
AWS API compatibility feature is enabled.
+    <para>The following Amazon EC2 commands are supported by &PRODUCT; when the
AWS API compatible interface is enabled.
         For a few commands, there are differences between the &PRODUCT; and Amazon EC2
versions, and these differences are noted. The underlying SOAP call for each command is also
given, for those who have built tools using those calls.
     </para>
     <table frame='all'>

http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/09b68ce1/docs/en-US/aws-ec2-timeouts.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/aws-ec2-timeouts.xml b/docs/en-US/aws-ec2-timeouts.xml
index c8b3ec6..73d0c16 100644
--- a/docs/en-US/aws-ec2-timeouts.xml
+++ b/docs/en-US/aws-ec2-timeouts.xml
@@ -24,7 +24,7 @@
 
 <section id="aws-ec2-timeouts">
   <title>Using Timeouts to Ensure AWS API Command Completion</title>
-  <para>The Amazon EC2 command-line tools have a default connection timeout. When used
with &PRODUCT;, a longer timeout might be needed for some commands. If you find that commands
are not completing due to timeouts, you can gain more time for commands to finish by overriding
the default timeouts on individual commands. You can add the following optional command-line
parameters to any &PRODUCT;-supported EC2 command:</para>
+  <para>The Amazon EC2 command-line tools have a default connection timeout. When used
with &PRODUCT;, a longer timeout might be needed for some commands. If you find that commands
are not completing due to timeouts, you can specify a custom timeouts. You can add the following
optional command-line parameters to any &PRODUCT;-supported EC2 command:</para>
   <informaltable frame="all">
     <tgroup cols="2" align="left" colsep="1" rowsep="1">
       <colspec colname="c1" />
@@ -47,4 +47,5 @@
   </informaltable>
   <para>Example:</para>
   <programlisting>ec2-run-instances 2 –z us-test1 –n 1-3 --connection-timeout 120
--request-timeout 120</programlisting>
-</section>
\ No newline at end of file
+  <note><para>The timeouts optional arguments are not specific to &PRODUCT;.</para></note>
+</section>

http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/09b68ce1/docs/en-US/aws-ec2-user-setup.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/aws-ec2-user-setup.xml b/docs/en-US/aws-ec2-user-setup.xml
index 8607378..edc371e 100644
--- a/docs/en-US/aws-ec2-user-setup.xml
+++ b/docs/en-US/aws-ec2-user-setup.xml
@@ -22,76 +22,84 @@
  under the License.
 -->
 <section id="aws-ec2-user-setup">
-  <title>AWS API User Setup Steps</title>
+  <title>AWS API User Setup</title>
   <para>In general, users need not be aware that they are using a translation service
provided by &PRODUCT;.
-    They need only send AWS API calls to &PRODUCT;'s endpoint, and it will translate
the calls to the native API.
-    Users of the Amazon EC2 compatible interface will be able to keep their existing EC2
tools
+    They only need to send AWS API calls to &PRODUCT;'s endpoint, and it will translate
the calls to the native &PRODUCT; API. Users of the Amazon EC2 compatible interface will
be able to keep their existing EC2 tools
     and scripts and use them with their &PRODUCT; deployment, by specifying the endpoint
of the
     management server and using the proper user credentials. In order to do this, each user
must
     perform the following configuration steps: </para>
   <para>
     <itemizedlist>
       <listitem>
-        <para>Generate user credentials and register with the service.</para>
+        <para>Generate user credentials.</para>
       </listitem>
       <listitem>
-        <para>Set up the environment variables for the EC2 command-line tools.</para>
+        <para>Register with the service.</para>
       </listitem>
       <listitem>
-        <para>For SOAP access, use the endpoint http://<replaceable>&PRODUCT;-management-server</replaceable>:7080/awsapi.
-          The <replaceable>&PRODUCT;-management-server</replaceable> can
be specified by a fully-qualified domain name or IP address.</para>
+        <para>For convenience, set up environment variables for the EC2 SOAP command-line
tools.</para>
       </listitem>
     </itemizedlist>
   </para>
   <section id="aws-ec2-user-registration">
     <title>AWS API User Registration</title>
-  <para>Each user must perform a one-time registration.  The user follows these steps:</para>
-  <orderedlist>
-    <listitem>
-      <para>Obtain the following by looking in the &PRODUCT; UI, using the API,
or asking the cloud administrator:</para>
-      <itemizedlist>
-        <listitem><para>The &PRODUCT; server's publicly available DNS name
or IP address</para></listitem>
-        <listitem><para>The user account's API key and Secret key</para></listitem>
-      </itemizedlist>
-    </listitem>
-	<listitem>
-      <para>
-        Generate a private key and a self-signed X.509 certificate. The user substitutes
their own desired storage location for /path/to/… below.
-      </para>
-      <para><programlisting>$ openssl req -x509 -nodes -days 365 -newkey rsa:2048
-keyout /path/to/private_key.pem -out /path/to/cert.pem</programlisting>
-      </para>
-    </listitem>
-    <listitem>
-      <para>
-        Register the mapping from the X.509 certificate to the API/Secret keys.
-        Download the following script from http://download.cloud.com/releases/3.0.3/cloudstack-aws-api-register
and run it.
-        Substitute the values that were obtained in step 1 in the URL below.
-      </para>
-      <para>
-<programlisting>$ cloudstack-aws-api-register --apikey=<replaceable>User’s
&PRODUCT; API key</replaceable> --secretkey=<replaceable>User’s &PRODUCT;
Secret key</replaceable> --cert=<replaceable>/path/to/cert.pem</replaceable>
--url=http://<replaceable>&PRODUCT;.server</replaceable>:7080/awsapi</programlisting>
-       </para>
-     </listitem>
-   </orderedlist>
+    <para>Each user must perform a one-time registration.  The user follows these steps:</para>
+    <orderedlist>
+      <listitem>
+          <para>Obtain the following by looking in the &PRODUCT; UI, using the
API, or asking the cloud administrator:
+          </para>
+          <itemizedlist>
+              <listitem><para>The &PRODUCT; server's publicly available DNS
name or IP address</para></listitem>
+              <listitem><para>The user account's Access key and Secret key</para></listitem>
+          </itemizedlist>
+      </listitem>
+      <listitem>
+          <para>Generate a private key and a self-signed X.509 certificate. The user
substitutes their own desired storage location for /path/to/… below.
+          </para>
+          <para>
+              <programlisting>$ openssl req -x509 -nodes -days 365 -newkey rsa:2048
-keyout /path/to/private_key.pem -out /path/to/cert.pem</programlisting>
+          </para>
+      </listitem>
+      <listitem>
+          <para>Register the user X.509 certificate and Access/Secret keys with the
AWS compatible service. 
+      If you have the source code of &PRODUCT; go to the awsapi-setup/setup directory
and use the Python script 
+      cloudstack-aws-api-register. If you do not have the source then download the script
using the following command.
+          </para>
+          <para>
+              <programlisting>wget -O cloudstack-aws-api-register <ulink url="https://git-wip-us.apache.org/repos/asf?p=incubator-cloudstack.git;a=blob_plain;f=awsapi-setup/setup/cloudstack-aws-api-register;hb=HEAD">"https://git-wip-us.apache.org/repos/asf?p=incubator-cloudstack.git;a=blob_plain;f=awsapi-setup/setup/cloudstack-aws-api-register;hb=HEAD"</ulink>
+              </programlisting>
+          </para>
+          <para> Then execute it, using the parameter values that were obtained in
step 1. An example is shown below.</para>
+          <para>
+              <programlisting>$ cloudstack-aws-api-register --apikey=<replaceable>User’s
&PRODUCT; API key</replaceable> --secretkey=<replaceable>User’s &PRODUCT;
Secret key</replaceable> --cert=<replaceable>/path/to/cert.pem</replaceable>
--url=http://<replaceable>&PRODUCT;.server</replaceable>:7080/awsapi</programlisting>
+          </para>
+      </listitem>
+    </orderedlist>
    <note>
      <para>
-       A user with an existing AWS certificate could choose to use the same certificate with
&PRODUCT;, but the public key would be uploaded to the &PRODUCT; management server
database.
+       A user with an existing AWS certificate could choose to use the same certificate with
&PRODUCT;, but note that the       certificate would be uploaded to the &PRODUCT;
management server database.
      </para>
    </note>
   </section>
   <section id="aws-api-tools-setup">
-    <title>AWS API Command-Line Tools Setup</title>
-    <para>To use the EC2 command-line tools, the user must perform these steps:</para>
-    <orderedlist>
-      <listitem><para>Be sure you have the right  version of EC2 Tools.
-        The supported version is available at <ulink url="http://s3.amazonaws.com/ec2-downloads/ec2-api-tools-1.3-62308.zip">http://s3.amazonaws.com/ec2-downloads/ec2-api-tools-1.3-62308.zip</ulink>.</para>
-      </listitem>
-      <listitem>
-        <para>Set up the environment variables that will direct the tools to the server.
 As a best practice, you may wish to place these commands in a script that may be sourced
before using the AWS API translation feature.</para>
-        <programlisting>$ export EC2_CERT=/path/to/cert.pem
-$ export EC2_PRIVATE_KEY=/path/to/private_key.pem
-$ export EC2_URL=http://<replaceable>&PRODUCT;.server</replaceable>:7080/awsapi
-$ export EC2_HOME=/path/to/EC2_tools_directory</programlisting>
-      </listitem>
-    </orderedlist>
+      <title>AWS API Command-Line Tools Setup</title>
+      <para>To use the EC2 command-line tools, the user must perform these steps:</para>
+      <orderedlist>
+          <listitem>
+              <para>Be sure you have the right  version of EC2 Tools.
+          The supported version is available at <ulink url="http://s3.amazonaws.com/ec2-downloads/ec2-api-tools-1.3-62308.zip">http://s3.amazonaws.com/ec2-downloads/ec2-api-tools-1.3-62308.zip</ulink>.
+              </para>
+          </listitem>
+          <listitem>
+              <para>Set up the EC2 environment variables.  This can be done every time
you use the service or you can set them up in the proper shell profile. Replace the endpoint
(i.e EC2_URL) with the proper address of your &PRODUCT; management server and port. In
a bash shell do the following.
+              </para>
+              <programlisting>
+                  $ export EC2_CERT=/path/to/cert.pem
+                  $ export EC2_PRIVATE_KEY=/path/to/private_key.pem
+                  $ export EC2_URL=http://localhost:7080/awsapi
+                  $ export EC2_HOME=/path/to/EC2_tools_directory
+              </programlisting>
+          </listitem>
+      </orderedlist>
   </section>
-</section>
\ No newline at end of file
+</section>

http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/09b68ce1/docs/en-US/aws-interface-compatibility.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/aws-interface-compatibility.xml b/docs/en-US/aws-interface-compatibility.xml
index a03d447..2c85c24 100644
--- a/docs/en-US/aws-interface-compatibility.xml
+++ b/docs/en-US/aws-interface-compatibility.xml
@@ -23,11 +23,12 @@
 -->
 
 <chapter id="aws-interface-compatibility">
-    <title>Amazon Web Service Interface Compatibility</title>
+    <title>Amazon Web Services Compatible Interface</title>
     <xi:include href="aws-ec2-introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
     <xi:include href="aws-ec2-requirements.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
     <xi:include href="aws-ec2-configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
     <xi:include href="aws-ec2-user-setup.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
     <xi:include href="aws-ec2-timeouts.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
     <xi:include href="aws-ec2-supported-commands.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
+    <xi:include href="aws-api-examples.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
/>
 </chapter>

http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/09b68ce1/docs/en-US/images/compute-service-offerings.png
----------------------------------------------------------------------
diff --git a/docs/en-US/images/compute-service-offerings.png b/docs/en-US/images/compute-service-offerings.png
new file mode 100644
index 0000000..88eb6f8
Binary files /dev/null and b/docs/en-US/images/compute-service-offerings.png differ

http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/09b68ce1/docs/en-US/images/ec2-s3-configuration.png
----------------------------------------------------------------------
diff --git a/docs/en-US/images/ec2-s3-configuration.png b/docs/en-US/images/ec2-s3-configuration.png
new file mode 100644
index 0000000..e69de29


Mime
View raw message