skippy-amazon-ec2 0.0.2

data/Rakefile

@@ -0,0 +1,30 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+# read the contents of the gemspec, eval it, and assign it to 'spec'
+# this lets us maintain all gemspec info in one place.  Nice and DRY.
+spec = eval(IO.read("amazon-ec2.gemspec"))
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+task :install => [:package] do
+  sh %{sudo gem install pkg/#{GEM}-#{VERSION}}
+end
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/test*.rb']
+  t.verbose = true
+end
+
+Rake::RDocTask.new do |rd|
+  rd.main = "README.rdoc"
+  rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+  rd.rdoc_dir = 'doc'
+  rd.options = spec.rdoc_options
+end
+

data/bin/ec2-gem-example.rb

@@ -0,0 +1,58 @@
+#!/usr/bin/env ruby
+
+# Amazon Web Services EC2 Query API Ruby library
+#
+# Ruby Gem Name::  amazon-ec2
+# Author::    Glenn Rempe  (mailto:grempe@rubyforge.org)
+# Copyright:: Copyright (c) 2007-2008 Glenn Rempe
+# License::   Distributes under the same terms as Ruby
+# Home::      http://amazon-ec2.rubyforge.org
+#++
+
+require 'rubygems'
+require File.dirname(__FILE__) + '/../lib/EC2'
+
+# 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"
+
+ACCESS_KEY_ID = ENV['AMAZON_ACCESS_KEY_ID']
+SECRET_ACCESS_KEY = ENV['AMAZON_SECRET_ACCESS_KEY']
+
+if ACCESS_KEY_ID.nil? || ACCESS_KEY_ID.empty?
+  puts "Error : You must add the shell environment variables AMAZON_ACCESS_KEY_ID and AMAZON_SECRET_ACCESS_KEY before calling #{$0}!"
+  exit
+end
+
+ec2 = EC2::Base.new( :access_key_id => ACCESS_KEY_ID, :secret_access_key => SECRET_ACCESS_KEY )
+
+puts "----- ec2.methods.sort -----"
+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]}" 
+  end
+end
+
+puts "----- listing all running instances -----"
+puts 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.")
+
+puts "----- listing security groups -----"
+puts ec2.describe_security_groups()
+
+puts "----- deleting a security group -----"
+puts ec2.delete_security_group(:group_name => "ec2-example-rb-test-group")
+
+puts "----- listing my keypairs (verbose mode) -----"
+puts ec2.describe_keypairs()
+

data/bin/ec2sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env ruby
+
+# Amazon Web Services EC2 Query API Ruby library
+#
+# Ruby Gem Name::  amazon-ec2
+# Author::    Glenn Rempe  (mailto:grempe@rubyforge.org)
+# Copyright:: Copyright (c) 2007-2008 Glenn Rempe
+# License::   Distributes under the same terms as Ruby
+# Home::      http://amazon-ec2.rubyforge.org
+#++
+
+# CREDITS : Credit for this bit of shameful ripoff coolness 
+# goes to Marcel Molina and his AWS::S3 gem.  Thanks!
+
+# Usage : running this starts up an irb session and 
+# sets up the connection to EC2 as a class variable called
+# '@ec2'.  So just do something like the following on the 
+# shell command line:
+
+#   macbook-pro:~ glenn$ ec2sh 
+#   >> @ec2.describe_images
+#   => [#<EC2::Item image_location...
+
+ec2_lib   = File.dirname(__FILE__) + '/../lib/EC2'
+setup = File.dirname(__FILE__) + '/setup'
+irb_name = RUBY_PLATFORM =~ /mswin32/ ? 'irb.bat' : 'irb'
+
+if ( ENV['AMAZON_ACCESS_KEY_ID'] && ENV['AMAZON_SECRET_ACCESS_KEY'] )
+  
+  welcome_message = <<-MESSAGE
+  
+  '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 EC2::Response objects, each an EC2 image and its data
+      >> @ec2.describe_images.imagesSet.item
+      >> @ec2.describe_images.imagesSet.item[0] (an OpenStruct of a single item in that array)
+      >> @ec2.describe_images.imagesSet.item[0].to_s (a String representation of that OpenStruct item)
+      
+      returns : an XML representation of all images
+      >> puts @ec2.describe_images.xml
+      
+      returns : an XML representation of all images owned by Amazon
+      >> puts @ec2.describe_images(:owner_id => 'amazon').xml
+    
+  MESSAGE
+  
+  puts welcome_message
+  exec "#{irb_name} -r #{ec2_lib} -r #{setup} --simple-prompt"
+else
+  puts "You must define AMAZON_ACCESS_KEY_ID and AMAZON_SECRET_ACCESS_KEY as shell environment variables before running #{$0}!"
+end

