Skip to content

Commit 09b68ce

Browse files
sebgoajzb
sebgoa
authored and
jzb
committed
Improvements to AWS installation, configuration and use in installation guide
1 parent 999ecb6 commit 09b68ce

10 files changed

Lines changed: 306 additions & 83 deletions

‎docs/en-US/aws-api-examples.xml‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
<?xml version='1.0' encoding='utf-8' ?>
2+
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
3+
<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
4+
%BOOK_ENTITIES;
5+
]>
6+
7+
<!-- Licensed to the Apache Software Foundation (ASF) under one
8+
or more contributor license agreements. See the NOTICE file
9+
distributed with this work for additional information
10+
regarding copyright ownership. The ASF licenses this file
11+
to you under the Apache License, Version 2.0 (the
12+
"License"); you may not use this file except in compliance
13+
with the License. You may obtain a copy of the License at
14+
15+
http://www.apache.org/licenses/LICENSE-2.0
16+
17+
Unless required by applicable law or agreed to in writing,
18+
software distributed under the License is distributed on an
19+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
20+
KIND, either express or implied. See the License for the
21+
specific language governing permissions and limitations
22+
under the License.
23+
-->
24+
25+
<section id="aws-api-examples">
26+
<title>Examples</title>
27+
<para>There are many tools available to interface with a AWS compatible API. In this section we provide
28+
a few examples that users of &PRODUCT; can build upon.</para>
29+
30+
<section id="aws-api-boto-examples">
31+
<title>Boto Examples</title>
32+
<para>Boto is one of them. It is a Python package available at https://github.com/boto/boto.
33+
In this section we provide two examples of Python scripts that use Boto and have been tested with the
34+
&PRODUCT; AWS API Interface.</para>
35+
<para>First is an EC2 example. Replace the Access and Secret Keys with your own and
36+
update the endpoint.</para>
37+
<para>
38+
<example>
39+
<title>An EC2 Boto example</title>
40+
<programlisting>#!/usr/bin/env python
41+
42+
import sys
43+
import os
44+
import boto
45+
import boto.ec2
46+
47+
region = boto.ec2.regioninfo.RegionInfo(name="ROOT",endpoint="localhost")
48+
apikey='GwNnpUPrO6KgIdZu01z_ZhhZnKjtSdRwuYd4DvpzvFpyxGMvrzno2q05MB0ViBoFYtdqKd'
49+
secretkey='t4eXLEYWw7chBhDlaKf38adCMSHx_wlds6JfSx3z9fSpSOm0AbP9Moj0oGIzy2LSC8iw'
50+
51+
def main():
52+
'''Establish connection to EC2 cloud'''
53+
conn =boto.connect_ec2(aws_access_key_id=apikey,
54+
aws_secret_access_key=secretkey,
55+
is_secure=False,
56+
region=region,
57+
port=7080,
58+
path="/awsapi",
59+
api_version="2010-11-15")
60+
61+
'''Get list of images that I own'''
62+
images = conn.get_all_images()
63+
print images
64+
myimage = images[0]
65+
'''Pick an instance type'''
66+
vm_type='m1.small'
67+
reservation = myimage.run(instance_type=vm_type,security_groups=['default'])
68+
69+
if __name__ == '__main__':
70+
main()
71+
</programlisting>
72+
</example>
73+
</para>
74+
<para>Second is an S3 example. Replace the Access and Secret keys with your own,
75+
as well as the endpoint of the service. Be sure to also update the file paths to something
76+
that exists on your machine.</para>
77+
<para>
78+
<example>
79+
<title>An S3 Boto Example</title>
80+
<programlisting>#!/usr/bin/env python
81+
82+
import sys
83+
import os
84+
from boto.s3.key import Key
85+
from boto.s3.connection import S3Connection
86+
from boto.s3.connection import OrdinaryCallingFormat
87+
88+
apikey='ChOw-pwdcCFy6fpeyv6kUaR0NnhzmG3tE7HLN2z3OB_s-ogF5HjZtN4rnzKnq2UjtnHeg_yLA5gOw'
89+
secretkey='IMY8R7CJQiSGFk4cHwfXXN3DUFXz07cCiU80eM3MCmfLs7kusgyOfm0g9qzXRXhoAPCH-IRxXc3w'
90+
91+
cf=OrdinaryCallingFormat()
92+
93+
def main():
94+
'''Establish connection to S3 service'''
95+
conn =S3Connection(aws_access_key_id=apikey,aws_secret_access_key=secretkey, \
96+
is_secure=False, \
97+
host='localhost', \
98+
port=7080, \
99+
calling_format=cf, \
100+
path="/awsapi/rest/AmazonS3")
101+
102+
try:
103+
bucket=conn.create_bucket('cloudstack')
104+
k = Key(bucket)
105+
k.key = 'test'
106+
try:
107+
k.set_contents_from_filename('/Users/runseb/Desktop/s3cs.py')
108+
except:
109+
print 'could not write file'
110+
pass
111+
except:
112+
bucket = conn.get_bucket('cloudstack')
113+
k = Key(bucket)
114+
k.key = 'test'
115+
try:
116+
k.get_contents_to_filename('/Users/runseb/Desktop/foobar')
117+
except:
118+
print 'Could not get file'
119+
pass
120+
121+
try:
122+
bucket1=conn.create_bucket('teststring')
123+
k=Key(bucket1)
124+
k.key('foobar')
125+
k.set_contents_from_string('This is my silly test')
126+
except:
127+
bucket1=conn.get_bucket('teststring')
128+
k = Key(bucket1)
129+
k.key='foobar'
130+
k.get_contents_as_string()
131+
132+
if __name__ == '__main__':
133+
main()
134+
135+
</programlisting>
136+
</example>
137+
</para>
138+
</section>
139+
140+
<section id="aws-api-jclouds-examples">
141+
<title>JClouds Examples</title>
142+
<para></para>
143+
</section>
144+
145+
</section>

