right_aws 1.1.0 → 1.2.0

data/lib/ec2/right_ec2.rb

@@ -23,55 +23,106 @@
 
 module RightAws
 
+  # = RightAWS::EC2 -- RightScale Amazon EC2 interface
+  # The RightAws::EC2 class provides a complete interface to Amazon's
+  # Elastic Compute Cloud service.
+  # For explanations of the semantics
+  # of each call, please refer to Amazon's documentation at
+  # http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=87
+  #
+  # Examples:
+  #
+  # Create an EC2 interface handle:
+  #   
+  #   @ec2   = RightAws::Ec2.new(aws_access_key_id,
+  #                               aws_secret_access_key)
+  # Create a new SSH key pair:
+  #  @key   = 'right_ec2_awesome_test_key'
+  #  new_key = @ec2.create_key_pair(@key)
+  #  keys = @ec2.describe_key_pairs
+  #
+  # Create a security group:
+  #  @group = 'right_ec2_awesome_test_security_group'
+  #  @ec2.create_security_group(@group,'My awesome test group')
+  #  group = @ec2.describe_security_groups([@group])[0]
+  #
+  # Configure a security group:
+  #  @ec2.authorize_security_group_named_ingress(@group, account_number, 'default')
+  #  @ec2.authorize_security_group_IP_ingress(@group, 80,80,'udp','192.168.1.0/8')
+  #
+  # Describe the available images:
+  #  images = @ec2.describe_images
+  #
+  # Launch an instance:
+  #  ec2.run_instances('ami-9a9e7bf3', 1, 1, ['default'], @key, 'SomeImportantUserData', 'public')
+  # 
+  #
+  # Describe running instances:
+  #  @ec2.describe_instances
+  #
+  # Error handling: all operations raise an RightAws::AwsError in case
+  # of problems. Note that transient errors are automatically retried.
+    
   class Ec2
     
     SIGNATURE_VERSION = "1"
-    API_VERSION       = "2007-01-19"
+    # Amazon EC2 API version being used
+    API_VERSION       = "2007-03-01"
     DEFAULT_HOST      = "ec2.amazonaws.com"
     DEFAULT_PROTOCOL  = 'https'
     DEFAULT_PORT      = 443
     
+    # Default addressing type (public=NAT, direct=no-NAT) used when launching instances.
     DEFAULT_ADDRESSING_TYPE =  'public'
     DNS_ADDRESSING_SET      = ['public','direct']
     
-        # A list if Amazons problems we can handle by AWSErrorHandler.
+    # A list of Amazon problems we can handle by AWSErrorHandler.
     @@amazon_problems = RightAws::AMAZON_PROBLEMS
     
-      # Current aws_access_key_id
+    # Current aws_access_key_id
     attr_reader :aws_access_key_id
-      # Last HTTP request object
+    # Last HTTP request object
     attr_reader :last_request
-      # Last HTTP response object
+    # Last HTTP response object
     attr_reader :last_response
-      # Last AWS errors list (used by AWSErrorHandler)
+    # Last AWS errors list (used by AWSErrorHandler)
     attr_accessor :last_errors
-      # Last AWS request id (used by AWSErrorHandler)
+    # Last AWS request id (used by AWSErrorHandler)
     attr_accessor :last_request_id
-      # Logger object
+    # Logger object, used by this class to generate log messages
     attr_accessor :logger
-      # Initial params hash
+    # Option params passed into new
     attr_accessor :params
     
     @@bench_ec2 = Benchmark::Tms.new()
     @@bench_xml = Benchmark::Tms.new()
     
-      # Benchmark::Tms instance for EC2 access benchmark.
+    # Benchmark::Tms instance that accumulates time spent in requests to EC2.
     def self.bench_ec2;  @@bench_ec2;  end
     
-      # Benchmark::Tms instance for XML parsing benchmark.
+    # Benchmark::Tms instance that accumulates time spent in XML parsing.
     def self.bench_xml; @@bench_xml; end
 
-      # Returns a list of Amazon service responses which are known as problems on Amazon side. 
-      # We have to re-request again if we've got any of them - probably the problem will disappear. By default returns the same value as AMAZON_PROBLEMS const.
+    # Returns a list of Amazon service responses which are known to be transient errors.
+    # By default returns the same value as AMAZON_PROBLEMS const. See AWSErrorHandler.
     def self.amazon_problems
       @@amazon_problems
     end
 
-      # Sets a list of Amazon side problems.
+    # Sets the list of Amazon problems that are automatically retried. See AWSErrorHandler.
     def self.amazon_problems=(problems_list)
       @@amazon_problems = problems_list
     end
     
