kerryb-amazon-ec2 0.3.6

data/lib/EC2/image_attributes.rb

@@ -0,0 +1,166 @@
+#--
+# Amazon Web Services EC2 Query API Ruby library
+#
+# Ruby Gem Name::  amazon-ec2
+# Author::    Glenn Rempe  (mailto:glenn@rempe.us)
+# Copyright:: Copyright (c) 2007-2008 Glenn Rempe
+# License::   Distributes under the same terms as Ruby
+# Home::      http://github.com/grempe/amazon-ec2/tree/master
+#++
+
+module EC2
+
+  class Base
+
+    #Amazon Developer Guide Docs:
+    #
+    # The ModifyImageAttribute operation modifies an attribute of an AMI.  The following attributes may
+    # currently be modified:
+    #
+    # 'launchPermission' : Controls who has permission to launch the AMI. Launch permissions can be
+    # granted to specific users by adding userIds. The AMI can be made public by adding the 'all' group.
+    #
+    # 'productCodes' : Associates product codes with AMIs. This allows a developer to charge a user extra
+    # for using the AMIs. productCodes is a write once attribute - once it has been set it can not be
+    # changed or removed.  Currently only one product code is supported per AMI.
+    #
+    #Required Arguments:
+    #
+    # :image_id => String (default : "")
+    # :attribute => String ('launchPermission' or 'productCodes', default : "launchPermission")
+    # :operation_type => String (default : "")
+    #
+    #Optional Arguments:
+    #
+    # :user_id => Array (default : [])
+    # :group => Array (default : [])
+    # :product_code => Array (default : [])
+    #
+    def modify_image_attribute( options = {} )
+
+      # defaults
+      options = { :image_id => "",
+                  :attribute => "launchPermission",
+                  :operation_type => "",
+                  :user_id => [],
+                  :group => [],
+                  :product_code => [] }.merge(options)
+
+      raise ArgumentError, "No ':image_id' provided" if options[:image_id].nil? || options[:image_id].empty?
+      raise ArgumentError, "No ':attribute' provided" if options[:attribute].nil? || options[:attribute].empty?
+
+      # OperationType is not required if modifying a product code.
+      unless options[:attribute] == 'productCodes'
+        raise ArgumentError, "No ':operation_type' provided" if options[:operation_type].nil? || options[:operation_type].empty?
+      end
+
+      params = {
+        "ImageId" => options[:image_id],
+        "Attribute" => options[:attribute],
+        "OperationType" => options[:operation_type]
+      }
+
+      # test options provided and make sure they are valid
+      case options[:attribute]
+      when "launchPermission"
+
+        unless options[:operation_type] == "add" || options[:operation_type] == "remove"
+          raise ArgumentError, ":operation_type was #{options[:operation_type].to_s} but must be either 'add' or 'remove'"
+        end
+
+        if (options[:user_id].nil? || options[:user_id].empty?) && (options[:group].nil? || options[:group].empty?)
+          raise ArgumentError, "Option :attribute=>'launchPermission' requires ':user_id' or ':group' options to also be specified"
+        end
+        params.merge!(pathlist("UserId", options[:user_id])) unless options[:user_id].nil?
+        params.merge!(pathlist("Group", options[:group])) unless options[:group].nil?
+      when "productCodes"
+        if (options[:product_code].nil? || options[:product_code].empty?)
+          raise ArgumentError, "Option :attribute=>'productCodes' requires ':product_code' to be specified"
+        end
+        params.merge!(pathlist("ProductCode", options[:product_code])) unless options[:product_code].nil?
+      else
+        raise ArgumentError, "attribute : #{options[:attribute].to_s} is not an known attribute."
+      end
+
+      return response_generator(:action => "ModifyImageAttribute", :params => params)
+
+    end
+
+    #Amazon Developer Guide Docs:
+    #
+    # The DescribeImageAttribute operation returns information about an attribute of an AMI.
+    #
+    #Required Arguments:
+    #
+    # :image_id => String (default : "")
+    # :attribute => String ("launchPermission" or "productCodes", default : "launchPermission")
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def describe_image_attribute( options = {} )
+
+      # defaults
+      options = {:image_id => "",
+                 :attribute => "launchPermission"
+                 }.merge(options)
+
+      raise ArgumentError, "No ':image_id' provided" if options[:image_id].nil? || options[:image_id].empty?
+      raise ArgumentError, "No ':attribute' provided" if options[:attribute].nil? || options[:attribute].empty?
+
+      params = { "ImageId" => options[:image_id], "Attribute" => options[:attribute] }
+
+      # test options provided and make sure they are valid
+      case options[:attribute]
+      when "launchPermission", "productCodes"
+        # these args are ok
+      else
+        raise ArgumentError, "attribute : #{options[:attribute].to_s} is not an known attribute."
+      end
+
+      return response_generator(:action => "DescribeImageAttribute", :params => params)
+
+    end
+
+
+    #Amazon Developer Guide Docs:
+    #
+    # The ResetImageAttribute operation resets an attribute of an AMI to its default value.
+    #
+    #Required Arguments:
+    #
+    # :image_id => String (default : "")
+    # :attribute => String (default : "launchPermission")
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def reset_image_attribute( options = {} )
+
+      # defaults
+      options = {:image_id => "",
+                 :attribute => "launchPermission"}.merge(options)
+
+      raise ArgumentError, "No ':image_id' provided" if options[:image_id].nil? || options[:image_id].empty?
+      raise ArgumentError, "No ':attribute' provided" if options[:attribute].nil? || options[:attribute].empty?
+
+      params = {"ImageId" => options[:image_id],
+                "Attribute" => options[:attribute] }
+
+      # test options provided and make sure they are valid
+      case options[:attribute]
+      when "launchPermission"
+        # these args are ok
+      else
+        raise ArgumentError, "attribute : #{options[:attribute].to_s} is not an known attribute."
+      end
+
+      return response_generator(:action => "ResetImageAttribute", :params => params)
+
+    end
+
+  end
+
+end