‎docs/en-US/aws-ec2-configuration.xml‎

Lines changed: 83 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -23,26 +23,88 @@
2323
-->
2424

2525
<section id="aws-ec2-configuration">
26-
<title>Enabling the AWS API Compatible Interface</title>
27-
<para>
28-
The software that provides AWS API compatibility is installed along with &PRODUCT;. However, you must enable the feature and perform some setup steps.
29-
</para>
30-
<orderedlist>
31-
<listitem><para>Set the global configuration parameter enable.ec2.api to true. See <xref linkend="global-config" />.</para></listitem>
32-
<listitem><para>Create a set of &PRODUCT; service offerings with names that match the Amazon service offerings.
33-
You can do this through the &PRODUCT; UI as described in the Administration Guide.</para>
34-
<warning><para>Be sure you have included the Amazon default service offering, m1.small.</para></warning></listitem>
35-
<listitem><para>If you did not already do so when you set the configuration parameter in step 1, restart the Management Server.</para>
36-
<programlisting># service cloud-management restart</programlisting></listitem>
37-
<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>
38-
<orderedlist numeration="loweralpha">
39-
<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>
40-
<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>
41-
<listitem><para>Change the port to whatever port you want to use, then save the files.</para></listitem>
42-
<listitem><para>Restart the Management Server.</para>
43-
<note><para>If you re-install CloudStack, you will have to make these changes again.</para></note>
26+
<title>Enabling the EC2 and S3 Compatible Interface</title>
27+
28+
<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.
29+
</para>
30+
<orderedlist>
31+
<listitem><para>Set the global configuration parameters for each service to true.
32+
See <xref linkend="global-config" />.</para></listitem>
33+
<listitem><para>Create a set of &PRODUCT; service offerings with names that match the Amazon service offerings.
34+
You can do this through the &PRODUCT; UI as described in the Administration Guide.</para>
35+
<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>
36+
</listitem>
37+
<listitem><para>If you did not already do so when you set the configuration parameter in step 1,
38+
restart the Management Server.</para>
39+
<programlisting># service cloud-management restart</programlisting>
4440
</listitem>
45-
</orderedlist>
46-
</listitem>
47-
</orderedlist>
41+
</orderedlist>
42+
<para>The following sections provides details to perform these steps</para>
43+
44+
<section id="aws-api-settings">
45+
<title>Enabling the Services</title>
46+
<para>To enable the EC2 and S3 compatible services you need to set the configuration variables <emphasis>enable.ec2.api</emphasis>
47+
and <emphasis>enable.s3.api</emphasis> to true. You do not have to enable both at the same time. Enable the ones you need.
48+
This can be done via the &PRODUCT; GUI by going in <emphasis>Global Settings</emphasis> or via the API.</para>
49+
<para>The snapshot below shows you how to use the GUI to enable these services</para>
50+
51+
<para>
52+
<mediaobject>
53+
<imageobject>
54+
<imagedata fileref="./images/ec2-s3-configuration.png"/>
55+
</imageobject>
56+
<textobject>
57+
<phrase>Use the GUI to set the configuration variable to <emphasis>true</emphasis></phrase>
58+
</textobject>
59+
</mediaobject>
60+
</para>
61+
62+
<para>Using the &PRODUCT; API, the easiest is to use the so-called integration port on which you can make
63+
unauthenticated calls. In Global Settings set the port to 8096 and subsequently call the <emphasis>updateConfiguration</emphasis> method.
64+
The following urls shows you how:</para>
65+
66+
<para>
67+
<programlisting>
68+
http://localhost:8096/client/api?command=updateConfiguration&amp;name=enable.ec2.api&amp;value=true
69+
http://localhost:8096/client/api?command=updateConfiguration&amp;name=enable.ec2.api&amp;value=true
70+
</programlisting>
71+
</para>
72+
73+
<para>Once you have enabled the services, restart the server.</para>
74+
</section>
75+
76+
<section id="aws-ec2-service-offerings">
77+
<title>Creating EC2 Compatible Service Offerings</title>
78+
<para>You will also need to define compute service offerings with names compatible with the <ulink url="http://aws.amazon.com/ec2/instance-types/">
79+
Amazon EC2 instance types</ulink> API names (e.g m1.small,m1.large). This can be done via the &PRODUCT; GUI.
80+
Go under <emphasis>Service Offerings</emphasis> select <emphasis>Compute offering</emphasis> and either create
81+
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>
82+
<para>
83+
<mediaobject>
84+
<imageobject>
85+
<imagedata fileref="./images/compute-service-offerings.png"/>
86+
</imageobject>
87+
<textobject>
88+
<phrase>Use the GUI to set the name of a compute service offering to an EC2 instance
89+
type API name.</phrase>
90+
</textobject>
91+
</mediaobject>
92+
</para>
93+
</section>
94+
<section id="aws-api-port-change">
95+
<title>Modifying the AWS API Port</title>
96+
<note>
97+
<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>
98+
<orderedlist numeration="loweralpha">
99+
<listitem><para>Edit the files /etc/cloud/management/server.xml, /etc/cloud/management/server-nonssl.xml,
100+
and /etc/cloud/management/server-ssl.xml.</para></listitem>
101+
<listitem><para>In each file, find the tag &lt;Service name="Catalina7080"&gt;. Under this tag,
102+
locate &lt;Connector executor="tomcatThreadPool-internal" port= ....&lt;.</para></listitem>
103+
<listitem><para>Change the port to whatever port you want to use, then save the files.</para></listitem>
104+
<listitem><para>Restart the Management Server.</para></listitem>
105+
</orderedlist>
106+
<para>If you re-install &PRODUCT;, you will have to re-enable the services and if need be update the port.</para>
107+
</note>
108+
</section>
109+
48110
</section>