data/bin/setup.rb

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+
+# Amazon Web Services EC2 Query API Ruby library
+#
+# Ruby Gem Name::  amazon-ec2
+# Author::    Glenn Rempe  (mailto:grempe@rubyforge.org)
+# Copyright:: Copyright (c) 2007-2008 Glenn Rempe
+# License::   Distributes under the same terms as Ruby
+# Home::      http://amazon-ec2.rubyforge.org
+#++
+
+if ENV['AMAZON_ACCESS_KEY_ID'] && ENV['AMAZON_SECRET_ACCESS_KEY']
+  @ec2 = EC2::Base.new( 
+    :access_key_id => ENV['AMAZON_ACCESS_KEY_ID'],
+    :secret_access_key => ENV['AMAZON_SECRET_ACCESS_KEY'] 
+  )
+end
+
+include EC2 

data/lib/EC2.rb

@@ -0,0 +1,247 @@
+#--
+# Amazon Web Services EC2 Query API Ruby library
+#
+# Ruby Gem Name::  amazon-ec2
+# Author::    Glenn Rempe  (mailto:grempe@rubyforge.org)
+# Copyright:: Copyright (c) 2007-2008 Glenn Rempe
+# License::   Distributes under the same terms as Ruby
+# Home::      http://amazon-ec2.rubyforge.org
+#++
+
+%w[ base64 cgi openssl digest/sha1 net/https rexml/document time ostruct ].each { |f| require f }
+
+# Require any lib files that we have bundled with this Ruby Gem in the lib/EC2 directory.
+# Parts of the EC2 module and Base class are broken out into separate
+# files for maintainability and are organized by the functional groupings defined
+# in the EC2 API developers guide.
+Dir[File.join(File.dirname(__FILE__), 'EC2/**/*.rb')].sort.each { |lib| require lib }
+
+module EC2
+
+  # Which host FQDN will we connect to for all API calls to AWS?
+  DEFAULT_HOST = 'ec2.amazonaws.com'
+
+  # This is the version of the API as defined by Amazon Web Services
+  API_VERSION = '2008-05-05'
+
+  # Builds the canonical string for signing. This strips out all '&', '?', and '='
+  # from the query string to be signed.
+  #   Note:  The parameters in the path passed in must already be sorted in
+  #   case-insensitive alphabetical order and must not be url encoded.
+  def EC2.canonical_string(path)
+    buf = ""
+    path.split('&').each { |field|
+      buf << field.gsub(/\&|\?/,"").sub(/=/,"")
+    }
+    return buf
+  end
+
+  # Encodes the given string with the secret_access_key, by taking the
+  # hmac-sha1 sum, and then base64 encoding it.  Optionally, it will also
+  # url encode the result of that to protect the string if it's going to
+  # be used as a query string parameter.
+  def EC2.encode(secret_access_key, str, urlencode=true)
+    digest = OpenSSL::Digest::Digest.new('sha1')
+    b64_hmac =
+      Base64.encode64(
+        OpenSSL::HMAC.digest(digest, secret_access_key, str)).strip
+
+    if urlencode
+      return CGI::escape(b64_hmac)
+    else
+      return b64_hmac
+    end
+  end
+
+
+  #Introduction:
+  #
+  # The library exposes one main interface class, 'EC2::Base'.
+  # This class provides all the methods for using the EC2 service
+  # including the handling of header signing and other security issues .
+  # This class uses Net::HTTP to interface with the EC2 Query API interface.
+  #
+  #Required Arguments:
+  #
+  # :access_key_id => String (default : "")
+  # :secret_access_key => String (default : "")
+  #
+  #Optional Arguments:
+  #
+  # :use_ssl => Boolean (default : true)
+  # :server => String (default : 'ec2.amazonaws.com')
+  # :proxy_server => String (default : nil)
+  #
+  class Base
+
+    attr_reader :use_ssl, :server, :proxy_server, :port
+
+    def initialize( options = {} )
+
+      options = { :access_key_id => "",
+                  :secret_access_key => "",
+                  :use_ssl => true,
+                  :server => DEFAULT_HOST,
+                  :proxy_server => nil
+                  }.merge(options)
+
+      @server = options[:server]
+      @proxy_server = options[:proxy_server]
+      @use_ssl = options[:use_ssl]
+
+      raise ArgumentError, "No :access_key_id provided" if options[:access_key_id].nil? || options[:access_key_id].empty?
+      raise ArgumentError, "No :secret_access_key provided" if options[:secret_access_key].nil? || options[:secret_access_key].empty?
+      raise ArgumentError, "No :use_ssl value provided" if options[:use_ssl].nil?
+      raise ArgumentError, "Invalid :use_ssl value provided, only 'true' or 'false' allowed" unless options[:use_ssl] == true || options[:use_ssl] == false
+      raise ArgumentError, "No :server provided" if options[:server].nil? || options[:server].empty?
+
+
+      # based on the :use_ssl boolean, determine which port we should connect to
+      case @use_ssl
+      when true
+        # https
+        @port = 443
+      when false
+        # http
+        @port = 80
+      end
+
+      @access_key_id = options[:access_key_id]
+      @secret_access_key = options[:secret_access_key]
+
+      # Use proxy server if defined
+      # Based on patch by Mathias Dalheimer.  20070217
+      proxy = @proxy_server ? URI.parse(@proxy_server) : OpenStruct.new
+      @http = Net::HTTP::Proxy( proxy.host,
+                                proxy.port,
+                                proxy.user,
+                                proxy.password).new(options[:server], @port)
+
+      @http.use_ssl = @use_ssl
+
+      # Don't verify the SSL certificates.  Avoids SSL Cert warning in log on every GET.
+      @http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+
+    end
+
+
+    private
+
+      # pathlist is a utility method which takes a key string and and array as input.
+      # It converts the array into a Hash with the hash key being 'Key.n' where
+      # 'n' increments by 1 for each iteration.  So if you pass in args
+      # ("ImageId", ["123", "456"]) you should get
+      # {"ImageId.1"=>"123", "ImageId.2"=>"456"} returned.
+      def pathlist(key, arr)
+        params = {}
+        arr.each_with_index do |value, i|
+          params["#{key}.#{i+1}"] = value
+        end
+        params
+      end
+
+
+      # Make the connection to AWS EC2 passing in our request.  This is generally called from
+      # within a 'Response' class object or one of its sub-classes so the response is interpreted
+      # in its proper context.  See lib/EC2/responses.rb
+      def make_request(action, params, data='')
+
+        @http.start do
+
+          # remove any keys that have nil or empty values
+          params.reject! { |key, value| value.nil? or value.empty?}
+
+          params.merge!( {"Action" => action,
+                          "SignatureVersion" => "1",
+                          "AWSAccessKeyId" => @access_key_id,
+                          "Version" => API_VERSION,
+                          "Timestamp"=>Time.now.getutc.iso8601} )
+
+          sigquery = params.sort_by { |param| param[0].downcase }.collect { |param| param.join("=") }.join("&")
+
+          sig = get_aws_auth_param(sigquery, @secret_access_key)
+
+          query = params.sort.collect do |param|
+            CGI::escape(param[0]) + "=" + CGI::escape(param[1])
+          end.join("&") + "&Signature=" + sig
+
+          req = Net::HTTP::Post.new("/")
+          req.content_type = 'application/x-www-form-urlencoded'
+          req['User-Agent'] = "github-amazon-ec2-ruby-gem"
+
+          response = @http.request(req, query)
+
+          # Make a call to see if we need to throw an error based on the response given by EC2
+          # All error classes are defined in EC2/exceptions.rb
+          ec2_error?(response)
+
+          return response
+
+        end
+
+      end
+
+      # Set the Authorization header using AWS signed header authentication
+      def get_aws_auth_param(path, secret_access_key)
+        canonical_string =  EC2.canonical_string(path)
+        encoded_canonical = EC2.encode(secret_access_key, canonical_string)
+      end
+
+      # allow us to have a one line call in each method which will do all of the work
+      # in making the actual request to AWS.
+      def response_generator( options = {} )
+
+        options = {
+          :action => "",
+          :params => {}
+        }.merge(options)
+
+        raise ArgumentError, ":action must be provided to response_generator" if options[:action].nil? || options[:action].empty?
+
+        http_response = make_request(options[:action], options[:params])
+        http_xml = http_response.body
+        return Response.parse(:xml => http_xml)
+
+      end
+
+      # Raises the appropriate error if the specified Net::HTTPResponse object
+      # contains an Amazon EC2 error; returns +false+ otherwise.
+      def ec2_error?(response)
+
+        # return false if we got a HTTP 200 code,
+        # otherwise there is some type of error (40x,50x) and
+        # we should try to raise an appropriate exception
+        # from one of our exception classes defined in
+        # exceptions.rb
+        return false if response.is_a?(Net::HTTPSuccess)
+
+        # parse the XML document so we can walk through it
+        doc = REXML::Document.new(response.body)
+
+        # Check that the Error element is in the place we would expect.
+        # and if not raise a generic error exception
+        unless doc.root.elements['Errors'].elements['Error'].name == 'Error'
+          raise Error, "Unexpected error format. response.body is: #{response.body}"
+        end
+
+        # An valid error response looks like this:
+        # <?xml version="1.0"?><Response><Errors><Error><Code>InvalidParameterCombination</Code><Message>Unknown parameter: foo</Message></Error></Errors><RequestID>291cef62-3e86-414b-900e-17246eccfae8</RequestID></Response>
+        # AWS EC2 throws some exception codes that look like Error.SubError.  Since we can't name classes this way
+        # we need to strip out the '.' in the error 'Code' and we name the error exceptions with this
+        # non '.' name as well.
+        error_code    = doc.root.elements['Errors'].elements['Error'].elements['Code'].text.gsub('.', '')
+        error_message = doc.root.elements['Errors'].elements['Error'].elements['Message'].text
+
+        # Raise one of our specific error classes if it exists.
+        # otherwise, throw a generic EC2 Error with a few details.
+        if EC2.const_defined?(error_code)
+          raise EC2.const_get(error_code), error_message
+        else
+          raise Error, "This is an undefined error code which needs to be added to exceptions.rb : error_code => #{error_code} : error_message => #{error_message}"
+        end
+
+      end
+
+  end
+
+end

data/lib/EC2/availability_zones.rb

@@ -0,0 +1,42 @@
+#--
+# Amazon Web Services EC2 Query API Ruby library
+#
+# Ruby Gem Name::  amazon-ec2
+# Author::    Glenn Rempe  (mailto:grempe@rubyforge.org)
+# Copyright:: Copyright (c) 2007-2008 Glenn Rempe
+# License::   Distributes under the same terms as Ruby
+# Home::      http://amazon-ec2.rubyforge.org
+#++
+
+module EC2
+
+  class Base
+
+    #Amazon Developer Guide Docs:
+    #
+    # The DescribeAvailabilityZones operation describes availability zones that are currently 
+    # available to the account and their states. 
+    #
+    # An optional list of zone names can be passed.
+    #
+    #Required Arguments:
+    #
+    # none
+    #
+    #Optional Arguments:
+    #
+    # :zone_name => Array (default : [])
+    #
+
+    def describe_availability_zones( options = {} )
+
+      options = { :zone_name => [] }.merge(options)
+
+      params = pathlist("ZoneName", options[:zone_name] )
+
+      return response_generator(:action => "DescribeAvailabilityZones", :params => params)
+
+    end
+  end
+end
+