README.rdoc

Amazon Web Services Elastic Compute Cloud (EC2) Ruby Gem

About amazon-ec2

Amazon Web Services offers a compute power on demand capability known as
the Elastic Compute Cloud (EC2). The server resources in the cloud can be
provisioned on demand by making HTTP Query API calls to EC2.

This 'amazon-ec2' Ruby Gem is an interface library that can be used
to interact with the Amazon EC2 system and control server resources on
demand from your Ruby scripts, or from applications written in your Ruby
framework of choice (Ruby on Rails, Merb, etc.).

More recently, support has been added for the following EC2 related AWS
API's as well:

Autoscaling

Cloudwatch

Elastic Load Balancing (ELB)

Relational Database Service (RDS)

For the most complete and up-to date README information please visit the
project homepage at:

Installation

This gem follows the standard conventions for installation on any system
with Ruby and RubyGems installed. If you have worked with gems before this
will look very familiar.

Get an AWS account

Before you can make use of this gem you will need an Amazon Web Services
developer account which you can sign up for at aws-portal.amazon.com/gp/aws/developer/registration/index.html.
This account must also be specifically enabled for Amazon EC2 usage. AWS
will provide you with an 'AWS Access Key ID' and a 'Secret
Access Key' which will allow you to authenticate any API calls you make
and ensure correct billing to you for usage of the service. Take note of
these (and keep them secret!).

Install required gem pre-requisites

The following gems should be installed automatically as part of your
install of amazon-ec2. Most of them are needed for testing build
dependencies but they should be painless to install even if you don't
plan on running the tests or building this gem manually on your own.

Using amazon-ec2

The library exposes one main interface class AWS::EC2::Base. It is through
an instance of this class that you will perform all the operations for
using the EC2 service including query string header signing.

Setting up

The 'ec2sh' and 'ec2-gem-example.rb' scripts which will be
introduced to you shortly expect your AWS EC2 credentials to be stored as
shell environment variables which are accessible to those scripts. This
makes them convenient to use whenever you need to do a quick query to see
what images you have available to you, what's running now, or to start
or stop an instance on EC2. You'll find 'ec2sh' to be a very
handy tool. I'll describe only the OS X route for setting up (of course
the setup steps will vary depending on your particular system and preferred
shell). If you don't want to do it this way, feel free to copy these
scripts from the gem dir to any location where you can run them from and
modify them directly to include your credentials.

Edit the file ~/.bash_login and add the following to the existing contents:

(which you have already if you configured standard EC2 command line tools
to work with this region).

Once you save the file you should close and re-open your terminal so the
new variables are made available. You'll need to do this close/re-open
step for each terminal window you have open (or issue the 'source
~/.bash_login' command in each). Make sure that this file is only
readable by your user so you don't inadvertently expose your
credentials to other users on your system.

You can verify that this setup is complete by running the 'set' in
a command window and seeing that your credentials are in the list of shell
variables.

The basics

The library exposes one main interface module

AWS::EC2::Base

This method requires arguments which include your AWS credentials and it
will return an object that you can use to make method calls directly
against EC2. All the operations for using the EC2 service, including query
string header signing, are handled automatically for you. The connection
string will look something like this:

I've tried to keep the public methods on 'amazon-ec2' as close
as possible to the AWS EC2 Query API. This similarity allows you to
reference the Query API Reference in the EC2 Developer Guide and be able to
get started right away. In most cases the methods names only differ in how
they are presented. e.g. 'DescribeImages' becomes
'#describe_images()' in Ruby. Feel free to browse the full RDoc
documentation for all classes and methods of 'amazon-ec2' if you
want more details.

Examples

The best way to become familiar with 'amazon-ec2' is to take it for
a test drive. We have provided a few simple ways to get you started. There
is also some sample code below that should help out in using
'amazon-ec2' with a plain Ruby script, or as part of a Ruby on
Rails application.

Using the 'ec2-gem-example.rb' sample test script

An example Ruby script which exercises the library a bit more is installed
for you to check out when you install this gem. You can run this script to
verify that everything is setup and working correctly in your environment.
Consult the file which is installed at :

[your amazon-ec2 gem dir]/examples/ec2-example.rb

Since we also package this sample file in the gem's bin/ dir you should
also be able to run it from anywhere on your shell path (once you have set
your environment variables as described above).

Using the 'ec2sh' command shell

The 'ec2sh' command shell is actually a standard 'irb' Ruby
shell, with the main difference being we read your AWS credentials from
your environment and pre-configure a connection string for you. This lets
you run any EC2 command very simply. This has proven to be a valuable tool
during the development of this gem and you should try it out. Since we
install this tool in your system path as part of the installation of this
gem, you should be able to simply run 'ec2sh' from any terminal
command prompt on your local system. You'll see some basic instructions
for use, and a few examples when you start 'ec2sh'. Go ahead and
try it out now. We'll wait…

If you're not in front of a terminal shell now (perhaps you're
browsing this site on your iPhone) this is what you would see:

