Auto Scaling
Developer Guide (API Version 2011-01-01)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

Install the Auto Scaling Command Line Interface

Auto Scaling provides a command line interface (CLI) to access Auto Scaling functionality without using the APIs, or the SDKs. The CLI wraps the API actions to provide multi-function commands. The CLI commands are written in Java and include shell scripts for both Windows and Linux/Unix/Mac OSX. The shell scripts are available as a self-contained ZIP file. This section describes how to set up your environment for use with the Auto Scaling command line interface.

You require an installation of a Java version 5 or later –compatible Java Runtime Environment (JRE). 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> command line prompt. The actual command line prompt on your computer is likely to be different. We also use $ to indicate a Linux/UNIX–specific command and C:\> for a Windows–specific command. Although we don't provide explicit instructions, the tools also work correctly on Mac OS X (which resemble the Linux and UNIX commands). The example output resulting from the command is shown immediately thereafter without any prefix.

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

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 Linux/UNIX example sets JAVA_HOME for a Java executable in the /usr/local/jre/bin directory.

$ export JAVA_HOME=/usr/local/jre

The following Windows example uses set and setx to set JAVA_HOME for a Java executable in the C:\java\jdk1.6.0_6\bin directory. The set command defines JAVA_HOME for the current session and setx makes the change permanent.

C:\> set JAVA_HOME=C:\java\jdk1.6.0_6
C:\> setx JAVA_HOME C:\java\jdk1.6.0_6

Note

Don't include the bin directory in JAVA_HOME; that's a common mistake some users make. The command line interface won't work if you do.

You can confirm the installation by running $JAVA_HOME/bin/java -version and checking the output.

$ $JAVA_HOME/bin/java -version
java version "1.6.0_33"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.6.0_33-b03)
Java HotSpot(TM) Client VM (build 1.6.0_33-b03, mixed mode, sharing)

The syntax is different on Windows, but the output is similar.

C:\> %JAVA_HOME%\bin\java -version
java version "1.6.0_33"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.6.0_33-b03)
Java HotSpot(TM) Client VM (build 1.6.0_33-b03, mixed mode, sharing)

Setting Up the Tools

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

The following Linux/UNIX example sets AWS_AUTO_SCALING_HOME for a directory named as-1.0.12.0 in the /usr/local directory.

$ export AWS_AUTO_SCALING_HOME=/usr/local/as-1.0.12.0  

The following Windows example sets AWS_AUTO_SCALING_HOME for a directory named as-1.0.12.0 in the C:\CLIs directory.

C:\> set AWS_AUTO_SCALING_HOME=C:\CLIs\as-1.0.12.0 
C:\> setx AWS_AUTO_SCALING_HOME C:\CLIs\as-1.0.12.0             

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 
C:\> setx 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 setx command.

Consult the documentation for your version of Windows for more information.

How to Tell the Tools Who You Are

After you sign up for AWS, you must create access keys for the account. Your access keys consists of an Access Key ID and a Secret Access Key. You must provide your access keys to the command line tool so that they know that the commands that you issue come from your account. The command line tool reads your access keys from a credential file that you create on your local system.

You can either specify your credential file with the --aws-credential-file parameter every time you issue a command, or you can create an environment variable that points to the credential file on your local system. If the environment variable is properly configured, you can omit the --aws-credential-file parameter when you issue a command. The following procedure describes how to create a credential file and a corresponding AWS_CREDENTIAL_FILE environment variable.

To create a credential file on your local system

  1. Retrieve your access keys

    Although you can retrieve the access key ID from the Security Credentials page, you cannot retrieve the secret access key. You'll need to create new access keys if the secret access key was lost or forgotten. You can create new access keys for the account by going to the Security Credentials page. In the Access Keys section, click Create New Root Key.

  2. Write down your secret key and access key ID, or save them.

  3. Add your access key ID and secret access key to the file named credential-file-path.template:

    1. Open the file credential-file-path.template included in your command line interface (CLI) archive.

    2. Copy and paste your access key ID and secret access key into the file.

    3. Rename the file and save it to a convenient location on your computer.

    4. If you are using Linux, set the file permissions as follows:

      $ chmod 600 credential-file-name
  4. Set the AWS_CREDENTIAL_FILE environment variable to the fully qualified path of the file you just created.

    The following Linux/UNIX example sets AWS_CREDENTIAL_FILE for myCredentialFile in the /usr/local directory.

    $ export AWS_CREDENTIAL_FILE=/usr/local/myCredentialFile  

    The following Windows example sets AWS_CREDENTIAL_FILE for myCredentialFile.txt in the C:\aws directory.

    C:\> set AWS_CREDENTIAL_FILE=C:\aws\myCredentialFile.txt 
    C:\> setx AWS_CREDENTIAL_FILE C:\aws\myCredentialFile.txt 

