fog 1.9.0 → 1.10.0

data/lib/fog/rackspace/docs/getting_started.md

@@ -1,16 +1,16 @@
-# Getting Started with Rackspace Open Cloud
+# Getting Started with Fog and the Rackspace Cloud
 
-This document will explain how to get started using Fog with the [Rackspace Open Cloud](http://www.rackspace.com/cloud/).
+This document explains how to get started using Fog with the [Rackspace Cloud](http://www.rackspace.com/cloud/).
 
 ## Requirements
 
-Fog is officially supports Ruby 1.9.3, 1.9.2, and 1.8.7 (Also known as Matz Ruby Interpreter or MRI). While not officially supported, fog has been known to work with Rubinus and JRuby. 
+Fog officially supports Ruby 1.9.3, 1.9.2, and 1.8.7 (also known as Matz Ruby Interpreter or MRI). While not officially supported, fog has been known to work with Rubinus and JRuby. 
 
 Ruby 1.9.3 is suggested for new projects. For information on installing Ruby please refer to the [Ruby download page](http://www.ruby-lang.org/en/downloads/). 
 
 ## Credentials
 
-To obtain credentials for the US Rackspace Open Cloud, please sign up for an account at [US Rackspace Open Cloud](https://cart.rackspace.com/cloud/). Once an account is created, you can login to the [Cloud Control Panel (US)](https://mycloud.rackspace.com/) and find your credentials by clicking on your username in the top right corner and then selecting API keys.
+To obtain credentials for the US Rackspace Cloud, please sign up for an account at [US Rackspace Open Cloud](https://cart.rackspace.com/cloud/). Once an account is created, you can login to the [Cloud Control Panel (US)](https://mycloud.rackspace.com/) and find your credentials by clicking on your username in the top right corner and then selecting API keys.
 
 Likewise, you can create an account on our UK Rackspace Open Cloud by going to [UK Rackspace Open Cloud](https://buyonline.rackspace.co.uk/cloud/userinfo?type=normal) and login into [Cloud Control Panel (UK)](https://mycloud.rackspace.co.uk/).
 
@@ -57,20 +57,20 @@ You should now be able to execute the following command to see a list of service
 
 These services can be explored in further depth in the following documents:
 
-* Next Gen Cloud Servers™ (compute_v2)
+* [Next Generation Cloud Servers™ (compute_v2)](/cloud_servers.md)
 * Cloud Files™ (storage)
 * Cloud Block Storage (block_storage)
 
-*Note: The compute service provides an interface to the First Gen Cloud Servers™ (compute). This service is deprecated. Users are encouraged to use Next Gen Cloud Servers™ (compute_v2).*
+**Note**: *The compute service provides an interface to the First Geneneration Cloud Servers™ (compute). This service is deprecated. Users are encouraged to use Next Geneneration Cloud Servers™ (compute_v2).*
 
 ## Additional Resources
 * [fog.io](http://fog.io)
-* [API Documentation](http://rubydoc.info/gems/fog)
-* [Source](https://github.com/fog/fog)
+* [Fog rdoc](http://rubydoc.info/gems/fog)
+* [Fog Github repo](https://github.com/fog/fog)
 * [Release Notes](https://github.com/fog/fog/blob/master/changelog.txt)
 * [developer.rackspace.com](http://developer.rackspace.com/)
 
 ## Support and Feedback
-Your feedback is appreciated! If you have specific issues with the **fog** SDK, developers should file an [issue via Github](https://github.com/fog/fog/issues).
+Your feedback is appreciated! If you have specific issues with the **fog** SDK, you should file an [issue via Github](https://github.com/fog/fog/issues).
 
 For general feedback and support requests, send an email to: <sdk-support@rackspace.com>.

data/lib/fog/rackspace/examples/README.md

@@ -0,0 +1,47 @@
+# Getting Started Examples
+
+## Download
+
+Examples using the Rackspace Open Cloud and Fog can be found in the [fog repository](https://github.com/fog/fog) under the directory `fog/lib/fog/rackspace/examples`.
+
+This repository can be downloaded via `git` by executing the following:
+
+	git clone git://github.com/fog/fog.git
+
+Optionally you can download a zip by clicking on this [link](https://github.com/fog/fog/archive/master.zip).
+
+## Requirements
+
+Examples require the following:
+
+* Rackspace Open Cloud account
+* Ruby 1.8.x or 1.9.x
+* `fog` gem
+
+For more information please refer to the [Getting Started with Fog and the Rackspace Open Cloud](https://github.com/fog/fog/blob/master/lib/fog/rackspace/docs/getting_started.md) document.
+
+## Credentials
+
+Examples will prompt for Rackspace Open Cloud credentials. Prompts can be skipped by creating a `.fog` file in the user's home directory. This is an example of a `.fog` file for the Rackspace Open Cloud: 
+
+	default:
+    	rackspace_username: RACKSPACE_USERNAME
+    	rackspace_api_key: RACKSPACE_API_KEY
+
+***Note:* Replace capitalized values with the appropriate credential information.*
+
+## Executing
+
+To execute scripts using `bundler`:
+
+	bundle exec ruby <script>
+	
+To execute scripts without `bundler`:
+
+	ruby <script>
+	
+## Support and Feedback
+
+Your feedback is appreciated! If you have specific issues with the **fog** SDK, developers should file an [issue via Github](https://github.com/fog/fog/issues).
+
+For general feedback and support requests, send an email to: <sdk-support@rackspace.com>.

data/lib/fog/rackspace/examples/compute_v2/README.md

@@ -0,0 +1,47 @@
+# Getting Started Examples
+
+## Download
+
+You can find examples using the Rackspace and Fog in the [fog repository](https://github.com/fog/fog) under the `fog/lib/fog/rackspace/examples` directory.
+
+You can download this repository by executing the following command:
+
+	git clone git://github.com/fog/fog.git
+
+Optionally you can download a zip by clicking on this [link](https://github.com/fog/fog/archive/master.zip).
+
+## Requirements
+
+Examples require the following:
+
+* Rackspace Cloud account
+* Ruby 1.8.x or 1.9.x
+* `fog` gem
+
+For more information please refer to the [Getting Started with Fog and the Rackspace Cloud](https://github.com/fog/fog/blob/master/lib/fog/rackspace/docs/getting_started.md) document.
+
+## Credentials
+
+Examples will prompt for Rackspace Cloud credentials. You can skip prompts by creating a `.fog` file in the user's home directory. This is an example of a `.fog` file for the Rackspace Cloud: 
+
+	default:
+    	rackspace_username: RACKSPACE_USERNAME
+    	rackspace_api_key: RACKSPACE_API_KEY
+
+**Note:** *Replace capitalized values with the appropriate credential information.*
+
+## Executing
+
+To execute scripts using `bundler`:
+
+	bundle exec ruby <script>
+	
+To execute scripts without `bundler`:
+
+	ruby <script>
+	
+## Support and Feedback
+
+Your feedback is appreciated! If you have specific issues with the **fog** SDK, you should file an [issue via Github](https://github.com/fog/fog/issues).
+
+For general feedback and support requests, send an email to: <sdk-support@rackspace.com>.

data/lib/fog/rackspace/examples/compute_v2/create_image.rb

@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby
+
+# This example demonstrates creating a server image with the Rackpace Open Cloud
+
+require 'rubygems' #required for Ruby 1.8.x
+require 'fog'
+
+def get_user_input(prompt)
+  print "#{prompt}: "
+  gets.chomp
+end
+
+def select_server(servers)
+  abort "\nThere are not any servers avaliable to image. Try running create_server.rb\n\n" if servers.empty?
+  
+  puts "\nSelect Server To Image:\n\n"
+  servers.each_with_index do |server, i|
+    puts "\t #{i}. #{server.name} [#{server.public_ip_address}]"
+  end
+  
+  selected_str = get_user_input "\nEnter Server Number"
+  servers[selected_str.to_i]
+end
+
+# Use username defined in ~/.fog file, if absent prompt for username. 
+# For more details on ~/.fog refer to http://fog.io/about/getting_started.html
+def rackspace_username
+  Fog.credentials[:rackspace_username] || get_user_input("Enter Rackspace Username")
+end
+
+# Use api key defined in ~/.fog file, if absent prompt for api key
+# For more details on ~/.fog refer to http://fog.io/about/getting_started.html
+def rackspace_api_key
+  Fog.credentials[:rackspace_api_key] || get_user_input("Enter Rackspace API key")
+end
+
+# create Next Generation Cloud Server service
+service = Fog::Compute.new({
+  :provider             => 'rackspace',
+  :rackspace_username   => rackspace_username,
+  :rackspace_api_key    => rackspace_api_key,
+  :version => :v2,  # Use Next Gen Cloud Servers
+  :rackspace_endpoint => Fog::Compute::RackspaceV2::ORD_ENDPOINT #Use Chicago Region
+})
+
+# retrieve list of servers
+servers = service.servers
+
+# prompt user for server
+server = select_server(servers)
+
+# prompt user for image name
+image_name = get_user_input "Enter Image Name"
+
+# creates image for server
+server.create_image image_name
+  
+puts "\nImage #{image_name} is being created for server #{server.name}.\n\n"
+puts "To delete the image please execute the delete_image.rb script\n\n"
+
+

data/lib/fog/rackspace/examples/compute_v2/create_server.rb

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+
+# This example demonstrates creating a server with the Rackpace Open Cloud
+
+require 'rubygems' #required for Ruby 1.8.x
+require 'fog'
+require "base64" #required to encode files for personality functionality
+
+def get_user_input(prompt)
+  print "#{prompt}: "
+  gets.chomp
+end
+
+# Use username defined in ~/.fog file, if absent prompt for username. 
+# For more details on ~/.fog refer to http://fog.io/about/getting_started.html
+def rackspace_username
+  Fog.credentials[:rackspace_username] || get_user_input("Enter Rackspace Username")
+end
+
+# Use api key defined in ~/.fog file, if absent prompt for api key
+# For more details on ~/.fog refer to http://fog.io/about/getting_started.html
+def rackspace_api_key
+  Fog.credentials[:rackspace_api_key] || get_user_input("Enter Rackspace API key")
+end
+
+# create Next Generation Cloud Server service
+service = Fog::Compute.new({
+  :provider             => 'rackspace',
+  :rackspace_username   => rackspace_username,
+  :rackspace_api_key    => rackspace_api_key,
+  :version => :v2,  # Use Next Gen Cloud Servers
+  :rackspace_endpoint => Fog::Compute::RackspaceV2::ORD_ENDPOINT #Use Chicago Region
+})
+
+# pick the first flavor
+flavor = service.flavors.first
+
+# pick the first Ubuntu image we can find
+image = service.images.find {|image| image.name =~ /Ubuntu/}
+
+# prompt for server name
+server_name = get_user_input "\nEnter Server Name"
+
+# create server
+server = service.servers.create :name => server_name, 
+                                :flavor_id => flavor.id, 
+                                :image_id => image.id,
+                                :metadata => { 'fog_sample' => 'true'},
+                                :personality => [{
+                                  :path => '/root/fog.txt',
+                                  :contents => Base64.encode64('Fog was here!')
+                                }]
+
+# reload flavor in order to retrieve all of its attributes
+flavor.reload
+
+puts "\nNow creating server '#{server.name}' the following with specifications:\n" 
+puts "\t* #{flavor.ram} MB RAM"
+puts "\t* #{flavor.disk} GB"
+puts "\t* #{flavor.vcpus} CPU(s)"
+puts "\t* #{image.name}"
+
+puts "\n"
+
+begin
+  # Check every 5 seconds to see if server is in the active state (ready?). 
+  # If the server has not been built in 5 minutes (600 seconds) an exception will be raised.
+  server.wait_for(600, 5) do
+    print "."
+    STDOUT.flush
+    ready?
+  end
+  
+  puts "[DONE]\n\n"
+
+  puts "The server has been successfully created, to login onto the server:\n\n"
+  puts "\t ssh #{server.username}@#{server.public_ip_address}\n\n"
+  
+rescue Fog::Errors::TimeoutError
+  puts "[TIMEOUT]\n\n"
+  
+  puts "This server is currently #{server.progress}% into the build process and is taking longer to complete than expected."
+  puts "You can continute to monitor the build process through the web console at https://mycloud.rackspace.com/\n\n" 
+end
+
+puts "The #{server.username} password is #{server.password}\n\n"
+puts "To delete the server please execute the delete_server.rb script\n\n"
+
+

data/lib/fog/rackspace/examples/compute_v2/delete_image.rb

@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby
+
+# This example demonstrates deleting a server image with the Rackpace Open Cloud
+
+require 'rubygems' #required for Ruby 1.8.x
+require 'fog'
+
+def get_user_input(prompt)
+  print "#{prompt}: "
+  gets.chomp
+end
+
+def select_image(snapshot_images)
+  abort "\nThere are not any images to delete. Try running create_image.rb\n\n" if snapshot_images.empty?
+  
+  puts "\nSelect Image To Delete:\n\n"
+  snapshot_images.each_with_index do |image, i|
+    puts "\t #{i}. #{image.name}"
+  end
+
+  delete_str = get_user_input "\nEnter Image Number"  
+  snapshot_images[delete_str.to_i]
+end
+
+# Use username defined in ~/.fog file, if absent prompt for username. 
+# For more details on ~/.fog refer to http://fog.io/about/getting_started.html
+def rackspace_username
+  Fog.credentials[:rackspace_username] || get_user_input("Enter Rackspace Username")
+end
+
+# Use api key defined in ~/.fog file, if absent prompt for api key
+# For more details on ~/.fog refer to http://fog.io/about/getting_started.html
+def rackspace_api_key
+  Fog.credentials[:rackspace_api_key] || get_user_input("Enter Rackspace API key")
+end
+
+# create Next Generation Cloud Server service
+service = Fog::Compute.new({
+  :provider             => 'rackspace',
+  :rackspace_username   => rackspace_username,
+  :rackspace_api_key    => rackspace_api_key,
+  :version => :v2,  # Use Next Gen Cloud Servers
+  :rackspace_endpoint => Fog::Compute::RackspaceV2::ORD_ENDPOINT #Use Chicago Region
+})
+
+# retrieve list of images
+images = service.images
+
+# select all of the snapshot type images. base images are not user deletable 
+snapshot_images = images.select do |image|
+  image.metadata["image_type"] == "snapshot" 
+end
+
+# prompt user for image to delete
+image = select_image(snapshot_images)
+
+# delete image
+image.destroy
+
+puts "\n#{image.name} has been destroyed\n\n"
+

data/lib/fog/rackspace/examples/compute_v2/delete_server.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+
+# This example demonstrates how to delete servers with Fog and the Rackspace Open Cloud
+
+require 'rubygems' #required for Ruby 1.8.x
+require 'fog'
+
+def get_user_input(prompt)
+  print "#{prompt}: "
+  gets.chomp
+end
+
+def select_server(servers)
+  abort "\nThere are not any servers to delete. Try running create_server.rb\n\n" if servers.empty?
+  
+  puts "\nSelect Server To Delete:\n\n"
+  servers.each_with_index do |server, i|
+    puts "\t #{i}. #{server.name} [#{server.public_ip_address}]"
+  end
+
+  delete_str = get_user_input "\nEnter Server Number"
+  servers[delete_str.to_i]
+end
+
+# Use username defined in ~/.fog file, if absent prompt for username. 
+# For more details on ~/.fog refer to http://fog.io/about/getting_started.html
+def rackspace_username
+  Fog.credentials[:rackspace_username] || get_user_input("Enter Rackspace Username")
+end
+
+# Use api key defined in ~/.fog file, if absent prompt for api key
+# For more details on ~/.fog refer to http://fog.io/about/getting_started.html
+def rackspace_api_key
+  Fog.credentials[:rackspace_api_key] || get_user_input("Enter Rackspace API key")
+end
+
+#create Next Generation Cloud Server service
+service = Fog::Compute.new({
+  :provider             => 'rackspace',
+  :rackspace_username   => rackspace_username,
+  :rackspace_api_key    => rackspace_api_key,
+  :version => :v2,  # Use Next Gen Cloud Servers
+  :rackspace_endpoint => Fog::Compute::RackspaceV2::ORD_ENDPOINT #Use Chicago Region
+})
+
+#retrieve list of servers
+servers = service.servers
+
+#prompt user for server
+server = select_server(servers)
+
+#destroy server
+server.destroy
+
+puts "\nServer #{server.name} has been destroyed\n"
+

data/lib/fog/rackspace/examples/compute_v2/detach_volume.rb

@@ -0,0 +1,93 @@
+#!/usr/bin/env ruby
+
+# This example demonstrates working with server and volumes on the Rackpace Open Cloud
+
+require 'rubygems' #required for Ruby 1.8.x
+require 'fog'
+
+def get_user_input(prompt)
+  print "#{prompt}: "
+  gets.chomp
+end
+
+def select_server(servers)
+  abort "\nThere are not any servers. Try running create_server.rb\n\n" if servers.empty?
+  
+  puts "\nSelect Server For Volume Detachment:\n\n"
+  servers.each_with_index do |server, i|
+    puts "\t #{i}. #{server.name} [#{server.public_ip_address}]"
+  end
+
+  delete_str = get_user_input "\nEnter Server Number"
+  servers[delete_str.to_i]
+end
+
+def select_attachment(attachments)
+  abort "\nThis server does not contain any volumes. Try running server_attachments.rb\n\n" if attachments.empty?
+  
+  puts "\nSelect Volume To Detach:\n\n"
+  attachments.each_with_index do |attachment, i|
+    puts "\t #{i}. #{attachment.device}"
+  end
+
+  delete_str = get_user_input "\nEnter Volume Number"
+  attachments[delete_str.to_i]
+end
+
+# Use username defined in ~/.fog file, if absent prompt for username. 
+# For more details on ~/.fog refer to http://fog.io/about/getting_started.html
+def rackspace_username
+  Fog.credentials[:rackspace_username] || get_user_input("Enter Rackspace Username")
+end
+
+# Use api key defined in ~/.fog file, if absent prompt for api key
+# For more details on ~/.fog refer to http://fog.io/about/getting_started.html
+def rackspace_api_key
+  Fog.credentials[:rackspace_api_key] || get_user_input("Enter Rackspace API key")
+end
+
+#create Next Generation Cloud Server service
+compute_service = Fog::Compute.new({
+  :provider             => 'rackspace',
+  :rackspace_username   => rackspace_username,
+  :rackspace_api_key    => rackspace_api_key,
+  :version => :v2,  # Use Next Gen Cloud Servers
+  :rackspace_endpoint => Fog::Compute::RackspaceV2::ORD_ENDPOINT #Use Chicago Region
+})
+
+cbs_service = Fog::Rackspace::BlockStorage.new({
+  :rackspace_username => rackspace_username,
+  :rackspace_api_key  => rackspace_api_key,
+  :rackspace_endpoint => Fog::Rackspace::BlockStorage::ORD_ENDPOINT #Use Chicago Region  
+})
+
+# retrieve list of servers
+servers = compute_service.servers
+
+# prompt user for server
+server = select_server(servers)
+
+# get attached volumes --also know as attachments
+attachments = server.attachments
+
+# prompt user for volume to detach
+attachment = select_attachment(attachments)
+
+volume = cbs_service.volumes.get attachment.volume_id
+puts "Detaching Volume #{volume.display_name} From Server #{server.name}"
+attachment.detach
+
+puts "\n"
+delete_confirm = get_user_input "Would You Like To Destroy Volume #{volume.display_name} (y/n)"
+if delete_confirm.downcase ==  'y'
+  # wait for server to finish detaching before attempting to delete
+  volume.wait_for(600)  do 
+    print "."
+    STDOUT.flush
+    ready? && attachments.empty?
+  end
+  
+  volume.destroy
+  
+  puts "\n\nThe Volume Has been Destroyed"
+end