hostname:/tmp/rails/amazon_test glenn$ ec2sh
'ec2sh' usage :
This is an interactive 'irb' command shell that allows you to use all
commands available to the amazon-ec2 gem. You'll find this to be a
great tool to help you debug issues and practice running commands
against the live EC2 servers prior to putting them in your code.
The EC2 connection is wired to the class instance '@ec2'. Make method calls
on this to execute commands on EC2. Adding a #to_s
at the end of any command should give you a full String representation of the
response. The #xml data is available for each response
which allows you to view the full and complete XML response returned by
EC2 without any parsing applied. This is useful for viewing the
hierarchy of an entire response in a friendly way (if XML is friendly
to you!). Understanding the hierarchy of the XML response is critical
to making effective use of this library.
Examples to try:
returns : all ec2 public methods
>> @ec2.methods.sort
returns : a string representation of ALL images
>> @ec2.describe_images.to_s
returns : an Array of AWS::Response objects, each an EC2 image and its data
>> @ec2.describe_images.imagesSet.item
>> @ec2.describe_images.imagesSet.item[0] (a hash representing a single item in that array)
>> @ec2.describe_images.imagesSet.item[0].to_s (a String representation of that item)
>> @ec2.describe_images.imagesSet.item[0].to_s
=> "#<AWS::Response:0x100A465B4 imageId=\"ami-018e6b68\" imageLocation=\"rbuilder-online/phonehome-1.5.6-x86_10132.img.manifest.xml\" imageOwnerId=\"099034111737\" imageState=\"available\" isPublic=\"true\" parent=#<AWS::Response:0x100A469A6 ...>>"

Ruby script usage example:

Try out the following bit of code. This should walk through each image
returned by a call to #describe_images and print out its key data. Note in
the example below that you cannot walk through the results of the
#describe_images call with the '.each' iterator (You'll get
errors if you try). You need to instead walk through the Array of items
which are in the 'imagesSet' embedded in the response. This
reflects exactly the XML hierarchy of data returned from EC2 which we parse
to Ruby OpenStruct objects (AWS::Response).

Important notes regarding the structure of AWS::Response Objects

One of the key benefits of this new version of the library is that all
responses from EC2 are bundled up in a real data structure and no longer
require parsing of text. The hash returned is populated directly from the
XML given to us by EC2 in response to any command we issue. This means that
future changes to the API and what is returned by EC2 will be handled
transparently by the gem. This is a huge benefit. What this means though,
is that you may have to do a little homework on what actually gets returned
by EC2 as XML. For example, when you make a #describe_images call in
'ec2sh' what AWS returns behind the scenes looks like:

EC2 will typically return sets of things (imagesSet, reservationSet, etc.)
which we map to ruby Arrays (.imagesSet.item in the example above). If you
want to iterate over a response set you will need to iterate over this
array. The Arrays will typically contain additional AWS::Response objects
that represent each individual item. You'll find that you can use the
'ec2sh' to help you understand the structure more completely if you
try issuing commands there as a way to practice seeing what will be
returned and making sure you get exactly what you want.

Handling Exceptions

If for some reason an error occurs when executing a method (e.g. its
arguments were incorrect, or it simply failed) then an exception will be
thrown. The exceptions are defined in exceptions.rb as individual classes
and should match the exceptions that AWS has defined in the API. If the
exception raised cannot be identified then a more generic exception class
will be thrown.

The implication of this is that you need to be prepared to handle any
exceptions that may be raised by this library in YOUR code with a
'rescue' clause. It is up to you to determine how you want to
handle these exceptions in your code.