amazon-ec2 0.5.1 → 0.5.2

Sign up to get free protection for your applications and to get access to all the features.
data/.gitignore CHANGED
@@ -2,5 +2,7 @@
2
2
  .DS_Store
3
3
  coverage
4
4
  rdoc
5
+ doc
6
+ .yardoc
5
7
  pkg
6
8
 
data/.yardopts ADDED
@@ -0,0 +1 @@
1
+ --title amazon-ec2 - ChangeLog LICENSE
data/ChangeLog CHANGED
@@ -1,3 +1,6 @@
1
+ === 0.5.2 2009-08-20
2
+ * Converted to YardDoc documentation format. See : http://yard.soen.ca/getting_started
3
+
1
4
  === 0.5.0 2009-08-11
2
5
  * Major re-factor by Kris Rasmussen (krisr) to add support for the AWS Elastic Load Balancer API. Kudos Kris!
3
6
 
data/LICENSE CHANGED
@@ -1,4 +1,4 @@
1
- Copyright (c) 2007-2008 Glenn Rempe
1
+ Copyright (c) 2007-2009 Glenn Rempe
2
2
 
3
3
  This software is distributed under the Ruby License. A copy of which is
4
4
  provided below.
data/README.rdoc CHANGED
@@ -305,12 +305,24 @@ So, for example, if you wanted to get the image ID of the third image listed in
305
305
 
306
306
  EC2 will typically return sets of things (imagesSet, reservationSet, etc.) which we map to ruby Arrays (.imagesSet.item in the example above). If you want to iterate over a response set you will need to iterate over this array. The Arrays will typically contain additional AWS::Response objects that represent each individual item. You'll find that you can use the 'ec2sh' to help you understand the structure more completely if you try issuing commands there as a way to practice seeing what will be returned and making sure you get exactly what you want.
307
307
 
308
+ === Handling Exceptions
309
+ If for some reason an error occurs when executing a method (e.g. its arguments were
310
+ incorrect, or it simply failed) then an exception will be thrown. The exceptions are
311
+ defined in exceptions.rb as individual classes and should match the exceptions that
312
+ AWS has defined in the API. If the exception raised cannot be identified then a
313
+ more generic exception class will be thrown.
314
+
315
+ The implication of this is that you need to be prepared to handle any exceptions that
316
+ may be raised by this library in YOUR code with a 'rescue' clause. It is up to you
317
+ to determine how you want to handle these exceptions in your code.
318
+
308
319
 
309
320
  == Additional Resources
310
321
 
311
322
  === Project Websites
312
323
 
313
324
  * Project Home : http://github.com/grempe/amazon-ec2/tree/master
325
+ * API Documentation : http://rdoc.info/projects/grempe/amazon-ec2
314
326
  * Discussion Group : http://groups.google.com/group/amazon-ec2
315
327
  * Report Bugs / Request Features : http://github.com/grempe/amazon-ec2/issues
316
328
  * Amazon Web Services : http://aws.amazon.com
@@ -321,7 +333,7 @@ The original code for this library was provided by Amazon Web Services, LLC as s
321
333
 
322
334
  == Contact
323
335
 
324
- Comments, patches, Git pull requests and bug reports are welcome. Send an email to mailto:glenn@rempe.us or use the Google Groups forum for this project.
336
+ Comments, patches, Git pull requests and bug reports are welcome. Send an email to mailto:glenn@rempe.us or join the Google Groups forum.
325
337
 
326
338
  Enjoy!
327
339
 
data/Rakefile CHANGED
@@ -1,5 +1,6 @@
1
1
  require 'rubygems'
2
2
  require 'rake'
3
+ require 'yard'
3
4
 
4
5
  require 'jeweler'
5
6
  Jeweler::Tasks.new do |gem|
@@ -47,19 +48,8 @@ end
47
48
 
48
49
  task :default => :test
49
50
 
