capify-ec2 1.3.7 → 1.4.0.pre1

data/Changelog.md

@@ -1,3 +1,10 @@
+## 1.4.0.pre1 (Feb 15, 2013)
+
+Features:
+
+  - New rolling deployment mode, allows you to deploy to your instances in serial, rather than in parallel, with an option to perform a healthcheck before proceeding to the next instance. For more information on this feature, check out the [documentation](readme.md#rolling-deployments).
+  - The documentation has been rewritten to make it clearer how to use Capify-EC2 and what the available options are.
+
 ## 1.3.7 (Jan 20, 2013)
 
   - Make the behaviour for passing hash/filename consistent

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2012 Forward
+Copyright (c) 2011, 2012, 2013 Forward
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/capify-ec2.gemspec

@@ -7,10 +7,10 @@ Gem::Specification.new do |s|
   s.version     = Capify::Ec2::VERSION
   s.platform    = Gem::Platform::RUBY
   s.authors     = ["Noah Cantor", "Siddharth Dawara"]
-  s.email       = ["noah.cantor@forward.co.uk", "siddharth.dawara@forward.co.uk"]
+  s.email       = ["capify-ec2@forwardtechnology.co.uk"]
   s.homepage    = "http://github.com/forward/capify-ec2"
-  s.summary     = %q{Grabs roles from ec2's tags and autogenerates capistrano tasks}
-  s.description = %q{Grabs roles from ec2's tags and autogenerates capistrano tasks}
+  s.summary     = %q{Capify-EC2 is used to generate Capistrano namespaces and tasks from Amazon EC2 instance tags, dynamically building the list of servers to be deployed to.}
+  s.description = %q{Capify-EC2 is used to generate Capistrano namespaces and tasks from Amazon EC2 instance tags, dynamically building the list of servers to be deployed to.}
 
   s.rubyforge_project = "capify-ec2"
 

data/lib/capify-ec2.rb

@@ -57,7 +57,7 @@ class CapifyEc2
 
     # Title row.
     puts sprintf "%-3s   %s   %s   %s   %s   %s   %s   %s", 
-      '',
+      'Num'                                     .bold,
       'Name'   .ljust( column_widths[:name]    ).bold,
       'ID'     .ljust( 10                      ).bold,
       'Type'   .ljust( column_widths[:type]    ).bold,
@@ -165,4 +165,48 @@ class CapifyEc2
       STDERR.puts "#{instance.name}: tests timed out after #{time_elapsed} seconds."
     end
   end
+
+  def instance_health_by_url(dns, port, path, expected_response, options = {})
+    protocol = options[:https] ? 'https://' : 'http://'
+    uri = URI("#{protocol}#{dns}:#{port}#{path}")
+    http = Net::HTTP.new(uri.host, uri.port)
+
+    result = nil
+
+    begin
+      Timeout::timeout(options[:timeout]) do
+        begin
+          result = http.get(uri.path)
+          raise "Server responded with '#{result.code}: #{result.body}', expected '#{expected_response}'" unless result.body == expected_response
+        rescue => e
+          puts "[Capify-EC2] Unexpected response: #{e}..."
+          sleep 1
+          retry
+        end
+      end
+    rescue Timeout::Error => e
+    end
+    result ? result.body == expected_response : false
+  end
+end
+
+def instance_dns_with_name_tag(dns)
+  name_tag     = ''
+  current_node = capify_ec2.desired_instances.select { |instance| instance.dns_name == dns }
+  name_tag     = current_node.first.tags['Name'] unless current_node.empty?
+  "#{dns} (#{name_tag})"
+end
+
+def format_rolling_deploy_results(all_servers, results)
+  puts '[Capify-EC2]      None.' unless results.any?
+  results.each {|server| puts "[Capify-EC2]      #{instance_dns_with_name_tag(server)} with #{all_servers[server].count >1 ? 'roles' : 'role'} '#{all_servers[server].join(', ')}'."}
+end
+
+class CapifyEC2RollingDeployError < Exception
+  attr_reader :dns
+
+  def initialize(msg, dns)
+    super(msg)
+    @dns = dns
+  end
 end

data/lib/capify-ec2/capistrano.rb

@@ -1,5 +1,6 @@
 require File.join(File.dirname(__FILE__), '../capify-ec2')
 require 'colored'
+require 'pp'
 
 Capistrano::Configuration.instance(:must_exist).load do  
   def capify_ec2
@@ -34,24 +35,121 @@ Capistrano::Configuration.instance(:must_exist).load do
     task :server_names do
       puts capify_ec2.server_names.sort
     end
-    
+
     desc "Allows ssh to instance by id. cap ssh <INSTANCE NAME>"
     task :ssh do
       server = variables[:logger].instance_variable_get("@options")[:actions][1]
       instance = numeric?(server) ? capify_ec2.desired_instances[server.to_i] : capify_ec2.get_instance_by_name(server)
-      port = ssh_options[:port] || 22 
-      command = "ssh -p #{port} #{user}@#{instance.contact_point}"
-      puts "Running `#{command}`"
-      exec(command)
+
+      if instance and instance.contact_point then
+        port = ssh_options[:port] || 22 
+        command = "ssh -p #{port} #{user}@#{instance.contact_point}"
+        puts "Running `#{command}`"
+        exec(command)
+      else
+        puts "[Capify-EC2] Error: You did not specify the instance number, which can be found via the 'ec2:status' command as follows:".bold.red
+        top.ec2.status
+      end
     end
   end
-  
+
   namespace :deploy do
     before "deploy", "ec2:deregister_instance"
     after "deploy", "ec2:register_instance"
     after "deploy:rollback", "ec2:register_instance"
   end
     
+  desc "Deploy to servers one at a time."
+  task :rolling_deploy do
+    puts "[Capify-EC2] Performing rolling deployment..."
+
+    all_servers       = {}
+    all_roles         = {}
+
+    roles.each do |role|
+      role[1].servers.each do |s|
+        all_servers[ s.host.to_s ] ||= []
+        all_servers[ s.host.to_s ] << role[0]
+        all_roles[ role[0] ] = {:options => {:healthcheck => s.options[:healthcheck] ||= nil}} unless all_roles[ role[0] ]
+      end
+    end
+
+    successful_deploys = []
+    failed_deploys     = []
+
+    begin
+      all_servers.each do |server_dns,server_roles|
+
+        roles.clear
+
+        server_roles.each do |a_role|  
+          #TODO: Look at defining any options associated to the specific role, maybe through calling 'ec2_role'.
+          role a_role, server_dns
+        end
+        
+        puts "[Capify-EC2]"
+        puts "[Capify-EC2] Beginning deployment to #{instance_dns_with_name_tag(server_dns)} with #{server_roles.count > 1 ? 'roles' : 'role'} '#{server_roles.join(', ')}'...".bold
+
+        # Call the standard 'cap deploy' task with our redefined role containing a single server.
+        top.deploy.default
+
+        server_roles.each do |a_role|
+          
+          # If a healthcheck is defined for this role, run it.
+          if all_roles[a_role][:options][:healthcheck]
+            options = {}
+            options[:https]   = all_roles[a_role][:options][:healthcheck][:https]   ||= false
+            options[:timeout] = all_roles[a_role][:options][:healthcheck][:timeout] ||= 60
+            puts "[Capify-EC2] Starting healthcheck for role '#{a_role}'..."
+            healthcheck = capify_ec2.instance_health_by_url( server_dns,
+                                                             all_roles[a_role][:options][:healthcheck][:port], 
+                                                             all_roles[a_role][:options][:healthcheck][:path], 
+                                                             all_roles[a_role][:options][:healthcheck][:result], 
+                                                             options )
+            if healthcheck
+              puts "[Capify-EC2] Healthcheck for role '#{a_role}' successful.".green.bold
+            else
+              puts "[Capify-EC2] Healthcheck for role '#{a_role}' failed!".red.bold
+              raise CapifyEC2RollingDeployError.new("Healthcheck timeout exceeded", server_dns)
+            end
+          end
+
+        end
+   
+        puts "[Capify-EC2] Deployment successful to #{instance_dns_with_name_tag(server_dns)}.".green.bold
+        successful_deploys << server_dns
+
+      end
+    rescue CapifyEC2RollingDeployError => e
+      failed_deploys << e.dns
+      puts "[Capify-EC2]"
+      puts "[Capify-EC2] Deployment aborted due to error: #{e}!".red.bold
+
+    rescue => e
+      failed_deploys << roles.values.first.servers.first.host
+      puts "[Capify-EC2]"
+      puts "[Capify-EC2] Deployment aborted due to error: #{e}!".red.bold
+
+    else
+      puts "[Capify-EC2]"
+      puts "[Capify-EC2] Rolling deployment completed.".green.bold  
+
+    end
+
+    puts "[Capify-EC2]"
+    puts "[Capify-EC2]   Successful servers:"
+    format_rolling_deploy_results( all_servers, successful_deploys )
+     
+    puts "[Capify-EC2]"
+    puts "[Capify-EC2]   Failed servers:"
+    format_rolling_deploy_results( all_servers, failed_deploys )
+    
+    puts "[Capify-EC2]"
+    puts "[Capify-EC2]   Pending servers:"
+    pending_deploys = (all_servers.keys - successful_deploys) - failed_deploys
+    format_rolling_deploy_results( all_servers, pending_deploys )
+  end
+
   def ec2_roles(*roles)
     server_name = variables[:logger].instance_variable_get("@options")[:actions].first unless variables[:logger].instance_variable_get("@options")[:actions][1].nil?
     
@@ -130,16 +228,19 @@ Capistrano::Configuration.instance(:must_exist).load do
   def define_role(role, instance)
     options     = role[:options] || {}
     variables   = role[:variables] || {}
-    
+
     cap_options = options.inject({}) do |cap_options, (key, value)| 
       cap_options[key] = true if value.to_s == instance.name
       cap_options
     end 
-    
+
     ec2_options = instance.tags["Options"] || ""
     ec2_options.split(%r{,\s*}).compact.each { |ec2_option|  cap_options[ec2_option.to_sym] = true }
-    
-    variables.each { |key, value| set key, value }
+
+    variables.each do |key, value| 
+      set key, value
+      cap_options[key] = value unless cap_options.has_key? key
+    end
 
     role role[:name].to_sym, instance.contact_point, cap_options
   end

data/lib/capify-ec2/version.rb

@@ -1,6 +1,6 @@
 module Capify
   module Ec2
-    VERSION = "1.3.7"
+    VERSION = "1.4.0.pre1"
   end
 end
 

data/readme.md

@@ -1,194 +1,442 @@
-Capify Ec2
-====================================================
+## Capify-EC2
 
-capify-ec2 is used to generate capistrano namespaces using ec2 tags.
+Capify-EC2 is used to generate Capistrano namespaces and tasks from Amazon EC2 instance tags, dynamically building the list of servers to be deployed to.
 
-eg: If you have three servers on amazon's ec2.
 
-    server-1 Tag: Roles => "web", Options => "cron,resque, db"
-    server-2 Tag: Roles => "db"
-    server-3 Tag: Roles => "web,db, app"
-
-Installing
+### Installation
 
     gem install capify-ec2
 
-In your deploy.rb:
+or add the gem to your project's Gemfile.
+
+You will need to create a YML configuration file at 'config/ec2.yml' that looks like the following:
+
+```ruby
+:aws_access_key_id: "YOUR ACCESS KEY"
+:aws_secret_access_key: "YOUR SECRET"
+:aws_params:
+  :region: 'eu-west-1'
+:load_balanced: true
+:project_tag: "YOUR APP NAME"
+```
+
+Finally, add the gem to your 'deploy.rb':
 
 ```ruby
 require "capify-ec2/capistrano"
+```
+
+
+
+#### Configuration
+
+Note: 'aws_access_key_id', 'aws_secret_access_key', and 'region' are required. Other settings are optional.
+
+* :project_tag
+
+  If this is defined, Capify-EC2 will only create namespaces and tasks for the EC2 instances that have a matching 'Project' tag. By default, all instances available to the configured AWS access key will be used.
+
+  It is possible to include multiple projects simultaneously by using the :project_tags parameter, like so: 
+
+  ```ruby
+  :project_tags: 
+    - "YOUR APP NAME"
+    - "YOUR OTHER APP NAME"
+   ```
+
+* :load_balanced
+
+  When ':load_balanced' is set to 'true', Capify-EC2 uses pre and post-deploy hooks to deregister the instance from an associated Elastic Load Balancer, perform the actual deploy, then finally reregister with the ELB and validated the instance health.
+  Note: This options only applies to deployments made to an individual instance, using the command 'cap INSTANCE_NAME_HERE deploy' - it doesn't apply to roles.
+
+
+
+#### EC2 Tags
+
+You will need to create instance tags using the AWS Management Console or API, to further configure Capify-EC2. The following tags are used:
+
+* Tag 'Project'
+
+  Used with the ':project_tag' option in 'config/ec2.yml' to limit Capify-EC2's functionality to a subset of your instances.
+
+* Tag 'Roles'
+
+  A comma seperated list of roles that will be converted into Capistrano namespaces, for example 'app,workers', 'app,varnish,workers', 'db' and so on.
+
+* Tag 'Options'
+
+  A comma seperated list of options which will be defined as 'true' for that instance. See the 'Options' section below for more information on their use.
+  task :bob, :only => {:option_nmame => true}
+  on_no_matching_servers => :continue
+  "one of those ten is cron" etc.
+
+
+
+### Usage
+
+In our examples, imagine that you have three servers on EC2 defined as follows:
+
+    server-1 Tags: Name => "server-1", Roles => "web", Options => "cron,resque"
+    server-2 Tags: Name => "server-2", Roles => "db"
+    server-3 Tags: Name => "server-3", Roles => "web,db,app"
+
+#### Single Roles
+
+You need to add a call to 'ec2_roles' in your 'deploy.rb', like so:
+
+```ruby
 ec2_roles :web
 ```
 
-Will generate
+This will generate the following tasks:
 
 ```ruby
 task :server-1 do
-  role :web, {server-1 public dns fetched from Amazon}, :cron=>true, :resque=>true
+  role :web, SERVER-1_EC2_PUBLIC_DNS_HERE, :cron=>true, :resque=>true
 end
 
 task :server-3 do
-  role :web, {server-1 public dns fetched from Amazon}
+  role :web, SERVER-3_EC2_PUBLIC_DNS_HERE
 end
 
 task :web do
-  role :web, {server-1 public dns fetched from Amazon}, :cron=>true, :resque=>true
-  role :web, {server-3 public dns fetched from Amazon}
+  role :web, SERVER-1_EC2_PUBLIC_DNS_HERE, :cron=>true, :resque=>true
+  role :web, SERVER-3_EC2_PUBLIC_DNS_HERE
 end
 ```
 
-Additionally
+Note that there are no tasks created for 'server-2', as it does not have the role 'web'. If we were to change the 'ec2_roles' definition in your 'deploy.rb' to the following:
 
 ```ruby
-require "capify-ec2/capistrano"
 ec2_roles :db
 ```
 
-Will generate
+Then we will instead see the following tasks generated:
 
 ```ruby
 task :server-2 do
-  role :db, {server-2 public dns fetched from Amazon}
+  role :db, SERVER-2_EC2_PUBLIC_DNS_HERE
 end
 
 task :server-3 do
-  role :db, {server-3 public dns fetched from Amazon}
+  role :db, SERVER-3_EC2_PUBLIC_DNS_HERE
 end
 
 task :db do
-  role :db, {server-2 public dns fetched from Amazon}
-  role :db, {server-3 public dns fetched from Amazon}
+  role :db, SERVER-2_EC2_PUBLIC_DNS_HERE
+  role :db, SERVER-3_EC2_PUBLIC_DNS_HERE
 end
 ```
 
-Running
+
+#### Multiple Roles
+
+If you want to create tasks for servers using multiple roles, you can call 'ec2_roles' multiple times in your 'deploy.rb' as follows:
 
 ```ruby
-cap web ec2:date
+ec2_roles :web
+ec2_roles :db
 ```
 
-will run the date command on all server's tagged with the web role
+Which would generate the following tasks:
 
-Running
+```ruby
+task :server-1 do
+  role :web, SERVER-1_EC2_PUBLIC_DNS_HERE, :cron=>true, :resque=>true
+end
+
+task :server-2 do
+  role :db, SERVER-2_EC2_PUBLIC_DNS_HERE
+end
+
+task :server-3 do
+  role :web, SERVER-3_EC2_PUBLIC_DNS_HERE
+  role :db, SERVER-3_EC2_PUBLIC_DNS_HERE
+end
+
+task :web do
+  role :web, SERVER-1_EC2_PUBLIC_DNS_HERE
+  role :web, SERVER-3_EC2_PUBLIC_DNS_HERE
+end
+
+task :db do
+  role :db, SERVER-2_EC2_PUBLIC_DNS_HERE, :cron=>true, :resque=>true
+  role :db, SERVER-3_EC2_PUBLIC_DNS_HERE
+end
+```
+
+
+
+#### Role Variables
+
+You can define custom variables which will be set as standard Capistrano variables within the scope of the role you define them one, for example:
+
+```ruby
+ec2_roles {:name=>"web", :variables => {:rails_env => 'staging'}}
+```
+
+In this case, instances that that are tagged with the 'web' role will have the custom variable 'rails_env' available to them in any tasks they use. The following tasks would be generated:
 
 ```ruby
-cap server-1 ec2:register_instance -s loadbalancer=elb-1
+task :server-1 do
+  role :web, SERVER-1_EC2_PUBLIC_DNS_HERE, :cron=>true, :resque=>true, :rails_env=>'staging'
+end
+
+task :server-3 do
+  role :web, SERVER-3_EC2_PUBLIC_DNS_HERE
+end
+
+task :web do
+  role :web, SERVER-1_EC2_PUBLIC_DNS_HERE, :cron=>true, :resque=>true, :rails_env=>'staging'
+  role :web, SERVER-3_EC2_PUBLIC_DNS_HERE, :rails_env=>'staging'
+end
 ```
 
-will register server-1 to be used by elb-1
 
-Running
+
+#### Options
+
+##### Via EC2 Tags
+
+As mentioned in the 'EC2 Tags' section, creating an 'Options' tag on your EC2 instances will define those options as 'true' for the associated instance. This allows you to refine your capistrano tasks.
+For example, if we had the following group of instances in EC2:
+
+    server-A Tags: Name => "server-A", Roles => "web"
+    server-B Tags: Name => "server-B", Roles => "web"
+    server-C Tags: Name => "server-C", Roles => "web", Options => "worker"
+
+You could then create a task in your 'deploy.rb' that will only be executed on the worker machine, like so:
 
 ```ruby
-cap server-1 ec2:deregister_instance
+task :reload_workers => :web, :only=>{:worker} do
+  # Do something to a server with cron on it
+end
 ```
 
-will remove server-1 from whatever instance it is currently
-registered against.
+##### Via Role Definitions
 
-Running
+As well as defining Options at an instance level via EC2 tags, you can define an Option in your 'deploy.rb' at the same time as defining the role, as follows:
 
 ```ruby
-cap ec2:status
+ec2_roles {:name=>"web", :options=>{:worker=>"server-C"}}
 ```
 
-will list the currently running servers and their associated details
-(public dns, instance id, roles etc)
+In this case, you set the value of ':worker' equal to the instance name you want to be a worker.
+
 
-Running
+
+#### Deploying
+
+Once you have defined the various roles used by your application, you can deploy to it as you normally would a namespace, for example if you define the following in your 'deploy.rb':
 
 ```ruby
-cap ec2:ssh #
+ec2_roles :web
+ec2_roles :app
 ```
 
-will launch ssh using the user and port specified in your configuration.
-The # argument is the index of the server to ssh into. Use the 'ec2:status'
-command to see the list of servers with their indices.
+You can deploy to just the 'web' instances like so:
 
-More options
-====================================================
+```ruby
+cap web deploy
+```
 
-In addition to specifying options (e.g. 'cron') at the server level, it is also possible to specify it at the project level.
-Use with caution! This does not work with autoscaling.
+If you've defined multiple roles, you can deploy to them all by chaining the tasks, like so:
 
 ```ruby
-ec2_roles {:name=>"web", :options=>{:cron=>"server-1"}}
+cap web app deploy
 ```
 
-Will generate
+
+
+##### Default Deploys
+
+You can set a role as the default so that it will be included when you run 'cap deploy' without specifying any roles, for example in your 'deploy.rb':
 
 ```ruby
-task :server-1 do
-  role :web, {server-1 public dns fetched from Amazon}, :cron=>true
-end
+ec2_roles {:name=>"web", :options{:default=>true}
+```
 
-task :server-3 do
-  role :web, {server-1 public dns fetched from Amazon}
-end
+Then run:
 
-task :web do
-  role :web, {server-1 public dns fetched from Amazon}, :cron=>true
-  role :web, {server-3 public dns fetched from Amazon}
-end
+```ruby
+cap deploy
 ```
 
-Which is cool if you want a task like this in deploy.rb
+You can set multiple roles as defaults, so they are all included when you run 'cap deploy', like so:
 
 ```ruby
-task :update_cron => :web, :only=>{:cron} do
-  Do something to a server with cron on it
-end
+ec2_roles {:name=>"web", :options{:default=>true}
+ec2_roles {:name=>"db", :options{:default=>true}
+```
+
+
+
+#### Rolling Deployments
+
+This feature allows you to deploy your code to instances one at a time, rather than simultaneously. This becomes useful for more complex applications that may take longer to startup after a deployment. Capistrano will perform a full deploy (including any custom hooks) against a single instance, optionally perform a HTTP healthcheck against the instance, then proceed to the next instance if deployment was successful.
 
-ec2_roles :name=>:web, :options=>{ :default => true }
+##### Usage
+
+To use the rolling deployment feature without a healthcheck, simple run your deployments with the following command:
+
+```ruby
+cap rolling_deploy
 ```
 
-Will make :web the default role so you can just type 'cap deploy'.
-Multiple roles can be defaults so:
+You can restrict the scope of the rolling deploy by targetting one or more roles like so:
 
 ```ruby
-ec2_roles :name=>:web, :options=>{ :default => true }
-ec2_roles :name=>:app, :options=>{ :default => true }
+cap web rolling_deploy
 ```
 
-would be the equivalent of 'cap app web deploy'
+```ruby
+cap web db rolling_deploy
+```
 
-Ec2 config
-====================================================
+##### Usage with Healthchecks
 
-This gem requires 'config/ec2.yml' in your project.
-The yml file needs to look something like this:
+When defining a role with the 'ec2_role' command, if you configure a healthcheck for that role as follows, it will automatically be used during the rolling deployment:
 
 ```ruby
-:aws_access_key_id: "YOUR ACCESS KEY"
-:aws_secret_access_key: "YOUR SECRET"
-:aws_params:
-  :region: 'eu-west-1'
-:load_balanced: true
-:project_tag: "YOUR APP NAME"
+ec2_roles { :name => "web",
+            :variables => { 
+              :healthcheck => {
+                :path   => '/status', 
+                :port   => 80, 
+                :result => 'OK'
+              }
+          }
 ```
-aws_access_key_id, aws_secret_access_key, and region are required. Other settings are optional.
 
-If :load_balanced is set to true, the gem uses pre and post-deploy
-hooks to deregister the instance, reregister it, and validate its
-health.
-:load_balanced only works for individual instances, not for roles.
+In this example, the following URL would be generated:
 
-The :project_tag parameter is optional. It will limit any commands to
-running against those instances with a "Project" tag set to the value
-"YOUR APP NAME". It is also possible to apply commands to multiple projects using the :project_tags parameter, like so: 
+```
+http://EC2_INSTANCE_PUBLIC_DNS_HERE:80/status
+```
+
+And the contents of the page at that URL must match 'OK' for the healthcheck to pass. If unsuccessful, the healthcheck is repeated every second, until a timeout of 60 seconds is reached, at which point the rolling deployment is aborted, and a progress summary displayed.
+
+The default timeout is 60 seconds, which can be overridden by setting ':timeout' to a custom value in seconds. The protocol used defaults to 'http://', however you can switch to 'https://' by setting ':https' equal to 'true'. For example:
+
+```ruby
+ec2_roles { :name => "web",
+            :variables => { 
+              :healthcheck => {
+                :path    => '/status', 
+                :port    => 80, 
+                :result  => 'OK',
+                :https   => true, 
+                :timeout => 10
+              }
+          }
+```
+
+Sets a 10 second timeout, and performs the health check over HTTPS.
+
+#### Managing Load Balancers
+
+You can use the following commands to deregister and reregister instances in an Elastic Load Balancer.
+
+```ruby
+cap SERVER_NAME_HERE ec2:deregister_instance
+```
 
 ```ruby
-:project_tags: 
- - "YOUR APP NAME"
- - "YOUR OTHER APP NAME"
+cap SERVER_NAME_HERE ec2:register_instance -s loadbalancer=ELB_NAME_HERE
 ```
 
-## Development
+You need to specify the ELB when reregistering an instance, but not when deregistering. This can also be done automatically using the ':load_balanced' setting (see the 'Configuration' section above).
+
+
+
+#### Viewing All Instances
+
+The following command will generate a listing of all instances that match your configuration (projects and roles), along with their associated details:
+
+```ruby
+cap ec2:status
+```
+
+
+
+#### Connecting to an Instance via SSH
+
+Using the 'cap ec2:ssh' command, you can quickly connect to a specific instance, by checking the listing from 'ec2:status' and using the instance number as a parameter, for example:
+
+```ruby
+cap ec2:ssh 1
+```
+
+will attempt to connect to instance number 1 (as shown in 'ec2:status'), using the public DNS address provided by AWS.
+
+
+
+#### Other Commands
+
+Running the following command:
+
+```ruby
+cap ec2:date
+```
+
+Will execute the 'date' command on all instances that match your configuration (projects and roles). You can limit this further by using a role, for example:
+
+```ruby
+cap web ec2:date
+```
+
+Will restrict the 'date' command so it is only run on instances that are tagged with the 'web' role. You can chain many roles together to increase the scope of the command:
+
+```ruby
+cap web db ec2:date
+```
+
+##### Cap Invoke
+
+You can use the standard Capistrano 'invoke' task to run an arbitrary command on your instances, for example:
+
+```ruby
+cap COMMAND='uptime' invoke
+```
+
+Will run the 'uptime' command on all instances that match your configuration (projects and roles). As with the 'ec2:date' command, you can further limit this by using a role, like so:
+
+```ruby
+cap web COMMAND='uptime' invoke
+```
+
+You can also chain many roles together to increase the scope of the command:
+
+```ruby
+cap web db COMMAND='uptime' invoke
+```
+
+##### Cap Shell
+
+You can use the standard Capistrano 'shell' task to open an interactive terminal session with your instances, for example:
+
+```ruby
+cap shell
+```
+
+Will open an interactive terminal on all instances that match your configuration (projects and roles). You can of course limit the scope of the shell to a certain role or roles like so:
+
+```ruby
+cap web shell
+```
+
+```ruby
+cap web db shell
+```
+
+
+
+### Development
 
 Source hosted at [GitHub](http://github.com/forward/capify-ec2).
 Report Issues/Feature requests on [GitHub Issues](http://github.com/forward/capify-ec2/issues).
 
-### Note on Patches/Pull Requests
+#### Note on Patches/Pull Requests
 
  * Fork the project.
  * Make your feature addition or bug fix.
@@ -198,6 +446,6 @@ Report Issues/Feature requests on [GitHub Issues](http://github.com/forward/capi
    (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
  * Send me a pull request. Bonus points for topic branches.
 
-## Copyright
+### Copyright
 
-Copyright (c) 2012 Forward. See [LICENSE](https://github.com/forward/capify-ec2/blob/master/LICENSE) for details.
+Copyright (c) 2011, 2012, 2013 Forward. See [LICENSE](https://github.com/forward/capify-ec2/blob/master/LICENSE) for details.

metadata

@@ -1,73 +1,80 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: capify-ec2
-version: !ruby/object:Gem::Version
-  version: 1.3.7
-  prerelease: 
+version: !ruby/object:Gem::Version 
+  hash: -2106362774
+  prerelease: 6
+  segments: 
+  - 1
+  - 4
+  - 0
+  - pre
+  - 1
+  version: 1.4.0.pre1
 platform: ruby
-authors:
+authors: 
 - Noah Cantor
 - Siddharth Dawara
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-20 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
+
+date: 2013-02-15 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
   name: fog
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
-        version: 1.3.1
-  type: :runtime
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        hash: 25
+        segments: 
+        - 1
+        - 3
+        - 1
         version: 1.3.1
-- !ruby/object:Gem::Dependency
-  name: colored
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
-        version: '1.2'
   type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: colored
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
-        version: '1.2'
-- !ruby/object:Gem::Dependency
-  name: capistrano
-  requirement: !ruby/object:Gem::Requirement
+  requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        hash: 11
+        segments: 
+        - 1
+        - 2
+        version: "1.2"
   type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: capistrano
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-description: Grabs roles from ec2's tags and autogenerates capistrano tasks
-email:
-- noah.cantor@forward.co.uk
-- siddharth.dawara@forward.co.uk
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id003
+description: Capify-EC2 is used to generate Capistrano namespaces and tasks from Amazon EC2 instance tags, dynamically building the list of servers to be deployed to.
+email: 
+- capify-ec2@forwardtechnology.co.uk
 executables: []
+
 extensions: []
+
 extra_rdoc_files: []
-files:
+
+files: 
 - .gitignore
 - Changelog.md
 - Gemfile
@@ -81,26 +88,38 @@ files:
 - readme.md
 homepage: http://github.com/forward/capify-ec2
 licenses: []
+
 post_install_message: 
 rdoc_options: []
-require_paths:
+
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
+required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      hash: 25
+      segments: 
+      - 1
+      - 3
+      - 1
+      version: 1.3.1
 requirements: []
+
 rubyforge_project: capify-ec2
-rubygems_version: 1.8.23
+rubygems_version: 1.8.15
 signing_key: 
 specification_version: 3
-summary: Grabs roles from ec2's tags and autogenerates capistrano tasks
+summary: Capify-EC2 is used to generate Capistrano namespaces and tasks from Amazon EC2 instance tags, dynamically building the list of servers to be deployed to.
 test_files: []
+