grempe-amazon-ec2 0.2.9

data/History.txt

@@ -0,0 +1,230 @@
+=== 0.2.10 2008-04-13
+ * Fix bug where ec2#disassociate_address would return 'undefined method 'reject!' for "xxx.xxx.xxx.xxx":String'.
+   Thanks to Brian Thomas for reporting.
+
+=== 0.2.9 2008-03-31
+ * Added initial support for API version 2008-02-01.  Support for new 'Elastic IP' functionality added.
+
+=== 0.2.8 2008-02-25
+ * Change HTTP API requests to use POST instead of GET.  Based on patch #18380 from 'anonymous'.
+
+=== 0.2.7 2008-02-17
+ * Add support for HTTP Proxy when :proxy_server argument is passed.  Based on patch from Mathias Dalheimer.
+
+=== 0.2.6 2007-10-16
+ * Updated to support EC2 API version 2007-08-29 released on 2007-10-16
+ * Supports new instances type feature.  Specify an instance type to launch
+   (m1.small, m1.large, m1.xlarge) when you call the 'run_instances' method.
+
+   e.g. add to the params hash ':instance_type => "m1.small"'
+  * RunInstances and DescribeInstances now return the time when the Amazon EC2 instance was launched.
+  * Code Tidyup : Removed trailing spaces in code docs.
+
+=== 0.2.5 2007-09-26
+ * Updated using Dr. Nic's newgem v. 0.13.5
+ * Updated email address.
+ * No functional changes in the gem.
+
+=== 0.2.4 2007-07-09
+ * Changed how require statement for xmlsimple is called so we don't get warnings when running in rails.
+ 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 
+ 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 
+  cases, and added a new method EC2#confirm_product_instance.
+
+=== 0.2.2 2007-07-03
+ * Minor change to test case.
+
+=== 0.2.1 2007-07-03
+ * Some minor changes to the RDocs and README.txt
+
+=== 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 
+ 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 
+ 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 
+ 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 
+ 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. :-/ 
+ 
+ * 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 
+ 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 
+ 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 
+ 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.
+
+ * Removed deprecated alias's used in the library that were added in v0.0.3
+
+ * Gem now requires XmlSimple gem to be installed.
+
+
+=== 0.1.0 2007-05-30
+
+ * Repackaged with updated newgem generator v. 0.10.3 from http://newgem.rubyforge.org/ to take advantage of new deployment goodness.
+
+
+=== 0.0.7 2007-03-15
+
+ * Applied patch from Kevin Clark which does the following:
+   * New method to the instances.rb to allow for issuing a reboot command to an EC2 instance.
+   * 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 
+ 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 
+ 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  
+ 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 
+ breakage.  More specifically it turns something like this (the actual base64 encoded string):
+
+ YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh
+ eHh4eHh4eHh4eHh4eHh4eHh4eHgg
+ 
+ Into this:
+ 
+ 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 
+ EOL at every 47 chars, no matter what:
+
+ ---
+ [randyb@master randyb] cat /tmp/foo.rb
+ #!/usr/bin/env ruby
+ #
+ require 'rubygems'
+ require_gem 'amazon-ec2'
+ require 'getoptlong'
+ puts Base64.encode64 
+ ("012345678901234567890123456789012345678901234567890123456789")
+ 
+ [randyb@master randyb] /tmp/foo.rb
+ MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0
+ NTY3ODkwMTIzNDU2Nzg5
+ ---
+
+ The best way to handle this is to strip the CRLFs/EOLs before passing to CGI.escape.
+
+
+=== 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 
+   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 
+   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.  
+   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 
+   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 
+   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
+   neighbor if it instead accessed the REXML::Document and REXML::XPath
+   classes explicitly through the module."
+
+
+=== 0.0.3 2006-12-16
+
+ * 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.
+ * 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 
+   "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.
+
+
+=== 0.0.2 2006-12-14
+
+ * Bugfix in run_instances method.  Method works now.  Patch submitted by Stephen Caudill on AWS forums.  Thanks!
+
+
+=== 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 
+   packaging it as a Ruby Gem.
+ * RubyForge project created.  http://amazon-ec2.rubyforge.org

data/License.txt

@@ -0,0 +1,66 @@
+Copyright (c) 2007-2008 Glenn Rempe
+
+This software is distributed under the Ruby License.  A copy of which is
+provided below.
+
+RUBY LICENSE
+
+http://www.ruby-lang.org/en/LICENSE.txt
+
+Ruby is copyrighted free software by Yukihiro Matsumoto <matz@netlab.co.jp>.
+You can redistribute it and/or modify it under either the terms of the GPL
+(see COPYING.txt file), or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+          modifications to Usenet or an equivalent medium, or by allowing
+          the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) rename any non-standard executables so the names do not conflict
+          with standard executables, which must also be provided.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or executable
+     form, provided that you do at least ONE of the following:
+
+       a) distribute the executables and library files of the software,
+          together with instructions (in the manual page or equivalent)
+          on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+          the software.
+
+       c) give non-standard executables non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  But some files in the distribution
+     are not written by the author, so that they are not under this terms.
+
+     They are gc.c(partly), utils.c(partly), regex.[ch], st.[ch] and some
+     files under the ./missing directory.  See each file for the copying
+     condition.
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.

data/Manifest.txt

