amazon-ec2 0.0.2 → 0.0.3

data/lib/EC2/image_attributes.rb

@@ -0,0 +1,47 @@
+# Amazon Web Services EC2 Query API Ruby Library
+# This library has been packaged as a Ruby Gem 
+# by Glenn Rempe ( glenn @nospam@ elasticworkbench.com ).
+# 
+# Source code and gem hosted on RubyForge
+# under the Ruby License as of 12/14/2006:
+# http://amazon-ec2.rubyforge.org
+
+module EC2
+  
+  class AWSAuthConnection
+    
+    # The ModifyImageAttribute operation modifies an attribute of an AMI.
+    #
+    # Currently the only attribute supported is launchPermission. By 
+    # modifying this attribute it is possible to make an AMI public or 
+    # to grant specific users launch permissions for the AMI. To make the 
+    # AMI public add the group=all attribute item. To grant launch permissions 
+    # for a specific user add a userId=<userid> attribute item.
+    def modify_image_attribute(imageId, attribute, operationType, attributeValueHash)
+      params = {
+        "ImageId" => imageId,
+        "Attribute" => attribute,
+        "OperationType" => operationType
+      }
+      if attribute == "launchPermission"
+        params.merge!(pathlist("UserGroup", attributeValueHash[:userGroups])) if attributeValueHash.has_key? :userGroups
+        params.merge!(pathlist("UserId", attributeValueHash[:userIds])) if attributeValueHash.has_key? :userIds
+      end
+      ModifyImageAttributeResponse.new(make_request("ModifyImageAttribute", params))
+    end
+    
+    # The DescribeImageAttribute operation returns information about an attribute of an AMI.
+    def describe_image_attribute(imageId, attribute)
+      params = { "ImageId" => imageId, "Attribute" => attribute }
+      DescribeImageAttributeResponse.new(make_request("DescribeImageAttribute", params))
+    end
+    
+    # The ResetImageAttribute operation resets an attribute of an AMI to its default value.
+    def reset_image_attribute(imageId, attribute)
+      params = { "ImageId" => imageId, "Attribute" => attribute }
+      ResetImageAttributeResponse.new(make_request("ResetImageAttribute", params))
+    end
+    
+  end
+  
+end

data/lib/EC2/images.rb

@@ -0,0 +1,87 @@
+# Amazon Web Services EC2 Query API Ruby Library
+# This library has been packaged as a Ruby Gem 
+# by Glenn Rempe ( glenn @nospam@ elasticworkbench.com ).
+# 
+# Source code and gem hosted on RubyForge
+# under the Ruby License as of 12/14/2006:
+# http://amazon-ec2.rubyforge.org
+
+module EC2
+  
+  class AWSAuthConnection
+    
+    # The RegisterImage operation registers an AMI with Amazon EC2. 
+    # Images must be registered before they can be launched.  Each 
+    # AMI is associated with an unique ID which is provided by the 
+    # EC2 service via the Registerimage operation. As part of the 
+    # registration process, Amazon EC2 will retrieve the specified 
+    # image manifest from Amazon S3 and verify that the image is 
+    # owned by the user requesting image registration.  The image 
+    # manifest is retrieved once and stored within the Amazon EC2 
+    # network. Any modifications to an image in Amazon S3 invalidate 
+    # this registration. If you do have to make changes and upload 
+    # a new image deregister the previous image and register the new image.
+    def register_image(imageLocation)
+      params = { "ImageLocation" => imageLocation }
+      RegisterImageResponse.new(make_request("RegisterImage", params))
+    end
+    
+    # The DescribeImages operation returns information about AMIs available 
+    # for use by the user. This includes both public AMIs (those available 
+    # for any user to launch) and private AMIs (those owned by the user 
+    # making the request and those owned by other users that the user 
+    # making the request has explicit launch permissions for).
+    #
+    # The list of AMIs returned can be modified via optional lists of AMI IDs, 
+    # owners or users with launch permissions. If all three optional lists 
+    # are empty all AMIs the user has launch permissions for are returned. 
+    # Launch permissions fall into three categories:
+    #
+    # Launch Permission	Description
+    #  * public	The all group has launch permissions for the AMI. All users have 
+    #    launch permissions for these AMIs.
+    #  * explicit	The owner of the AMIs has granted a specific user launch permissions for the AMI.
+    #  * implicit	A user has implicit launch permissions for all AMIs he or she owns.
+    #
+    # If one or more of the lists are specified the result set is the intersection 
+    # of AMIs matching the criteria of the individual lists.
+    #
+    # Providing the list of AMI IDs requests information for those AMIs only. 
+    # If no AMI IDs are provided, information of all relevant AMIs will be 
+    # returned. If an AMI is specified that does not exist a fault is returned. 
+    # If an AMI is specified that exists but the user making the request does 
+    # not have launch permissions for, then that AMI will not be included in 
+    # the returned results.
+    #
+    # Providing the list of owners requests information for AMIs owned 
+    # by the specified owners only. Only AMIs the user has launch permissions 
+    # for are returned. The items of the list may be account ids for AMIs 
+    # owned by users with those account ids, amazon for AMIs owned by Amazon 
+    # or self for AMIs owned by the user making the request.
+    # 
+    # The executable list may be provided to request information for AMIs 
+    # that only the specified users have launch permissions for. The items of 
+    # the list may be account ids for AMIs owned by the user making the request 
+    # that the users with the specified account ids have explicit launch permissions 
+    # for, self for AMIs the user making the request has explicit launch permissions 
+    # for or all for public AMIs.
+    #
+    # Deregistered images will be included in the returned results for an 
+    # unspecified interval subsequent to deregistration.
+    def describe_images(imageIds=[], owners=[], executableBy=[])
+      params = pathlist("ImageId", imageIds)
+      params.merge!(pathlist("Owner", owners))
+      params.merge!(pathlist("ExecutableBy", executableBy))
+      DescribeImagesResponse.new(make_request("DescribeImages", params))
+    end
+    
+    # The DeregisterImage operation deregisters an AMI. Once deregistered, 
+    # instances of the AMI may no longer be launched.
+    def deregister_image(imageId)
+      params = { "ImageId" => imageId }
+      DeregisterImageResponse.new(make_request("DeregisterImage", params))
+    end
+    
+  end
+  
+end