How to Change the Region

By default, the Auto Scaling command line interface (CLI) uses the US East Region (us-east-1) with the autoscaling.us-east-1.amazonaws.com service endpoint URL. If your instances are in a different region, you must specify the region where your instances reside. For example, if your instances are in Europe, you must specify the eu-west-1 region by using the --region eu-west-1 parameter or by setting the AWS_AUTO_SCALING_URL environment variable.

This section describes how to specify a different region by changing the service endpoint URL.

To specify a different Region

  1. View available Regions by going to Regions and Endpoints in the Amazon Web Services General Reference.

  2. If you want to change the service endpoint, set the AWS_AUTO_SCALING_URL environment variable as follows:

    Note

    Keep in mind that if you set the EC2_REGION environment variable, such as us-east-1, its value supersedes any value you set using AWS_AUTO_SCALING_URL.

    • The following Linux/UNIX example sets AWS_AUTO_SCALING_URL to the EU (Ireland) Region.

      $ export AWS_AUTO_SCALING_URL=https://autoscaling.eu-west-1.amazonaws.com  
    • The following Windows example sets AWS_AUTO_SCALING_URL to the EU (Ireland) Region.

      C:\> set AWS_AUTO_SCALING_URL=https://autoscaling.eu-west-1.amazonaws.com  
      C:\> setx AWS_AUTO_SCALING_URL https://autoscaling.eu-west-1.amazonaws.com  

Verify if Auto Scaling Command Line Interface is Installed

Before you begin using the CLI you should verify that it is properly installed.

To verify your Auto Scaling installation and configuration

  1. On your Linux or Windows workstation, open a new command prompt.

  2. Type the command as-cmd.

  3. You should see output similar to the following:

    Command Name                                Description                                            
    ------------                                -----------                                            
    as-create-auto-scaling-group                Create a new Auto Scaling group.
    as-create-launch-config                     Creates a new launch configuration.
    as-create-or-update-tags                    Create or update tags.
    as-delete-auto-scaling-group                Deletes the specified Auto Scaling group.
    as-delete-launch-config                     Deletes the specified launch configuration.
    as-delete-notification-configuration        Deletes the specified notification configuration.
    as-delete-policy                            Deletes the specified policy.
    as-delete-scheduled-action                  Deletes the specified scheduled action.
    as-delete-tags                              Delete the specified tags
    as-describe-adjustment-types                Describes all policy adjustment types.
    as-describe-auto-scaling-groups             Describes the specified Auto Scaling groups.
    as-describe-auto-scaling-instances          Describes the specified Auto Scaling instances.
    as-describe-auto-scaling-notification-types Describes all Auto Scaling notification types.
    as-describe-launch-configs                  Describes the specified launch configurations.
    as-describe-metric-collection-types         Describes all metric colle... metric granularity types.
    as-describe-notification-configurations     Describes all notification...given Auto Scaling groups.
    as-describe-policies                        Describes the specified policies.
    as-describe-process-types                   Describes all Auto Scaling process types.
    as-describe-scaling-activities              Describes a set of activities belonging to a group.
    as-describe-scheduled-actions               Describes the specified scheduled actions.
    as-describe-tags                            Describes tags
    as-describe-termination-policy-types        Describes all Auto Scaling termination policy types.
    as-disable-metrics-collection               Disables collection of Auto Scaling group metrics.
    as-enable-metrics-collection                Enables collection of Auto Scaling group metrics.
    as-execute-policy                           Executes the specified policy.
    as-put-notification-configuration           Creates or replaces notifi...or the Auto Scaling group.
    as-put-scaling-policy                       Creates or updates an Auto Scaling policy.
    as-put-scheduled-update-group-action        Creates or updates a scheduled update group action.
    as-resume-processes                         Resumes all suspended Auto... given Auto Scaling group.
    as-set-desired-capacity                     Sets the desired capacity of the Auto Scaling group.
    as-set-instance-health                      Sets the health of the instance.
    as-suspend-processes                        Suspends all Auto Scaling ... given Auto Scaling group.
    as-terminate-instance-in-auto-scaling-group Terminates a given instance.
    as-update-auto-scaling-group                Updates the specified Auto Scaling group.
    help
    version                                     Prints the version of the CLI tool and the API.
    
        For help on a specific command, type 'commandname --help'
    

This completes your installation and configuration of the Auto Scaling command line tools. You're ready to start accessing Auto Scaling using the command line interface (CLI). For descriptions of all the Auto Scaling commands, see Auto Scaling Quick Reference Card.