@@ -0,0 +1,46 @@
+History.txt
+License.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/ec2-gem-example.rb
+bin/ec2sh
+bin/setup.rb
+config/hoe.rb
+config/requirements.rb
+lib/EC2.rb
+lib/EC2/console.rb
+lib/EC2/elastic_ips.rb
+lib/EC2/exceptions.rb
+lib/EC2/image_attributes.rb
+lib/EC2/images.rb
+lib/EC2/instances.rb
+lib/EC2/keypairs.rb
+lib/EC2/products.rb
+lib/EC2/responses.rb
+lib/EC2/security_groups.rb
+lib/EC2/version.rb
+script/destroy
+script/generate
+script/txt2html
+setup.rb
+tasks/deployment.rake
+tasks/environment.rake
+tasks/website.rake
+test/test_EC2.rb
+test/test_EC2_console.rb
+test/test_EC2_elastic_ips.rb
+test/test_EC2_image_attributes.rb
+test/test_EC2_images.rb
+test/test_EC2_instances.rb
+test/test_EC2_keypairs.rb
+test/test_EC2_products.rb
+test/test_EC2_responses.rb
+test/test_EC2_security_groups.rb
+test/test_EC2_version.rb
+test/test_helper.rb
+website/index.html
+website/index.txt
+website/javascripts/rounded_corners_lite.inc.js
+website/stylesheets/screen.css
+website/template.rhtml

data/README.txt

@@ -0,0 +1,154 @@
+= 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).  Using the current API's the compute resources in the cloud can be provisioned on demand by making SOAP or 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 using the Query API (No SOAP please...).
+
+For the most complete and up-to date README information please visit the project homepage at: http://amazon-ec2.rubyforge.org or the EC2 website at http://aws.amazon.com/ec2
+
+
+== 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.
+
+=== Installation pre-requisites
+
+Before you can make use of this gem you will need an Amazon Web Services developer account which you can sign up for at https://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!).
+
+=== Installing the gem (Mac OS X / Linux)
+
+  sudo gem install amazon-ec2
+
+=== Installing the gem (Windows)
+
+  gem install amazon-ec2
+
+
+== Usage Examples
+
+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.
+
+The public methods on EC2::Base closely mirror the EC2 Query API, and as such the Query API Reference in the EC2 Developer Guide ( http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=84 ) will prove helpful.
+
+=== 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 (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!
+	  image.members.each do |member|
+	    puts "#{member} => #{image[member]}" 
+	  end
+	end
+
+=== Ruby on Rails usage example:
+
+<b>config/environment.rb</b>
+
+	# Require the amazon-ec2 gem and make its methods available in your Rails app
+	# Put this at the bottom of your environment.rb
+	require 'EC2'
+
+<b>app/controllers/my_controller.rb</b>
+
+	[some controller code ...]
+	
+	ec2 = EC2::Base.new(:access_key_id => "YOUR_AWS_ACCESS_KEY_ID", :secret_access_key => "YOUR_AWS_SECRET_ACCESS_KEY")
+	
+	# get ALL public images
+	@ec2_images = ec2.describe_images().imagesSet.item
+	
+	# Get info on all public EC2 images created by the Amazon EC2 team.
+	@ec2_images_amazon = ec2.describe_images(:owner_id => "amazon").imagesSet.item
+	
+	[some more controller code ...]
+
+	
+<b>app/views/my/index.rhtml</b>
+
+	<h1>EC2 Test#index</h1>
+	
+	<h1>Sample 1 - debug() view</h1>
+	
+	<%= debug(@ec2_images_amazon) %>
+	
+	<h1>Sample 2 - Build a table</h1>
+	
+	<table border='1'>
+	  <tr>
+	    <th>image.imageId</th>
+	    <th>image.imageLocation</th>
+	    <th>image.imageOwnerId</th>
+	    <th>image.imageState</th>
+	    <th>image.isPublic</th>
+	  </tr>
+	
+	  <% for image in @ec2_images_amazon %>
+	    <tr>
+	      <td><%=h image.imageId %></td>
+	      <td><%=h image.imageLocation %></td>
+	      <td><%=h image.imageOwnerId %></td>
+	      <td><%=h image.imageState %></td>
+	      <td><%=h image.isPublic %></td>
+	    </tr>
+	  <% end %>
+	</table>
+	
+	<h1>Sample 3 - Iterate</h1>
+	
+	<% @ec2_images_amazon.each do |image| %>
+		<% image.each_pair do |key, value| %>
+			<% unless key == 'parent' %>
+				<%= "#{key} => #{value}" %><br />
+			<% end %>
+		<% end %>
+		<br />
+	<% end %>
+	
+
+== Additional Resources
+
+=== Information
+
+* Amazon Web Services : http://aws.amazon.com
+* amazon-ec2 GEM home : http://amazon-ec2.rubyforge.org
+
+=== Project Tools
+
+* Project Home : http://rubyforge.org/projects/amazon-ec2
+* Downloads : http://rubyforge.org/frs/?group_id=2753
+* Browse Code : http://rubyforge.org/scm/?group_id=2753
+* Report Bugs : http://rubyforge.org/tracker/?group_id=2753
+* Request Features : http://rubyforge.org/tracker/?group_id=2753
+* Submit Patches : http://rubyforge.org/tracker/?group_id=2753
+
+=== Related Projects
+
+* Capsize : http://capsize.rubyforge.org
+
+== Credits
+
+The original sample code for this library was provided by Amazon Web Services, LLC.  Thanks to them for providing all of us with samples that got this started.
+
+Thanks to Dr. Nic Williams and his great 'NewGem' Ruby Gem Generator.  This "gem" of a Gem helped me package up this code for distribution in a relative flash!  You can find Dr. Nic's NewGem generator at http://newgem.rubyforge.org.
+
+== Contact
+
+Comments, patches, and bug reports are welcome. Send an email to mailto:grempe@nospam@rubyforge.org or use the RubyForge forum for this project.
+
+Enjoy!
+
+Glenn Rempe