@@ -23,7 +23,7 @@ Before you can make use of this gem you will need an Amazon Web Services develop === Install required gem pre-requisites -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. +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. XmlSimple (required) Mocha (optional for testing) @@ -64,7 +64,7 @@ The public methods on EC2::Base closely mirror the EC2 Query API, and as such th === Setting up -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. +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. Edit the file ~/.bash_login and add the following to the existing contents: @@ -82,9 +82,9 @@ If you are using EC2 in the EU region, make sure you also set: (which you have already if you configured standard EC2 command line tools to work with this region). -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. +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. -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. +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. === The basics @@ -109,13 +109,13 @@ An example Ruby script which exercises the library a bit more is installed for y [your amazon-ec2 gem dir]/examples/ec2-example.rb -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). +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). ==== Using the 'ec2sh' command shell -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... +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... -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: +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: hostname:/tmp/rails/amazon_test glenn$ ec2sh @@ -155,7 +155,7 @@ If you're not in front of a terminal shell now (perhaps you’re browsing this s === Ruby script usage example: -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 (EC2::Response). +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 (EC2::Response). #!/usr/bin/env ruby @@ -303,7 +303,7 @@ So, for example, if you wanted to get the image ID of the third image listed in >> puts @ec2.describe_images(:owner_id => 'amazon').imagesSet.item[2].imageId ami-23b6534a -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 EC2::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. +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 EC2::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. == Additional Resources README.rdoc 62b2d3764b4ba72c89686e5fbd5bb25e9f099b20 Glenn Rempe glenn@rempe.us http://github.com/grempe/amazon-ec2/commit/16322a0b35739602549cc0097130cd26441d5f0c 16322a0b35739602549cc0097130cd26441d5f0c 2009-06-11T23:31:35-07:00 2009-06-11T23:31:35-07:00 Damn smart quotes. Screw up rdoc formatting. 5b65df788bcb11adc74056a64f12d6a7bf598ab0 Glenn Rempe glenn@rempe.us