From 22b5c0cddd798829788b4e630b8ae77b81a05c2f Mon Sep 17 00:00:00 2001 From: Jessica Tomechak Date: Wed, 17 Oct 2012 00:30:44 -0700 Subject: [PATCH] Docs: Fix up grammar and missing text in AWS API compatibility chapter and add it to the Install Guide. --- docs/en-US/Installation_Guide.xml | 1 + docs/en-US/aws-ec2-configuration.xml | 56 +++++-------- docs/en-US/aws-ec2-introduction.xml | 13 +-- docs/en-US/aws-ec2-requirements.xml | 15 ++-- docs/en-US/aws-ec2-supported-commands.xml | 37 +++------ docs/en-US/aws-ec2-timeouts.xml | 50 +++++++++++ docs/en-US/aws-ec2-user-setup.xml | 82 ++++++++++--------- ...de.xml => aws-interface-compatibility.xml} | 5 +- 8 files changed, 148 insertions(+), 111 deletions(-) create mode 100644 docs/en-US/aws-ec2-timeouts.xml rename docs/en-US/{aws-interface-guide.xml => aws-interface-compatibility.xml} (88%) diff --git a/docs/en-US/Installation_Guide.xml b/docs/en-US/Installation_Guide.xml index bdc3b8ea20a..26c25219d43 100644 --- a/docs/en-US/Installation_Guide.xml +++ b/docs/en-US/Installation_Guide.xml @@ -53,5 +53,6 @@ + diff --git a/docs/en-US/aws-ec2-configuration.xml b/docs/en-US/aws-ec2-configuration.xml index e1924072168..b8966c12495 100644 --- a/docs/en-US/aws-ec2-configuration.xml +++ b/docs/en-US/aws-ec2-configuration.xml @@ -23,42 +23,26 @@ -->
- Enabling the AWS API compatible Interface + Enabling the AWS API Compatible Interface - To enable the EC2 compatible service you need to set the configuration variable enable.ec2.apito true. This can be done via the &PRODUCT; GUI by going in Global Settings or via the API. - - - - - - - - Use the GUI to set the configuration variable to true - - - - - 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 url shows you how: - - - - http://localhost:8096/client/api?command=updateConfiguration&name=enable.ec2.api&value=true - - - - Once you have updated enable.ec2.apito true, restart the server. - - - 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 is easiest 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. - - + The software that provides AWS API compatibility is installed along with CloudPlatform. 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. + + + +
diff --git a/docs/en-US/aws-ec2-introduction.xml b/docs/en-US/aws-ec2-introduction.xml index c2bfb32bc61..a4df086d465 100644 --- a/docs/en-US/aws-ec2-introduction.xml +++ b/docs/en-US/aws-ec2-introduction.xml @@ -24,13 +24,14 @@
Amazon Web Services EC2 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 as well as the REST query interface. - - Expect the SOAP service to be deprecated in new releases in favor of the REST 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. - This service was previously enabled by a separate software called CloudBridge, it is now fully integrated with the &PRODUCT; management server. - + This service was previously enabled by separate software called CloudBridge. It is now + fully integrated with the &PRODUCT; management server. Limitations diff --git a/docs/en-US/aws-ec2-requirements.xml b/docs/en-US/aws-ec2-requirements.xml index 916cec5fdda..59fb5b6f5ab 100644 --- a/docs/en-US/aws-ec2-requirements.xml +++ b/docs/en-US/aws-ec2-requirements.xml @@ -23,8 +23,13 @@ -->
- System Requirements - This interface complies with Amazon's WDSL version dated November 15, 2010, available at http://ec2.amazonaws.com/doc/2010-11-15/. The EC2 command line utilities compatible with it are EC2 tools v. 1.3.6230that can be downloaded at http://s3.amazonaws.com/ec2-downloads/ec2-api-tools-1.3-62308.zip - - Effort is underway to provide support for a newer API -
+ System Requirements + + This 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 + 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 diff --git a/docs/en-US/aws-ec2-supported-commands.xml b/docs/en-US/aws-ec2-supported-commands.xml index 77e47bd90a5..9494218cd1c 100644 --- a/docs/en-US/aws-ec2-supported-commands.xml +++ b/docs/en-US/aws-ec2-supported-commands.xml @@ -24,10 +24,9 @@
Supported AWS API Calls - - The following Amazon EC2 commands are supported by &PRODUCT; when the AWS API compatibility feature 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. + The following Amazon EC2 commands are supported by &PRODUCT; when the AWS API compatibility feature 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. - Elastic IP Addresses Elastic IP API mapping @@ -36,7 +35,7 @@ EC2 command - SOAP all + SOAP call &PRODUCT; API call @@ -69,7 +68,6 @@
- Availability Zones Availability Zone API mapping @@ -78,7 +76,7 @@ EC2 command - SOAP all + SOAP call &PRODUCT; API call @@ -91,7 +89,6 @@
- Images Images API mapping @@ -100,7 +97,7 @@ EC2 command - SOAP all + SOAP call &PRODUCT; API call @@ -128,7 +125,6 @@
- Image Attributes Image Attributes API mapping @@ -137,7 +133,7 @@ EC2 command - SOAP all + SOAP call &PRODUCT; API call @@ -160,7 +156,6 @@
- Instances Instances API mapping @@ -169,7 +164,7 @@ EC2 command - SOAP all + SOAP call &PRODUCT; API call @@ -207,7 +202,6 @@
- Instance Attributes Instance Attributes Mapping @@ -216,7 +210,7 @@ EC2 command - SOAP all + SOAP call &PRODUCT; API call @@ -229,7 +223,6 @@
- Key Pairs Keys Pairs Mapping @@ -238,7 +231,7 @@ EC2 command - SOAP all + SOAP call &PRODUCT; API call @@ -266,7 +259,6 @@
- Passwords Passwords API Mapping @@ -275,7 +267,7 @@ EC2 command - SOAP all + SOAP call &PRODUCT; API call @@ -288,7 +280,6 @@
- Security Groups Security Groups API Mapping @@ -297,7 +288,7 @@ EC2 command - SOAP all + SOAP call &PRODUCT; API call @@ -330,7 +321,6 @@
- Snapshots Snapshots API Mapping @@ -339,7 +329,7 @@ EC2 command - SOAP all + SOAP call &PRODUCT; API call @@ -362,7 +352,6 @@
- Volumes Volumes API Mapping @@ -371,7 +360,7 @@ EC2 command - SOAP all + SOAP call &PRODUCT; API call diff --git a/docs/en-US/aws-ec2-timeouts.xml b/docs/en-US/aws-ec2-timeouts.xml new file mode 100644 index 00000000000..c8b3ec6465f --- /dev/null +++ b/docs/en-US/aws-ec2-timeouts.xml @@ -0,0 +1,50 @@ + + +%BOOK_ENTITIES; +]> + + + +
+ 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: + + + + +
+ + --connection-timeout TIMEOUT + Specifies a connection timeout (in seconds). + Example: --connection-timeout 30 + + + + --request-timeout TIMEOUT + Specifies a request timeout (in seconds). + Example: --request-timeout 45 + + + + + + Example: + ec2-run-instances 2 –z us-test1 –n 1-3 --connection-timeout 120 --request-timeout 120 + \ No newline at end of file diff --git a/docs/en-US/aws-ec2-user-setup.xml b/docs/en-US/aws-ec2-user-setup.xml index 50c9fe26656..55b2950a317 100644 --- a/docs/en-US/aws-ec2-user-setup.xml +++ b/docs/en-US/aws-ec2-user-setup.xml @@ -22,70 +22,76 @@ under the License. -->
- User configuration - - 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 specifyingi the endpoint of the managment server and using the proper user credentials.In order to do this, each user must perform the following configuration steps: - + AWS API User Setup Steps + 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 + 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. + Generate user credentials and register with the service. - Register with the service. + Set up the environment variables for the EC2 command-line tools. - Setup the environment variables + For SOAP access, use the endpoint http://&PRODUCT;-management-server:8080/awsapi. + The &PRODUCT;-management-server can be specified by a fully-qualified domain name or IP address. - - - To register, a user needs to: - - +
+ AWS API User Registration + Each user must perform a one-time registration. The user follows these steps: - - Obtain his API key and his secret key as well as the DNS name or IP address of the &PRODUCT; server. Obtaining the keys can be done by asking the &PRODUCT; administrator or by using the GUI or via the API. - + 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 + - Obtain a self-signed X.509 certificate. It can be generated with the following command: + 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 + $ 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 you obtained from the administrator in the URL below. + 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 CloudPlatform API key --secretkey=User’s CloudPlatform Secret key --cert=/path/to/cert.pem --url=http://&PRODUCT;.server:8080/awsapi +$ 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:8080/awsapi - - A user with an existing AWS certificate could choose to use the same certificate with &PRODUCT; but note that 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 the public key would be uploaded to the &PRODUCT; management server database. - - - To use the EC2 command line tools, setup the environment variable in a similar fashion than with Amazon EC2 service. Specifically, in bash shell: - - $ export EC2_CERT=/path/to/cert.pem - $ export EC2_PRIVATE_KEY=/path/to/private_key.pem - $ export EC2_URL=http://&PRODUCT;.server:8080/awsapi - $ export EC2_HOME=/path/to/EC2_tools_directory - - - - - The Amazon EC2 command-line tools have a default connection timeout. If you find that EC2 commands are not completing due to timeouts, you can pass a new timeout value as an argument with --connection-timeout TIMEOUT or --request-timeout TIMEOUT - - - -
+
+
+ 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:8080/awsapi +$ export EC2_HOME=/path/to/EC2_tools_directory + + +
+ \ No newline at end of file diff --git a/docs/en-US/aws-interface-guide.xml b/docs/en-US/aws-interface-compatibility.xml similarity index 88% rename from docs/en-US/aws-interface-guide.xml rename to docs/en-US/aws-interface-compatibility.xml index 0c42b5bdb07..a03d447b50d 100644 --- a/docs/en-US/aws-interface-guide.xml +++ b/docs/en-US/aws-interface-compatibility.xml @@ -22,11 +22,12 @@ under the License. --> - - Amazon Web Service Interface Guide + + Amazon Web Service Interface Compatibility +