nirvdrum-amazon-ec2 0.7.9

Sign up to get free protection for your applications and to get access to all the features.
Files changed (69) hide show
  1. data/.gitignore +9 -0
  2. data/.yardopts +1 -0
  3. data/ChangeLog +304 -0
  4. data/LICENSE +66 -0
  5. data/README.rdoc +359 -0
  6. data/README_dev.rdoc +10 -0
  7. data/Rakefile +70 -0
  8. data/VERSION +1 -0
  9. data/amazon-ec2.gemspec +142 -0
  10. data/bin/ec2-gem-example.rb +137 -0
  11. data/bin/ec2-gem-profile.rb +10 -0
  12. data/bin/ec2sh +62 -0
  13. data/bin/setup.rb +29 -0
  14. data/deps.rip +1 -0
  15. data/lib/AWS.rb +321 -0
  16. data/lib/AWS/Autoscaling.rb +70 -0
  17. data/lib/AWS/Autoscaling/autoscaling.rb +273 -0
  18. data/lib/AWS/Cloudwatch.rb +32 -0
  19. data/lib/AWS/Cloudwatch/monitoring.rb +80 -0
  20. data/lib/AWS/EC2.rb +33 -0
  21. data/lib/AWS/EC2/availability_zones.rb +29 -0
  22. data/lib/AWS/EC2/console.rb +25 -0
  23. data/lib/AWS/EC2/devpay.rb +18 -0
  24. data/lib/AWS/EC2/elastic_ips.rb +86 -0
  25. data/lib/AWS/EC2/image_attributes.rb +133 -0
  26. data/lib/AWS/EC2/images.rb +117 -0
  27. data/lib/AWS/EC2/instances.rb +234 -0
  28. data/lib/AWS/EC2/keypairs.rb +47 -0
  29. data/lib/AWS/EC2/products.rb +21 -0
  30. data/lib/AWS/EC2/security_groups.rb +164 -0
  31. data/lib/AWS/EC2/snapshots.rb +102 -0
  32. data/lib/AWS/EC2/spot_instance_requests.rb +105 -0
  33. data/lib/AWS/EC2/volumes.rb +100 -0
  34. data/lib/AWS/ELB.rb +71 -0
  35. data/lib/AWS/ELB/load_balancers.rb +178 -0
  36. data/lib/AWS/RDS.rb +73 -0
  37. data/lib/AWS/RDS/rds.rb +522 -0
  38. data/lib/AWS/exceptions.rb +200 -0
  39. data/lib/AWS/responses.rb +21 -0
  40. data/perftools/ec2prof +0 -0
  41. data/perftools/ec2prof-results.dot +132 -0
  42. data/perftools/ec2prof-results.txt +100 -0
  43. data/perftools/ec2prof.symbols +102 -0
  44. data/test/test_Autoscaling_groups.rb +337 -0
  45. data/test/test_EC2.rb +68 -0
  46. data/test/test_EC2_availability_zones.rb +49 -0
  47. data/test/test_EC2_console.rb +54 -0
  48. data/test/test_EC2_elastic_ips.rb +144 -0
  49. data/test/test_EC2_image_attributes.rb +238 -0
  50. data/test/test_EC2_images.rb +229 -0
  51. data/test/test_EC2_instances.rb +611 -0
  52. data/test/test_EC2_keypairs.rb +123 -0
  53. data/test/test_EC2_products.rb +48 -0
  54. data/test/test_EC2_responses.rb +53 -0
  55. data/test/test_EC2_s3_xmlsimple.rb +80 -0
  56. data/test/test_EC2_security_groups.rb +205 -0
  57. data/test/test_EC2_snapshots.rb +83 -0
  58. data/test/test_EC2_spot_instance_requests.rb +178 -0
  59. data/test/test_EC2_volumes.rb +142 -0
  60. data/test/test_ELB_load_balancers.rb +239 -0
  61. data/test/test_RDS.rb +354 -0
  62. data/test/test_helper.rb +23 -0
  63. data/wsdl/2007-08-29.ec2.wsdl +1269 -0
  64. data/wsdl/2008-02-01.ec2.wsdl +1614 -0
  65. data/wsdl/2008-05-05.ec2.wsdl +2052 -0
  66. data/wsdl/2008-12-01.ec2.wsdl +2354 -0
  67. data/wsdl/2009-10-31.ec2.wsdl +4261 -0
  68. data/wsdl/2009-11-30.ec2.wsdl +4668 -0
  69. metadata +199 -0