+    # Create a new handle to an EC2 account. All handles share the same per process or per thread
+    # HTTP connection to Amazon EC2. Each handle is for a specific account. The params have the
+    # following options:
+    # * <tt>:server</tt>: EC2 service host, default: DEFAULT_HOST
+    # * <tt>:port</tt>: EC2 service port, default: DEFAULT_PORT
+    # * <tt>:protocol</tt>: 'http' or 'https', default: DEFAULT_PROTOCOL
+    # * <tt>:multi_thread</tt>: true=HTTP connection per thread, false=per process
+    # * <tt>:logger</tt>: for log messages, default: RAILS_DEFAULT_LOGGER else STDOUT
+    #
     def initialize(aws_access_key_id, aws_secret_access_key, params={})
       @params = params
       raise AwsError.new("AWS access keys are required to operate on EC2") \
@@ -94,7 +145,7 @@ module RightAws
       AwsError::on_aws_exception(self, options)
     end
     
-      # Return the +true+ if this RightEc2NativeQuery instance works in multi_thread state and +false+ otherwise.
+      # Return +true+ if this RightEc2NativeQuery instance works in multi_thread mode and +false+ otherwise.
     def multi_thread
       @params[:multi_thread]
     end
@@ -132,13 +183,7 @@ module RightAws
       @last_response = response
       if response.is_a?(Net::HTTPSuccess)
         @error_handler = nil
-        @@bench_xml.add! do
-          if parser.kind_of?(RightAWSParser)
-            REXML::Document.parse_stream(response.body, parser)
-          else
-            parser.parse(response)
-          end
-        end
+        @@bench_xml.add! { parser.parse(response) }
         return parser.result
       else
         @error_handler = AWSErrorHandler.new(self, parser, @@amazon_problems) unless @error_handler
@@ -167,49 +212,66 @@ module RightAws
   #-----------------------------------------------------------------
 
     def ec2_describe_images(type, list) #:nodoc:
-      link   = generate_request("DescribeImages", hash_params(type,list))
-      return request_info(link, QEc2DescribeImagesParser.new)
-    end
-
-    def ec2_describe_images_by_id( list) #:nodoc:
-      return ec2_describe_images('ImageId', list)
-    end
-
-    def ec2_describe_images_by_owner(list) #:nodoc:
-      return ec2_describe_images('Owner', list)
-    end
-
-    def ec2_describe_images_by_executable_by(list) #:nodoc:
-      return ec2_describe_images('ExecutableBy', list)
+      link   = generate_request("DescribeImages", hash_params(type,list.to_a))
+      images = request_info(link, QEc2DescribeImagesParser.new(:logger => @logger))
+      images.collect! do |image|
+                    {:aws_id            => image.imageId,
+                     :aws_location      => image.imageLocation,
+                     :aws_owner         => image.imageOwnerId,
+                     :aws_state         => image.imageState.downcase,
+                     :aws_is_public     => image.isPublic,
+                     :aws_product_codes => image.productCodes}
+      end
+      images
+    rescue Exception
+      on_exception
     end
 
-      # Retrieve a list of images. Returns array of hashes or an exception:
+      # Retrieve a list of images. Returns array of hashes describing the images or an exception:
       #
       #  ec2.describe_images #=>
-      #    [{:aws_owner=>"522821470517", :aws_id=>"ami-e4b6538d", :aws_state=>"available",
-      #      :aws_location=>"marcins_cool_public_images/ubuntu-6.10.manifest.xml",:aws_is_public=>true},
-      #      ..., {...} ]
+      #    [{:aws_owner => "522821470517",
+      #      :aws_id => "ami-e4b6538d",
+      #      :aws_state => "available",
+      #      :aws_location => "marcins_cool_public_images/ubuntu-6.10.manifest.xml",
+      #      :aws_is_public => true},
+      #     {...},
+      #     {...} ]
       #
       # If +list+ param is set, then retrieve information about the listed images only:
       #
       #  ec2.describe_images(['ami-e4b6538d']) #=>
-      #    [{:aws_owner=>"522821470517", :aws_id=>"ami-e4b6538d", :aws_state=>"available",
-      #      :aws_location=>"marcins_cool_public_images/ubuntu-6.10.manifest.xml",:aws_is_public=>true}]
+      #    [{:aws_owner => "522821470517",
+      #      :aws_id => "ami-e4b6538d",
+      #      :aws_state => "available",
+      #      :aws_location => "marcins_cool_public_images/ubuntu-6.10.manifest.xml",
+      #      :aws_is_public => true}]
       #
     def describe_images(list=[])
-      images = list.nil? ? ec2_describe_images_by_executable_by(['self']) : ec2_describe_images_by_id(list)
-      images.collect! do |image|
-                    {:aws_id        => image.imageId,
-                     :aws_location  => image.imageLocation,
-                     :aws_owner     => image.imageOwnerId,
-                     :aws_state     => image.imageState.downcase,
-                     :aws_is_public => image.isPublic }
-      end
-      images
-    rescue Exception
-      on_exception
+      ec2_describe_images('ImageId', list)
+    end
+
+      #
+      #  Example:
+      #
+      #  ec2.describe_images_by_owner('522821470517')
+      #  ec2.describe_images_by_owner('self')
+      #
+    def describe_images_by_owner(list)
+      ec2_describe_images('Owner', list)
+    end
+
+      #
+      #  Example:
+      #
+      #  ec2.describe_images_by_executable_by('522821470517')
+      #  ec2.describe_images_by_executable_by('self')
+      #
+    def describe_images_by_executable_by(list)
+      ec2_describe_images('ExecutableBy', list)
     end