data/lib/EC2/instances.rb

@@ -0,0 +1,95 @@
+# Amazon Web Services EC2 Query API Ruby Library
+# This library has been packaged as a Ruby Gem 
+# by Glenn Rempe ( glenn @nospam@ elasticworkbench.com ).
+# 
+# Source code and gem hosted on RubyForge
+# under the Ruby License as of 12/14/2006:
+# http://amazon-ec2.rubyforge.org
+
+module EC2
+  
+  class AWSAuthConnection
+    
+    # The RunInstances operation launches a specified number of instances.
+    #
+    # Note:
+    #   The Query version of RunInstances only allows instances of a 
+    #   single AMI to be launched in one call. This is different 
+    #   from the SOAP API call of the same name but similar to the 
+    #   ec2-run-instances command line tool.
+    # 
+    # A call to RunInstances is guaranteed to start no fewer than the 
+    # requested minimum. If there is insufficient capacity available 
+    # then no instances will be started. Amazon EC2 will make a best 
+    # effort attempt to satisfy the requested maximum values.
+    #
+    # Every instance is launched in a security group. This may be 
+    # specified as part of the launch request. If a security group is 
+    # not indicated then instances are started in a the default security group.
+    #
+    # An optional keypair ID may be provided for each image in the launch 
+    # request. All instances that are created from images for which this 
+    # is provided will have access to the associated public key at boot 
+    # time (detailed below). This key may be used to provide secure access 
+    # to an instance of an image on a per-instance basis. Amazon EC2 public 
+    # images make use of this functionality to provide secure passwordless 
+    # access to instances (and launching those images without a keypair ID 
+    # will leave them inaccessible).
+    #
+    # The public key material is made available to the instance at boot 
+    # time by placing it in a file named openssh_id.pub on a logical 
+    # device that is exposed to the instance as /dev/sda2 (the ephemeral store). 
+    # The format of this file is suitable for use as an entry within 
+    # ~/.ssh/authorized_keys (the OpenSSH format). This can be done at boot 
+    # time (as part of rclocal, for example) allowing for secure 
+    # password-less access. As the need arises, other formats will 
+    # also be considered.
+    def run_instances(imageId, kwargs={})
+      in_params = { :minCount=>1, :maxCount=>1, :keyname=>nil, :groupIds=>[], :userData=>nil, :base64Encoded=>false }
+      in_params.merge!(kwargs)
+      userData = Base64.encode64(userData) if userData and not base64Encoded
+      
+      params = {
+        "ImageId"  => imageId,
+        "MinCount" => in_params[:minCount].to_s,
+        "MaxCount" => in_params[:maxCount].to_s,
+      }.merge(pathlist("SecurityGroup", in_params[:groupIds])) 
+      
+      params["KeyName"] = in_params[:keyname] unless in_params[:keyname].nil? 
+      
+      RunInstancesResponse.new(make_request("RunInstances", params))
+    end
+    
+    # The DescribeInstances operation returns information about instances owned 
+    # by the user making the request.
+    #
+    # An optional list of instance IDs may be provided to request information 
+    # for those instances only. If no instance IDs are provided, information of 
+    # all relevant instances information will be returned. If an instance is 
+    # specified that does not exist a fault is returned. If an instance is specified 
+    # that exists but is not owned by the user making the request, then that 
+    # instance will not be included in the returned results.
+    #
+    # Recently terminated instances will be included in the returned results 
+    # for a small interval subsequent to their termination. This interval 
+    # is typically of the order of one hour.
+    def describe_instances(instanceIds=[])
+      params = pathlist("InstanceId", instanceIds)
+      DescribeInstancesResponse.new(make_request("DescribeInstances", params))
+    end
+    
+    # The TerminateInstances operation shuts down one or more instances. 
+    # This operation is idempotent and terminating an instance that is 
+    # in the process of shutting down (or already terminated) will succeed.
+    #
+    # Terminated instances remain visible for a short period of time 
+    # (approximately one hour) after termination, after which their 
+    # instance ID is invalidated.
+    def terminate_instances(instanceIds)
+      params = pathlist("InstanceId", instanceIds)
+      TerminateInstancesResponse.new(make_request("TerminateInstances", params))
+    end
+    
+  end
+  
+end