@@ -0,0 +1,9 @@
1
+ *.sw?
2
+ .DS_Store
3
+ coverage
4
+ rdoc
5
+ doc
6
+ .yardoc
7
+ pkg
8
+ .idea
9
+
@@ -0,0 +1 @@
1
+ --title amazon-ec2 - ChangeLog LICENSE
@@ -0,0 +1,304 @@
1
+ === 0.7.4 2009-12-05
2
+ * Initial support for new EBS AMI's
3
+ * Updated EC2 API version
4
+ * Added US West 1 Data Center to list of valid endpoints. (us-west-1.ec2.amazonaws.com)
5
+ * Updated exceptions.rb to be in sync with latest documented exceptions.
6
+ * Updated #run_instances to support EBS AMI's and sync with latest options.
7
+ * Added new #stop_instances and #start_instances methods.
8
+ * Added new #create_image to allow bundling of a running instance to an EBS backed AMI.
9
+ * Added stub methods for all known missing EC2 methods. (Please help with patches + tests!)
10
+ * Added and updated tests for new/modified methods.
11
+
12
+ === 0.6.1 2009-10-13
13
+ * Additional commits for AutoScaling. Thanks to Ari (auser)!
14
+ * Updated README.rdoc installation instructions. Reflects removal of deprecated GitHub gem building.
15
+
16
+ === 0.6.0 2009-09-30
17
+ * Added support for AWS AutoScaling for EC2. Thanks to Ari Lerner (auser)!
18
+
19
+ === 0.5.2 2009-08-20
20
+ * Converted to YardDoc documentation format. See : http://yard.soen.ca/getting_started
21
+
22
+ === 0.5.0 2009-08-11
23
+ * Major re-factor by Kris Rasmussen (krisr) to add support for the AWS Elastic Load Balancer API. Kudos Kris!
24
+
25
+ === 0.4.0 2009-06-06
26
+ * Using technicalpickles/jeweler to manage gem now. See : http://github.com/technicalpickles/jeweler/tree/master
27
+
28
+ === 0.3.8 2009-04-16
29
+ * Applied patch, with updated tests to fix issue with base64 encoded user data (rsanheim).
30
+ * Applied patch, fixing an issue with EU Signature version 2 creation (delano).
31
+
32
+ === 0.3.6 2009-03-02
33
+ * You can now specify any arbitrary SSL tcp port to connect to (kerryb)
34
+ * Added rake target to quickly install the gem without docs
35
+
36
+ === 0.3.5 2009-02-26
37
+ * Honor the EC2_URL env var if provided in the main lib
38
+ * Some minor modifications to the exceptions raised when unknown
39
+
40
+ === 0.3.4 2009-01-31
41
+ * Added support in the helper binaries for EC2_URL server url for Euro servers
42
+ * AWS Signature v2 support
43
+
44
+ === 0.3.3 2009-01-24
45
+ * Removed docs related to the ability to get Response#xml which is deprecated
46
+ * Fixed conflict when aws/s3 gem was included in user code
47
+
48
+ === 0.3.2 2008-12-11
49
+ * Updated API version to 2008-12-01
50
+ * Note : The new European EC2 zone should just work if you specify ':server => "eu-west-1.ec2.amazonaws.com"' when initializing AWS::EC2::Base.new(). Please report any issues you have with using this new service.
51
+
52
+ === 0.3.1 2008-09-18
53
+ * Added basic custom kernel id support to run_instances. Thanks to Keith Hudgins for the patch.
54
+
55
+ === 0.3.0 2008-08-24
56
+ * Changed response object from AmazonAWS::Response to Hash (patch from Yan Pritzker 'skwp') Thanks!
57
+ * Added support for Elastic Block Storage (patch from Yann Klis 'yannski') Thanks!
58
+ * Bumped AWS EC2 API version to 2008-05-05
59
+ * Bumped gem version number
60
+ * Whitespace cleanup
61
+
62
+ === 0.2.15 2008-08-20
63
+ * Updated gem install instructions, and dependency specifications in the gemspec.
64
+
65
+ === 0.2.14 2008-06-30
66
+ * Merged patch from 'orionz' which adds support for EC2 Availability Zones. Thanks!
67
+
68
+ === 0.2.12 2008-04-25
69
+ * A few adjustments to work with GitHub.
70
+
71
+ === 0.2.11 2008-04-25
72
+ * Moved gem completely to GitHub.
73
+ * Removed a LOT of RubyForge related cruft that's no longer needed.
74
+
75
+ === 0.2.10 2008-04-13
76
+ * Fix bug where ec2#disassociate_address would return 'undefined method 'reject!' for "xxx.xxx.xxx.xxx":String'.
77
+ Thanks to Brian Thomas for reporting.
78
+
79
+ === 0.2.9 2008-03-31
80
+ * Added initial support for API version 2008-02-01. Support for new 'Elastic IP' functionality added.
81
+
82
+ === 0.2.8 2008-02-25
83
+ * Change HTTP API requests to use POST instead of GET. Based on patch #18380 from 'anonymous'.
84
+
85
+ === 0.2.7 2008-02-17
86
+ * Add support for HTTP Proxy when :proxy_server argument is passed. Based on patch from Mathias Dalheimer.
87
+
88
+ === 0.2.6 2007-10-16
89
+ * Updated to support EC2 API version 2007-08-29 released on 2007-10-16
90
+ * Supports new instances type feature. Specify an instance type to launch
91
+ (m1.small, m1.large, m1.xlarge) when you call the 'run_instances' method.
92
+
93
+ e.g. add to the params hash ':instance_type => "m1.small"'
94
+ * RunInstances and DescribeInstances now return the time when the Amazon EC2 instance was launched.
95
+ * Code Tidyup : Removed trailing spaces in code docs.
96
+
97
+ === 0.2.5 2007-09-26
98
+ * Updated using Dr. Nic's newgem v. 0.13.5
99
+ * Updated email address.
100
+ * No functional changes in the gem.
101
+
102
+ === 0.2.4 2007-07-09
103
+ * Changed how require statement for xmlsimple is called so we don't get warnings when running in rails.
104
+ Now it looks like: require 'xmlsimple' unless defined? XmlSimple
105
+
106
+ === 0.2.3 2007-07-06
107
+ * Updated gem to work with new official release of AWS API version 2007-03-01 which occurred
108
+ on July 6, 2007.
109
+ * Added support for primary new feature which supports Paid AMI's and the product codes
110
+ associated with them. Modified several methods to support this change, updated the test
111
+ cases, and added a new method EC2#confirm_product_instance.
112
+
113
+ === 0.2.2 2007-07-03
114
+ * Minor change to test case.
115
+
116
+ === 0.2.1 2007-07-03
117
+ * Some minor changes to the RDocs and README.txt
118
+
119
+ === 0.2.0 2007-07-03
120
+
121
+ * MAJOR library changes : THESE CHANGES ARE NOT BACKWARD COMPATIBLE!! You will need to update
122
+ the way in which you make calls, handle responses, and rescue exceptions from this library.
123
+ If you prefer not to make these changes you can feel free to continue to use the older version
124
+ of the gem. These older versions however will no longer be maintained.
125
+
126
+ * MAJOR refactoring of how methods calls are made. Now all methods are called with a simple hash
127
+ of arguments and none of them are positional. This feels much more "Ruby'ish".
128
+
129
+ * MAJOR refactoring of how responses are returned to users. No longer do you have to call the
130
+ .parse method, and no longer are you getting back simple arrays of information. Responses
131
+ now come in the form of OpenStruct objects that contain all of the data for an object in
132
+ Enumerable form so you can use iterators (.each, .each_pair, etc). All methods return an AWS::Response object
133
+ which inherits from OpenStruct. The return data from EC2, which is in XML form, is parsed
134
+ with XmlSimple and is used to directly construct the return data structure. This allows us
135
+ to know with some confidence that the data structure returned from AWS will always be consistent
136
+ with this library's responses. There is also an .xml attribute for each response object that lets you
137
+ see the full and complete XML response from AWS if that is useful to you.
138
+
139
+ * Added an exception framework which will now throw appropriate Ruby exceptions
140
+ that match those handed to us by Amazon EC2. ArgumentError exceptions will also
141
+ be thrown if you are making calls we know to be illegal or malformed. You should rescue
142
+ these exceptions in your application instead of parsing text responses. All exceptions
143
+ descend from AWS::Error. You can see them all in exceptions.rb in the gem install.
144
+
145
+ * Added a full suite of test/spec unit tests which currently cover 100% of the public methods
146
+ in this library. We have abot 92% code coverage according to rcov. This has greatly enhanced
147
+ the reliability of the library as well as our confidence in the code.
148
+ We used to have 0% test coverage. :-/
149
+
150
+ * Added an EC2 command shell : 'ec2sh' which can be called from anywhere and gives you
151
+ an interactive irb session with an EC2 connection pre-made for you as @ec2. You can use this
152
+ to interactively execute any command on EC2 that this library supports. Try @ec2.methods.sort
153
+ or @ec2.describe_images to test it out. You must first setup two shell environment variables
154
+ which contain your ACCESS_KEY_ID and SECRET_ACCESS_KEY for this to work. Otherwise an error
155
+ will be thrown when you try to start it. This is way cool and shamelessly borrowed from
156
+ Marcel Molina's fine AWS::S3 library.
157
+
158
+ * Updated API version in the query API request to 2007-01-19, and added all known method calls
159
+ in this version of the API to the gem (including reboot, viewing console output, NAT addressing
160
+ and more!)
161
+
162
+ * Removed .parse method as it is no longer needed or wanted.
163
+
164
+ * Removed 'verbose' attribute writer and a couple of related debug 'puts' calls in EC2.rb.
165
+
166
+ * Removed deprecated alias's used in the library that were added in v0.0.3
167
+
168
+ * Gem now requires XmlSimple gem to be installed.
169
+
170
+
171
+ === 0.1.0 2007-05-30
172
+
173
+ * Repackaged with updated newgem generator v. 0.10.3 from http://newgem.rubyforge.org/ to take advantage of new deployment goodness.
174
+
175
+
176
+ === 0.0.7 2007-03-15
177
+
178
+ * Applied patch from Kevin Clark which does the following:
179
+ * New method to the instances.rb to allow for issuing a reboot command to an EC2 instance.
180
+ * New Mocha based tests (Mocha test suite must be installed to run tests. 'sudo gem install mocha')
181
+ * Cleanup of the test directory.
182
+ * Applied patch from Randy Bias related to CGI escaping error. From his notes:
183
+
184
+ I finally figured out what was going on. It was a compound problem. The first being that you can't
185
+ CGI::encode the UserData early. You have to just Base64 encode it. Unfortunately, when you Base64
186
+ encode it, it means that some encodings will be padded with extra chars, specifically the '=', but &, ?
187
+ and = get stripped by EC2.canonial_string. So if a Base64 encoding has trailing ='s for padding,
188
+ these get stripped and then you sign the UserData Base64 payload sans the padding. But it looks
189
+ like Amazon's side is doing the right thing and is signing the padding. So, the signatures mis-match.
190
+
191
+ I've got the complete patch here and it's about as elegant/clean as I could make it in a short
192
+ period of time. It's a little tough to strip those equal signs when there are so many in the URI.
193
+ I think this works pretty well, though. I'm splitting the URI on '&', then for each field ripping
194
+ out all '&' and '?' and only the first '='. Then stitching it back together.
195
+
196
+
197
+ === 0.0.6 2007-03-02
198
+ * Patched instances.rb with a bugfix and patch provided by Randy Bias (Thanks Randy!).
199
+ Only minimally tested so please let me know if this causes any problems for anyone.
200
+
201
+ From his notes:
202
+ I wanted to let you know that there appears to be a bug in how user data is passed. In
203
+ instances.rb the line that creates the base64 encoded package of user data is as follows:
204
+
205
+ userData = CGI::escape(Base64.encode64(in_params[:userData]).strip())
206
+
207
+ This may have worked prior, but at least right now the CGI::escape appears to cause a
208
+ breakage. More specifically it turns something like this (the actual base64 encoded string):
209
+
210
+ YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh
211
+ eHh4eHh4eHh4eHh4eHh4eHh4eHgg
212
+
213
+ Into this:
214
+
215
+ YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh%
216
+ 0AeHh4eHh4eHh4eHh4eHh4eHh4eHgg
217
+
218
+ And it looks like EC2 chokes on the %0, which is CGI::escape's way for handling an EOL.
219
+ Unfortunately, the Base64.encode64 (at least in my 1.8.5 version of Ruby) inserts a
220
+ EOL at every 47 chars, no matter what:
221
+
222
+ ---
223
+ [randyb@master randyb] cat /tmp/foo.rb
224
+ #!/usr/bin/env ruby
225
+ #
226
+ require 'rubygems'
227
+ require_gem 'amazon-ec2'
228
+ require 'getoptlong'
229
+ puts Base64.encode64
230
+ ("012345678901234567890123456789012345678901234567890123456789")
231
+
232
+ [randyb@master randyb] /tmp/foo.rb
233
+ MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0
234
+ NTY3ODkwMTIzNDU2Nzg5
235
+ ---
236
+
237
+ The best way to handle this is to strip the CRLFs/EOLs before passing to CGI.escape.
238
+
239
+
240
+ === 0.0.5 2006-12-21
241
+
242
+ * Changes to home page documentation and example files to indicate that you
243
+ should use 'require_gem' instead of a simple require. Not sure if this
244
+ is a result of something I am doing in the packaging of the gem that is
245
+ incorrect or if this is right and proper. I will investigate further.
246
+ * Patched instances.rb run_instances method to allow for submission of
247
+ user data with the command to start an instance. Patch submitted
248
+ anonymously on RubyForge. This had not been functionally implemented
249
+ in the Amazon Web Services sample library prior to this patch.
250
+ * Added simple framework for adding unit tests for the library under test dir.
251
+ No functional unit tests exist yet.
252
+
253
+
254
+ === 0.0.4 2006-12-21
255
+
256
+ * Applied patch from Kevin Clark to svn version 7. Thanks for the
257
+ patch and the description Kevin! Please report if you
258
+ encounter any issues with this patched version. Here is Kevin's
259
+ description which I requested : "It helps me to think of modules as boxes full of classes and
260
+ methods. REXML is a module which holds various classes related to parsing XML
261
+ including REXML::Node, REXML::Document and REXML::XPath. When you
262
+ include a module it takes everything out of the box and places it in
263
+ the local context. So, when you include REXML in the global namespace
264
+ on line 27 of EC2.rb, it includes classes called Node, Document and XPath in the
265
+ global object space. This means that I can't have a class called Node
266
+ in my own project (which I do). The library would be a much better
267
+ neighbor if it instead accessed the REXML::Document and REXML::XPath
268
+ classes explicitly through the module."
269
+
270
+
271
+ === 0.0.3 2006-12-16
272
+
273
+ * API CHANGE : Changed method name 'authorize' to 'authorize_security_group_ingress' to ensure consistent
274
+ naming of Ruby library methods to match AWS EC2 API actions. Alias to 'authorize' for backwards compatibility.
275
+ * API CHANGE : Changed method name 'revoke' to 'revoke_security_group_ingress' to ensure consistent
276
+ naming of Ruby library methods to match AWS EC2 API actions. Alias to 'revoke' for backwards compatibility.
277
+ * API CHANGE : Changed method name 'delete_securitygroup' to 'delete_security_group' to ensure consistent
278
+ naming of Ruby library methods to match AWS EC2 API actions. Alias to 'delete_securitygroup' for backwards compatibility.
279
+ * API CHANGE : Changed method name 'describe_securitygroups' to 'describe_security_group' to ensure consistent
280
+ naming of Ruby library methods to match AWS EC2 API actions. Alias to 'describe_securitygroups' for backwards compatibility.
281
+ * API CHANGE : Changed method name 'create_securitygroup' to 'create_security_group' to ensure consistent
282
+ naming of Ruby library methods to match AWS EC2 API actions. Alias to 'create_securitygroup' for backwards compatibility.
283
+ * Added many API rdoc's, some method descriptions copied from Amazon Query API Developer Guide.
284
+ * Extracted some parts of the formerly monolithic EC2 library out into separate files for manageability.
285
+ * Changed the HTTP 'User-Agent' string used for each request so that we have our own user agent
286
+ to identify this library's calls. Now set the version # in the user agent string based on the
287
+ master version number for this library which is stored in lib/EC2/version.rb and should only
288
+ be defined in one place.
289
+ * Set @http.verify_mode = OpenSSL::SSL::VERIFY_NONE to avoid seeing SSL Cert warning
290
+ "warning: peer certificate won't be verified in this SSL session". File EC2.rb:96
291
+ * Make 'pathlist' utility method a private method (EC2.rb:111). No reason I can see for this to be exposed.
292
+
293
+
294
+ === 0.0.2 2006-12-14
295
+
296
+ * Bugfix in run_instances method. Method works now. Patch submitted by Stephen Caudill on AWS forums. Thanks!
297
+
298
+
299
+ === 0.0.1 2006-12-13
300
+
301
+ * Initial release of the Ruby Gem. This includes the version of the library exactly as provided by
302
+ Amazon Web Services as example code. No changes or enhancements to that code were made other than
303
+ packaging it as a Ruby Gem.
304
+ * RubyForge project created. http://github.com/grempe/amazon-ec2/tree/master
data/LICENSE ADDED
@@ -0,0 +1,66 @@
1
+ Copyright (c) 2007-2009 Glenn Rempe
2
+
3
+ This software is distributed under the Ruby License. A copy of which is
4
+ provided below.
5
+
6
+ RUBY LICENSE
7
+
8
+ http://www.ruby-lang.org/en/LICENSE.txt
9
+
10
+ Ruby is copyrighted free software by Yukihiro Matsumoto <matz@netlab.co.jp>.
11
+ You can redistribute it and/or modify it under either the terms of the GPL
12
+ (see COPYING.txt file), or the conditions below:
13
+
14
+ 1. You may make and give away verbatim copies of the source form of the
15
+ software without restriction, provided that you duplicate all of the
16
+ original copyright notices and associated disclaimers.
17
+
18
+ 2. You may modify your copy of the software in any way, provided that
19
+ you do at least ONE of the following:
20
+
21
+ a) place your modifications in the Public Domain or otherwise
22
+ make them Freely Available, such as by posting said
23
+ modifications to Usenet or an equivalent medium, or by allowing
24
+ the author to include your modifications in the software.
25
+
26
+ b) use the modified software only within your corporation or
27
+ organization.
28
+
29
+ c) rename any non-standard executables so the names do not conflict
30
+ with standard executables, which must also be provided.
31
+
32
+ d) make other distribution arrangements with the author.
33
+
34
+ 3. You may distribute the software in object code or executable
35
+ form, provided that you do at least ONE of the following:
36
+
37
+ a) distribute the executables and library files of the software,
38
+ together with instructions (in the manual page or equivalent)
39
+ on where to get the original distribution.
40
+
41
+ b) accompany the distribution with the machine-readable source of
42
+ the software.
43
+
44
+ c) give non-standard executables non-standard names, with
45
+ instructions on where to get the original software distribution.
46
+
47
+ d) make other distribution arrangements with the author.
48
+
49
+ 4. You may modify and include the part of the software into any other
50
+ software (possibly commercial). But some files in the distribution
51
+ are not written by the author, so that they are not under this terms.
52
+
53
+ They are gc.c(partly), utils.c(partly), regex.[ch], st.[ch] and some
54
+ files under the ./missing directory. See each file for the copying
55
+ condition.
56
+
57
+ 5. The scripts and library files supplied as input to or produced as
58
+ output from the software do not automatically fall under the
59
+ copyright of the software, but belong to whomever generated them,
60
+ and may be sold commercially, and may be aggregated with this
61
+ software.
62
+
63
+ 6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
64
+ IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
65
+ WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
66
+ PURPOSE.
@@ -0,0 +1,359 @@
1
+ = Amazon Web Services Elastic Compute Cloud (EC2) Ruby Gem
2
+
3
+ == About amazon-ec2
4
+
5
+ Amazon Web Services offers a compute power on demand capability known as the Elastic Compute Cloud (EC2). The server resources in the cloud can be provisioned on demand by making HTTP Query API calls to EC2.
6
+
7
+ This 'amazon-ec2' Ruby Gem is an interface library that can be used to interact with the Amazon EC2 system and control server resources on demand from your Ruby scripts, or from applications written in your Ruby framework of choice (Ruby on Rails, Merb, etc.).
8
+
9
+ More recently, support has been added for the following EC2 related AWS API's as well:
10
+
11
+ * Autoscaling
12
+ * Cloudwatch
13
+ * Elastic Load Balancing (ELB)
14
+ * Relational Database Service (RDS)
15
+
16
+ For the most complete and up-to date README information please visit the project homepage at:
17
+
18
+ http://github.com/grempe/amazon-ec2/tree/master
19
+
20
+ or the official EC2 website at http://aws.amazon.com/ec2
21
+
22
+
23
+ == Installation
24
+
25
+ This gem follows the standard conventions for installation on any system with Ruby and RubyGems installed. If you have worked with gems before this will look very familiar.
26
+
27
+ === Get an AWS account
28
+
29
+ Before you can make use of this gem you will need an Amazon Web Services developer account which you can sign up for at https://aws-portal.amazon.com/gp/aws/developer/registration/index.html. This account must also be specifically enabled for Amazon EC2 usage. AWS will provide you with an 'AWS Access Key ID' and a 'Secret Access Key' which will allow you to authenticate any API calls you make and ensure correct billing to you for usage of the service. Take note of these (and keep them secret!).
30
+
31
+ === Install required gem pre-requisites
32
+
33
+ The following gems should be installed automatically as part of your install of amazon-ec2. Most of them are needed for testing build dependencies but they should be painless to install even if you don't plan on running the tests or building this gem manually on your own.
34
+
35
+ XmlSimple (required)
36
+ Mocha (optional for testing)
37
+ Rcov (optional for testing)
38
+ Test-Spec (optional for testing)
39
+
40
+
41
+ === Install the amazon-ec2 gem (Canonical Release)
42
+
43
+ This is the standard install for stable releases from Gemcutter.
44
+
45
+ # Install the stable release gem from Gemcutter (one time only) ( learn more here : http://gemcutter.org/pages/faq )
46
+ sudo gem install gemcutter
47
+
48
+ # Set Gemcutter to be your canonical gems source (one time only)
49
+ sudo gem tumble
50
+
51
+ # Install the gem
52
+ sudo gem install amazon-ec2
53
+
54
+ # OR if you want to skip the Gemcutter setup
55
+ sudo gem install amazon-ec2 -s http://gemcutter.org
56
+
57
+
58
+ === Install from local Git clone (for amazon-ec2 developers)
59
+
60
+ GitHub has unfortunately given up on the feature they had where they would build gems
61
+ when pushed to git. Too bad. So to install from git, you'll need to clone and build.
62
+
63
+ git clone git://github.com/grempe/amazon-ec2.git
64
+ cd amazon-ec2
65
+ rake gemspec
66
+ rake build
67
+ rake install
68
+
69
+
70
+ === EXPERIMENTAL : Install the amazon-ec2 gem using Rip (for more bleeding edge versions)
71
+
72
+ For those who intend to do development on the gem, or want the bleeding edge. Install Rip as described at hellorip.com.
73
+
74
+ # (Experimental) Install using Rip (hellorip.com) instead of RubyGems
75
+ rip install git://github.com/grempe/amazon-ec2.git
76
+
77
+
78
+ == Using amazon-ec2
79
+
80
+ The library exposes one main interface class AWS::EC2::Base. It is through an instance of this class that you will perform all the operations for using the EC2 service including query string header signing.
81
+
82
+ The public methods on AWS::EC2::Base closely mirror the EC2 Query API, and as such the Query API Reference in the EC2 Developer Guide ( http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=84 ) will prove helpful.
83
+
84
+
85
+ === Setting up
86
+
87
+ The 'ec2sh' and 'ec2-gem-example.rb' scripts which will be introduced to you shortly expect your AWS EC2 credentials to be stored as shell environment variables which are accessible to those scripts. This makes them convenient to use whenever you need to do a quick query to see what images you have available to you, what's running now, or to start or stop an instance on EC2. You'll find 'ec2sh' to be a very handy tool. I'll describe only the OS X route for setting up (of course the setup steps will vary depending on your particular system and preferred shell). If you don't want to do it this way, feel free to copy these scripts from the gem dir to any location where you can run them from and modify them directly to include your credentials.
88
+
89
+ Edit the file ~/.bash_login and add the following to the existing contents:
90
+
91
+ # OPTIONAL : Why 'export RUBYOPT'? Because we leave loading libs up to you... See : http://gist.github.com/54177
92
+ export RUBYOPT="rubygems"
93
+
94
+ # For amazon-ec2 and amazon s3 ruby gems
95
+ export AMAZON_ACCESS_KEY_ID="YOUR_ACCESS_KEY_ID"
96
+ export AMAZON_SECRET_ACCESS_KEY="YOUR_SECRET_ACCESS_KEY_ID"
97
+
98
+ If you are using EC2 in the EU region, make sure you also set:
99
+
100
+ export EC2_URL="https://eu-west-1.ec2.amazonaws.com"
101
+
102
+ (which you have already if you configured standard EC2 command line tools to work with this region).
103
+
104
+ Once you save the file you should close and re-open your terminal so the new variables are made available. You'll need to do this close/re-open step for each terminal window you have open (or issue the 'source ~/.bash_login' command in each). Make sure that this file is only readable by your user so you don't inadvertently expose your credentials to other users on your system.
105
+
106
+ You can verify that this setup is complete by running the 'set' in a command window and seeing that your credentials are in the list of shell variables.
107
+
108
+ === The basics
109
+
110
+ The library exposes one main interface module
111
+
112
+ AWS::EC2::Base
113
+
114
+ This method requires arguments which include your AWS credentials and it will return an object that you can use to make method calls directly against EC2. All the operations for using the EC2 service, including query string header signing, are handled automatically for you. The connection string will look something like this:
115
+
116
+ @ec2 = AWS::EC2::Base.new(:access_key_id => ACCESS_KEY_ID, :secret_access_key => SECRET_ACCESS_KEY)
117
+
118
+ I've tried to keep the public methods on 'amazon-ec2' as close as possible to the AWS EC2 Query API. This similarity allows you to reference the Query API Reference in the EC2 Developer Guide and be able to get started right away. In most cases the methods names only differ in how they are presented. e.g. 'DescribeImages' becomes '#describe_images()' in Ruby. Feel free to browse the full RDoc documentation for all classes and methods of 'amazon-ec2' if you want more details.
119
+
120
+
121
+ === Examples
122
+
123
+ The best way to become familiar with 'amazon-ec2' is to take it for a test drive. We have provided a few simple ways to get you started. There is also some sample code below that should help out in using 'amazon-ec2' with a plain Ruby script, or as part of a Ruby on Rails application.
124
+
125
+ ==== Using the 'ec2-gem-example.rb' sample test script
126
+
127
+ An example Ruby script which exercises the library a bit more is installed for you to check out when you install this gem. You can run this script to verify that everything is setup and working correctly in your environment. Consult the file which is installed at :
128
+
129
+ [your amazon-ec2 gem dir]/examples/ec2-example.rb
130
+
131
+ Since we also package this sample file in the gem's bin/ dir you should also be able to run it from anywhere on your shell path (once you have set your environment variables as described above).
132
+
133
+ ==== Using the 'ec2sh' command shell
134
+
135
+ The 'ec2sh' command shell is actually a standard 'irb' Ruby shell, with the main difference being we read your AWS credentials from your environment and pre-configure a connection string for you. This lets you run any EC2 command very simply. This has proven to be a valuable tool during the development of this gem and you should try it out. Since we install this tool in your system path as part of the installation of this gem, you should be able to simply run 'ec2sh' from any terminal command prompt on your local system. You'll see some basic instructions for use, and a few examples when you start 'ec2sh'. Go ahead and try it out now. We'll wait...
136
+
137
+ If you're not in front of a terminal shell now (perhaps you're browsing this site on your iPhone) this is what you would see:
138
+
139
+
140
+ hostname:/tmp/rails/amazon_test glenn$ ec2sh
141
+
142
+ 'ec2sh' usage :
143
+ This is an interactive 'irb' command shell that allows you to use all
144
+ commands available to the amazon-ec2 gem. You'll find this to be a
145
+ great tool to help you debug issues and practice running commands
146
+ against the live EC2 servers prior to putting them in your code.
147
+
148
+ The EC2 connection is wired to the class instance '@ec2'. Make method calls
149
+ on this to execute commands on EC2. Adding a #to_s
150
+ at the end of any command should give you a full String representation of the
151
+ response. The #xml data is available for each response
152
+ which allows you to view the full and complete XML response returned by
153
+ EC2 without any parsing applied. This is useful for viewing the
154
+ hierarchy of an entire response in a friendly way (if XML is friendly
155
+ to you!). Understanding the hierarchy of the XML response is critical
156
+ to making effective use of this library.
157
+
158
+ Examples to try:
159
+
160
+ returns : all ec2 public methods
161
+ >> @ec2.methods.sort
162
+
163
+ returns : a string representation of ALL images
164
+ >> @ec2.describe_images.to_s
165
+
166
+ returns : an Array of AWS::Response objects, each an EC2 image and its data
167
+ >> @ec2.describe_images.imagesSet.item
168
+ >> @ec2.describe_images.imagesSet.item[0] (a hash representing a single item in that array)
169
+ >> @ec2.describe_images.imagesSet.item[0].to_s (a String representation of that item)
170
+
171
+ >> @ec2.describe_images.imagesSet.item[0].to_s
172
+ => "#<AWS::Response:0x100A465B4 imageId=\"ami-018e6b68\" imageLocation=\"rbuilder-online/phonehome-1.5.6-x86_10132.img.manifest.xml\" imageOwnerId=\"099034111737\" imageState=\"available\" isPublic=\"true\" parent=#<AWS::Response:0x100A469A6 ...>>"
173
+
174
+
175
+ === Ruby script usage example:
176
+
177
+ Try out the following bit of code. This should walk through each image returned by a call to #describe_images and print out its key data. Note in the example below that you cannot walk through the results of the #describe_images call with the '.each' iterator (You'll get errors if you try). You need to instead walk through the Array of items which are in the 'imagesSet' embedded in the response. This reflects exactly the XML hierarchy of data returned from EC2 which we parse to Ruby OpenStruct objects (AWS::Response).
178
+
179
+ #!/usr/bin/env ruby
180
+
181
+ require 'rubygems'
182
+ require 'AWS'
183
+
184
+ ACCESS_KEY_ID = '--YOUR AWS ACCESS KEY ID--'
185
+ SECRET_ACCESS_KEY = '--YOUR AWS SECRET ACCESS KEY--'
186
+
187
+ ec2 = AWS::EC2::Base.new(:access_key_id => ACCESS_KEY_ID, :secret_access_key => SECRET_ACCESS_KEY)
188
+
189
+ puts "----- listing images owned by 'amazon' -----"
190
+ ec2.describe_images(:owner_id => "amazon").imagesSet.item.each do |image|
191
+ # OpenStruct objects have members!
192
+ image.members.each do |member|
193
+ puts "#{member} => #{image[member]}"
194
+ end
195
+ end
196
+
197
+ === Ruby on Rails usage example:
198
+
199
+ <b>config/environment.rb</b>
200
+
201
+ Rails::Initializer.run do |config|
202
+ ...
203
+ config.gem "amazon-ec2", :lib => "AWS", :source => "http://gemcutter.org/"
204
+ ...
205
+ end
206
+
207
+
208
+ <b>app/controllers/my_controller.rb</b>
209
+
210
+ [some controller code ...]
211
+
212
+ ec2 = AWS::EC2::Base.new(:access_key_id => "YOUR_AWS_ACCESS_KEY_ID", :secret_access_key => "YOUR_AWS_SECRET_ACCESS_KEY")
213
+
214
+ # get ALL public images
215
+ @ec2_images = ec2.describe_images().imagesSet.item
216
+
217
+ # Get info on all public EC2 images created by the Amazon EC2 team.
218
+ @ec2_images_amazon = ec2.describe_images(:owner_id => "amazon").imagesSet.item
219
+
220
+ [some more controller code ...]
221
+
222
+
223
+ <b>app/views/my/index.rhtml</b>
224
+
225
+ <h1>EC2 Test#index</h1>
226
+
227
+ <h1>Sample 1 - debug() view</h1>
228
+
229
+ <%= debug(@ec2_images_amazon) %>
230
+
231
+ <h1>Sample 2 - Build a table</h1>
232
+
233
+ <table border='1'>
234
+ <tr>
235
+ <th>image.imageId</th>
236
+ <th>image.imageLocation</th>
237
+ <th>image.imageOwnerId</th>
238
+ <th>image.imageState</th>
239
+ <th>image.isPublic</th>
240
+ </tr>
241
+
242
+ <% for image in @ec2_images_amazon %>
243
+ <tr>
244
+ <td><%=h image.imageId %></td>
245
+ <td><%=h image.imageLocation %></td>
246
+ <td><%=h image.imageOwnerId %></td>
247
+ <td><%=h image.imageState %></td>
248
+ <td><%=h image.isPublic %></td>
249
+ </tr>
250
+ <% end %>
251
+ </table>
252
+
253
+ <h1>Sample 3 - Iterate</h1>
254
+
255
+ <% @ec2_images_amazon.each do |image| %>
256
+ <% image.each_pair do |key, value| %>
257
+ <% unless key == 'parent' %>
258
+ <%= "#{key} => #{value}" %><br />
259
+ <% end %>
260
+ <% end %>
261
+ <br />
262
+ <% end %>
263
+
264
+
265
+ === Important notes regarding the structure of AWS::Response Objects
266
+
267
+ One of the key benefits of this new version of the library is that all responses from EC2 are bundled up in a real data structure and no longer require parsing of text. The hash returned is populated directly from the XML given to us by EC2 in response to any command we issue. This means that future changes to the API and what is returned by EC2 will be handled transparently by the gem. This is a huge benefit. What this means though, is that you may have to do a little homework on what actually gets returned by EC2 as XML. For example, when you make a #describe_images call in 'ec2sh' what AWS returns behind the scenes looks like:
268
+
269
+ <?xml version="1.0"?>
270
+ <DescribeImagesResponse xmlns="http://ec2.amazonaws.com/doc/2007-01-19/">
271
+ <imagesSet>
272
+ <item>
273
+ <imageId>ami-20b65349</imageId>
274
+ <imageLocation>ec2-public-images/fedora-core4-base.manifest.xml</imageLocation>
275
+ <imageState>available</imageState>
276
+ <imageOwnerId>amazon</imageOwnerId>
277
+ <isPublic>true</isPublic>
278
+ </item>
279
+ <item>
280
+ <imageId>ami-22b6534b</imageId>
281
+ <imageLocation>ec2-public-images/fedora-core4-mysql.manifest.xml</imageLocation>
282
+ <imageState>available</imageState>
283
+ <imageOwnerId>amazon</imageOwnerId>
284
+ <isPublic>true</isPublic>
285
+ </item>
286
+ <item>
287
+ <imageId>ami-23b6534a</imageId>
288
+ <imageLocation>ec2-public-images/fedora-core4-apache.manifest.xml</imageLocation>
289
+ <imageState>available</imageState>
290
+ <imageOwnerId>amazon</imageOwnerId>
291
+ <isPublic>true</isPublic>
292
+ </item>
293
+ <item>
294
+ <imageId>ami-25b6534c</imageId>
295
+ <imageLocation>ec2-public-images/fedora-core4-apache-mysql.manifest.xml</imageLocation>
296
+ <imageState>available</imageState>
297
+ <imageOwnerId>amazon</imageOwnerId>
298
+ <isPublic>true</isPublic>
299
+ </item>
300
+ <item>
301
+ <imageId>ami-26b6534f</imageId>
302
+ <imageLocation>ec2-public-images/developer-image.manifest.xml</imageLocation>
303
+ <imageState>available</imageState>
304
+ <imageOwnerId>amazon</imageOwnerId>
305
+ <isPublic>true</isPublic>
306
+ </item>
307
+ <item>
308
+ <imageId>ami-2bb65342</imageId>
309
+ <imageLocation>ec2-public-images/getting-started.manifest.xml</imageLocation>
310
+ <imageState>available</imageState>
311
+ <imageOwnerId>amazon</imageOwnerId>
312
+ <isPublic>true</isPublic>
313
+ </item>
314
+ </imagesSet>
315
+ </DescribeImagesResponse>
316
+
317
+ You can see here the XML the structure that you will need to follow when constructing queries for information and parsing responses from EC2.
318
+
319
+ So, for example, if you wanted to get the image ID of the third image listed in the response above you would need to do:
320
+
321
+ >> puts @ec2.describe_images(:owner_id => 'amazon').imagesSet.item[2].imageId
322
+ ami-23b6534a
323
+
324
+ 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.
325
+
326
+ === Handling Exceptions
327
+ If for some reason an error occurs when executing a method (e.g. its arguments were
328
+ incorrect, or it simply failed) then an exception will be thrown. The exceptions are
329
+ defined in exceptions.rb as individual classes and should match the exceptions that
330
+ AWS has defined in the API. If the exception raised cannot be identified then a
331
+ more generic exception class will be thrown.
332
+
333
+ The implication of this is that you need to be prepared to handle any exceptions that
334
+ may be raised by this library in YOUR code with a 'rescue' clause. It is up to you
335
+ to determine how you want to handle these exceptions in your code.
336
+
337
+
338
+ == Additional Resources
339
+
340
+ === Project Websites
341
+
342
+ * Project Home : http://github.com/grempe/amazon-ec2/tree/master
343
+ * API Documentation : http://rdoc.info/projects/grempe/amazon-ec2
344
+ * Discussion Group : http://groups.google.com/group/amazon-ec2
345
+ * Report Bugs / Request Features : http://github.com/grempe/amazon-ec2/issues
346
+ * Amazon Web Services : http://aws.amazon.com
347
+
348
+ == Credits
349
+
350
+ The original code for this library was provided by Amazon Web Services, LLC as sample code. Thanks to them for providing all of us with something to get us started.
351
+
352
+ == Contact
353
+
354
+ Comments, patches, Git pull requests and bug reports are welcome. Send an email to mailto:glenn@rempe.us or join the Google Groups forum.
355
+
356
+ Enjoy!
357
+
358
+ Glenn Rempe
359
+