         | Did this page help you? Yes No Tell us about it... |
Auto Scaling Tools
Currently, there are two tools you can use to work with Auto Scaling. You can use the command line tools (CLI), or you can use the Query API. The command line tools must be installed on the computer with which you access your Amazon EC2 resources on the AWS cloud. This section discusses how you can use these tools.
Using the Command Line Tools
This section describes how to set up your environment for use with the Auto Scaling command line tools.
An installation of a Java 5–compatible Java Runtime Environment (JRE) is required. Additionally, accessing Linux and UNIX instances requires access to an SSH client and accessing Windows instances requires access to a Remote Desktop client. For more information, refer to the two following sections.
As a convention, all command line text is prefixed with a generic
PROMPT> $ C:\>
Setting the Java Home Variable
The Auto Scaling command line tools require Java version 5 or later to run. Either a JRE or JDK installation is acceptable. To view and download JREs for a range of platforms, including Linux/UNIX and Windows, go to http://java.sun.com/j2se/1.5.0/.
The command line tools depend on an environment variable
(JAVA_HOME) to locate the Java runtime. This
environment variable should be set to the full path of the
directory that contains a subdirectory
named bin that in turn contains
the java (on Linux and UNIX) or
the java.exe (on Windows) executable. You
might want to simplify the process by adding this directory to your
path before other versions of Java. Make sure you don't include the bin directory in the path;
that's a common mistake some users make. The command line tools won't work if you do.
![[Note]](http://docs.amazonwebservices.com/docs-common/images/note.png) | Note |
|---|---|
If you are using Cygwin, AWS_AUTO_SCALING_HOME, EC2_PRIVATE_KEY, and EC2_CERT, you must use Linux/UNIX paths (e.g., /usr/bin instead of C:\usr\bin). However, JAVA_HOME should have a Windows path. Additionally, the value of AWS_AUTO_SCALING_HOME cannot contain any spaces, even if the value is quoted or the spaces are escaped. |
The following is an example of how to set this environment variable in Linux and UNIX.
$export JAVA_HOME=<PATH>
The following is an example of the syntax in Windows.
C:\>set JAVA_HOME=<PATH>
You can confirm this by running $JAVA_HOME/bin/java -version and
checking the output.
$$JAVA_HOME/bin/java -versionjava version "1.5.0_09" Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_09-b03) Java HotSpot(TM) Client VM (build 1.5.0_09-b03, mixed mode, sharing)
The syntax is different on Windows, but the output is similar.
C:\>%JAVA_HOME%\bin\java -versionjava version "1.5.0_09" Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_09-b03) Java HotSpot(TM) Client VM (build 1.5.0_09-b03, mixed mode, sharing)
Setting Up the Tools
Topics
To use the Auto Scaling command line tool, you need to download it and set it up to use your AWS account.
How to Get the Command Line Tool
The command line tool is available as a ZIP file in the Auto Scaling Command Line Tools. These tools are written in Java and include shell scripts for both Windows 2000/XP and Linux/UNIX/Mac OSX. The ZIP file is self-contained; no installation is required. You just download it and unzip it.
Some additional setup is required for the tools to use your AWS account credentials. These are discussed next.
How to Tell the Tools Where They Live
The command line tools depend on an environment variable (AWS_AUTO_SCALING_HOME) to locate
supporting libraries. You'll need to set this environment variable before you can use the tools.
You should set this variable to the path of the directory into which the command line tools were unzipped.
This directory is named AutoScaling-A.B.C.D
(A, B, C, and D are version/release
numbers) and contains sub-directories named bin and
lib.
On Linux and UNIX, you can set this environment variable as follows:
$exportAWS_AUTO_SCALING_HOME=<path-to-tools>
On Windows the syntax is slightly different:
C:\>setAWS_AUTO_SCALING_HOME=<path-to-tools>
In addition, to make your life a little easier, you probably want to add the tools'
bin directory to your system PATH. The rest of this guide
assumes that you've done this.
On Linux and UNIX, you can update your PATH as follows:
$export PATH=$PATH:$AWS_AUTO_SCALING_HOME/bin
On Windows the syntax is slightly different:
C:\>set PATH=%PATH%;%AWS_AUTO_SCALING_HOME%\bin
| Note |
|---|---|
The Windows environment variables are reset when you close the command window. You might
want to set them permanently with the |
How to Tell the Tools Who You Are
You must also provide your AWS credentials to the command line tools. You can use your AWS access keys or your AWS X.509 certificates.
To use access keys with the command line tools
Log in to the AWS security credentials web site.
Retrieve an access key and its corresponding secret key. For instructions on how to get these keys, see How to Get Your Access Key ID and Secret Access Key.
Open the file
$AWS_AUTO_SCALING_HOME/credential-file-path.template(%AWS_AUTO_SCALING_HOME%\credential-file-path.templateon Windows) that you downloaded as part of the command line tools ZIP file. Add your access key and secret key to the appropriate locations in the template file. Save the file to a convenient location on your workstation. You should use a new name for the file and, on Linux, set its file permissions usingchmod 600file name.Use this file in either of two ways:
Set the AWS_CREDENTIAL_FILE environment variable to the fully qualified path of the file you just created.
Specify the
--aws-credential-filefile nameparameter with each command you use.
Alternatively, you can specify your access keys directly on the command line by including the
--I[your access key]--S[your secret key] parameters.
| Note |
|---|---|
Many developers find that creating a credential file and a corresponding AWS_CREDENTIAL_FILE environment variable is the most convenient way to supply credentials to the command line tools. |
To use your X.509 certificate files with the command line tools
Log in to the AWS security credentials site.
Click the X.509 Certificate tab, and follow the instructions to download your certificate and private key files to a secure location on your workstation. Name the files appropriately (for example, my-aws-cert.pem and my-aws-pk.pem).
Use these files in either of two ways:
Specify the
--ec2-cert-file-path=certificate file nameand--ec2-private-key-file-pathkey file nameparameters with each command you use.Set the EC2_CERT environment variable to the fully qualified path of the certificate file you just created, and set the EC2_PRIVATE_KEY environment variable to the fully qualified path of the key file you just created. This method saves you the effort of specifying two parameters with each command you use.
How to Change the Region
By default, the Auto Scaling tools use the US East (Northern Virginia) Region (us-east-1) with
the autoscaling.us-east-1.amazonaws.com service endpoint URL.
If you want to explicitly specify the Region for your Auto Scaling service, set AWS_AUTO_SCALING_REGION to the service endpoint URL
(autoscaling.us-east-1.amazonaws.com, for example).
To specify a different Region
View available Regions by going to Regions and Endpoints.
If you want to change the service endpoint, set the
AWS_AUTO_SCALING_URLenvironment variable as follows:Note Keep in mind that if you set the
EC2_REGIONenvironment variable, such as us-east-1, its value supersedes any value you set usingAWS_AUTO_SCALING_URL.For Linux and UNIX:
$export AWS_AUTO_SCALING_URL=https://<service_endpoint>For Windows:
C:\>set AWS_AUTO_SCALING_URL=https://<service_endpoint>
You're ready to start using Auto Scaling.
Using Credentials
Topics
This section describes how to use the following Auto Scaling credentials:
Amazon Login and Password—Used to sign up for Amazon EC2 and other services, view your bills, perform account-based tasks, and get many of your security credentials. Additionally, they are used by the AWS Management Console. For information, see How to Log In with Your Amazon Login and Password.
Access Key ID and Secret Access Key—Used to make Query and REST-based requests. Also commonly used by UI-based tools, such as ElasticFox. For more information, see How to Get Your Access Key ID and Secret Access Key.
X.509 Certificate and Private Key—Used by the command line tools and SOAP API. For more information, see How to Create an X.509 Certificate and Private Key.
Account ID—Used to share resources with other AWS accounts. For more information, see Viewing Your Account ID.
How to Log In with Your Amazon Login and Password
The Amazon login and password enable you to sign up for services, view your bills, perform account-based tasks, and get many of your security credentials. You also use the login and password to perform Amazon EC2 tasks through the AWS Management Console.
This section describes how to log in with your login and password.
To log in with your login and password (if you have an existing account)
Go to the AWS web site.
Select an option from the Your Account menu.
The Amazon Web Services Sign In page appears.
Enter your e-mail address, select I am a returning user and my password is, enter your password, and click the Sign In button.
To get a new Amazon login and password (create a new AWS account)
Go to the AWS web site.
Click Create an AWS Account.
The Amazon Web Services Sign In page appears.
Enter your e-mail address, select I am a new user, and click the Sign In button.
Follow the on-screen prompts to create a new account.
| Note |
|---|---|
It is important to keep your Amazon login and password secret as they can be used to view and create new credentials. As an increased security measure, Amazon offers Multi-Factor Authentication, which uses the combination of a physical device and passcode to log in to your AWS account. For more information, go to http://aws.amazon.com/mfa. |
How to View Your AWS Access Credentials
You can reuse active AWS access credentials that you've created in the past.
To view your AWS access credentials
Go to the Amazon Web Services website at http://aws.amazon.com.
Click My Account/Console, and then click Security Credentials.
Under Your Account, click Security Credentials.
In the spaces provided, type your user name and password, and then click Sign in using our secure server.
Under Access Credentials, on the Access Keys tab, your access key ID is displayed. To view your secret key, under Secret Access Key, click Show.
How to Get Your Access Key ID and Secret Access Key
The Access Key ID and Secret Access Key are the most commonly used AWS credentials. You can use them to make Query and REST-based requests and to use the command line tools. They are also commonly used by UI-based tools, such as ElasticFox. You can use up to two sets of Access Keys at a time. You can generate new keys at any time or disable existing keys.
To get your Access Key ID and Secret Access Key
Go to the AWS web site.
Point to Your Account and select Security Credentials.
If you are not already logged in, you are prompted to do so.
Scroll down to the Access Credentials section and verify that the Access Keys tab is selected.
Locate an active Access Key in the Your Access Keys list.
To display the Secret Access Key, click Show in the Secret Access Key column.
Write down the keys or save them.
If no Access Keys appear in the list, click Create a New Access Key and follow the on-screen prompts.
How to Create an X.509 Certificate and Private Key
The X.509 Certificate and Private Key are used by the command line tools and SOAP. You can download the private key file once. If you lose it, you will need to create a new certificate. Up to two certificates can be active at any time.
This section describes how to create a new certificate.
To create a certificate
Go to the AWS web site.
Point to Your Account and select Security Credentials.
If you are not already logged in, you are prompted to do so.
Click the X.509 Certificates tab.
Click Create a New Certificate and follow the on-screen prompts.
The new certificate is created and appears in the X.509 certificates list. You are prompted to download the certificate and private key files.
Create an .as directory (the "as" stands for "Auto Scaling") in your home directory, and save these files to it with the file names offered by your browser.
You should end up with a PEM-encoded X.509 certificate and a private key file.
Viewing Your Account ID
The Account ID identifies your account to AWS and enables other accounts to access resources that you want to share, such as Amazon EC2 AMIs and Amazon EBS snapshots.
To view your Account ID
Go to the AWS web site.
Point to Your Account and select Security Credentials.
If you are not already logged in, you are prompted to do so.
Scroll down to the Account Identifiers section.
Locate your AWS Account ID.
For information on how to share AMIs, see Using Shared AMIs. For information on how to share snapshots, see How to Modify Snapshot Permissions.
| Note |
|---|---|
The Account ID number is not a secret. When granting access to resources, make sure to specify the Account ID without hyphens. |
Using the Query API
Query requests are HTTP or HTTPS requests that use the HTTP verb GET or POST and a Query parameter named Action or Operation. Action is used throughout this documentation, although Operation is supported for backward compatibility with other AWS Query APIs.
Endpoints
For information about this product's regions and endpoints, go to Regions and Endpoints in the Amazon Web Services General Reference.
Making Query Requests
Query requests are HTTP or HTTPS requests that use the HTTP verb GET or POST and a Query parameter named Action or Operation. Action is used throughout this documentation, although Operation is supported for backwards compatibility with other AWS Query APIs.
Query Parameters
Each query request must include some common parameters to handle authentication and selection of an action. For more information, go to Common Query Parameters in the Auto Scaling API Reference.
| Note |
|---|---|
Some API operations take lists of parameters. These lists are specified using the following notation: param.member.n. Values of n are integers starting from 1. All lists of parameters must follow this notation, including lists that contain only one parameter. For example, a query parameter list looks like this:
&attribute.member.1=this
&attribute.member.2=that
|
The Request ID
In every response from AWS, you will see the element ResponseMetadata, which
contains a string element called RequestId. This is simply a unique identifier that AWS
assigns to this request for tracking and troubleshooting purposes.
Request Authentication
You can send Query requests over either HTTP or HTTPS. Regardless of which protocol you use, you must include a signature in every Query request. This section describes how to create the signature. The method described in the following procedure is known as signature version 2.
To create the signature
Create the canonicalized query string that you need later in this procedure:
Sort the UTF-8 query string components by parameter name with natural byte ordering.
The parameters can come from the GET URI or from the POST body (when
Content-Typeisapplication/x-www-form-urlencoded).URL-encode the parameter name and values according to the following rules:
Do not URL-encode any of the unreserved characters that RFC 3986 defines.
These unreserved characters are A-Z, a-z, 0-9, hyphen ( - ), underscore ( _ ), period ( . ), and tilde ( ~ ).
Percent-encode all other characters with
%XY, where X and Y are hex characters 0-9 and uppercase A-F.Percent-encode extended UTF-8 characters in the form
%XY%ZA, and so on.Percent-encode the space character as
%20(and not +, as common encoding schemes do).
Note Currently, all AWS service parameter names use unreserved characters, so you don't need to encode them. However, you might want to include code to handle parameter names that use reserved characters, for possible future use.
Separate the encoded parameter names from their encoded values with the equals sign ( = ) (ASCII character 61), even if the parameter value is empty.
Separate the name-value pairs with an ampersand ( & ) (ASCII code 38).
Create the string to sign according to the following pseudo-grammar (the
"\n"represents an ASCII newline).StringToSign = HTTPVerb + "\n" + ValueOfHostHeaderInLowercase + "\n" + HTTPRequestURI + "\n" + CanonicalizedQueryString <from the preceding step>The
HTTPRequestURIcomponent is the HTTP absolute path component of the URI up to but not including the query string. If theHTTPRequestURIis empty, use a forward slash ( / ).Calculate an RFC 2104-compliant HMAC with the string you just created, your Secret Access Key as the key, and SHA256 or SHA1 as the hash algorithm.
For more information, go to http://www.ietf.org/rfc/rfc2104.txt.
Convert the resulting value to base64.
Use the resulting value as the value of the
Signaturerequest parameter.
![[Important]](http://docs.amazonwebservices.com/docs-common/images/important.png) | Important |
|---|---|
The final signature you send in the request must be URL-encoded as specified in RFC 3986 (for more information, go to http://www.ietf.org/rfc/rfc3986.txt). If your toolkit URL-encodes your final request, then it handles the required URL-encoding of the signature. If your toolkit doesn't URL-encode the final request, then make sure to URL-encode the signature before you include it in the request. Most importantly, make sure the signature is URL-encoded only once. A common mistake is to URL-encode it manually during signature formation, and then again when the toolkit URL-encodes the entire request. |
Query Example
Example Describe AutoScalingGroup API Request
This example uses CreateAutoScalingGroup.
http://autoscaling.amazonaws.com/?AutoScalingGroupName=webtier
&LaunchConfigurationName=wt20080929
&MinSize=0
&MaxSize=2
&DefaultCooldown=0
&Expires=2011-02-10T12%3A00%3A00Z
&AvailabilityZones.member.1=us-east-1c
&Action=CreateAutoScalingGroup
&Version=2011-01-01
&SignatureVersion=2
&SignatureMethod=HmacSHA256
&AWSAccessKeyId=<Your AWS Access Key ID>
The following is the string to sign.
GET\n
autoscaling.amazonaws.com\n
/\n
AWSAccessKeyId=<Your AWS Access Key ID>
&Action=CreateAutoScalingGroup
&AutoScalingGroupName=webtier
&AvailabilityZones.member.1=us-east-1c
&DefaultCooldown=0
&Expires=2011-02-10T12%3A00%3A00Z
&LaunchConfigurationName=wt20080929
&MinSize=0
&MaxSize=2
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Version=2011-01-01
The following is the signed request.
http://autoscaling.amazonaws.com/?AutoScalingGroupName=webtier
&LaunchConfigurationName=wt20080929
&MinSize=0
&MaxSize=2
&DefaultCooldown=0
&AvailabilityZones.member.1=us-east-1c
&Action=CreateAutoScalingGroup
&Version=2011-01-01
&SignatureVersion=2
&SignatureMethod=HmacSHA256
&AWSAccessKeyId=<Your AWS Access Key ID>
&Signature=<URLEncode(Base64Encode(Signature))>
&Expires=2011-02-10T12%3A00%3A00Z