‎docs/en-US/aws-ec2-introduction.xml‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,16 +23,19 @@
2323
-->
2424

2525
<section id="aws-ec2-introduction">
26-
<title>Amazon Web Services EC2 Compatible Interface</title>
26+
<title>Amazon Web Services Compatible Interface</title>
2727
<para>&PRODUCT; can translate Amazon Web Services (AWS) API calls to native &PRODUCT; API calls
2828
so that users can continue using existing AWS-compatible tools. This translation service runs as
2929
a separate web application in the same tomcat server as the management server of &PRODUCT;,
30-
listening on the same port. This Amazon EC2-compatible API is accessible through a SOAP web
31-
service.</para>
30+
listening on a different port. The Amazon Web Services (AWS) compatible interface provides the
31+
EC2 SOAP and Query APIs as well as the S3 REST API.</para>
3232
<note>
3333
<para>This service was previously enabled by separate software called CloudBridge. It is now
3434
fully integrated with the &PRODUCT; management server. </para>
3535
</note>
36+
<warning>
37+
<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>
38+
</warning>
3639
<para>Limitations</para>
3740
<itemizedlist>
3841
<listitem>
@@ -42,7 +45,9 @@
4245
<para>Available in fresh installations of &PRODUCT;. Not available through upgrade of previous versions.</para>
4346
</listitem>
4447
<listitem>
45-
<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>
48+
<para>Features such as Elastic IP (EIP) and Elastic Load Balacing (ELB) are only available in an infrastructure
49+
with a Citrix NetScaler device. Users accessing a Zone with a NetScaler device will need to use a
50+
NetScaler-enabled network offering (DefaultSharedNetscalerEIP and ELBNetworkOffering).</para>
4651
</listitem>
4752
</itemizedlist>
4853
</section>