-     
+
+
       # Register new image at Amazon. 
       # Returns new image id or an exception.
       #
@@ -218,7 +280,7 @@ module RightAws
     def register_image(image_location)
       link = generate_request("RegisterImage", 
                               'ImageLocation' => image_location.to_s)
-      request_info(link, QEc2RegisterImageParser.new)
+      request_info(link, QEc2RegisterImageParser.new(:logger => @logger))
     rescue Exception
       on_exception
     end
@@ -230,13 +292,13 @@ module RightAws
     def deregister_image(image_id)
       link = generate_request("DeregisterImage", 
                               'ImageId' => image_id.to_s)
-      request_info(link, RightBoolResponseParser.new)
+      request_info(link, RightBoolResponseParser.new(:logger => @logger))
     rescue Exception
       on_exception
     end
 
 
-      # Describe image attributes. Currently, only 'launchPermission' is supported.
+      # Describe image attributes. Currently 'launchPermission' and 'productCodes' are supported.
       #
       #  ec2.describe_image_attribute('ami-e444444d') #=> {:groups=>["all"], :users=>["000000000777"]}
       #
@@ -244,9 +306,15 @@ module RightAws
       link = generate_request("DescribeImageAttribute", 
                               'ImageId'   => image_id,
                               'Attribute' => attribute)
-      image_attr = request_info(link, QEc2DescribeImageAttributeParser.new)
-      { :users  => image_attr.launchPermission.userIds,
-        :groups => image_attr.launchPermission.groups }
+      image_attr = request_info(link, QEc2DescribeImageAttributeParser.new(:logger => @logger))
+      result = {}
+      if image_attr.launchPermission
+        result = { :users  => image_attr.launchPermission.userIds,
+                   :groups => image_attr.launchPermission.groups }
+      elsif image_attr.productCodes
+        result = { :aws_product_codes => image_attr.productCodes}
+      end
+      result
     rescue Exception
       on_exception
     end
@@ -259,37 +327,42 @@ module RightAws
       link = generate_request("ResetImageAttribute", 
                               'ImageId'   => image_id,
                               'Attribute' => attribute)
-      request_info(link, RightBoolResponseParser.new)
+      request_info(link, RightBoolResponseParser.new(:logger => @logger))
     rescue Exception
       on_exception
     end
 
-      # Users should prefer modify_image_launch_perm_add|remove_users|groups() instead of modify_image_attribute() because the signature of 
-      # modify_image_attribute() may change with EC2 service changes.
+      # Modify an image's attributes. It is recommended that you use
+      # modify_image_launch_perm_add_users, modify_image_launch_perm_remove_users, etc.
+      # instead of modify_image_attribute because the signature of 
+      # modify_image_attribute may change with EC2 service changes.
       #
-      #  attribute     : currently, only 'launchPermission' is supported.
-      #  operationType : currently, only 'add' & 'remove' are supported.
-      #  userGroup     : currently, only 'all' is supported.
-    def modify_image_attribute(image_id, attribute, operation_type, user_id=[], user_group=[])
-      user_id    = user_id.to_a
-      user_group = user_group.to_a
-      params =  {'ImageId'       => image_id,
-                 'Attribute'     => attribute,
-                 'OperationType' => operation_type}
-      params.update(hash_params('UserId',    user_id))    unless user_id.empty?
-      params.update(hash_params('UserGroup', user_group)) unless user_group.empty?
+      #  attribute      : currently, only 'launchPermission' is supported.
+      #  operation_type : currently, only 'add' & 'remove' are supported.
+      #  vars: 
+      #    :user_group  : currently, only 'all' is supported.  
+      #    :user_id
+      #    :product_code
+    def modify_image_attribute(image_id, attribute, operation_type = nil, vars = {})
+      params =  {'ImageId'   => image_id,
+                 'Attribute' => attribute}
+      params['OperationType'] = operation_type if operation_type
+      params.update(hash_params('UserId',      vars[:user_id].to_a))    if vars[:user_id]
+      params.update(hash_params('UserGroup',   vars[:user_group].to_a)) if vars[:user_group]
+      params.update(hash_params('ProductCode', vars[:product_code]))    if vars[:product_code]
       link = generate_request("ModifyImageAttribute", params)
-      request_info(link, RightBoolResponseParser.new)
+      request_info(link, RightBoolResponseParser.new(:logger => @logger))
     rescue Exception
       on_exception
     end
 