50
- require 'rake/rdoctask'
51
- Rake::RDocTask.new do |rdoc|
52
- if File.exist?('VERSION.yml')
53
- config = YAML.load(File.read('VERSION.yml'))
54
- version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
55
- else
56
- version = ""
57
- end
58
-
59
- rdoc.rdoc_dir = 'rdoc'
60
- rdoc.title = "amazon-ec2 #{version}"
61
- rdoc.rdoc_files.include('README*')
62
- rdoc.rdoc_files.include('lib/**/*.rb')
51
+ YARD::Rake::YardocTask.new do |t|
52
+ #t.files = ['lib/**/*.rb']
63
53
  end
64
54
 
65
55
  begin
@@ -70,15 +60,15 @@ begin
70
60
  task :release => ["rubyforge:release:gem", "rubyforge:release:docs"]
71
61
 
72
62
  namespace :release do
73
- desc "Publish RDoc to RubyForge."
74
- task :docs => [:rdoc] do
63
+ desc "Publish YARD docs to RubyForge."
64
+ task :docs => [:doc] do
75
65
  config = YAML.load(
76
66
  File.read(File.expand_path('~/.rubyforge/user-config.yml'))
77
67
  )
78
68
 
79
69
  host = "#{config['username']}@rubyforge.org"
80
70
  remote_dir = "/var/www/gforge-projects/amazon-ec2/"
81
- local_dir = 'rdoc'
71
+ local_dir = 'doc'
82
72
 
83
73
  Rake::SshDirPublisher.new(host, remote_dir, local_dir).upload
84
74
  end
data/VERSION CHANGED
@@ -1 +1 @@
1
- 0.5.1
1
+ 0.5.2
data/amazon-ec2.gemspec CHANGED
@@ -5,7 +5,7 @@
5
5
 
6
6
  Gem::Specification.new do |s|
7
7
  s.name = %q{amazon-ec2}
8
- s.version = "0.5.1"
8
+ s.version = "0.5.2"
9
9
 
10
10
  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
11
11
  s.authors = ["Glenn Rempe"]
@@ -21,6 +21,7 @@ Gem::Specification.new do |s|
21
21
  ]
22
22
  s.files = [
23
23
  ".gitignore",
24
+ ".yardopts",
24
25
  "ChangeLog",
25
26
  "LICENSE",
26
27
  "README.rdoc",
@@ -75,12 +76,11 @@ Gem::Specification.new do |s|
75
76
  "wsdl/2008-05-05.ec2.wsdl",
76
77
  "wsdl/2008-12-01.ec2.wsdl"
77
78
  ]
