amazon-ec2 0.2.15 → 0.3.1

data/CHANGELOG

@@ -1,3 +1,16 @@
+=== 0.3.1 2008-09-18
+ * Added basic custom kernel id support to run_instances.  Thanks to Keith Hudgins for the patch.
+
+=== 0.3.0 2008-08-24
+ * Changed response object from AmazonEC2::Response to Hash (patch from Yan Pritzker 'skwp') Thanks!
+ * Added support for Elastic Block Storage (patch from Yann Klis 'yannski') Thanks!
+ * Bumped AWS EC2 API version to 2008-05-05
+ * Bumped gem version number
+ * Whitespace cleanup
+
+=== 0.2.15 2008-08-20
+ * Updated gem install instructions, and dependency specifications in the gemspec.
+
 === 0.2.14 2008-06-30
  * Merged patch from 'orionz' which adds support for EC2 Availability Zones.  Thanks!
 
@@ -40,10 +53,10 @@
  Now it looks like: require 'xmlsimple' unless defined? XmlSimple
 
 === 0.2.3 2007-07-06
- * Updated gem to work with new official release of AWS API version 2007-03-01 which occurred 
+ * Updated gem to work with new official release of AWS API version 2007-03-01 which occurred
  on July 6, 2007.
-  * Added support for primary new feature which supports Paid AMI's and the product codes 
-  associated with them.  Modified several methods to support this change, updated the test 
+  * Added support for primary new feature which supports Paid AMI's and the product codes
+  associated with them.  Modified several methods to support this change, updated the test
   cases, and added a new method EC2#confirm_product_instance.
 
 === 0.2.2 2007-07-03
@@ -54,47 +67,47 @@
 
 === 0.2.0 2007-07-03
 
- * MAJOR library changes : THESE CHANGES ARE NOT BACKWARD COMPATIBLE!!  You will need to update 
- the way in which you make calls, handle responses, and rescue exceptions from this library.  
- If you prefer not to make these changes you can feel free to continue to use the older version 
+ * MAJOR library changes : THESE CHANGES ARE NOT BACKWARD COMPATIBLE!!  You will need to update
+ the way in which you make calls, handle responses, and rescue exceptions from this library.
+ If you prefer not to make these changes you can feel free to continue to use the older version
  of the gem.  These older versions however will no longer be maintained.
- 
+
  * MAJOR refactoring of how methods calls are made.  Now all methods are called with a simple hash
  of arguments and none of them are positional.  This feels much more "Ruby'ish".
- 
- * MAJOR refactoring of how responses are returned to users.  No longer do you have to call the 
- .parse method, and no longer are you getting back simple arrays of information.  Responses 
- now come in the form of OpenStruct objects that contain all of the data for an object in 
+
+ * MAJOR refactoring of how responses are returned to users.  No longer do you have to call the
+ .parse method, and no longer are you getting back simple arrays of information.  Responses
+ now come in the form of OpenStruct objects that contain all of the data for an object in
  Enumerable form so you can use iterators (.each, .each_pair, etc).  All methods return an EC2::Response object
  which inherits from OpenStruct.  The return data from EC2, which is in XML form, is parsed
  with XmlSimple and is used to directly construct the return data structure.  This allows us
  to know with some confidence that the data structure returned from AWS will always be consistent
- with this library's responses.  There is also an .xml attribute for each response object that lets you 
+ with this library's responses.  There is also an .xml attribute for each response object that lets you
  see the full and complete XML response from AWS if that is useful to you.
- 
+
  * Added an exception framework which will now throw appropriate Ruby exceptions
  that match those handed to us by Amazon EC2.  ArgumentError exceptions will also
- be thrown if you are making calls we know to be illegal or malformed.  You should rescue 
- these exceptions in your application instead of parsing text responses.  All exceptions 
+ be thrown if you are making calls we know to be illegal or malformed.  You should rescue
+ these exceptions in your application instead of parsing text responses.  All exceptions
  descend from EC2::Error.  You can see them all in exceptions.rb in the gem install.
- 
+
  * Added a full suite of test/spec unit tests which currently cover 100% of the public methods