-      # Grant image launch permissions for users. Parameter +userId+ is a list of users' AWS account ids. Returns +true+ or an exception.
+      # Grant image launch permissions to users.
+      # Parameter +userId+ is a list of user AWS account ids.
+      # Returns +true+ or an exception.
       #
       #  ec2.modify_image_launch_perm_add_users('ami-e444444d',['000000000777','000000000778']) #=> true
-      #
     def modify_image_launch_perm_add_users(image_id, user_id=[])
-      modify_image_attribute(image_id, 'launchPermission', 'add', user_id, [])
+      modify_image_attribute(image_id, 'launchPermission', 'add', :user_id => user_id.to_a)
     end
 
       # Revokes image launch permissions for users. +userId+ is a list of users AWS accounts ids. Returns +true+ or an exception.
@@ -297,7 +370,7 @@ module RightAws
       #  ec2.modify_image_launch_perm_remove_users('ami-e444444d',['000000000777','000000000778']) #=> true
       #
     def modify_image_launch_perm_remove_users(image_id, user_id=[])
-      modify_image_attribute(image_id, 'launchPermission', 'remove', user_id, [])
+      modify_image_attribute(image_id, 'launchPermission', 'remove', :user_id => user_id.to_a)
     end
 
       # Add image launch permissions for users groups (currently only 'all' is supported, which gives public launch permissions). 
@@ -306,7 +379,7 @@ module RightAws
       #  ec2.modify_image_launch_perm_add_groups('ami-e444444d') #=> true
       #
     def modify_image_launch_perm_add_groups(image_id, userGroup=['all'])
-      modify_image_attribute(image_id, 'launchPermission', 'add', [], userGroup)
+      modify_image_attribute(image_id, 'launchPermission', 'add', :user_group => userGroup.to_a)
     end
     
       # Remove image launch permissions for users groups (currently only 'all' is supported, which gives public launch permissions). 
@@ -314,7 +387,15 @@ module RightAws
       #  ec2.modify_image_launch_perm_remove_groups('ami-e444444d') #=> true
       #
     def modify_image_launch_perm_remove_groups(image_id, userGroup=['all'])
-      modify_image_attribute(image_id, 'launchPermission', 'remove', [], userGroup)
+      modify_image_attribute(image_id, 'launchPermission', 'remove', :user_group => userGroup.to_a)
+    end
+    
+      # Add product code to image
+      #
+      #  ec2.modify_image_product_code('ami-e444444d','0ABCDEF') #=> true
+      #
+    def modify_image_product_code(image_id, productCode=[])
+      modify_image_attribute(image_id, 'productCodes', nil, :product_code => productCode.to_a)
     end
 
     def get_desc_instances(instances)  # :nodoc:
@@ -334,7 +415,8 @@ module RightAws
                      :aws_state          => instance.instanceState.name,
                      :ssh_key_name       => instance.keyName,
                      :aws_image_id       => instance.imageId,
-                     :aws_reason         => reason}
+                     :aws_reason         => reason,
+                     :aws_product_codes  => instance.productCodes}
         end
       end
       result
@@ -342,7 +424,8 @@ module RightAws
       on_exception
     end
     
-      # Retrieve information about EC2 instances. If +list+ is omitted then returns the whole list.
+      # Retrieve information about EC2 instances. If +list+ is omitted then returns the
+      # list of all instances.
       #
       #  ec2.describe_instances #=> 
       #    [{:aws_image_id       => "ami-e444444d",
@@ -359,16 +442,27 @@ module RightAws
       #       ..., {...}]
       #
     def describe_instances(list=[])
-      link      = generate_request("DescribeInstances", hash_params('InstanceId',list))
-      instances = request_info(link, QEc2DescribeInstancesParser.new)
+      link      = generate_request("DescribeInstances", hash_params('InstanceId',list.to_a))
+      instances = request_info(link, QEc2DescribeInstancesParser.new(:logger => @logger))
       get_desc_instances(instances)
     rescue Exception
       on_exception
     end
     
+      # Return the product code attached to instance or +nil+ otherwise.
+      #
+      #  ec2.confirm_product_instance('ami-e444444d','12345678') #=> nil
+      #  ec2.confirm_product_instance('ami-e444444d','00001111') #=> "000000000888"
+      #
+    def confirm_product_instance(instance, product_code)
+      link = generate_request("ConfirmProductInstance", { 'ProductCode' => product_code,
+                                                          'InstanceId'  => instance })
+      request_info(link, QEc2ConfirmProductInstanceParser.new(:logger => @logger))
+    end
+    
       # Launch new EC2 instances. Returns a list of launched instances or an exception.
       #
