You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.rdoc
+23-34
Original file line number
Diff line number
Diff line change
@@ -22,50 +22,32 @@ or the official EC2 website at http://aws.amazon.com/ec2
22
22
23
23
== Installation
24
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.
25
+
This gem follows the standard conventions for installation on any system with Ruby and RubyGems installed and uses Bundler for gem installation and build management. If you have worked with gems before this will look very familiar.
26
26
27
27
=== Get an AWS account
28
28
29
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
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
31
=== Install the amazon-ec2 gem (Canonical Release)
42
32
43
33
This is the standard install for stable releases from RubyGems.
44
34
45
35
# Install the gem
46
-
sudo gem install amazon-ec2
36
+
[sudo] gem install amazon-ec2
47
37
48
38
49
39
=== Install from local Git clone (for amazon-ec2 developers)
50
40
51
-
GitHub has unfortunately given up on the feature they had where they would build gems
52
-
when pushed to git. Too bad. So to install from git, you'll need to clone and build.
41
+
To install from git for adding features or fixing bugs, you'll need to clone and build.
53
42
54
43
git clone git://github.com/grempe/amazon-ec2.git
55
44
cd amazon-ec2
56
-
rake gemspec
45
+
bundle install
46
+
rake test
57
47
rake build
58
48
rake install
59
49
60
50
61
-
=== EXPERIMENTAL : Install the amazon-ec2 gem using Rip (for more bleeding edge versions)
62
-
63
-
For those who intend to do development on the gem, or want the bleeding edge. Install Rip as described at hellorip.com.
64
-
65
-
# (Experimental) Install using Rip (hellorip.com) instead of RubyGems
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.
@@ -75,7 +57,7 @@ The public methods on AWS::EC2::Base closely mirror the EC2 Query API, and as su
75
57
76
58
=== Setting up
77
59
78
-
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.
60
+
The 'awshell' 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 'awshell' 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.
79
61
80
62
Edit the file ~/.bash_login and add the following to the existing contents:
81
63
@@ -121,16 +103,16 @@ An example Ruby script which exercises the library a bit more is installed for y
121
103
122
104
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).
123
105
124
-
==== Using the 'ec2sh' command shell
106
+
==== Using the 'awshell' command shell
125
107
126
-
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...
108
+
The 'awshell' 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 'awshell' from any terminal command prompt on your local system. You'll see some basic instructions for use, and a few examples when you start 'awshell'. Go ahead and try it out now. We'll wait...
127
109
128
110
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:
129
111
130
112
131
-
hostname:/tmp/rails/amazon_test glenn$ ec2sh
113
+
hostname:/tmp/rails/amazon_test glenn$ awshell
132
114
133
-
'ec2sh' usage :
115
+
'awshell' usage :
134
116
This is an interactive 'irb' command shell that allows you to use all
135
117
commands available to the amazon-ec2 gem. You'll find this to be a
136
118
great tool to help you debug issues and practice running commands
@@ -182,7 +164,8 @@ Try out the following bit of code. This should walk through each image returned
182
164
183
165
=== Ruby on Rails usage example:
184
166
185
-
<b>config/environment.rb</b>
167
+
168
+
<b>Rails 2.3.x - config/environment.rb</b>
186
169
187
170
Rails::Initializer.run do |config|
188
171
...
@@ -191,6 +174,12 @@ Try out the following bit of code. This should walk through each image returned
191
174
end
192
175
193
176
177
+
<b>Rails 3.x.x - Gemfile</b>
178
+
179
+
...
180
+
gem "amazon-ec2", :require => "AWS"
181
+
182
+
194
183
<b>app/controllers/my_controller.rb</b>
195
184
196
185
[some controller code ...]
@@ -250,7 +239,7 @@ Try out the following bit of code. This should walk through each image returned
250
239
251
240
=== Important notes regarding the structure of AWS::Response Objects
252
241
253
-
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:
242
+
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 'awshell' what AWS returns behind the scenes looks like:
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.
299
+
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 'awshell' 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.
311
300
312
301
=== Handling Exceptions
313
302
If for some reason an error occurs when executing a method (e.g. its arguments were
@@ -346,11 +335,11 @@ Please follow these steps if you want to send a patch or a GitHub pull request:
346
335
* Fork grempe/amazon-ec2
347
336
* Create a topic branch: `git checkout -b my_fix`
348
337
* Make sure you add tests for your changes and that they all pass with 'rake test'
349
-
* Don't change files that you don't own like the gemspec or VERSION
338
+
* Don't change files that you don't own like the gemspec or version.rb
350
339
* Commit your changes, one change/fix per commit
351
340
* Push your fixes branch: `git push origin my_fix`
352
-
* Open an Issue referencing your branch.
353
-
* Please do not push to `master` on your fork. This will make everyone’s life easier.
341
+
* Open an Issue on GitHub referencing your branch and send a pull request.
342
+
* Please do not push to `master` on your fork. Using a feature/bugfix branch will make everyone’s life easier.
0 commit comments