Auto Scaling
Developer Guide (API Version 2011-01-01)
Did this page help you?  Yes | No |  Tell us about it...
« 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.

Install the Auto Scaling CLI

Auto Scaling provides a command line interface (CLI) to access Auto Scaling functionality without using the AWS Management Console, 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 OS X. The shell scripts are available as a self-contained ZIP file.

This section describes how to set up the Auto Scaling CLI.


Note

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 toolCLIs read an environment variable (JAVA_HOME) on your computer to locate the Java runtime. The CLI requires Java version 5 or later to run. Either a JRE or JDK installation is acceptable.

To set the JAVA_HOME environment variable

  1. If you do not have Java 1.5 or later installed, download and install it now. To view and download JREs for a range of platforms, including Linux/UNIX and Windows, go to http://java.oracle.com/.

  2. Set JAVA_HOME to the full path of the directory that contains a subdirectory named bin that in turn contains the Java executable. For example, if your Java executable is in the /usr/jdk/bin directory, set JAVA_HOME to /usr/jdk. If your Java executable is in C:\jdk\bin, set JAVA_HOME to C:\jdk.

    Note

    If you are using Cygwin, you must use Linux/UNIX paths (e.g., /usr/bin instead of C:\usr\bin) for AWS_AUTO_SCALING_HOME and AWS_CREDENTIAL_FILE. However, JAVA_HOME should have a Windows path. Additionally, the value 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

    • The setx command does not use the = sign.

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

    • The value for JAVA_HOME cannot contain any spaces, even if the value is quoted or the spaces are escaped. If the value contains a space character, the CLI returns an error when you add JAVA_HOME to your path in the next step.

  3. Add your Java directory to your path before other versions of Java.

    On Linux and UNIX, you can update your PATH as follows:

    $ export PATH=$JAVA_HOME/bin:$PATH 

    On Windows, the syntax is slightly different:

    C:\> set PATH=%JAVA_HOME%\bin;%PATH% 
    C:\> setx PATH %JAVA_HOME%\bin;%PATH% 
  4. On Linux or UNIX, verify your JAVA_HOME setting with the command $JAVA_HOME/bin/java -version.

    $ $JAVA_HOME/bin/java -version
    java 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 -version
    java 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 CLI

To use the Auto Scaling CLI, you need to download it and set it up to use your AWS account.

Get the CLI

The CLI is available as a ZIP file in the Auto Scaling Command Line Tools website. These CLI 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 CLI to use your AWS credentials. These are discussed next.

Set the Environment Variable for the CLI

The CLI depends on an environment variable (AWS_AUTO_SCALING_HOME) to locate supporting libraries. You need to set this environment variable before you can use the CLI. You should set this variable to the path of the directory into which the CLI was 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, you may want to add the CLI bin directory to your system PATH to avoid having to reference this directory specifically in every command. The examples in this guide assume that you have modified your PATH as noted.

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.

Manage Access for the CLI

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 CLI to authenticate the commands that you issue from your account. The CLI 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 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 ScalingCLI uses the US East (N. Virginia) 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 (Ireland) 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 in the Regions and Endpoints topic in the AWS 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 the Auto Scaling CLI 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.