data/lib/EC2/keypairs.rb

@@ -0,0 +1,38 @@
+# Amazon Web Services EC2 Query API Ruby Library
+# This library has been packaged as a Ruby Gem 
+# by Glenn Rempe ( glenn @nospam@ elasticworkbench.com ).
+# 
+# Source code and gem hosted on RubyForge
+# under the Ruby License as of 12/14/2006:
+# http://amazon-ec2.rubyforge.org
+
+module EC2
+  
+  class AWSAuthConnection
+    
+    # The CreateKeyPair operation creates a new 2048 bit RSA keypair 
+    # and returns a unique ID that can be used to reference this 
+    # keypair when launching new instances.
+    def create_keypair(keyName)
+      params = { "KeyName" => keyName }
+      CreateKeyPairResponse.new(make_request("CreateKeyPair", params))
+    end
+    
+    # The DescribeKeyPairs operation returns information about keypairs 
+    # available for use by the user making the request. Selected keypairs 
+    # may be specified or the list may be left empty if information for 
+    # all registered keypairs is required.
+    def describe_keypairs(keyNames=[])
+      params = pathlist("KeyName", keyNames)
+      DescribeKeyPairsResponse.new(make_request("DescribeKeyPairs", params))
+    end
+    
+    # The DeleteKeyPair operation deletes a keypair.
+    def delete_keypair(keyName)
+      params = { "KeyName" => keyName }
+      DeleteKeyPairResponse.new(make_request("DeleteKeyPair", params))
+    end
+    
+  end
+  
+end

data/lib/EC2/responses.rb