data/lib/EC2/images.rb

@@ -0,0 +1,134 @@
+#--
+# Amazon Web Services EC2 Query API Ruby library
+#
+# Ruby Gem Name::  amazon-ec2
+# Author::    Glenn Rempe  (mailto:glenn@rempe.us)
+# Copyright:: Copyright (c) 2007-2008 Glenn Rempe
+# License::   Distributes under the same terms as Ruby
+# Home::      http://github.com/grempe/amazon-ec2/tree/master
+#++
+
+module EC2
+
+  class Base
+
+    #Amazon Developer Guide Docs:
+    #
+    # 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.
+    #
+    #Required Arguments:
+    #
+    # :image_location => String (default : "")
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def register_image( options = {} )
+
+      options = {:image_location => ""}.merge(options)
+
+      raise ArgumentError, "No :image_location provided" if options[:image_location].nil? || options[:image_location].empty?
+
+      params = { "ImageLocation" => options[:image_location] }
+
+      return response_generator(:action => "RegisterImage", :params => params)
+
+    end
+
+    #Amazon Developer Guide Docs:
+    #
+    # 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.
+    #
+    #Required Arguments:
+    #
+    # none
+    #
+    #Optional Arguments:
+    #
+    # :image_id => Array (default : [])
+    # :owner_id => Array (default : [])
+    # :executable_by => Array (default : [])
+    #
+    def describe_images( options = {} )
+
+      options = { :image_id => [], :owner_id => [], :executable_by => [] }.merge(options)
+
+      params = pathlist( "ImageId", options[:image_id] )
+      params.merge!(pathlist( "Owner", options[:owner_id] ))
+      params.merge!(pathlist( "ExecutableBy", options[:executable_by] ))
+
+      return response_generator(:action => "DescribeImages", :params => params)
+
+    end
+
+    #Amazon Developer Guide Docs:
+    #
+    # The DeregisterImage operation deregisters an AMI. Once deregistered, instances of the AMI may no
+    # longer be launched.
+    #
+    #Required Arguments:
+    #
+    # :image_id => String (default : "")
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def deregister_image( options = {} )
+
+      # defaults
+      options = { :image_id => "" }.merge(options)
+
+      raise ArgumentError, "No :image_id provided" if options[:image_id].nil? || options[:image_id].empty?
+
+      params = { "ImageId" => options[:image_id] }
+
+      return response_generator(:action => "DeregisterImage", :params => params)
+
+    end
+
+  end
+
+end

data/lib/EC2/instances.rb