- in this library.  We have abot 92% code coverage according to rcov.  This has greatly enhanced 
- the reliability of the library as well as our confidence in the code.  
- We used to have 0% test coverage. :-/ 
- 
+ in this library.  We have abot 92% code coverage according to rcov.  This has greatly enhanced
+ the reliability of the library as well as our confidence in the code.
+ We used to have 0% test coverage. :-/
+
  * Added an EC2 command shell : 'ec2sh' which can be called from anywhere and gives you
- an interactive irb session with an EC2 connection pre-made for you as @ec2.  You can use this 
- to interactively execute any command on EC2 that this library supports.  Try @ec2.methods.sort 
+ an interactive irb session with an EC2 connection pre-made for you as @ec2.  You can use this
+ to interactively execute any command on EC2 that this library supports.  Try @ec2.methods.sort
  or @ec2.describe_images to test it out.  You must first setup two shell environment variables
  which contain your ACCESS_KEY_ID and SECRET_ACCESS_KEY for this to work.  Otherwise an error
- will be thrown when you try to start it.  This is way cool and shamelessly borrowed from 
+ will be thrown when you try to start it.  This is way cool and shamelessly borrowed from
  Marcel Molina's fine AWS::S3 library.
- 
+
  * Updated API version in the query API request to 2007-01-19, and added all known method calls