‎docs/en-US/aws-ec2-requirements.xml‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,13 +23,14 @@
2323
-->
2424

2525
<section id="aws-ec2-requirements">
26-
<title>System Requirements</title>
26+
<title>Supported API Version</title>
2727
<itemizedlist>
28-
<listitem><para>This interface complies with Amazon's WDSL version dated November 15, 2010, available at
28+
<listitem><para>The EC2 interface complies with Amazon's WDSL version dated November 15, 2010, available at
2929
<ulink url="http://ec2.amazonaws.com/doc/2010-11-15/">http://ec2.amazonaws.com/doc/2010-11-15/</ulink>.</para></listitem>
30-
<listitem><para>Compatible with the EC2 command-line
30+
<listitem><para>The interface is compatible with the EC2 command-line
3131
tools <emphasis>EC2 tools v. 1.3.6230</emphasis>, which can be downloaded at <ulink
3232
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>
3333
</listitem>
3434
</itemizedlist>
35-
</section>
35+
<note><para>Work is underway to support a more recent version of the EC2 API</para></note>
36+
</section>

‎docs/en-US/aws-ec2-supported-commands.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424

2525
<section id="aws-ec2-supported-commands">
2626
<title>Supported AWS API Calls</title>
27-
<para>The following Amazon EC2 commands are supported by &PRODUCT; when the AWS API compatibility feature is enabled.
27+
<para>The following Amazon EC2 commands are supported by &PRODUCT; when the AWS API compatible interface is enabled.
2828
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.
2929
</para>
3030
<table frame='all'>

‎docs/en-US/aws-ec2-timeouts.xml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424

2525
<section id="aws-ec2-timeouts">
2626
<title>Using Timeouts to Ensure AWS API Command Completion</title>
27-
<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>
27+
<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>
2828
<informaltable frame="all">
2929
<tgroup cols="2" align="left" colsep="1" rowsep="1">
3030
<colspec colname="c1" />
@@ -47,4 +47,5 @@
4747
</informaltable>
4848
<para>Example:</para>
4949
<programlisting>ec2-run-instances 2 –z us-test1 –n 1-3 --connection-timeout 120 --request-timeout 120</programlisting>
50-
</section>
50+
<note><para>The timeouts optional arguments are not specific to &PRODUCT;.</para></note>
51+
</section>

0 commit comments

Comments
 (0)