-      #  ec2.run_instances('ami-e444444d',1,1,['my_awesome_group'],'my_awesome_key', 'Woohoo!!!', public) #=>
+      #  ec2.run_instances('ami-e444444d',1,1,['my_awesome_group'],'my_awesome_key', 'Woohoo!!!', 'public') #=>
       #   [{:aws_image_id       => "ami-e444444d",
       #     :aws_reason         => "",
       #     :aws_state_code     => "0",
@@ -382,9 +476,9 @@ module RightAws
       #     :private_dns_name   => ""}]
       #
     def run_instances(image_id, min_count, max_count, group_ids, key_name, user_data='', addressing_type=DEFAULT_ADDRESSING_TYPE)
-      @logger.info("Launching instance of image #{image_id} for #{@aws_access_key_id}, key: #{key_name}, groups: #{(group_ids||[]).join(',')}")
+      @logger.info("Launching instance of image #{image_id} for #{@aws_access_key_id}, key: #{key_name}, groups: #{(group_ids||[]).to_a.join(',')}")
         # careful: keyName and securityGroups may be nil
-      params = hash_params('SecurityGroup', group_ids)
+      params = hash_params('SecurityGroup', group_ids.to_a)
       params.update( {'ImageId'        => image_id,
                       'MinCount'       => min_count.to_s,
                       'MaxCount'       => max_count.to_s,
@@ -394,13 +488,13 @@ module RightAws
         user_data.strip!
           # Do not use CGI::escape(encode64(...)) as it is done in Amazons EC2 library.
           # Amazon 169.254.169.254 does not like escaped symbols!
-          # And it dont like "\n" inside of encoded string! Grrr....
+          # And it doesn't like "\n" inside of encoded string! Grrr....
           # Otherwise, some of UserData symbols will be lost...
-        params['UserData'] = Base64.encode64(user_data).delete("\n") unless user_data.empty?
+        params['UserData'] = Base64.encode64(user_data).delete("\n") unless user_data.blank?
       end
       link = generate_request("RunInstances", params)
         #debugger
-      instances = request_info(link, QEc2RunInstancesParser.new)
+      instances = request_info(link, QEc2RunInstancesParser.new(:logger => @logger))
       get_desc_instances(instances)
     rescue Exception
       on_exception
@@ -421,8 +515,8 @@ module RightAws
       #      :aws_prev_state_code     => 16}]
       #
     def terminate_instances(list=[])
-      link      = generate_request("TerminateInstances", hash_params('InstanceId',list))
-      instances = request_info(link, QEc2TerminateInstancesParser.new)
+      link      = generate_request("TerminateInstances", hash_params('InstanceId',list.to_a))
+      instances = request_info(link, QEc2TerminateInstancesParser.new(:logger => @logger))
       instances.collect! do |instance|
               { :aws_instance_id         => instance.instanceId,
                 :aws_shutdown_state      => instance.shutdownState.name,
@@ -444,7 +538,7 @@ module RightAws
       #     :aws_output      => "Linux version 2.6.16-xenU (builder@patchbat.amazonsa) (gcc version 4.0.1 20050727 ..."
     def get_console_output(instance_id)
       link   = generate_request("GetConsoleOutput", { 'InstanceId.1' => instance_id })
-      result = request_info(link, QEc2GetConsoleOutputParser.new)
+      result = request_info(link, QEc2GetConsoleOutputParser.new(:logger => @logger))
       { :aws_instance_id => result.instanceId,
         :aws_timestamp   => result.timestamp,
         :timestamp       => (Time.parse(result.timestamp)).utc,
@@ -459,7 +553,7 @@ module RightAws
       #
     def reboot_instances(list)
       link = generate_request("RebootInstances", hash_params('InstanceId', list.to_a))
-      request_info(link, RightBoolResponseParser.new)
+      request_info(link, RightBoolResponseParser.new(:logger => @logger))
     rescue Exception
       on_exception
     end
@@ -480,8 +574,8 @@ module RightAws
       #    ..., {...}]
       #
     def describe_security_groups(list=[])
-      link   = generate_request("DescribeSecurityGroups", hash_params('GroupName',list))
-      groups = request_info(link, QEc2DescribeSecurityGroupsParser.new)
+      link   = generate_request("DescribeSecurityGroups", hash_params('GroupName',list.to_a))
+      groups = request_info(link, QEc2DescribeSecurityGroupsParser.new(:logger => @logger))
       
       result = []     
       groups.each do |item|
@@ -527,7 +621,7 @@ module RightAws
       link = generate_request("CreateSecurityGroup", 
                               'GroupName'        => name.to_s, 
                               'GroupDescription' => description.to_s)
-      request_info(link, RightBoolResponseParser.new)
+      request_info(link, RightBoolResponseParser.new(:logger => @logger))
     rescue Exception
       on_exception
     end
@@ -539,21 +633,22 @@ module RightAws
     def delete_security_group(name)
       link = generate_request("DeleteSecurityGroup", 
                               'GroupName' => name.to_s)
-      request_info(link, RightBoolResponseParser.new)
+      request_info(link, RightBoolResponseParser.new(:logger => @logger))
     rescue Exception
       on_exception
     end
     
-      # Authorize named ingress for security group.
+      # Authorize named ingress for security group. Allows instances that are member of someone
+      # else's security group to open connections to instances in my group.
       #
-      #  ec2.authorize_security_group_named_ingress('my_awesome_group', aws_user_id, 'another_group_name') #=> true
+      #  ec2.authorize_security_group_named_ingress('my_awesome_group', '7011-0219-8268', 'their_group_name') #=> true
       #
     def authorize_security_group_named_ingress(name, owner, group)
       link = generate_request("AuthorizeSecurityGroupIngress", 
                               'GroupName'                  => name.to_s, 
                               'SourceSecurityGroupName'    => group.to_s, 
                               'SourceSecurityGroupOwnerId' => owner.to_s.gsub(/-/,''))
-      request_info(link, RightBoolResponseParser.new)
+      request_info(link, RightBoolResponseParser.new(:logger => @logger))
     rescue Exception
       on_exception
     end
@@ -567,12 +662,12 @@ module RightAws
                               'GroupName'                  => name.to_s, 
                               'SourceSecurityGroupName'    => group.to_s, 
                               'SourceSecurityGroupOwnerId' => owner.to_s.gsub(/-/,''))
-      request_info(link, RightBoolResponseParser.new)
+      request_info(link, RightBoolResponseParser.new(:logger => @logger))
     rescue Exception
       on_exception
     end
     
-      # Add permission to a security group. Returns +true+ or an exception. +protocol+ is one of :'tcp'|'udp'|'icmp' ('tcp' is default). 
+      # Add permission to a security group. Returns +true+ or an exception. +protocol+ is one of :'tcp'|'udp'|'icmp'.
       #
       #  ec2.authorize_security_group_IP_ingress('my_awesome_group', 80, 82, 'udp', '192.168.1.0/8') #=> true
       #  ec2.authorize_security_group_IP_ingress('my_awesome_group', -1, -1, 'icmp') #=> true
@@ -584,7 +679,7 @@ module RightAws
                               'FromPort'   => from_port.to_s, 
                               'ToPort'     => to_port.to_s, 
                               'CidrIp'     => cidr_ip.to_s)
-      request_info(link, RightBoolResponseParser.new)
+      request_info(link, RightBoolResponseParser.new(:logger => @logger))
     rescue Exception
       on_exception
     end
@@ -600,12 +695,13 @@ module RightAws
                               'FromPort'   => from_port.to_s, 
                               'ToPort'     => to_port.to_s, 
                               'CidrIp'     => cidr_ip.to_s)
-      request_info(link, RightBoolResponseParser.new)
+      request_info(link, RightBoolResponseParser.new(:logger => @logger))
     rescue Exception
       on_exception
     end
 
-      # Retrieve a list of SSH keys. Returms an array of keys or an exception.
+      # Retrieve a list of SSH keys. Returns an array of keys or an exception. Each key is
+      # represented as a two-element hash.
       #
       #  ec2.describe_key_pairs #=>
       #    [{:aws_fingerprint=> "01:02:03:f4:25:e6:97:e8:9b:02:1a:26:32:4e:58:6b:7a:8c:9f:03", :aws_key_name=>"key-1"},
@@ -613,8 +709,8 @@ module RightAws
       #      ..., {...} ]
       #
     def describe_key_pairs(list=[])
-      link   = generate_request("DescribeKeyPairs", hash_params('KeyName',list))
-      result = request_info(link, QEc2DescribeKeyPairParser.new)
+      link   = generate_request("DescribeKeyPairs", hash_params('KeyName',list.to_a))
+      result = request_info(link, QEc2DescribeKeyPairParser.new(:logger => @logger))
       result.collect! do |key|
           {:aws_key_name    => key.keyName,
            :aws_fingerprint => key.keyFingerprint }
@@ -624,7 +720,7 @@ module RightAws
       on_exception
     end
       
-      # Create new SSH key. Returns a hash of key's data or an exception.
+      # Create new SSH key. Returns a hash of the key's data or an exception.
       #
       #  ec2.create_key_pair('my_awesome_key') #=>
       #    {:aws_key_name    => "my_awesome_key",
@@ -634,7 +730,7 @@ module RightAws
     def create_key_pair(name)
       link = generate_request("CreateKeyPair", 
                               'KeyName' => name.to_s)
-      key  = request_info(link, QEc2CreateKeyPairParser.new)
+      key  = request_info(link, QEc2CreateKeyPairParser.new(:logger => @logger))
       { :aws_key_name    => key.keyName,
         :aws_fingerprint => key.keyFingerprint,
         :aws_material    => key.keyMaterial}
@@ -642,24 +738,26 @@ module RightAws
       on_exception
     end
       
-      # Delete key pair. Returns +true+ or an exception.
+      # Delete a key pair. Returns +true+ or an exception.
       #
       #  ec2.delete_key_pair('my_awesome_key') #=> true
       #
     def delete_key_pair(name)
       link = generate_request("DeleteKeyPair", 
                               'KeyName' => name.to_s)
-      request_info(link, RightBoolResponseParser.new)
+      request_info(link, RightBoolResponseParser.new(:logger => @logger))
     rescue Exception
       on_exception
     end
+    
+  #- Internal stuff from here on down...
 
 
   #-----------------------------------------------------------------
   #      PARSERS: Boolean Response Parser
   #-----------------------------------------------------------------
     
-  class RightBoolResponseParser < RightAWSParser # :nodoc:
+  class RightBoolResponseParser < RightAWSParser
     def tagend(name)
       @result = @text=='true' ? true : false if name == 'return'
     end
@@ -669,16 +767,16 @@ module RightAws
   #      PARSERS: Key Pair
   #-----------------------------------------------------------------
 
-    class QEc2DescribeKeyPairType # :nodoc:
+    class QEc2DescribeKeyPairType
       attr_accessor :keyName 
       attr_accessor :keyFingerprint
     end
 
-    class QEc2CreateKeyPairType < QEc2DescribeKeyPairType # :nodoc:
+    class QEc2CreateKeyPairType < QEc2DescribeKeyPairType
       attr_accessor :keyMaterial
     end
 
-    class QEc2DescribeKeyPairParser < RightAWSParser # :nodoc:
+    class QEc2DescribeKeyPairParser < RightAWSParser
       def tagstart(name, attributes)
         @item = QEc2DescribeKeyPairType.new if name == 'item'
       end
@@ -694,7 +792,7 @@ module RightAws
       end
     end
 
-    class QEc2CreateKeyPairParser < RightAWSParser # :nodoc:
+    class QEc2CreateKeyPairParser < RightAWSParser
       def tagstart(name, attributes)
         @result = QEc2CreateKeyPairType.new if !@result
       end
@@ -711,12 +809,12 @@ module RightAws
   #      PARSERS: Security Groups
   #-----------------------------------------------------------------
 
-    class QEc2UserIdGroupPairType # :nodoc:
+    class QEc2UserIdGroupPairType
       attr_accessor :userId
       attr_accessor :groupName
     end
 
-    class QEc2IpPermissionType # :nodoc:
+    class QEc2IpPermissionType
       attr_accessor :ipProtocol
       attr_accessor :fromPort
       attr_accessor :toPort
@@ -724,7 +822,7 @@ module RightAws
       attr_accessor :ipRanges
     end
 
-    class QEc2SecurityGroupItemType # :nodoc:
+    class QEc2SecurityGroupItemType
       attr_accessor :groupName
       attr_accessor :groupDescription
       attr_accessor :ownerId
@@ -732,7 +830,7 @@ module RightAws
     end
 
 
-    class QEc2DescribeSecurityGroupsParser < RightAWSParser # :nodoc:
+    class QEc2DescribeSecurityGroupsParser < RightAWSParser
       def tagstart(name, attributes)
         case name
           when 'item' 
@@ -782,17 +880,20 @@ module RightAws
   #      PARSERS: Images
   #-----------------------------------------------------------------
 
-    class QEc2DescribeImagesResponseItemType # :nodoc:
+    class QEc2DescribeImagesResponseItemType
       attr_accessor :imageId 
       attr_accessor :imageState 
       attr_accessor :imageLocation
       attr_accessor :imageOwnerId 
       attr_accessor :isPublic
+      attr_accessor :productCodes
     end
 
-    class QEc2DescribeImagesParser < RightAWSParser # :nodoc:
+    class QEc2DescribeImagesParser < RightAWSParser
       def tagstart(name, attributes)
-        @image = QEc2DescribeImagesResponseItemType.new if name == 'item'
+        if name == 'item' && @xmlpath[%r{.*/imagesSet$}]
+          @image = QEc2DescribeImagesResponseItemType.new 
+        end
       end
       def tagend(name)
         case name
@@ -801,7 +902,8 @@ module RightAws
           when 'imageState'    ; @image.imageState    = @text
           when 'imageOwnerId'  ; @image.imageOwnerId  = @text
           when 'isPublic'      ; @image.isPublic      = @text == 'true' ? true : false
-          when 'item'          ; @result << @image
+          when 'productCode'   ; (@image.productCodes ||= []) << @text
+          when 'item'          ; @result << @image if @xmlpath[%r{.*/imagesSet$}]
         end
       end
       def reset
@@ -809,7 +911,7 @@ module RightAws
       end
     end
 
-    class QEc2RegisterImageParser < RightAWSParser # :nodoc:
+    class QEc2RegisterImageParser < RightAWSParser
       def tagend(name)
         @result = @text if name == 'imageId'
       end
@@ -819,21 +921,22 @@ module RightAws
   #      PARSERS: Image Attribute
   #-----------------------------------------------------------------
 
-    class QEc2LaunchPermissionItemType # :nodoc:
+    class QEc2LaunchPermissionItemType
       attr_accessor :groups
       attr_accessor :userIds
     end
     
-    class QEc2DescribeImageAttributeType # :nodoc:
+    class QEc2DescribeImageAttributeType
       attr_accessor :imageId 
       attr_accessor :launchPermission
+      attr_accessor :productCodes
     end
 
-    class QEc2DescribeImageAttributeParser < RightAWSParser # :nodoc:
+    class QEc2DescribeImageAttributeParser < RightAWSParser
       def tagstart(name, attributes)
         case name
           when 'launchPermission'
-             @result.launchPermission = QEc2LaunchPermissionItemType.new
+            @result.launchPermission = QEc2LaunchPermissionItemType.new
             @result.launchPermission.groups  = []
             @result.launchPermission.userIds = []
         end
@@ -848,6 +951,8 @@ module RightAws
             @result.launchPermission.groups  << @text if @xmlpath == 'DescribeImageAttributeResponse/launchPermission/item'
           when 'userId'  
             @result.launchPermission.userIds << @text if @xmlpath == 'DescribeImageAttributeResponse/launchPermission/item'
+          when 'productCode'
+            (@result.productCodes ||= []) << @text
         end
       end
       def reset
@@ -859,12 +964,12 @@ module RightAws
   #      PARSERS: Instances
   #-----------------------------------------------------------------
 
-    class QEc2InstanceStateType # :nodoc:
+    class QEc2InstanceStateType
       attr_accessor :code
       attr_accessor :name
     end
 
-    class QEc2RunningInstancesItemType # :nodoc:
+    class QEc2RunningInstancesItemType
       attr_accessor :instanceId
       attr_accessor :imageId
       attr_accessor :instanceState
@@ -873,16 +978,17 @@ module RightAws
       attr_accessor :reason
       attr_accessor :keyName
       attr_accessor :amiLaunchIndex
+      attr_accessor :productCodes
     end
 
-    class QEc2DescribeInstancesType # :nodoc:
+    class QEc2DescribeInstancesType
       attr_accessor :reservationId
       attr_accessor :ownerId
       attr_accessor :groupSet
       attr_accessor :instancesSet 
     end
 
-    class QEc2DescribeInstancesParser < RightAWSParser # :nodoc:
+    class QEc2DescribeInstancesParser < RightAWSParser
       def tagstart(name, attributes)
         case name
           when 'item'
@@ -922,6 +1028,7 @@ module RightAws
             elsif @xmlpath=='DescribeInstancesResponse/reservationSet'
               @result << @reservation
             end
+          when 'productCode'   ; (@instance.productCodes ||= []) << @text
         end
       end
       def reset
@@ -929,7 +1036,16 @@ module RightAws
       end
     end
 
-    class QEc2RunInstancesParser < RightAWSParser # :nodoc:
+    class QEc2ConfirmProductInstanceParser < RightAWSParser
+      def tagend(name)
+        @result = @text if name == 'ownerId'
+      end
+      def reset
+        @result = nil
+      end
+    end
+
+    class QEc2RunInstancesParser < RightAWSParser
       def tagstart(name, attributes)
         case name
           when 'RunInstancesResponse'
@@ -966,6 +1082,7 @@ module RightAws
           when 'item'          
             @reservation.instancesSet << @instance if @xmlpath == 'RunInstancesResponse/instancesSet'
           when 'RunInstancesResponse'; @result << @reservation
+          when 'productCode'   ; (@instance.productCodes ||= []) << @text
         end
       end
       def reset
@@ -973,13 +1090,13 @@ module RightAws
       end
     end
 
-    class QEc2TerminateInstancesResponseInfoType # :nodoc:
+    class QEc2TerminateInstancesResponseInfoType
       attr_accessor :instanceId
       attr_accessor :shutdownState
       attr_accessor :previousState
     end
 
-    class QEc2TerminateInstancesParser < RightAWSParser # :nodoc:
+    class QEc2TerminateInstancesParser < RightAWSParser
       def tagstart(name, attributes)
         if name == 'item'
           @instance = QEc2TerminateInstancesResponseInfoType.new 
@@ -1010,13 +1127,13 @@ module RightAws
   #      PARSERS: Console
   #-----------------------------------------------------------------
 
-    class QEc2GetConsoleOutputResponseType # :nodoc:
+    class QEc2GetConsoleOutputResponseType
       attr_accessor :instanceId
       attr_accessor :timestamp
       attr_accessor :output
     end
 
-    class QEc2GetConsoleOutputParser < RightAWSParser # :nodoc:
+    class QEc2GetConsoleOutputParser < RightAWSParser
       def tagend(name)
         case name
         when 'instanceId' ; @result.instanceId = @text