22 12 / 2012

Exploring aws-cli

Yesterday Mitch Garnaat, a Senior Engineer at Amazon, announced the developer candidate release of a new AWS cli tool, awscli.

The tool is open source, available under the Apache 2.0 license, written in Python, and the code is up on Github.

The goal of this new cli tool is to provide a unified command line interface to Amazon Web Services.

It currently supports the following AWS services:

  • Amazon Elastic Compute Cloud (Amazon EC2)
  • Elastic Load Balancing
  • Auto Scaling
  • AWS CloudFormation
  • AWS Elastic Beanstalk
  • Amazon Simple Notification Service (Amazon SNS)
  • Amazon Simple Queue Service (Amazon SQS)
  • Amazon Relational Database Service (Amazon RDS)
  • AWS Identity and Access Management (IAM)
  • AWS Security Token Service (STS)
  • Amazon CloudWatch
  • Amazon Simple Email Service (Amazon SES)

This tool is still new, but it looks very promising. Let’s explore some of the ways we can use it.

Getting Started

To get started with awscli you’ll install it, create a configuration file, and optionally add some bash shell completions.

Installation

awscli can be quickly installed with either easy_install or pip

Once it is installed it you should have a aws tool available to use. You can confirm this with the command shown below:

$ which aws
/usr/local/bin/aws

If you run it without any arguments if should look like this:

$ aws
usage: aws [--output output_format] [--region region_name]
[--debug] [--profile profile_name] 
[--endpoint-url endpoint_url] [--version]
service_name

aws: error: too few arguments

Configuration

You’ll need to make a configuration file for it. I am assuming you’ve already created and know your AWS access keys.

I created my configuration file as ~/.aws, and when you create yours, it should look like

[default]
aws_access_key_id=
aws_secret_access_key=
region=us-west-1  # optional, to define default region for this profile

You’ll want to set the region to the region you have AWS resources running in.

Once you’ve created it, you’ll set an environement variable to tell the aws tool where to find your configuration, you can do this with the following command

export AWS_CONFIG_FILE=/path/to/config_file

bash Completions

If you’re a bash shell user, you can install some handy tab completions with the following command

complete -C aws_completer aws

zsh shell users should look at https://github.com/aws/aws-cli/issues/5 for how to try to get completion working.

While I am a zsh user, I am still on 4.3.11 so I used bash for the purposes of testing out the awscli.

Let’s test it out, the following command should return a bunch of JSON output describing any instances in the region you’ve put in your configuration file. You can also tell aws to return text output by using the –output text argument at the end of your command.

aws ec2 describe-instances

Since all the sample output is very instance specific, I don’t have a good example of the output to share, but if the command works, you’ll know you got the right output. ;)

Now that we have the aws tool installed and we know it’s working, let’s take a look at some of the ways we can use it for fun and profit.

Managing EC2

The primary way a lot of you may use the aws tool is to manage EC2 instances.

To do that with the aws command, you use the ec2 service name.

With the tab completion installed, you can quickly see that aws ec2 <tab><tab> has 144 possible functions to run.

To view your EC2 resources you use the describe- commands, such as describe-instances which lists all your instances, describe-snapshots which lists all your EBS snapshots, or describe-instance-status which you give the argument –instance-id to see a specific instance.

To create new resources you use the create- commands, such as create-snapshot to create a new snapshot of an EBS volume or create-vpc to create a new VPC.

To launch a new EC2 instance you use the run-instances command, which you give a number of arguments including –instance-type, –key-name (your ssh keypair), or –user-data. aws ec2 run-instances --<tab><tab> is a quick way to review the available options.

There are a number of other kinds of commands available, including attach-, delete-, and modify. You can use the bash completion or the documentation to learn and explore all the available commands and each command’s arguments.

Managing S3

Unfortunately the aws tool does not support S3 yet, but boto has great S3 support, s3cmd is popular, or you can use the AWS S3 Console.

Managing CloudFormation

The aws tool supports managing CloudFormation.

You can see your existing stacks with list-stacks or see an a specific stack’s resources with list-stacks-resources and the –stack-name argument.

You can create or delete a stack with the aptly named create-stack and delete-stack commands.

You can even use the handy estimate-template-cost command to get a template sent through the AWS calculator and you’ll get back a URL with all your potential resources filled out.

Managing ELB

The aws tool supports managing Elastic Load Balancer (ELB).

You can see your existing load balancers with the describe-load-balancers command. You can create a new load balancer with the create-load-balancer, which takes a number of arguments, including –availability-zones, –listeners, –subnets or –security-groups. You can delete an existing load balancer with the delete-load-balancer command.

You can add or remove listeners to an existing load balancer with the create-load-balancer-listeners and delete-load-balancer-listeners.

Managing CloudWatch

The aws tool supports managing CloudWatch.

You can review your existing metrics with the list-metrics command and your existing alarms with the describe-alarms command. You can look at the alarms for a specific metric by using describe-alarms-for-metric and the –metric-name argument.

You can enable and disable alarm actions with the enable-alarm-actions and disable-alarm-actions commands.

Where to go from here?

You should make sure you’ve read the README.

To get more familiar with the commands and arguments, you should use both the bash completions and the built-in help.

To see the help for a specific command you invoke it like shown below:

aws $service help

An example is

$ aws ses help

NAME
    email

DESCRIPTION Amazon Simple Email Service
    This is the API Reference for Amazon Simple Email Service (Amazon SES). This
    documentation is intended to be used in conjunction with the Amazon SES Getting
    Started Guide and the Amazon SES Developer Guide.

    For specific details on how to construct a service request, please consult the
    Amazon SES Developer Guide. The endpoint for Amazon SES is located at:
    https://email.us-east-1.amazonaws.com

    delete-identity
        Deletes the specified identity (email address or domain) from the list of
        verified identities.

    delete-verified-email-address
        Deletes the specified email address from the list of verified addresses.
        The DeleteVerifiedEmailAddress action is deprecated as of the May 15, 2012
        release of Domain Verification. The DeleteIdentity action is now preferred.
--snip--

You’ll get some details on each of the available commands for a given service.

From there, if you encounter issues or had ideas for feedback you should file an issue on Github.

While not an official channel, I idle in ##aws on irc.freenode.net and am happy to answer questions/provide help when I have time.