@@ -0,0 +1,213 @@
+#--
+# Amazon Web Services EC2 Query API Ruby library
+#
+# Ruby Gem Name::  amazon-ec2
+# Author::    Glenn Rempe  (mailto:glenn@rempe.us)
+# Copyright:: Copyright (c) 2007-2008 Glenn Rempe
+# License::   Distributes under the same terms as Ruby
+# Home::      http://github.com/grempe/amazon-ec2/tree/master
+#++
+
+module EC2
+
+  class Base
+
+    #Amazon Developer Guide Docs:
+    #
+    # 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.
+    #
+    # If Amazon EC2 cannot launch the minimum number AMIs you request, no instances launch. If there
+    # is insufficient capacity to launch the maximum number of AMIs you request, Amazon EC2 launches
+    # as many as possible to satisfy the requested maximum values.
+    #
+    # Every instance is launched in a security group. If you do not specify a security group at
+    # launch, the instances start in the default security group.
+    #
+    # An optional instance type can be specified.  Currently supported types are 'm1.small', 'm1.large',
+    # 'm1.xlarge' and the high CPU types 'c1.medium' and 'c1.xlarge'.  'm1.small' is the default
+    # if no instance_type is specified.
+    #
+    # You can provide an optional key pair ID for each image in the launch request. All instances
+    # that are created from images that use this key pair will have access to the associated public
+    # key at boot. You can use this key to provide secure access to an instance of an image on a
+    # per-instance basis. Amazon EC2  public images use this feature to provide secure access
+    # without passwords.
+    #
+    # Important!  Launching public images without a key pair 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.
+    #
+    # Optional user data can be provided in the launch request. All instances comprising the launch
+    # request have access to this data (see Instance Metadata for details).
+    #
+    # If any of the AMIs have product codes attached for which the user has not subscribed,
+    # the RunInstances call will fail.
+    #
+    #Required Arguments:
+    #
+    # :image_id => String (Default : "")
+    # :min_count => Integer (default : 1 )
+    # :max_count => Integer (default : 1 )
+    #
+    #Optional Arguments:
+    #
+    # :key_name => String (default : nil)
+    # :group_id => Array (default : [])
+    # :user_data => String (default : nil)
+    # :addressing_type => String (default : "public")
+    # :instance_type => String (default : "m1.small")
+    # :kernel_id => String (default : nil)
+    # :availability_zone => String (default : nil)
+    # :base64_encoded => Boolean (default : false)
+    #
+    def run_instances( options = {} )
+
+      options = { :image_id => "",
+                  :min_count => 1,
+                  :max_count => 1,
+                  :key_name => nil,
+                  :group_id => [],
+                  :user_data => nil,
+                  :addressing_type => "public",
+                  :instance_type => "m1.small",
+                  :kernel_id => nil,
+                  :availability_zone => nil,
+                  :base64_encoded => false }.merge(options)
+
+      # Do some validation on the arguments provided
+      raise ArgumentError, ":image_id must be provided" if options[:image_id].nil? || options[:image_id].empty?
+      raise ArgumentError, ":min_count is not valid" unless options[:min_count].to_i > 0
+      raise ArgumentError, ":max_count is not valid" unless options[:max_count].to_i > 0
+      raise ArgumentError, ":addressing_type must be 'direct' or 'public'" unless options[:addressing_type] == "public" || options[:addressing_type] == "direct"
+      raise ArgumentError, ":instance_type must be 'm1.small', 'm1.large', 'm1.xlarge', 'c1.medium', or 'c1.xlarge'" unless options[:instance_type] == "m1.small" || options[:instance_type] == "m1.large" || options[:instance_type] == "m1.xlarge" || options[:instance_type] == "c1.medium" || options[:instance_type] == "c1.xlarge"
+      raise ArgumentError, ":base64_encoded must be 'true' or 'false'" unless options[:base64_encoded] == true || options[:base64_encoded] == false
+
+      # If :user_data is passed in then URL escape and Base64 encode it
+      # as needed.  Need for URL Escape + Base64 encoding is determined
+      # by :base64_encoded param.
+      if options[:user_data]
+        if options[:base64_encoded]
+          user_data = options[:user_data]
+        else
+          user_data = Base64.encode64(options[:user_data]).gsub(/\n/,"").strip()
+        end
+      else
+        user_data = nil
+      end
+
+      params = {
+        "ImageId"  => options[:image_id],
+        "MinCount" => options[:min_count].to_s,
+        "MaxCount" => options[:max_count].to_s,
+      }.merge(pathlist("SecurityGroup", options[:group_id]))
+
+      params["KeyName"] = options[:key_name] unless options[:key_name].nil?
+      params["UserData"] = user_data unless user_data.nil?
+      params["AddressingType"] = options[:addressing_type]
+      params["InstanceType"] = options[:instance_type]
+      params["KernelId"] = options[:kernel_id] unless options[:kernel_id].nil?
+      params["Placement.AvailabilityZone"] = options[:availability_zone] unless options[:availability_zone].nil?
+
+      return response_generator(:action => "RunInstances", :params => params)
+
+    end
+
+
+    #Amazon Developer Guide Docs:
+    #
+    # 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
+    #
+    #Required Arguments:
+    #
+    # none
+    #
+    #Optional Arguments:
+    #
+    # :instance_id => Array (default : [])
+    #
+    def describe_instances( options = {} )
+
+      options = { :instance_id => [] }.merge(options)
+
+      params = pathlist("InstanceId", options[:instance_id])
+
+      return response_generator(:action => "DescribeInstances", :params => params)
+
+    end
+
+
+    #Amazon Developer Guide Docs:
+    #
+    # The RebootInstances operation requests a reboot of one or more instances. This operation is
+    # asynchronous; it only queues a request to reboot the specified instance(s). The operation will succeed
+    # provided the instances are valid and belong to the user. Terminated instances will be ignored.
+    #
+    #Required Arguments:
+    #
+    # :instance_id => Array (default : [])
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def reboot_instances( options = {} )
+
+      # defaults
+      options = { :instance_id => [] }.merge(options)
+
+      raise ArgumentError, "No instance IDs provided" if options[:instance_id].nil? || options[:instance_id].empty?
+
+      params = pathlist("InstanceId", options[:instance_id])
+
+      return response_generator(:action => "RebootInstances", :params => params)
+
+    end
+
+
+    #Amazon Developer Guide Docs:
+    #
+    # 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.
+    #
+    #Required Arguments:
+    #
+    # :instance_id => Array (default : [])
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def terminate_instances( options = {} )
+
+      options = { :instance_id => [] }.merge(options)
+
+      raise ArgumentError, "No :instance_id provided" if options[:instance_id].nil? || options[:instance_id].empty?
+
+      params = pathlist("InstanceId", options[:instance_id])
+
+      return response_generator(:action => "TerminateInstances", :params => params)
+
+    end
+
+  end
+
+end