78
- s.has_rdoc = true
79
79
  s.homepage = %q{http://github.com/grempe/amazon-ec2}
80
80
  s.rdoc_options = ["--title", "amazon-ec2 documentation", "--line-numbers", "--main", "README.rdoc"]
81
81
  s.require_paths = ["lib"]
82
82
  s.rubyforge_project = %q{amazon-ec2}
83
- s.rubygems_version = %q{1.3.1}
83
+ s.rubygems_version = %q{1.3.5}
84
84
  s.summary = %q{Amazon EC2 Ruby Gem}
85
85
  s.test_files = [
86
86
  "test/test_EC2.rb",
@@ -103,7 +103,7 @@ Gem::Specification.new do |s|
103
103
 
104
104
  if s.respond_to? :specification_version then
105
105
  current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
106
- s.specification_version = 2
106
+ s.specification_version = 3
107
107
 
108
108
  if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
109
109
  s.add_runtime_dependency(%q<xml-simple>, [">= 1.0.12"])
data/lib/AWS.rb CHANGED
@@ -1,16 +1,47 @@
1
- # Require any lib files that we have bundled with this Ruby Gem in the lib/AWS directory.
2
- # Parts of the AWS module and Base class are broken out into separate
3
- # files for maintainability and are organized by the functional groupings defined
4
- # in the AWS API developers guide.
5
-
1
+ #--
2
+ # Amazon Web Services EC2 + ELB API Ruby library
3
+ #
4
+ # Ruby Gem Name:: amazon-ec2
5
+ # Author:: Glenn Rempe (mailto:glenn@rempe.us)
6
+ # Copyright:: Copyright (c) 2007-2009 Glenn Rempe
7
+ # License:: Distributes under the same terms as Ruby
8
+ # Home:: http://github.com/grempe/amazon-ec2/tree/master
9
+ #++
6
10
 
7
11
  %w[ base64 cgi openssl digest/sha1 net/https rexml/document time ostruct ].each { |f| require f }
8
12
 
13
+ begin
14
+ require 'xmlsimple' unless defined? XmlSimple
15
+ rescue Exception => e
16
+ require 'xml-simple' unless defined? XmlSimple
17
+ end
18
+
19
+
20
+ # A custom implementation of Hash that allows us to access hash values using dot notation
21
+ #
22
+ # @example Access the hash keys in the standard way or using dot notation
23
+ # foo[:bar] => "baz"
24
+ # foo.bar => "baz"
25
+ class Hash
26
+ def method_missing(meth, *args, &block)
27
+ if args.size == 0
28
+ self[meth.to_s] || self[meth.to_sym]
29
+ end
30
+ end
31
+ end
32
+
33
+
9
34
  module AWS
10
- # Builds the canonical string for signing. This strips out all '&', '?', and '='
11
- # from the query string to be signed.
12
- # Note: The parameters in the path passed in must already be sorted in
13
- # case-insensitive alphabetical order and must not be url encoded.
35
+
36
+ # Builds the canonical string for signing requests. This strips out all '&', '?', and '='
37
+ # from the query string to be signed. The parameters in the path passed in must already
38
+ # be sorted in case-insensitive alphabetical order and must not be url encoded.
39
+ #
40
+ # @param [String] params the params that will be sorted and encoded as a canonical string.
41
+ # @param [String] host the hostname of the API endpoint.
42
+ # @param [String] method the HTTP method that will be used to submit the params.
43
+ # @param [String] base the URI path that this information will be submitted to.
44
+ # @return [String] the canonical request description string.
14
45
  def AWS.canonical_string(params, host, method="POST", base="/")
15
46
  # Sort, and encode parameters into a canonical string.
16
47
  sorted_params = params.sort {|x,y| x[0] <=> y[0]}
@@ -31,10 +62,15 @@ module AWS
31
62
 
32
63
  end
33
64
 
34
- # Encodes the given string with the secret_access_key, by taking the
65
+ # Encodes the given string with the secret_access_key by taking the
35
66
  # hmac-sha1 sum, and then base64 encoding it. Optionally, it will also
36
67
  # url encode the result of that to protect the string if it's going to
37
68
  # be used as a query string parameter.
69
+ #
70
+ # @param [String] secret_access_key the user's secret access key for signing.
71
+ # @param [String] str the string to be hashed and encoded.
72
+ # @param [Boolean] urlencode whether or not to url encode the result., true or false
73
+ # @return [String] the signed and encoded string.
38
74
  def AWS.encode(secret_access_key, str, urlencode=true)
39
75
  digest = OpenSSL::Digest::Digest.new('sha1')
40
76
  b64_hmac =
@@ -48,10 +84,21 @@ module AWS
48
84
  end
49
85
  end
50
86
 
87
+ # This class provides all the methods for using the EC2 or ELB service
88
+ # including the handling of header signing and other security concerns.
89
+ # This class uses the Net::HTTP library to interface with the AWS Query API
90
+ # interface. You should not instantiate this directly, instead
91
+ # you should setup an instance of 'AWS::EC2::Base' or 'AWS::ELB::Base'.
51
92
  class Base
52
93
 
53
94
  attr_reader :use_ssl, :server, :proxy_server, :port
54
95
 
96
+ # @option options [String] :access_key_id ("") The user's AWS Access Key ID
97
+ # @option options [String] :secret_access_key ("") The user's AWS Secret Access Key
98
+ # @option options [Boolean] :use_ssl (true) Connect using SSL?
99
+ # @option options [String] :server ("ec2.amazonaws.com") The server API endpoint host
100
+ # @option options [String] :proxy_server (nil) An HTTP proxy server FQDN
101
+ # @return [Object] the object.
55
102
  def initialize( options = {} )
56
103
 
57
104
  options = { :access_key_id => "",
@@ -242,4 +289,5 @@ module AWS
242
289
  end
243
290
  end
244
291
 
245
- Dir[File.join(File.dirname(__FILE__), 'AWS/*.rb')].sort.each { |lib| require lib }
292
+ Dir[File.join(File.dirname(__FILE__), 'AWS/**/*.rb')].sort.each { |lib| require lib }
293
+
data/lib/AWS/EC2.rb CHANGED
@@ -1,58 +1,23 @@
1
- #--
2
- # Amazon Web Services EC2 Query API Ruby library
3
- #
4
- # Ruby Gem Name:: amazon-ec2
5
- # Author:: Glenn Rempe (mailto:glenn@rempe.us)
6
- # Copyright:: Copyright (c) 2007-2008 Glenn Rempe
7
- # License:: Distributes under the same terms as Ruby
8
- # Home:: http://github.com/grempe/amazon-ec2/tree/master
9
- #++
10
-
11
- # Require any lib files that we have bundled with this Ruby Gem in the lib/EC2 directory.
12
- # Parts of the EC2 module and Base class are broken out into separate
13
- # files for maintainability and are organized by the functional groupings defined
14
- # in the EC2 API developers guide.
15
- Dir[File.join(File.dirname(__FILE__), 'EC2/**/*.rb')].sort.each { |lib| require lib }
16
-
17
1
  module AWS
18
2
  module EC2
19
3
 
20
4
  # Which host FQDN will we connect to for all API calls to AWS?
21
- # If EC2_URL is defined in the users ENV we can use that. It is
22
- # expected that this var is set with something like:
23
- # export EC2_URL='https://ec2.amazonaws.com'
5
+ # If EC2_URL is defined in the users ENV we can override the default with that.
24
6
  #
7
+ # @example
8
+ # export EC2_URL='https://ec2.amazonaws.com'
25
9
  if ENV['EC2_URL']
26
10
  EC2_URL = ENV['EC2_URL']
27
11
  VALID_HOSTS = ['https://ec2.amazonaws.com', 'https://us-east-1.ec2.amazonaws.com', 'https://eu-west-1.ec2.amazonaws.com']
28
12
  raise ArgumentError, "Invalid EC2_URL environment variable : #{EC2_URL}" unless VALID_HOSTS.include?(EC2_URL)
29
13
  DEFAULT_HOST = URI.parse(EC2_URL).host
30
14
  else
31
- # default US host
15
+ # Default US API endpoint
32
16
  DEFAULT_HOST = 'ec2.amazonaws.com'
33
17
  end
34
18
 
35
- # This is the version of the API as defined by Amazon Web Services
36
19
  API_VERSION = '2008-12-01'
37
20
 
38
- #Introduction:
39
- #
40
- # The library exposes one main interface class, 'AWS::EC2::Base'.
41
- # This class provides all the methods for using the EC2 service
42
- # including the handling of header signing and other security issues .
43
- # This class uses Net::HTTP to interface with the EC2 Query API interface.
44
- #
45
- #Required Arguments:
46
- #
47
- # :access_key_id => String (default : "")
48
- # :secret_access_key => String (default : "")
49
- #
50
- #Optional Arguments:
51
- #
52
- # :use_ssl => Boolean (default : true)
53
- # :server => String (default : 'ec2.amazonaws.com')
54
- # :proxy_server => String (default : nil)
55
- #
56
21
  class Base < AWS::Base
57
22
  def api_version
58
23
  API_VERSION
@@ -64,4 +29,5 @@ module AWS
64
29
  end
65
30
 
66
31
  end
67
- end
32
+ end
33
+
@@ -1,43 +1,21 @@
1
- #--
2
- # Amazon Web Services EC2 Query API Ruby library
3
- #
4
- # Ruby Gem Name:: amazon-ec2
5
- # Author:: Glenn Rempe (mailto:glenn@rempe.us)
6
- # Copyright:: Copyright (c) 2007-2008 Glenn Rempe
7
- # License:: Distributes under the same terms as Ruby
8
- # Home:: http://github.com/grempe/amazon-ec2/tree/master
9
- #++
10
-
11
1
  module AWS
12
2
  module EC2
13
-
14
3
  class Base < AWS::Base
15
4
 
16
- #Amazon Developer Guide Docs:
17
- #
18
5
  # The DescribeAvailabilityZones operation describes availability zones that are currently
19
6
  # available to the account and their states.
20
7
  #
21
8
  # An optional list of zone names can be passed.
22
9
  #
23
- #Required Arguments:
24
- #
25
- # none
10
+ # @option options [optional, String] :zone_name ([]) an Array of zone names
26
11
  #
27
- #Optional Arguments:
28
- #
29
- # :zone_name => Array (default : [])
30
- #
31
-
32
12
  def describe_availability_zones( options = {} )
33
-
34
13
  options = { :zone_name => [] }.merge(options)
35
-
36
14
  params = pathlist("ZoneName", options[:zone_name] )
37
-
38
15
  return response_generator(:action => "DescribeAvailabilityZones", :params => params)
39
-
40
16
  end
17
+
41
18
  end
42
19
  end
43
- end
20
+ end
21
+
@@ -1,46 +1,23 @@
1
- #--
2
- # Amazon Web Services EC2 Query API Ruby library
3
- #
4
- # Ruby Gem Name:: amazon-ec2
5
- # Author:: Glenn Rempe (mailto:glenn@rempe.us)
6
- # Copyright:: Copyright (c) 2007-2008 Glenn Rempe
7
- # License:: Distributes under the same terms as Ruby
8
- # Home:: http://github.com/grempe/amazon-ec2/tree/master
9
- #++
10
-
11
1
  module AWS
12
2
  module EC2
13
-
14
3
  class Base < AWS::Base
15
4
 
16
- #Amazon Developer Guide Docs:
17
- #
18
5
  # The GetConsoleOutput operation retrieves console output that has been posted for the specified instance.
19
6
  #
20
7
  # Instance console output is buffered and posted shortly after instance boot, reboot and once the instance
21
8
  # is terminated. Only the most recent 64 KB of posted output is available. Console output is available for
22
9
  # at least 1 hour after the most recent post.
23
10
  #
24
- #Required Arguments:
25
- #
26
- # :instance_id => String (default : "")
11
+ # @option options [String] :instance_id ("") an Instance ID
27
12
  #
28
- #Optional Arguments:
29
- #
30
- # none
31
- #
32
- def get_console_output( options ={} )
33
-
13
+ def get_console_output( options = {} )
34
14
  options = {:instance_id => ""}.merge(options)
35
-
36
15
  raise ArgumentError, "No instance ID provided" if options[:instance_id].nil? || options[:instance_id].empty?
37
-
38
16
  params = { "InstanceId" => options[:instance_id] }
39
-
40
17
  return response_generator(:action => "GetConsoleOutput", :params => params)
41
-
42
18
  end
43
- end
44
19
 
20
+ end
45
21
  end
46
- end
22
+ end
23
+
@@ -1,60 +1,23 @@
1
- #--
2
- # Amazon Web Services EC2 Query API Ruby library
3
- #
4
- # Ruby Gem Name:: amazon-ec2
5
- # Author:: Glenn Rempe (mailto:glenn@rempe.us)
6
- # Copyright:: Copyright (c) 2007-2008 Glenn Rempe
7
- # License:: Distributes under the same terms as Ruby
8
- # Home:: http://github.com/grempe/amazon-ec2/tree/master
9
- #++
10
-
11
1
  module AWS
12
2
  module EC2
13
3
  class Base < AWS::Base
14
4
 
15
-
16
- #Amazon Developer Guide Docs:
17
- #
18
5
  # The AllocateAddress operation acquires an elastic IP address for use with your account.
19
6
  #
20
- #Required Arguments:
21
- #
22
- # none
23
- #
24
- #Optional Arguments:
25
- #
26
- # none
27
- #
28
7
  def allocate_address
29
-
30
8
  return response_generator(:action => "AllocateAddress")
31
-
32
9
  end
33
10
 
34
- #Amazon Developer Guide Docs:
35
- #
36
11
  # The DescribeAddresses operation lists elastic IP addresses assigned to your account.
37
12
  #
38
- #Required Arguments:
39
- #
40
- # :public_ip => Array (default : [], can be empty)
41
- #
42
- #Optional Arguments:
43
- #
44
- # none
13
+ # @option options [Array] :public_ip ([]) an IP address to be described
45
14
  #
46
15
  def describe_addresses( options = {} )
47
-
48
16
  options = { :public_ip => [] }.merge(options)
49
-
50
17
  params = pathlist("PublicIp", options[:public_ip])
51
-
52
18
  return response_generator(:action => "DescribeAddresses", :params => params)
53
-
54
19
  end
55
20
 
56
- #Amazon Developer Guide Docs:
57
- #
58
21
  # The ReleaseAddress operation releases an elastic IP address associated with your account.
59
22
  #
60
23
  # If you run this operation on an elastic IP address that is already released, the address
@@ -68,87 +31,51 @@ module AWS
68
31
  # to update your DNS records and any servers or devices that communicate
69
32
  # with the address.
70
33
  #
71
- #Required Arguments:
72
- #
73
- # :public_ip => String (default : '')
74
- #
75
- #Optional Arguments:
76
- #
77
- # none
34
+ # @option options [String] :public_ip ('') an IP address to be released.
78
35
  #
79
36
  def release_address( options = {} )
80
-
81
37
  options = { :public_ip => '' }.merge(options)
82
-
83
38
  raise ArgumentError, "No ':public_ip' provided" if options[:public_ip].nil? || options[:public_ip].empty?
84
-
85
39
  params = { "PublicIp" => options[:public_ip] }
86
-
87
40
  return response_generator(:action => "ReleaseAddress", :params => params)
88
-
89
41
  end
90
42
 
91
- #Amazon Developer Guide Docs:
92
- #
93
43
  # The AssociateAddress operation associates an elastic IP address with an instance.
94
44
  #
95
45
  # If the IP address is currently assigned to another instance, the IP address
96
46
  # is assigned to the new instance. This is an idempotent operation. If you enter
97
47
  # it more than once, Amazon EC2 does not return an error.
98
48
  #
99
- #Required Arguments:
100
- #
101
- # :instance_id => String (default : '')
102
- # :public_ip => String (default : '')
103
- #
104
- #Optional Arguments:
105
- #
106
- # none
49
+ # @option options [String] :instance_id ('') the instance ID to associate an IP with.
50
+ # @option options [String] :public_ip ('') the public IP to associate an instance with.
107
51
  #
108
52
  def associate_address( options = {} )
109
-
110
53
  options = { :instance_id => '', :public_ip => '' }.merge(options)
111
-
112
54
  raise ArgumentError, "No ':instance_id' provided" if options[:instance_id].nil? || options[:instance_id].empty?
113
55
  raise ArgumentError, "No ':public_ip' provided" if options[:public_ip].nil? || options[:public_ip].empty?
114
-
115
56
  params = {
116
57
  "InstanceId" => options[:instance_id],
117
58
  "PublicIp" => options[:public_ip]
118
59
  }
119
-
120
60
  return response_generator(:action => "AssociateAddress", :params => params)
121
-
122
61
  end
123
62
 
124
- #Amazon Developer Guide Docs:
125
- #
126
63
  # The DisassociateAddress operation disassociates the specified elastic IP
127
64
  # address from the instance to which it is assigned. This is an idempotent
128
65
  # operation. If you enter it more than once, Amazon EC2 does not return
129
66
  # an error.
130
67
  #
131
- #Required Arguments:
132
- #
133
- # :public_ip => String (default : '')
134
- #
135
- #Optional Arguments:
136
- #
137
- # none
68
+ # @option options [String] :public_ip ('') the public IP to be dis-associated.
138
69
  #
139
70
  def disassociate_address( options = {} )
140
-
141
71
  options = { :public_ip => '' }.merge(options)
142
-
143
72
  raise ArgumentError, "No ':public_ip' provided" if options[:public_ip].nil? || options[:public_ip].empty?
144
-
145
73
  params = { "PublicIp" => options[:public_ip] }
146
-
147
74
  return response_generator(:action => "DisassociateAddress", :params => params)
148
-
149
75
  end
150
76
 
151
77
  end
152
78
 
153
79
  end
154
- end
80
+ end
81
+