@@ -0,0 +1,340 @@
+# Amazon Web Services EC2 Query API Ruby Library
+# This library has been packaged as a Ruby Gem 
+# by Glenn Rempe ( glenn @nospam@ elasticworkbench.com ).
+# 
+# Source code and gem hosted on RubyForge
+# under the Ruby License as of 12/14/2006:
+# http://amazon-ec2.rubyforge.org
+
+module EC2
+  
+  class Response
+    attr_reader :http_response
+    attr_reader :http_xml
+    attr_reader :structure
+    
+    ERROR_XPATH = "Response/Errors/Error"
+    
+    def initialize(http_response)
+      @http_response = http_response
+      @http_xml = http_response.body
+      @is_error = false
+      if http_response.is_a? Net::HTTPSuccess
+        @structure = parse
+      else
+        @is_error = true
+        @structure = parse_error
+      end
+    end
+    
+    def is_error?
+      @is_error
+    end
+    
+    def parse_error
+      doc = Document.new(@http_xml)
+      element = XPath.first(doc, ERROR_XPATH)
+      
+      errorCode = XPath.first(element, "Code").text
+      errorMessage = XPath.first(element, "Message").text
+      
+      [["#{errorCode}: #{errorMessage}"]]
+    end
+    
+    def parse
+      # Placeholder -- this method should be overridden in child classes.
+      nil
+    end
+    
+    def to_s
+      @structure.collect do |line|
+        line.join("\t")
+      end.join("\n")
+    end
+    
+  end
+  
+  
+  class DescribeImagesResponse < Response
+    ELEMENT_XPATH = "DescribeImagesResponse/imagesSet/item"
+    def parse
+      doc = Document.new(@http_xml)
+      lines = []
+      
+      doc.elements.each(ELEMENT_XPATH) do |element|
+        imageId = XPath.first(element, "imageId").text
+        imageLocation = XPath.first(element, "imageLocation").text
+        imageOwnerId = XPath.first(element, "imageOwnerId").text
+        imageState = XPath.first(element, "imageState").text
+        isPublic = XPath.first(element, "isPublic").text
+        lines << ["IMAGE", imageId, imageLocation, imageOwnerId, imageState, isPublic]
+      end
+      lines
+    end
+  end
+  
+  
+  class RegisterImageResponse < Response
+    ELEMENT_XPATH = "RegisterImageResponse/imageId"
+    def parse
+      doc = Document.new(@http_xml)
+      lines = [["IMAGE", XPath.first(doc, ELEMENT_XPATH).text]]
+    end
+  end
+  
+  
+  class DeregisterImageResponse < Response
+    def parse
+      # If we don't get an error, the deregistration succeeded.
+      [["Image deregistered."]]
+    end
+  end
+  
+  
+  class CreateKeyPairResponse < Response
+    ELEMENT_XPATH = "CreateKeyPairResponse"
+    def parse
+      doc = Document.new(@http_xml)
+      element = XPath.first(doc, ELEMENT_XPATH)
+      
+      keyName = XPath.first(element, "keyName").text
+      keyFingerprint = XPath.first(element, "keyFingerprint").text
+      keyMaterial = XPath.first(element, "keyMaterial").text
+      
+      line = [["KEYPAIR", keyName, keyFingerprint], [keyMaterial]]
+    end
+  end
+  
+  
+  class DescribeKeyPairsResponse < Response
+    ELEMENT_XPATH = "DescribeKeyPairsResponse/keySet/item"
+    def parse
+      doc = Document.new(@http_xml)
+      lines = []
+  
+      doc.elements.each(ELEMENT_XPATH) do |element|
+        keyName = XPath.first(element, "keyName").text
+        keyFingerprint = XPath.first(element, "keyFingerprint").text
+        lines << ["KEYPAIR", keyName, keyFingerprint]
+      end
+      lines
+    end
+  end
+  
+  
+  class DeleteKeyPairResponse < Response
+    def parse
+      # If we don't get an error, the deletion succeeded.
+      [["Keypair deleted."]]
+    end
+  end
+  
+  
+  class RunInstancesResponse < Response
+    ELEMENT_XPATH = "RunInstancesResponse"
+    def parse
+      doc = Document.new(@http_xml)
+      lines = []
+      
+      rootelement = XPath.first(doc, ELEMENT_XPATH)
+      
+      reservationId = XPath.first(rootelement, "reservationId").text
+      ownerId = XPath.first(rootelement, "ownerId").text
+      groups = nil
+      rootelement.elements.each("groupSet/item/groupId") do |element|
+        if not groups
+          groups = element.text
+        else
+          groups += "," + element.text
+        end
+      end
+      lines << ["RESERVATION", reservationId, ownerId, groups]
+      
+      #    rootelement = XPath.first(doc, ELEMENT_XPATH)
+      rootelement.elements.each("instancesSet/item") do |element|
+        instanceId = XPath.first(element, "instanceId").text
+        imageId = XPath.first(element, "imageId").text
+        instanceState = XPath.first(element, "instanceState/name").text
+        # Only for debug mode, which we don't support yet:
+        instanceStateCode = XPath.first(element, "instanceState/code").text
+        dnsName = XPath.first(element, "dnsName").text
+        # We don't return this, but still:
+        reason = XPath.first(element, "reason").text
+        lines << ["INSTANCE", instanceId, imageId, dnsName, instanceState]
+      end
+      lines
+    end
+  end
+  
+  
+  class DescribeInstancesResponse < Response
+    ELEMENT_XPATH = "DescribeInstancesResponse/reservationSet/item"
+    def parse
+      doc = Document.new(@http_xml)
+      lines = []
+      
+      doc.elements.each(ELEMENT_XPATH) do |rootelement|
+        reservationId = XPath.first(rootelement, "reservationId").text
+        ownerId = XPath.first(rootelement, "ownerId").text
+        groups = nil
+        rootelement.elements.each("groupSet/item/groupId") do |element|
+          if not groups
+            groups = element.text
+          else
+            groups += "," + element.text
+          end
+        end
+        lines << ["RESERVATION", reservationId, ownerId, groups]
+        
+        rootelement.elements.each("instancesSet/item") do |element|
+          instanceId = XPath.first(element, "instanceId").text
+          imageId = XPath.first(element, "imageId").text
+          instanceState = XPath.first(element, "instanceState/name").text
+          # Only for debug mode, which we don't support yet:
+          instanceStateCode = XPath.first(element, "instanceState/code").text
+          dnsName = XPath.first(element, "dnsName").text
+          # We don't return this, but still:
+          reason = XPath.first(element, "reason").text
+          lines << ["INSTANCE", instanceId, imageId, dnsName, instanceState]
+        end
+      end
+      lines
+    end
+  end
+  
+  
+  class TerminateInstancesResponse < Response
+    ELEMENT_XPATH = "TerminateInstancesResponse/instancesSet/item"
+    def parse
+      doc = Document.new(@http_xml)
+      lines = []
+      
+      doc.elements.each(ELEMENT_XPATH) do |element|
+        instanceId = XPath.first(element, "instanceId").text
+        shutdownState = XPath.first(element, "shutdownState/name").text
+        # Only for debug mode, which we don't support yet:
+        shutdownStateCode = XPath.first(element, "shutdownState/code").text
+        previousState = XPath.first(element, "previousState/name").text
+        # Only for debug mode, which we don't support yet:
+        previousStateCode = XPath.first(element, "previousState/code").text
+        lines << ["INSTANCE", instanceId, previousState, shutdownState]
+      end
+      lines
+    end
+  end
+  
+  
+  class CreateSecurityGroupResponse < Response
+    def parse
+      # If we don't get an error, the creation succeeded.
+      [["Security Group created."]]
+    end
+  end
+  
+  
+  class DescribeSecurityGroupsResponse < Response
+    ELEMENT_XPATH = "DescribeSecurityGroupsResponse/securityGroupInfo/item"
+    def parse
+      doc = Document.new(@http_xml)
+      lines = []
+      
+      doc.elements.each(ELEMENT_XPATH) do |rootelement|
+        groupName = XPath.first(rootelement, "groupName").text
+        ownerId = XPath.first(rootelement, "ownerId").text
+        groupDescription = XPath.first(rootelement, "groupDescription").text
+        lines << ["GROUP", ownerId, groupName, groupDescription]
+        rootelement.elements.each("ipPermissions/item") do |element|
+          ipProtocol = XPath.first(element, "ipProtocol").text
+          fromPort = XPath.first(element, "fromPort").text
+          toPort = XPath.first(element, "toPort").text
+          permArr = [
+                     "PERMISSION",
+                     ownerId,
+                     groupName,
+                     "ALLOWS",
+                     ipProtocol,
+                     fromPort,
+                     toPort,
+                     "FROM"
+                    ]
+          element.elements.each("groups/item") do |subelement|
+            userId = XPath.first(subelement, "userId").text
+            targetGroupName = XPath.first(subelement, "groupName").text
+            lines << permArr + ["USER", userId, "GRPNAME", targetGroupName]
+          end
+          element.elements.each("ipRanges/item") do |subelement|
+            cidrIp = XPath.first(subelement, "cidrIp").text
+            lines << permArr + ["CIDR", cidrIp]
+          end
+        end
+      end
+      lines
+    end
+  end
+  
+  
+  class DeleteSecurityGroupResponse < Response
+    def parse
+      # If we don't get an error, the deletion succeeded.
+      [["Security Group deleted."]]
+    end
+  end
+  
+  
+  class AuthorizeSecurityGroupIngressResponse < Response
+    def parse
+      # If we don't get an error, the authorization succeeded.
+      [["Ingress authorized."]]
+    end
+  end
+  
+  
+  class RevokeSecurityGroupIngressResponse < Response
+    def parse
+      # If we don't get an error, the revocation succeeded.
+      [["Ingress revoked."]]
+    end
+  end
+  
+  
+  class ModifyImageAttributeResponse < Response
+    def parse
+      # If we don't get an error, modification succeeded.
+      [["Image attribute modified."]]
+    end
+  end
+  
+  
+  class ResetImageAttributeResponse < Response
+    def parse
+      # If we don't get an error, reset succeeded.
+      [["Image attribute reset."]]
+    end
+  end
+  
+  
+  class DescribeImageAttributeResponse < Response
+    ELEMENT_XPATH = "DescribeImageAttributeResponse"
+    def parse
+      doc = Document.new(@http_xml)
+      lines = []
+      
+      rootelement = XPath.first(doc, ELEMENT_XPATH)
+      imageId = XPath.first(rootelement, "imageId").text
+      
+      # Handle launchPermission attributes:
+      rootelement.elements.each("launchPermission/item/*") do |element|
+        lines << [
+                  "launchPermission",
+                  imageId,
+                  element.name,
+                  element.text
+                 ]
+      end
+      lines
+    end
+  end
+
+# end EC2 Module
+end
+