- in this version of the API to the gem (including reboot, viewing console output, NAT addressing 
+ in this version of the API to the gem (including reboot, viewing console output, NAT addressing
  and more!)
- 
+
  * Removed .parse method as it is no longer needed or wanted.
 
  * Removed 'verbose' attribute writer and a couple of related debug 'puts' calls in EC2.rb.
@@ -116,43 +129,43 @@
    * New Mocha based tests (Mocha test suite must be installed to run tests.  'sudo gem install mocha')
    * Cleanup of the test directory.
  * Applied patch from Randy Bias related to CGI escaping error.  From his notes:
- 
- I finally figured out what was going on.  It was a compound problem.  The first being that you can't 
- CGI::encode the UserData early.    You have to just Base64 encode it.  Unfortunately, when you Base64 
- encode it, it means that some encodings will be padded with extra chars, specifically the '=', but &, ? 
- and = get stripped by EC2.canonial_string.  So if a Base64 encoding has trailing ='s for padding, 
- these get stripped and then you sign the UserData Base64 payload sans the padding.  But it looks 
+
+ I finally figured out what was going on.  It was a compound problem.  The first being that you can't
+ CGI::encode the UserData early.    You have to just Base64 encode it.  Unfortunately, when you Base64
+ encode it, it means that some encodings will be padded with extra chars, specifically the '=', but &, ?
+ and = get stripped by EC2.canonial_string.  So if a Base64 encoding has trailing ='s for padding,
+ these get stripped and then you sign the UserData Base64 payload sans the padding.  But it looks
  like Amazon's side is doing the right thing and is signing the padding.  So, the signatures mis-match.
- 
- I've got the complete patch here and it's about as elegant/clean as I could make it in a short 
- period of time.  It's a little tough to strip those equal signs when there are so many in the URI.  
- I think this works pretty well, though.  I'm splitting the URI on '&', then for each field ripping 
+
+ I've got the complete patch here and it's about as elegant/clean as I could make it in a short
+ period of time.  It's a little tough to strip those equal signs when there are so many in the URI.
+ I think this works pretty well, though.  I'm splitting the URI on '&', then for each field ripping
  out all '&' and '?' and only the first '='.  Then stitching it back together.
 
 
 === 0.0.6 2007-03-02
  * Patched instances.rb with a bugfix and patch provided by Randy Bias (Thanks Randy!).
  Only minimally tested so please let me know if this causes any problems for anyone.
- 
+
  From his notes:
- I wanted to let you know that there appears to be a bug in how user data is passed.  In  
+ I wanted to let you know that there appears to be a bug in how user data is passed.  In
  instances.rb the line that creates the base64 encoded package of user data is as follows:
- 
+
  userData = CGI::escape(Base64.encode64(in_params[:userData]).strip())
- 
- This may have worked prior, but at least right now the CGI::escape appears to cause a 
+
+ This may have worked prior, but at least right now the CGI::escape appears to cause a
  breakage.  More specifically it turns something like this (the actual base64 encoded string):
 
  YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh
  eHh4eHh4eHh4eHh4eHh4eHh4eHgg
- 
+
  Into this:
- 
- YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh% 
+
+ YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh%
  0AeHh4eHh4eHh4eHh4eHh4eHh4eHgg
- 
- And it looks like EC2 chokes on the %0, which is CGI::escape's way for handling an EOL.  
- Unfortunately, the Base64.encode64 (at least in my 1.8.5 version of Ruby) inserts a 
+
+ And it looks like EC2 chokes on the %0, which is CGI::escape's way for handling an EOL.
+ Unfortunately, the Base64.encode64 (at least in my 1.8.5 version of Ruby) inserts a
  EOL at every 47 chars, no matter what:
 
  ---
@@ -162,9 +175,9 @@
  require 'rubygems'
  require_gem 'amazon-ec2'
  require 'getoptlong'
- puts Base64.encode64 
+ puts Base64.encode64
  ("012345678901234567890123456789012345678901234567890123456789")
- 
+
  [randyb@master randyb] /tmp/foo.rb
  MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0
  NTY3ODkwMTIzNDU2Nzg5
@@ -175,28 +188,28 @@
 
 === 0.0.5 2006-12-21
 
- * Changes to home page documentation and example files to indicate that you 
-   should use 'require_gem' instead of a simple require.  Not sure if this 
-   is a result of something I am doing in the packaging of the gem that is 
+ * Changes to home page documentation and example files to indicate that you
+   should use 'require_gem' instead of a simple require.  Not sure if this
+   is a result of something I am doing in the packaging of the gem that is
    incorrect or if this is right and proper.  I will investigate further.
- * Patched instances.rb run_instances method to allow for submission of 
-   user data with the command to start an instance.  Patch submitted 
+ * Patched instances.rb run_instances method to allow for submission of
+   user data with the command to start an instance.  Patch submitted
    anonymously on RubyForge.  This had not been functionally implemented
    in the Amazon Web Services sample library prior to this patch.
- * Added simple framework for adding unit tests for the library under test dir.  
+ * Added simple framework for adding unit tests for the library under test dir.
    No functional unit tests exist yet.
 
 
 === 0.0.4 2006-12-21
 
- * Applied patch from Kevin Clark to svn version 7.  Thanks for the 
-   patch and the description Kevin!  Please report if you 
-   encounter any issues with this patched version.  Here is Kevin's 
-   description which I requested :  "It helps me to think of modules as boxes full of classes and 
+ * Applied patch from Kevin Clark to svn version 7.  Thanks for the
+   patch and the description Kevin!  Please report if you
+   encounter any issues with this patched version.  Here is Kevin's
+   description which I requested :  "It helps me to think of modules as boxes full of classes and
    methods.  REXML is a module which holds various classes related to parsing XML
    including REXML::Node, REXML::Document and REXML::XPath. When you
    include a module it takes everything out of the box and places it in
-   the local context.  So, when you include REXML in the global namespace 
+   the local context.  So, when you include REXML in the global namespace
    on line 27 of EC2.rb, it includes classes called Node, Document and XPath in the
    global object space. This means that I can't have a class called Node
    in my own project (which I do). The library would be a much better
@@ -206,23 +219,23 @@
 
 === 0.0.3 2006-12-16
 
- * API CHANGE : Changed method name 'authorize' to 'authorize_security_group_ingress' to ensure consistent 
+ * API CHANGE : Changed method name 'authorize' to 'authorize_security_group_ingress' to ensure consistent
    naming of Ruby library methods to match AWS EC2 API actions. Alias to 'authorize' for backwards compatibility.
- * API CHANGE : Changed method name 'revoke' to 'revoke_security_group_ingress' to ensure consistent 
- 	naming of Ruby library methods to match AWS EC2 API actions. Alias to 'revoke' for backwards compatibility.
- * API CHANGE : Changed method name 'delete_securitygroup' to 'delete_security_group' to ensure consistent 
- 	naming of Ruby library methods to match AWS EC2 API actions. Alias to 'delete_securitygroup' for backwards compatibility.
- * API CHANGE : Changed method name 'describe_securitygroups' to 'describe_security_group' to ensure consistent 
- 	naming of Ruby library methods to match AWS EC2 API actions. Alias to 'describe_securitygroups' for backwards compatibility.
- * API CHANGE : Changed method name 'create_securitygroup' to 'create_security_group' to ensure consistent 
- 	naming of Ruby library methods to match AWS EC2 API actions. Alias to 'create_securitygroup' for backwards compatibility.
+ * API CHANGE : Changed method name 'revoke' to 'revoke_security_group_ingress' to ensure consistent
+  naming of Ruby library methods to match AWS EC2 API actions. Alias to 'revoke' for backwards compatibility.
+ * API CHANGE : Changed method name 'delete_securitygroup' to 'delete_security_group' to ensure consistent
+  naming of Ruby library methods to match AWS EC2 API actions. Alias to 'delete_securitygroup' for backwards compatibility.
+ * API CHANGE : Changed method name 'describe_securitygroups' to 'describe_security_group' to ensure consistent
+  naming of Ruby library methods to match AWS EC2 API actions. Alias to 'describe_securitygroups' for backwards compatibility.
+ * API CHANGE : Changed method name 'create_securitygroup' to 'create_security_group' to ensure consistent
+  naming of Ruby library methods to match AWS EC2 API actions. Alias to 'create_securitygroup' for backwards compatibility.
  * Added many API rdoc's, some method descriptions copied from Amazon Query API Developer Guide.
  * Extracted some parts of the formerly monolithic EC2 library out into separate files for manageability.
  * Changed the HTTP 'User-Agent' string used for each request so that we have our own user agent
    to identify this library's calls.  Now set the version # in the user agent string based on the
    master version number for this library which is stored in lib/EC2/version.rb and should only
    be defined in one place.
- * Set @http.verify_mode = OpenSSL::SSL::VERIFY_NONE to avoid seeing SSL Cert warning 
+ * Set @http.verify_mode = OpenSSL::SSL::VERIFY_NONE to avoid seeing SSL Cert warning
    "warning: peer certificate won't be verified in this SSL session". File EC2.rb:96
  * Make 'pathlist' utility method a private method (EC2.rb:111).  No reason I can see for this to be exposed.
 
@@ -234,7 +247,7 @@
 
 === 0.0.1 2006-12-13
 
- * Initial release of the Ruby Gem.  This includes the version of the library exactly as provided by 
-   Amazon Web Services as example code.  No changes or enhancements to that code were made other than 
+ * Initial release of the Ruby Gem.  This includes the version of the library exactly as provided by
+   Amazon Web Services as example code.  No changes or enhancements to that code were made other than
    packaging it as a Ruby Gem.
- * RubyForge project created.  http://amazon-ec2.rubyforge.org
+ * RubyForge project created.  http://github.com/grempe/amazon-ec2/tree/master

data/README.rdoc

@@ -32,20 +32,29 @@ The following gems should be installed automatically as part of your install of
 
 === Install the amazon-ec2 gem
 
+  # ONE TIME ONLY
+  # It is highly recommended that you are running RubyGems version >= 1.2.0
+  # See : http://blog.segment7.net/articles/2008/06/21/rubygems-1-2-0
+  sudo gem update --system
+
   # ONE TIME ONLY
   # Execute this on each machine where you install gems to add GitHub as a gem source
   # Do this only once or you'll end up with multiple entries in 'gem sources'
   gem sources -a http://gems.github.com/
 
-  # ONE TIME ONLY
-  # Only if you had a previous version of the gem installed from RubyForge before we moved to GitHub
-  # Say 'Y' to remove all previous versions and all binaries when prompted.  It won't hurt to do
-  # this in any case.
-  sudo gem uninstall amazon-ec2
+  # Install the stable release gem from RubyForge
+  sudo gem install amazon-ec2
+
+  # OR
 
-  # Finally install the gem
+  # Install the gem from the GitHub bleeding edge as a normal runtime install
   sudo gem install grempe-amazon-ec2
 
+  # OR
+
+  # Install the gem from the GitHub bleeding edge with all developer dependencies
+  sudo gem install grempe-amazon-ec2 --development
+
 == Using amazon-ec2
 
 The library exposes one main interface class 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.
@@ -147,15 +156,15 @@ If you're not in front of a terminal shell now (perhaps you’re browsing this s
 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 (EC2::Response).
 
   #!/usr/bin/env ruby
-  
+
   require 'rubygems'
   require 'ec2'
-  
+
   ACCESS_KEY_ID = '--YOUR AWS ACCESS KEY ID--'
   SECRET_ACCESS_KEY = '--YOUR AWS SECRET ACCESS KEY--'
-  
+
   ec2 = EC2::Base.new(:access_key_id => ACCESS_KEY_ID, :secret_access_key => SECRET_ACCESS_KEY)
-  
+
   puts "----- listing images owned by 'amazon' -----"
   ec2.describe_images(:owner_id => "amazon").imagesSet.item.each do |image|
     # OpenStruct objects have members!
@@ -235,7 +244,7 @@ One of the key benefits of this new version of the library is that all responses
 
   $ ec2sh
   >> puts @ec2.describe_images(:owner_id => 'amazon').xml
-  
+
   <?xml version="1.0"?>
   <DescribeImagesResponse xmlns="http://ec2.amazonaws.com/doc/2007-01-19/">
       <imagesSet>
@@ -303,19 +312,13 @@ EC2 will typically return sets of things (imagesSet, reservationSet, etc.) which
 * Report Bugs / Request Features : http://grempe.lighthouseapp.com/projects/10644-amazon-ec2/overview
 * Amazon Web Services : http://aws.amazon.com
 
-=== Related Projects
-
-Jesse Newland and I created the Capsize project which can help when using Capistrano and EC2 together.  You can check out the latest code at:
-
-  http://github.com/jnewland/capsize/tree/master
-
 == Credits
 
 The original code for this library was provided by Amazon Web Services, LLC as sample code.  Thanks to them for providing all of us with something to get us started.
 
 == Contact
 
-Comments, patches, Git pull requests and bug reports are welcome. Send an email to mailto:glenn.rempe@nospam@gmail.com or use the Google Groups forum for this project.
+Comments, patches, Git pull requests and bug reports are welcome. Send an email to mailto:glenn@nospam@rempe.us or use the Google Groups forum for this project.
 
 Enjoy!
 

data/Rakefile

@@ -27,4 +27,3 @@ Rake::RDocTask.new do |rd|
   rd.rdoc_dir = 'doc'
   rd.options = spec.rdoc_options
 end
-

data/bin/ec2-gem-example.rb

@@ -3,20 +3,21 @@
 # Amazon Web Services EC2 Query API Ruby library
 #
 # Ruby Gem Name::  amazon-ec2
-# Author::    Glenn Rempe  (mailto:grempe@rubyforge.org)
+# Author::    Glenn Rempe  (mailto:glenn@rempe.us)
 # Copyright:: Copyright (c) 2007-2008 Glenn Rempe
 # License::   Distributes under the same terms as Ruby
-# Home::      http://amazon-ec2.rubyforge.org
+# Home::      http://github.com/grempe/amazon-ec2/tree/master
 #++
 
 require 'rubygems'
 require File.dirname(__FILE__) + '/../lib/EC2'
+require 'pp'
 
 # pull these from the local shell environment variables set in ~/.bash_login
 # or using appropriate methods specific to your login shell.
-# 
+#
 # e.g. in ~/.bash_login
-# 
+#
 #  # For amazon-ec2 and amazon s3 ruby gems
 #  export AMAZON_ACCESS_KEY_ID="FOO"
 #  export AMAZON_SECRET_ACCESS_KEY="BAR"
@@ -36,23 +37,22 @@ p ec2.methods.sort
 
 puts "----- listing images owned by 'amazon' -----"
 ec2.describe_images(:owner_id => "amazon").imagesSet.item.each do |image|
-  image.members.each do |member|
-    puts "#{member} => #{image[member]}" 
+  image.keys.each do |key|
+    puts "#{key} => #{image[key]}"
   end
 end
 
 puts "----- listing all running instances -----"
-puts ec2.describe_instances()
+pp ec2.describe_instances()
 
 puts "----- creating a security group -----"
-puts ec2.create_security_group(:group_name => "ec2-example-rb-test-group", :group_description => "ec-example.rb test group description.")
+pp ec2.create_security_group(:group_name => "ec2-example-rb-test-group", :group_description => "ec-example.rb test group description.")
 
 puts "----- listing security groups -----"
-puts ec2.describe_security_groups()
+pp ec2.describe_security_groups()
 
 puts "----- deleting a security group -----"
-puts ec2.delete_security_group(:group_name => "ec2-example-rb-test-group")
+pp ec2.delete_security_group(:group_name => "ec2-example-rb-test-group")
 
 puts "----- listing my keypairs (verbose mode) -----"
-puts ec2.describe_keypairs()
-
+pp ec2.describe_keypairs()

data/bin/ec2sh

@@ -3,10 +3,10 @@
 # Amazon Web Services EC2 Query API Ruby library
 #
 # Ruby Gem Name::  amazon-ec2
-# Author::    Glenn Rempe  (mailto:grempe@rubyforge.org)
+# Author::    Glenn Rempe  (mailto:glenn@rempe.us)
 # Copyright:: Copyright (c) 2007-2008 Glenn Rempe
 # License::   Distributes under the same terms as Ruby
-# Home::      http://amazon-ec2.rubyforge.org
+# Home::      http://github.com/grempe/amazon-ec2/tree/master
 #++
 
 # CREDITS : Credit for this bit of shameful ripoff coolness 

data/bin/setup.rb

@@ -3,17 +3,17 @@
 # Amazon Web Services EC2 Query API Ruby library
 #
 # Ruby Gem Name::  amazon-ec2
-# Author::    Glenn Rempe  (mailto:grempe@rubyforge.org)
+# Author::    Glenn Rempe  (mailto:glenn@rempe.us)
 # Copyright:: Copyright (c) 2007-2008 Glenn Rempe
 # License::   Distributes under the same terms as Ruby
-# Home::      http://amazon-ec2.rubyforge.org
+# Home::      http://github.com/grempe/amazon-ec2/tree/master
 #++
 
 if ENV['AMAZON_ACCESS_KEY_ID'] && ENV['AMAZON_SECRET_ACCESS_KEY']
-  @ec2 = EC2::Base.new( 
+  @ec2 = EC2::Base.new(
     :access_key_id => ENV['AMAZON_ACCESS_KEY_ID'],
-    :secret_access_key => ENV['AMAZON_SECRET_ACCESS_KEY'] 
+    :secret_access_key => ENV['AMAZON_SECRET_ACCESS_KEY']
   )
 end
 
-include EC2 
+include EC2

data/lib/EC2.rb

@@ -2,10 +2,10 @@
 # Amazon Web Services EC2 Query API Ruby library
 #
 # Ruby Gem Name::  amazon-ec2
-# Author::    Glenn Rempe  (mailto:grempe@rubyforge.org)
+# Author::    Glenn Rempe  (mailto:glenn@rempe.us)
 # Copyright:: Copyright (c) 2007-2008 Glenn Rempe
 # License::   Distributes under the same terms as Ruby
-# Home::      http://amazon-ec2.rubyforge.org
+# Home::      http://github.com/grempe/amazon-ec2/tree/master
 #++
 
 %w[ base64 cgi openssl digest/sha1 net/https rexml/document time ostruct ].each { |f| require f }
@@ -22,7 +22,7 @@ module EC2
   DEFAULT_HOST = 'ec2.amazonaws.com'
 
   # This is the version of the API as defined by Amazon Web Services
-  API_VERSION = '2008-02-01'
+  API_VERSION = '2008-05-05'
 
   # Builds the canonical string for signing. This strips out all '&', '?', and '='
   # from the query string to be signed.