Examples

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 @@ + + +%BOOK_ENTITIES; +]> + + + +

+ Examples + 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. + +

+ Boto Examples + 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. + First is an EC2 example. Replace the Access and Secret Keys with your own and + update the endpoint. + + + An EC2 Boto example + #!/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() + + + + 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. + + + An S3 Boto Example + #!/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() + + + + +

+ +

+ JClouds Examples + +

+ +

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 @@ -->

- Enabling the AWS API Compatible Interface - - The software that provides AWS API compatibility is installed along with &PRODUCT;. However, you must enable the feature and perform some setup steps. - - - Set the global configuration parameter enable.ec2.api to true. See . - 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. - Be sure you have included the Amazon default service offering, m1.small. - If you did not already do so when you set the configuration parameter in step 1, restart the Management Server. - # service cloud-management restart - (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: - - Edit the files /etc/cloud/management/server.xml, /etc/cloud/management/server-nonssl.xml, and /etc/cloud/management/server-ssl.xml. - In each file, find the tag <Service name="Catalina7080">. Under this tag, locate <Connector executor="tomcatThreadPool-internal" port= ....<. - Change the port to whatever port you want to use, then save the files. - Restart the Management Server. - If you re-install CloudStack, you will have to make these changes again. + Enabling the EC2 and S3 Compatible Interface + + 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. + + + Set the global configuration parameters for each service to true. + See . + 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. + Be sure you have included the Amazon default service offering, m1.small. As well as any EC2 instance types that you will use. + + If you did not already do so when you set the configuration parameter in step 1, + restart the Management Server. + # service cloud-management restart - - - + + The following sections provides details to perform these steps + +

+ Enabling the Services + To enable the EC2 and S3 compatible services you need to set the configuration variables enable.ec2.api + and enable.s3.api 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 Global Settings or via the API. + The snapshot below shows you how to use the GUI to enable these services + + + + + + + + Use the GUI to set the configuration variable to true + + + + + 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 updateConfiguration method. + The following urls shows you how: + + + + http://localhost:8096/client/api?command=updateConfiguration&name=enable.ec2.api&value=true + http://localhost:8096/client/api?command=updateConfiguration&name=enable.ec2.api&value=true + + + + Once you have enabled the services, restart the server. +

+ +

+ Creating EC2 Compatible Service Offerings + You will also need to define compute service offerings with names compatible with the + Amazon EC2 instance types API names (e.g m1.small,m1.large). This can be done via the &PRODUCT; GUI. + Go under Service Offerings select Compute offering 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: + + + + + + + Use the GUI to set the name of a compute service offering to an EC2 instance + type API name. + + + +

+ Modifying the AWS API Port + + (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: + + Edit the files /etc/cloud/management/server.xml, /etc/cloud/management/server-nonssl.xml, + and /etc/cloud/management/server-ssl.xml. + In each file, find the tag <Service name="Catalina7080">. Under this tag, + locate <Connector executor="tomcatThreadPool-internal" port= ....<. + Change the port to whatever port you want to use, then save the files. + Restart the Management Server. + + If you re-install &PRODUCT;, you will have to re-enable the services and if need be update the port. + +

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 @@ -->

- Amazon Web Services EC2 Compatible Interface + Amazon Web Services Compatible Interface &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. + 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. This service was previously enabled by separate software called CloudBridge. It is now fully integrated with the &PRODUCT; management server. + + 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. + Limitations @@ -42,7 +45,9 @@ Available in fresh installations of &PRODUCT;. Not available through upgrade of previous versions. - 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). + 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).

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 @@ -->

- System Requirements + Supported API Version - This interface complies with Amazon's WDSL version dated November 15, 2010, available at + The EC2 interface complies with Amazon's WDSL version dated November 15, 2010, available at http://ec2.amazonaws.com/doc/2010-11-15/. - Compatible with the EC2 command-line + The interface is compatible with the EC2 command-line tools EC2 tools v. 1.3.6230, which can be downloaded at http://s3.amazonaws.com/ec2-downloads/ec2-api-tools-1.3-62308.zip. -

\ No newline at end of file + Work is underway to support a more recent version of the EC2 API + 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 @@

Supported AWS API Calls - The following Amazon EC2 commands are supported by &PRODUCT; when the AWS API compatibility feature is enabled. + 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. 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 @@

Using Timeouts to Ensure AWS API Command Completion - 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: + 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: @@ -47,4 +47,5 @@ Example: ec2-run-instances 2 –z us-test1 –n 1-3 --connection-timeout 120 --request-timeout 120 -

\ No newline at end of file + The timeouts optional arguments are not specific to &PRODUCT;. + 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. -->

- AWS API User Setup Steps + AWS API User Setup 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: - Generate user credentials and register with the service. + Generate user credentials. - Set up the environment variables for the EC2 command-line tools. + Register with the service. - For SOAP access, use the endpoint http://&PRODUCT;-management-server:7080/awsapi. - The &PRODUCT;-management-server can be specified by a fully-qualified domain name or IP address. + For convenience, set up environment variables for the EC2 SOAP command-line tools.

AWS API User Registration - Each user must perform a one-time registration. The user follows these steps: - - - Obtain the following by looking in the &PRODUCT; UI, using the API, or asking the cloud administrator: - - The &PRODUCT; server's publicly available DNS name or IP address - The user account's API key and Secret key - - - - - Generate a private key and a self-signed X.509 certificate. The user substitutes their own desired storage location for /path/to/… below. - - $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /path/to/private_key.pem -out /path/to/cert.pem - - - - - 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. - - -$ cloudstack-aws-api-register --apikey=User’s &PRODUCT; API key --secretkey=User’s &PRODUCT; Secret key --cert=/path/to/cert.pem --url=http://&PRODUCT;.server:7080/awsapi - - - + Each user must perform a one-time registration. The user follows these steps: + + + Obtain the following by looking in the &PRODUCT; UI, using the API, or asking the cloud administrator: + + + The &PRODUCT; server's publicly available DNS name or IP address + The user account's Access key and Secret key + + + + Generate a private key and a self-signed X.509 certificate. The user substitutes their own desired storage location for /path/to/… below. + + + $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /path/to/private_key.pem -out /path/to/cert.pem + + + + 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. + + + wget -O cloudstack-aws-api-register "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" + + + Then execute it, using the parameter values that were obtained in step 1. An example is shown below. + + $ cloudstack-aws-api-register --apikey=User’s &PRODUCT; API key --secretkey=User’s &PRODUCT; Secret key --cert=/path/to/cert.pem --url=http://&PRODUCT;.server:7080/awsapi + + + - 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.

- AWS API Command-Line Tools Setup - To use the EC2 command-line tools, the user must perform these steps: - - Be sure you have the right version of EC2 Tools. - The supported version is available at http://s3.amazonaws.com/ec2-downloads/ec2-api-tools-1.3-62308.zip. - - - 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. - $ export EC2_CERT=/path/to/cert.pem -$ export EC2_PRIVATE_KEY=/path/to/private_key.pem -$ export EC2_URL=http://&PRODUCT;.server:7080/awsapi -$ export EC2_HOME=/path/to/EC2_tools_directory - - + AWS API Command-Line Tools Setup + To use the EC2 command-line tools, the user must perform these steps: + + + Be sure you have the right version of EC2 Tools. + The supported version is available at http://s3.amazonaws.com/ec2-downloads/ec2-api-tools-1.3-62308.zip. + + + + 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. + + + $ 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 + + +

\ No newline at end of file + 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 @@ --> - Amazon Web Service Interface Compatibility + Amazon Web Services Compatible Interface + 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