data/lib/EC2/keypairs.rb

@@ -0,0 +1,94 @@
+#--
+# Amazon Web Services EC2 Query API Ruby library
+#
+# Ruby Gem Name::  amazon-ec2
+# Author::    Glenn Rempe  (mailto:glenn@rempe.us)
+# Copyright:: Copyright (c) 2007-2008 Glenn Rempe
+# License::   Distributes under the same terms as Ruby
+# Home::      http://github.com/grempe/amazon-ec2/tree/master
+#++
+
+module EC2
+
+  class Base
+
+
+    #Amazon Developer Guide Docs:
+    #
+    # 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.
+    #
+    #Required Arguments:
+    #
+    # :key_name => String (default : "")
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def create_keypair( options = {} )
+
+      # defaults
+      options = { :key_name => "" }.merge(options)
+
+      raise ArgumentError, "No :key_name provided" if options[:key_name].nil? || options[:key_name].empty?
+
+      params = { "KeyName" => options[:key_name] }
+
+      return response_generator(:action => "CreateKeyPair", :params => params)
+
+    end
+
+
+    #Amazon Developer Guide Docs:
+    #
+    # 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.
+    #
+    #Required Arguments:
+    #
+    # :key_name => Array (default : [])
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def describe_keypairs( options = {} )
+
+      options = { :key_name => [] }.merge(options)
+
+      params = pathlist("KeyName", options[:key_name] )
+
+      return response_generator(:action => "DescribeKeyPairs", :params => params)
+
+    end
+
+
+    #Amazon Developer Guide Docs:
+    #
+    # The DeleteKeyPair operation deletes a keypair.
+    #
+    #Required Arguments:
+    #
+    # :key_name => String (default : "")
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def delete_keypair( options = {} )
+
+      options = { :key_name => "" }.merge(options)
+
+      raise ArgumentError, "No :key_name provided" if options[:key_name].nil? || options[:key_name].empty?
+
+      params = { "KeyName" => options[:key_name] }
+
+      return response_generator(:action => "DeleteKeyPair", :params => params)
+
+    end
+
+  end
+
+end

data/lib/EC2/products.rb

@@ -0,0 +1,43 @@
+#--
+# Amazon Web Services EC2 Query API Ruby library
+#
+# Ruby Gem Name::  amazon-ec2
+# Author::    Glenn Rempe  (mailto:glenn@rempe.us)
+# Copyright:: Copyright (c) 2007-2008 Glenn Rempe
+# License::   Distributes under the same terms as Ruby
+# Home::      http://github.com/grempe/amazon-ec2/tree/master
+#++
+
+module EC2
+
+  class Base
+
+    #Amazon Developer Guide Docs:
+    #
+    # The ConfirmProductInstance operation returns true if the given product code is attached to the instance
+    # with the given instance id. False is returned if the product code is not attached to the instance.
+    #
+    #Required Arguments:
+    #
+    # :product_code => String (default : "")
+    # :instance_id => String (default : "")
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def confirm_product_instance( options ={} )
+
+      options = {:product_code => "", :instance_id => ""}.merge(options)
+
+      raise ArgumentError, "No product code provided" if options[:product_code].nil? || options[:product_code].empty?
+      raise ArgumentError, "No instance ID provided" if options[:instance_id].nil? || options[:instance_id].empty?
+
+      params = { "ProductCode" => options[:product_code], "InstanceId" => options[:instance_id] }
+
+      return response_generator(:action => "ConfirmProductInstance", :params => params)
+
+    end
+  end
+
+end