kerryb-amazon-ec2 0.3.6

data/Rakefile

@@ -0,0 +1,35 @@
+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
+
+desc "Package and then install the gem locally"
+task :install => [:package] do
+  sh %{sudo gem install pkg/#{GEM}-#{VER}}
+end
+
+desc "Package and then install the gem locally omitting documentation"
+task :install_nodoc => [:package] do
+  sh %{sudo gem install --no-ri --no-rdoc pkg/#{GEM}-#{VER}}
+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,67 @@
+#!/usr/bin/env ruby
+
+# 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
+#++
+
+require 'rubygems'
+require File.dirname(__FILE__) + '/../lib/EC2'
+require 'pp'
+
+# 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
+
+# us-east-1.ec2.amazonaws.com == ec2.amazonaws.com
+# eu-west-1.ec2.amazonaws.com for the european region
+# test different servers by running something like:
+# export EC2_URL='https://ec2.amazonaws.com';./bin/ec2-gem-example.rb
+if ENV['EC2_URL']
+  ec2 = EC2::Base.new( :access_key_id => ACCESS_KEY_ID, :secret_access_key => SECRET_ACCESS_KEY, :server => URI.parse(ENV['EC2_URL']).host )
+else
+  # default server is US ec2.amazonaws.com
+  ec2 = EC2::Base.new( :access_key_id => ACCESS_KEY_ID, :secret_access_key => SECRET_ACCESS_KEY )
+end
+
+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.keys.each do |key|
+    puts "#{key} => #{image[key]}"
+  end
+end
+
+puts "----- listing all running instances -----"
+pp ec2.describe_instances()
+
+puts "----- creating a security group -----"
+pp ec2.create_security_group(:group_name => "ec2-example-rb-test-group", :group_description => "ec-example.rb test group description.")
+
+puts "----- listing security groups -----"
+pp ec2.describe_security_groups()
+
+puts "----- deleting a security group -----"
+pp ec2.delete_security_group(:group_name => "ec2-example-rb-test-group")
+
+puts "----- listing my keypairs (verbose mode) -----"
+pp ec2.describe_keypairs()

data/bin/ec2sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+
+# 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
+#++
+
+# 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.
+
+    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)
+
+  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,25 @@
+#!/usr/bin/env ruby
+
+# 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
+#++
+
+if ENV['AMAZON_ACCESS_KEY_ID'] && ENV['AMAZON_SECRET_ACCESS_KEY']
+  opts = {
+    :access_key_id => ENV['AMAZON_ACCESS_KEY_ID'],
+    :secret_access_key => ENV['AMAZON_SECRET_ACCESS_KEY']
+  }
+  if ENV['EC2_URL']
+    opts[:server] = URI.parse(ENV['EC2_URL']).host
+  end
+  @ec2 = EC2::Base.new(opts)
+end
+
+puts "EC2 Server: #{opts[:server]}"
+
+include EC2

data/lib/EC2/availability_zones.rb

@@ -0,0 +1,41 @@
+#--
+# 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 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

data/lib/EC2/console.rb

@@ -0,0 +1,44 @@
+#--
+# 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 GetConsoleOutput operation retrieves console output that has been posted for the specified instance.
+    #
+    # Instance console output is buffered and posted shortly after instance boot, reboot and once the instance
+    # is terminated. Only the most recent 64 KB of posted output is available. Console output is available for
+    # at least 1 hour after the most recent post.
+    #
+    #Required Arguments:
+    #
+    # :instance_id => String (default : "")
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def get_console_output( options ={} )
+
+      options = {:instance_id => ""}.merge(options)
+
+      raise ArgumentError, "No instance ID provided" if options[:instance_id].nil? || options[:instance_id].empty?
+
+      params = { "InstanceId" => options[:instance_id] }
+
+      return response_generator(:action => "GetConsoleOutput", :params => params)
+
+    end
+  end
+
+end

data/lib/EC2/elastic_ips.rb

@@ -0,0 +1,153 @@
+#--
+# 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 AllocateAddress operation acquires an elastic IP address for use with your account.
+    #
+    #Required Arguments:
+    #
+    # none
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def allocate_address
+
+      return response_generator(:action => "AllocateAddress")
+
+    end
+
+    #Amazon Developer Guide Docs:
+    #
+    # The DescribeAddresses operation lists elastic IP addresses assigned to your account.
+    #
+    #Required Arguments:
+    #
+    # :public_ip => Array (default : [], can be empty)
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def describe_addresses( options = {} )
+
+      options = { :public_ip => [] }.merge(options)
+
+      params = pathlist("PublicIp", options[:public_ip])
+
+      return response_generator(:action => "DescribeAddresses", :params => params)
+
+    end
+
+    #Amazon Developer Guide Docs:
+    #
+    # The ReleaseAddress operation releases an elastic IP address associated with your account.
+    #
+    # If you run this operation on an elastic IP address that is already released, the address
+    # might be assigned to another account which will cause Amazon EC2 to return an error.
+    #
+    # Note : Releasing an IP address automatically disassociates it from any instance
+    # with which it is associated. For more information, see DisassociateAddress.
+    #
+    # Important! After releasing an elastic IP address, it is released to the IP
+    # address pool and might no longer be available to your account. Make sure
+    # to update your DNS records and any servers or devices that communicate
+    # with the address.
+    #
+    #Required Arguments:
+    #
+    # :public_ip => String (default : '')
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def release_address( options = {} )
+
+      options = { :public_ip => '' }.merge(options)
+
+      raise ArgumentError, "No ':public_ip' provided" if options[:public_ip].nil? || options[:public_ip].empty?
+
+      params = { "PublicIp" => options[:public_ip] }
+
+      return response_generator(:action => "ReleaseAddress", :params => params)
+
+    end
+
+    #Amazon Developer Guide Docs:
+    #
+    # The AssociateAddress operation associates an elastic IP address with an instance.
+    #
+    # If the IP address is currently assigned to another instance, the IP address
+    # is assigned to the new instance. This is an idempotent operation. If you enter
+    # it more than once, Amazon EC2 does not return an error.
+    #
+    #Required Arguments:
+    #
+    # :instance_id  => String (default : '')
+    # :public_ip    => String (default : '')
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def associate_address( options = {} )
+
+      options = { :instance_id => '', :public_ip => '' }.merge(options)
+
+      raise ArgumentError, "No ':instance_id' provided" if options[:instance_id].nil? || options[:instance_id].empty?
+      raise ArgumentError, "No ':public_ip' provided" if options[:public_ip].nil? || options[:public_ip].empty?
+
+      params = {
+        "InstanceId" => options[:instance_id],
+        "PublicIp" => options[:public_ip]
+      }
+
+      return response_generator(:action => "AssociateAddress", :params => params)
+
+    end
+
+    #Amazon Developer Guide Docs:
+    #
+    # The DisassociateAddress operation disassociates the specified elastic IP
+    # address from the instance to which it is assigned. This is an idempotent
+    # operation. If you enter it more than once, Amazon EC2 does not return
+    # an error.
+    #
+    #Required Arguments:
+    #
+    # :public_ip    => String (default : '')
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def disassociate_address( options = {} )
+
+      options = { :public_ip => '' }.merge(options)
+
+      raise ArgumentError, "No ':public_ip' provided" if options[:public_ip].nil? || options[:public_ip].empty?
+
+      params = { "PublicIp" => options[:public_ip] }
+
+      return response_generator(:action => "DisassociateAddress", :params => params)
+
+    end
+
+  end
+
+end

data/lib/EC2/exceptions.rb

@@ -0,0 +1,147 @@
+#--
+# 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
+
+  # OUR CUSTOM ERROR CODES
+
+  # All of our errors are superclassed by Error < RuntimeError
+  class Error < RuntimeError #:nodoc:
+  end
+
+  # A client side only argument error
+  class ArgumentError < Error #:nodoc:
+  end
+
+
+  # AWS EC2 CLIENT ERROR CODES
+
+  # AWS EC2 can throw error exceptions that contain a '.' in them.
+  # since we can't name an exception class with that '.' I compressed
+  # each class name into the non-dot version.  This allows us to retain
+  # the granularity of the exception.
+
+  # User not authorized.
+  class AuthFailure < Error #:nodoc:
+  end
+
+  # Invalid AWS Account
+  class InvalidClientTokenId < Error #:nodoc:
+  end
+
+  # Invalid Parameters for Value
+  class InvalidParameterValue < Error #:nodoc:
+  end
+
+  # Specified AMI has an unparsable manifest.
+  class InvalidManifest < Error #:nodoc:
+  end
+
+  # Specified AMI ID is not valid.
+  class InvalidAMIIDMalformed < Error #:nodoc:
+  end
+
+  # Specified AMI ID does not exist.
+  class InvalidAMIIDNotFound < Error #:nodoc:
+  end
+
+  # Specified AMI ID has been deregistered and is no longer available.
+  class InvalidAMIIDUnavailable < Error #:nodoc:
+  end
+
+  # Specified instance ID is not valid.
+  class InvalidInstanceIDMalformed < Error #:nodoc:
+  end
+
+  # Specified instance ID does not exist.
+  class InvalidInstanceIDNotFound < Error #:nodoc:
+  end
+
+  # Specified keypair name does not exist.
+  class InvalidKeyPairNotFound < Error #:nodoc:
+  end
+
+  # Attempt to create a duplicate keypair.
+  class InvalidKeyPairDuplicate < Error #:nodoc:
+  end
+
+  # Specified group name does not exist.
+  class InvalidGroupNotFound < Error #:nodoc:
+  end
+
+  # Attempt to create a duplicate group.
+  class InvalidGroupDuplicate < Error #:nodoc:
+  end
+
+  # Specified group can not be deleted because it is in use.
+  class InvalidGroupInUse < Error #:nodoc:
+  end
+
+  # Specified group name is a reserved name.
+  class InvalidGroupReserved < Error #:nodoc:
+  end
+
+  # Attempt to authorize a permission that has already been authorized.
+  class InvalidPermissionDuplicate < Error #:nodoc:
+  end
+
+  # Specified permission is invalid.
+  class InvalidPermissionMalformed < Error #:nodoc:
+  end
+
+  # Specified reservation ID is invalid.
+  class InvalidReservationIDMalformed < Error #:nodoc:
+  end
+
+  # Specified reservation ID does not exist.
+  class InvalidReservationIDNotFound < Error #:nodoc:
+  end
+
+  # User has reached max allowed concurrent running instances.
+  class InstanceLimitExceeded < Error #:nodoc:
+  end
+
+  # An invalid set of parameters were passed as arguments
+  # e.g. RunInstances was called with minCount and maxCount set to 0 or minCount > maxCount.
+  class InvalidParameterCombination < Error #:nodoc:
+  end
+
+  # An unknown parameter was passed as an argument
+  class UnknownParameter < Error #:nodoc:
+  end
+
+  # The user ID is neither in the form of an AWS account ID or one
+  # of the special values accepted by the owner or executableBy flags
+  # in the DescribeImages call.
+  class InvalidUserIDMalformed < Error #:nodoc:
+  end
+
+  # The value of an item added to, or removed from, an image attribute is invalid.
+  class InvalidAMIAttributeItemValue < Error #:nodoc:
+  end
+
+  # AWS EC2 SERVER ERROR CODES
+
+  # Internal AWS EC2 Error.
+  class InternalError < Error #:nodoc:
+  end
+
+  # There are not enough available instances to satify your minimum request.
+  class InsufficientInstanceCapacity < Error #:nodoc:
+  end
+
+  # The server is overloaded and cannot handle request.
+  class Unavailable < Error #:nodoc:
+  end
+
+  class SignatureDoesNotMatch < Error #:nodoc:
+  end
+
+end