capify-ec2 1.4.11 → 1.5.0.pre

data/Changelog.md

@@ -1,3 +1,14 @@
+## 1.5.0.pre (Jul 19, 2013)
+
+Features:
+
+  - Added Support for the [Capistrano Multistage Extension](https://github.com/capistrano/capistrano/wiki/2.x-Multistage-Extension).
+  - Allow the use of IAM roles to authenticate with AWS, rather than an access key id and secret access key.
+
+Bugfixes:
+
+  - Fixed an issue executing cap tasks on individual instances.
+
 ## 1.4.11 (Jun 13, 2013)
 
 Features:

data/capify-ec2.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |s|
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
-  s.add_dependency('fog', '=1.3.1')
+  s.add_dependency('fog', '>= 1.12.0')
   s.add_dependency('colored', '=1.2')
   s.add_dependency('capistrano', '~> 2.14')
 end

data/lib/capify-ec2.rb

@@ -8,12 +8,12 @@ require File.expand_path(File.dirname(__FILE__) + '/capify-ec2/server')
 class CapifyEc2
 
   attr_accessor :load_balancer, :instances, :ec2_config
-  
+
   unless const_defined? :SLEEP_COUNT
     SLEEP_COUNT = 5
   end
-  
-  def initialize(ec2_config = "config/ec2.yml")
+
+  def initialize(ec2_config = "config/ec2.yml", stage = '')
     case ec2_config
     when Hash
       @ec2_config = ec2_config
@@ -22,6 +22,7 @@ class CapifyEc2
     else
       raise ArgumentError, "Invalid ec2_config: #{ec2_config.inspect}"
     end
+    @ec2_config[:stage] = stage
 
     # Maintain backward compatibility with previous config format
     @ec2_config[:project_tags] ||= []
@@ -31,41 +32,48 @@ class CapifyEc2
     @ec2_config[:aws_roles_tag] ||= "Roles"
     # User can change the Options tag string.
     @ec2_config[:aws_options_tag] ||= "Options"
+    # User can change the Stages tag string
+    @ec2_config[:aws_stages_tag] ||= "Stages"
 
     @ec2_config[:project_tags] << @ec2_config[:project_tag] if @ec2_config[:project_tag]
-    
+
     regions = determine_regions()
-    
+
     @instances = []
 
     regions.each do |region|
       begin
-        servers = Fog::Compute.new( :provider => 'AWS',
-                                    :aws_access_key_id => aws_access_key_id,
-                                    :aws_secret_access_key => aws_secret_access_key,
-                                    :region => region
-                                  ).servers
+        servers = Fog::Compute.new( {:provider => 'AWS', :region => region}.merge!(security_credentials) ).servers
       rescue => e
         puts "[Capify-EC2] Unable to connect to AWS: #{e}.".red.bold
         exit 1
       end
-
+      
       servers.each do |server|
         @instances << server if server.ready?
       end
     end
-  end 
+  end
+
+  def security_credentials
+    if @ec2_config[:use_iam_profile]
+      { :use_iam_profile       => true }
+    else
+      { :aws_access_key_id     => @ec2_config[:aws_access_key_id], 
+        :aws_secret_access_key => @ec2_config[:aws_secret_access_key] }
+    end
+  end
   
   def determine_regions()
     @ec2_config[:aws_params][:regions] || [@ec2_config[:aws_params][:region]]
   end
 
   def aws_access_key_id
-    @ec2_config[:aws_access_key_id] || Fog.credentials[:aws_access_key_id] || ENV['AWS_ACCESS_KEY_ID'] || raise("Missing AWS Access Key ID")
+    @ec2_config[:aws_access_key_id] || Fog.credentials[:aws_access_key_id] || ENV['AWS_ACCESS_KEY_ID'] || @ec2_config[:use_iam_profile] || raise("Missing AWS Access Key ID")
   end
 
   def aws_secret_access_key
-    @ec2_config[:aws_secret_access_key] || Fog.credentials[:aws_secret_access_key] || ENV['AWS_SECRET_ACCESS_KEY'] || raise("Missing AWS Secret Access Key")
+    @ec2_config[:aws_secret_access_key] || Fog.credentials[:aws_secret_access_key] || ENV['AWS_SECRET_ACCESS_KEY'] || @ec2_config[:use_iam_profile] || raise("Missing AWS Secret Access Key")
   end
 
   def display_instances
@@ -73,67 +81,85 @@ class CapifyEc2
       puts "[Capify-EC2] No instances were found using your 'ec2.yml' configuration.".red.bold
       return
     end
-    
+
     # Set minimum widths for the variable length instance attributes.
-    column_widths = { :name_min => 4, :type_min => 4, :dns_min => 5, :roles_min => @ec2_config[:aws_roles_tag].length, :options_min => @ec2_config[:aws_options_tag].length }
+    column_widths = { :name_min => 4, :type_min => 4, :dns_min => 5, :roles_min => @ec2_config[:aws_roles_tag].length, :stages_min => @ec2_config[:aws_stages_tag].length, :options_min => @ec2_config[:aws_options_tag].length }
 
     # Find the longest attribute across all instances, to format the columns properly.
     column_widths[:name]    = desired_instances.map{|i| i.name.to_s.ljust( column_widths[:name_min] )                                   || ' ' * column_widths[:name_min]    }.max_by(&:length).length
     column_widths[:type]    = desired_instances.map{|i| i.flavor_id                                                                     || ' ' * column_widths[:type_min]    }.max_by(&:length).length
     column_widths[:dns]     = desired_instances.map{|i| i.contact_point.to_s.ljust( column_widths[:dns_min] )                           || ' ' * column_widths[:dns_min]     }.max_by(&:length).length
     column_widths[:roles]   = desired_instances.map{|i| i.tags[@ec2_config[:aws_roles_tag]].to_s.ljust( column_widths[:roles_min] )     || ' ' * column_widths[:roles_min]   }.max_by(&:length).length
+    column_widths[:stages]  = desired_instances.map{|i| i.tags[@ec2_config[:aws_stages_tag]].to_s.ljust( column_widths[:stages_min] )   || ' ' * column_widths[:stages_min]  }.max_by(&:length).length
     column_widths[:options] = desired_instances.map{|i| i.tags[@ec2_config[:aws_options_tag]].to_s.ljust( column_widths[:options_min] ) || ' ' * column_widths[:options_min] }.max_by(&:length).length
 
-    # Title row.
-    puts "#{@ec2_config[:aws_project_tag].bold}: #{@ec2_config[:project_tags].join(', ')}." if @ec2_config[:project_tags].any?
-    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,
-      'DNS'                        .ljust( column_widths[:dns]     ).bold,
-      'Zone'                       .ljust( 10                      ).bold,
-      @ec2_config[:aws_roles_tag]  .ljust( column_widths[:roles]   ).bold,
-      @ec2_config[:aws_options_tag].ljust( column_widths[:options] ).bold
+    roles_present   = desired_instances.map{|i| i.tags[@ec2_config[:aws_roles_tag]].to_s}.max_by(&:length).length > 0
+    options_present = desired_instances.map{|i| i.tags[@ec2_config[:aws_options_tag]].to_s}.max_by(&:length).length > 0
+    stages_present  = desired_instances.map{|i| i.tags[@ec2_config[:aws_stages_tag]].to_s}.max_by(&:length).length > 0
 
+    # Project and Stages info..
+    info_label_width = [@ec2_config[:aws_project_tag], @ec2_config[:aws_stages_tag]].map(&:length).max
+    puts "#{@ec2_config[:aws_project_tag].rjust( info_label_width ).bold}: #{@ec2_config[:project_tags].join(', ')}." if @ec2_config[:project_tags].any?
+    puts "#{@ec2_config[:aws_stages_tag].rjust( info_label_width ).bold}: #{@ec2_config[:stage]}." unless @ec2_config[:stage].empty?
+    
+    # Title row.
+    status_output = []
+    status_output << 'Num'                                                         .bold
+    status_output << 'Name'                       .ljust( column_widths[:name]    ).bold
+    status_output << 'ID'                         .ljust( 10                      ).bold
+    status_output << 'Type'                       .ljust( column_widths[:type]    ).bold
+    status_output << 'DNS'                        .ljust( column_widths[:dns]     ).bold
+    status_output << 'Zone'                       .ljust( 10                      ).bold
+    status_output << @ec2_config[:aws_stages_tag] .ljust( column_widths[:stages]  ).bold if stages_present
+    status_output << @ec2_config[:aws_roles_tag]  .ljust( column_widths[:roles]   ).bold if roles_present
+    status_output << @ec2_config[:aws_options_tag].ljust( column_widths[:options] ).bold if options_present
+    puts status_output.join("   ")
+    
     desired_instances.each_with_index do |instance, i|
-      puts sprintf "%02d:   %-10s   %s   %s   %s   %-10s   %s   %s",
-        i, 
-        (instance.name || '')                               .ljust( column_widths[:name]    ).green,
-        instance.id                                         .ljust( 2                       ).red,
-        instance.flavor_id                                  .ljust( column_widths[:type]    ).cyan,
-        instance.contact_point                              .ljust( column_widths[:dns]     ).blue.bold,
-        instance.availability_zone                          .ljust( 10                      ).magenta,
-        (instance.tags[@ec2_config[:aws_roles_tag]] || '')  .ljust( column_widths[:roles]   ).yellow,
-        (instance.tags[@ec2_config[:aws_options_tag]] || '').ljust( column_widths[:options] ).yellow
+      status_output = []
+      status_output << "%02d:" % i
+      status_output << (instance.name || '')                               .ljust( column_widths[:name]    ).green
+      status_output << instance.id                                         .ljust( 2                       ).red
+      status_output << instance.flavor_id                                  .ljust( column_widths[:type]    ).cyan
+      status_output << instance.contact_point                              .ljust( column_widths[:dns]     ).blue.bold
+      status_output << instance.availability_zone                          .ljust( 10                      ).magenta
+      status_output << (instance.tags[@ec2_config[:aws_stages_tag]]  || '').ljust( column_widths[:stages]  ).yellow if stages_present
+      status_output << (instance.tags[@ec2_config[:aws_roles_tag]]   || '').ljust( column_widths[:roles]   ).yellow if roles_present
+      status_output << (instance.tags[@ec2_config[:aws_options_tag]] || '').ljust( column_widths[:options] ).yellow if options_present
+      puts status_output.join("   ")
     end
   end
 
   def server_names
     desired_instances.map {|instance| instance.name}
   end
-    
+
   def project_instances
     @instances.select {|instance| @ec2_config[:project_tags].include?(instance.tags[@ec2_config[:aws_project_tag]])}
   end
-  
+
   def desired_instances(region = nil)
-    @ec2_config[:project_tags].empty? ? @instances : project_instances
+    instances = @ec2_config[:project_tags].empty? ? @instances : project_instances
+    @ec2_config[:stage].empty? ? instances : get_instances_by_stage(instances)
   end
- 
+
   def get_instances_by_role(role)
     desired_instances.select {|instance| instance.tags[@ec2_config[:aws_roles_tag]].split(%r{,\s*}).include?(role.to_s) rescue false}
   end
-  
+
+  def get_instances_by_stage(instances=@instances)
+    instances.select {|instance| instance.tags[@ec2_config[:aws_stages_tag]].split(%r{,\s*}).include?(@ec2_config[:stage].to_s) rescue false}
+  end
+
   def get_instances_by_region(roles, region)
     return unless region
     desired_instances.select {|instance| instance.availability_zone.match(region) && instance.tags[@ec2_config[:aws_roles_tag]].split(%r{,\s*}).include?(roles.to_s) rescue false}
-  end 
-  
+  end
+
   def get_instance_by_name(name)
     desired_instances.select {|instance| instance.name == name}.first
   end
-    
+
   def get_instance_by_dns(dns)
     desired_instances.select {|instance| instance.dns_name == dns}.first
   end
@@ -141,10 +167,10 @@ class CapifyEc2
   def instance_health(load_balancer, instance)
     elb.describe_instance_health(load_balancer.id, instance.id).body['DescribeInstanceHealthResult']['InstanceStates'][0]['State']
   end
-    
+
   def elb
-    Fog::AWS::ELB.new(:aws_access_key_id => aws_access_key_id, :aws_secret_access_key => aws_secret_access_key, :region => @ec2_config[:aws_params][:region])
-  end 
+    Fog::AWS::ELB.new({:region => @ec2_config[:aws_params][:region]}.merge!(security_credentials))
+  end
 
   def get_load_balancer_by_instance(instance_id)
     hash = elb.load_balancers.inject({}) do |collect, load_balancer|
@@ -162,7 +188,7 @@ class CapifyEc2
     lbs[load_balancer_name]
 
   end
-     
+
   def deregister_instance_from_elb(instance_name)
     return unless @ec2_config[:load_balanced]
     instance = get_instance_by_name(instance_name)
@@ -172,7 +198,7 @@ class CapifyEc2
 
     elb.deregister_instances_from_load_balancer(instance.id, @@load_balancer.id)
   end
-  
+
   def register_instance_in_elb(instance_name, load_balancer_name = '')
     return if !@ec2_config[:load_balanced]
     instance = get_instance_by_name(instance_name)
@@ -185,7 +211,7 @@ class CapifyEc2
     fail_after = @ec2_config[:fail_after] || 30
     state = instance_health(load_balancer, instance)
     time_elapsed = 0
-    
+
     while time_elapsed < fail_after
       break if state == "InService"
       sleep SLEEP_COUNT
@@ -256,8 +282,8 @@ class CapifyEc2
 
     protocol = options[:https] ? 'https://' : 'http://'
     uri = URI("#{protocol}#{dns}:#{port}#{path}")
-    
-    puts "[Capify-EC2] Checking '#{uri}' for the content '#{expected_response.inspect}'..."    
+
+    puts "[Capify-EC2] Checking '#{uri}' for the content '#{expected_response.inspect}'..."
 
     http = Net::HTTP.new(uri.host, uri.port)
 

data/lib/capify-ec2/capistrano.rb

@@ -4,7 +4,7 @@ require 'pp'
 
 Capistrano::Configuration.instance(:must_exist).load do  
   def capify_ec2
-    @capify_ec2 ||= CapifyEc2.new(fetch(:ec2_config, 'config/ec2.yml'))
+    @capify_ec2 ||= CapifyEc2.new(fetch(:ec2_config, 'config/ec2.yml'), fetch(:stage, ''))
   end
 
   namespace :ec2 do
@@ -213,7 +213,7 @@ Capistrano::Configuration.instance(:must_exist).load do
         if named_instance.respond_to?(:roles)
           roles = named_instance.roles
         else
-          roles = [named_instance.tags[ @ec2_config[:aws_roles_tag] ]].flatten
+          roles = [named_instance.tags[ capify_ec2.ec2_config[:aws_roles_tag] ]].flatten
         end    
         
         roles.each do |role|

data/lib/capify-ec2/version.rb

@@ -1,6 +1,6 @@
 module Capify
   module Ec2
-    VERSION = "1.4.11"
+    VERSION = "1.5.0.pre"
   end
 end
 

data/readme.md

@@ -10,7 +10,7 @@ Capify-EC2 is used to generate Capistrano namespaces and tasks from Amazon EC2 i
 
 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:
+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"
@@ -21,7 +21,7 @@ You will need to create a YML configuration file at 'config/ec2.yml' that looks
 :project_tag: "YOUR APP NAME"
 ```
 
-Finally, add the gem to your 'deploy.rb':
+Finally, add the gem to your `deploy.rb`:
 
 ```ruby
 require "capify-ec2/capistrano"
@@ -31,54 +31,67 @@ require "capify-ec2/capistrano"
 
 #### Configuration
 
-Note: ':aws_access_key_id' and ':aws_secret_access_key' are required, unless you provide them via the two alternative methods detailed below under 'AWS Credentials'. ':region' is also required. Other settings are optional.
+Note: `:aws_access_key_id` and `:aws_secret_access_key` are required, unless you provide them via the two alternative methods detailed below under 'AWS Credentials' or have the `:use_iam_profile` option set to use IAM roles. `:region` is also 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 specified AWS access key will be used.
 
-  It is possible to include multiple projects simultaneously by using the :project_tags parameter, like so: 
+  It is possible to include multiple projects simultaneously by using the :project_tags parameter, like so:
 
   ```ruby
-  :project_tags: 
+  :project_tags:
     - "YOUR APP NAME"
     - "YOUR OTHER APP NAME"
    ```
 
 * :aws_project_tag
 
-  Use this option to change which EC2 instance tag Capify-EC2 uses to determine instance project. Defaults to 'Project' if ommited.
+  Use this option to change which EC2 instance tag Capify-EC2 uses to determine instance project. Defaults to 'Project' if omitted.
 
 * :aws_roles_tag
 
-  Use this option to change which EC2 instance tag Capify-EC2 uses to determine instance roles. Defaults to 'Roles' if ommited.
+  Use this option to change which EC2 instance tag Capify-EC2 uses to determine instance roles. Defaults to 'Roles' if omitted.
 
 * :aws_options_tag
 
-  Use this option to change which EC2 instance tag Capify-EC2 uses to determine instance options. Defaults to 'Options' if ommited.
+  Use this option to change which EC2 instance tag Capify-EC2 uses to determine instance options. Defaults to 'Options' if omitted.
+
+* :aws_stages_tag
+
+  Use this option to change which EC2 instance tag Capify-EC2 uses to determine which instances belong to a stage. Should be used in conjunction with the [Capistrano Multistage Extension](https://github.com/capistrano/capistrano/wiki/2.x-Multistage-Extension). Defaults to 'Stages' if omitted.
 
 * :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.
+  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.
+
+* :use_iam_profile
+
+  Use this option to use IAM roles for authentication, rather than an access key id and secret access key.
+
 
 ##### AWS Credentials
 
 ###### Via YML Configuration
 
-By default, Capify-EC2 will attempt to use the credentials found in your 'ec2.yml' configuration as detailed above.
+By default, Capify-EC2 will attempt to use the credentials found in your `ec2.yml` configuration as detailed above.
 
 ###### Via Fog Configuration
 
-If you wish, you can have Capify-EC2 use the AWS credentials found in your Fog configuration, instead of instead of specifying ':aws_access_key_id' and ':aws_secret_access_key' in the YML configuration file. Refer to the Fog documentation for details on specifying AWS credentials.
+If you wish, you can have Capify-EC2 use the AWS credentials found in your Fog configuration, instead of instead of specifying `:aws_access_key_id` and `:aws_secret_access_key` in the YML configuration file. Refer to the Fog documentation for details on specifying AWS credentials.
 
 ###### Via Environment Variables
 
-If you wish, you can define AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as environment variables, instead of specifying ':aws_access_key_id' and ':aws_secret_access_key' in the YML configuration file.
+If you wish, you can define AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as environment variables, instead of specifying `:aws_access_key_id` and `:aws_secret_access_key` in the YML configuration file.
+
+###### Via AWS IAM Roles
+
+If you have IAM roles set up on your box to allow querying EC2 information you tell Fog to use IAM roles and you will not need to provide any credentials at runtime. For more information on IAM roles read Amazon's [IAM documentation](http://aws.amazon.com/iam/).
 
 ###### Ordering
 
-Capify-EC2 will attempt to load your AWS credentials first from the 'ec2.yml' configuration file, then from your Fog configuration file, and finally from environment variables. It will display an error if no credentials are found by any of these methods.
+Capify-EC2 will attempt to load your AWS credentials first from the `ec2.yml` configuration file, then from your Fog configuration file, and finally from environment variables. It will display an error if no credentials are found by any of these methods.
 
 
 
@@ -88,7 +101,7 @@ You will need to create instance tags using the AWS Management Console or API, t
 
 * Tag 'Project'
 
-  Used with the ':project_tag' option in 'config/ec2.yml' to limit Capify-EC2's functionality to a subset of your instances.
+  Used with the `:project_tag` option in `config/ec2.yml` to limit Capify-EC2's functionality to a subset of your instances.
 
 * Tag 'Roles'
 
@@ -131,7 +144,7 @@ In our examples, imagine that you have three servers on EC2 named and tagged as
 
 #### Single Roles
 
-You need to add a call to 'ec2_roles' in your 'deploy.rb', like so:
+You need to add a call to `ec2_roles` in your `deploy.rb`, like so:
 
 ```ruby
 ec2_roles :web
@@ -154,7 +167,7 @@ task :web do
 end
 ```
 
-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:
+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
 ec2_roles :db
@@ -181,7 +194,7 @@ end
 
 #### 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:
+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
 ec2_roles :web
@@ -274,7 +287,7 @@ For example, if we had the following group of instances in EC2:
   </tr>
 </table>
 
-You could then create a task in your 'deploy.rb' that will only be executed on the worker machine, like so:
+You could then create a task in your `deploy.rb` that will only be executed on the worker machine, like so:
 
 ```ruby
 task :reload_workers, :only=>{:worker=>true} do
@@ -290,13 +303,13 @@ end
 
 ##### Via Role Definitions
 
-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:
+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
 ec2_roles {:name=>"web", :options=>{:worker=>"server-C"}}
 ```
 
-In this case, you set the value of ':worker' equal to the instance name you want to be a worker. The task definition remains the same:
+In this case, you set the value of `:worker` equal to the instance name you want to be a worker. The task definition remains the same:
 
 ```ruby
 task :reload_workers => :web, :only=>{:worker=>true} do
@@ -308,7 +321,7 @@ end
 
 #### 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':
+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
 ec2_roles :web
@@ -327,11 +340,18 @@ If you've defined multiple roles, you can deploy to them all by chaining the tas
 cap web app deploy
 ```
 
+You can also deploy to individual instances by specifying their 'Name' tag, for example, with the sample servers above:
+
+```ruby
+cap server-1 deploy
+```
+
+would deploy only to the instance named 'server-1'.
 
 
 ##### 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':
+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
 ec2_roles :name=>"web", :options => {:default=>true}
@@ -343,7 +363,7 @@ Then run:
 cap deploy
 ```
 
-You can set multiple roles as defaults, so they are all included when you run 'cap deploy', like so:
+You can set multiple roles as defaults, so they are all included when you run `cap deploy`, like so:
 
 ```ruby
 ec2_roles :name=>"web", :options => {:default=>true}
@@ -378,14 +398,14 @@ cap web db rolling_deploy
 
 ##### Usage with Healthchecks
 
-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:
+When defining a role with the `ec2_role` call, if you configure a healthcheck for that role as follows, it will automatically be used during the rolling deployment:
 
 ```ruby
 ec2_roles :name => "web",
-          :variables => { 
+          :variables => {
             :healthcheck => {
               :path   => '/status',
-              :port   => 80, 
+              :port   => 80,
               :result => 'OK'
             }
           }
@@ -425,16 +445,16 @@ ec2_roles :name => "web",
           }
 ```
 
-The default timeout of 60 seconds 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:
+The default timeout of 60 seconds 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 => { 
+          :variables => {
             :healthcheck => {
               :path   => '/status',
-              :port   => 80, 
+              :port   => 80,
               :result => 'OK'
-              :https   => true, 
+              :https   => true,
               :timeout => 10
             }
           }
@@ -446,14 +466,14 @@ You can run multiple different healthchecks for a role by specifying the healthc
 
 ```ruby
 ec2_roles :name => "web",
-          :variables => { 
+          :variables => {
             :healthcheck => [{
               :path   => '/status',
-              :port   => 80, 
+              :port   => 80,
               :result => 'OK'
             }, {
               :path   => '/other_status',
-              :port   => 81, 
+              :port   => 81,
               :result => 'OK'
             }]
           }
@@ -461,7 +481,7 @@ ec2_roles :name => "web",
 
 ##### Usage with Elastic Load Balancers
 
-You can have Capify-EC2 automatically deregister and reregister an instance from whichever ELB it is associated with, before and after the deployment, by setting ':load_balanced' to 'true' in the role definition, for example:
+You can have Capify-EC2 automatically deregister and reregister an instance from whichever ELB it is associated with, before and after the deployment, by setting `:load_balanced` to 'true' in the role definition, for example:
 
 ```ruby
 ec2_roles :name => "web",
@@ -479,7 +499,7 @@ ec2_roles :name => "web",
           :variables => {
             :healthcheck => {
                 :path   => '/status',
-                :port   => 80, 
+                :port   => 80,
                 :result => 'OK'
               }
             :load_balanced => true
@@ -488,9 +508,9 @@ ec2_roles :name => "web",
 
 In this example, the instance will be deregistered from the ELB it is associated with and then deployed to. A healthcheck will then be performed, and providing this passes, the instance will be reregistered with the ELB and verified.
 
-If an instance has been tagged with multiple roles, this behaviour will apply if ':load_balanced' is set to 'true' in at least one of those roles.
+If an instance has been tagged with multiple roles, this behaviour will apply if `:load_balanced` is set to 'true' in at least one of those roles.
 
-If an instance is not associated with any ELBs, then the behaviour will be skipped silently, even if ':load_balanced' is set to 'true'.
+If an instance is not associated with any ELBs, then the behaviour will be skipped silently, even if `:load_balanced` is set to 'true'.
 
 
 
@@ -516,19 +536,19 @@ cap SERVER_NAME_HERE ec2:deregister_instance
 cap SERVER_NAME_HERE ec2:register_instance -s loadbalancer=ELB_NAME_HERE
 ```
 
-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).
+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).
 
 
 
 #### 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:
+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.
+will attempt to connect to instance number 1 (as shown in `ec2:status`), using the public DNS address provided by AWS.
 
 
 
@@ -552,15 +572,21 @@ Will restrict the 'date' command so it is only run on instances that are tagged
 cap web db ec2:date
 ```
 
+You can use the 'Name' tag of an EC2 instance to limit the scope of the command to an individual instance:
+
+```ruby
+cap server-1 ec2:date
+```
+
 ##### Cap Invoke
 
-You can use the standard Capistrano 'invoke' task to run an arbitrary command on your instances, for example:
+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:
+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
@@ -572,9 +598,15 @@ You can also chain many roles together to increase the scope of the command:
 cap web db COMMAND='uptime' invoke
 ```
 
+As with ec2:date, you can use the 'Name' tag of an EC2 instance to limit the scope of the command to an individual instance:
+
+```ruby
+cap server-1 COMMAND='uptime' invoke
+```
+
 ##### Cap Shell
 
-You can use the standard Capistrano 'shell' task to open an interactive terminal session with your instances, for example:
+You can use the standard Capistrano `shell` task to open an interactive terminal session with your instances, for example:
 
 ```ruby
 cap shell
@@ -591,6 +623,101 @@ cap web db shell
 ```
 
 
+### Multistage
+
+You can use the [Capistrano Multistage Extension](https://github.com/capistrano/capistrano/wiki/2.x-Multistage-Extension) to manage deployments to multiple environments.
+
+##### Configuration
+
+You can set the tag name that Capify-EC2 will use to filter your server list by using the `:aws_stages_tag`. It defaults to 'Stages'.
+
+##### Usage
+
+In our examples, imagine that you have three servers on EC2 named and tagged as follows:
+
+<table>
+  <tr>
+    <td>'Name' Tag</td>
+    <td>'Roles' Tag</td>
+    <td>'Options' Tag</td>
+		<td>'Stages' Tag</td>
+  </tr>
+  <tr>
+    <td>server-1</td>
+    <td>web</td>
+    <td>cron,resque</td>
+		<td>production</td>
+  </tr>
+  <tr>
+    <td>server-2</td>
+    <td>db</td>
+    <td></td>
+		<td>production</td>
+  </tr>
+  <tr>
+    <td>server-3</td>
+    <td>web,db</td>
+    <td></td>
+		<td>staging</td>
+  </tr>
+</table>
+
+And you have the following 2 stages setup using Capistrano Multistage.
+
+production.rb
+
+```ruby
+ec2_roles name: :web
+ec2_roles name: :db
+```
+
+staging.rb
+
+```ruby
+ec2_roles name: :web
+ec2_roles name: :db
+```
+
+This will generate the following for production
+
+```ruby
+namespace :production do
+  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 :web do
+    role :web, SERVER-1_EC2_PUBLIC_DNS_HERE, :cron=>true, :resque=>true
+  end
+
+  task :db do
+    role :db, SERVER-2_EC2_PUBLIC_DNS_HERE
+  end
+end
+
+namespace :staging do
+  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-3_EC2_PUBLIC_DNS_HERE
+  end
+
+  task :db do
+    role :db, SERVER-3_EC2_PUBLIC_DNS_HERE
+  end
+end
+```
+
+With the above config you can deploy to production using `cap production deploy`.
+
+You will also need to add the environment when running other ec2 commands like `ec2:status`, for example: `cap production ec2:status`
 
 ### Development
 

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification 
 name: capify-ec2
 version: !ruby/object:Gem::Version 
-  hash: 17
-  prerelease: 
+  hash: -2020557639
+  prerelease: 6
   segments: 
   - 1
-  - 4
-  - 11
-  version: 1.4.11
+  - 5
+  - 0
+  - pre
+  version: 1.5.0.pre
 platform: ruby
 authors: 
 - Noah Cantor
@@ -18,7 +19,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2013-06-13 00:00:00 Z
+date: 2013-07-19 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: fog
@@ -26,14 +27,14 @@ dependencies:
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
-    - - "="
+    - - ">="
       - !ruby/object:Gem::Version 
-        hash: 25
+        hash: 39
         segments: 
         - 1
-        - 3
-        - 1
-        version: 1.3.1
+        - 12
+        - 0
+        version: 1.12.0
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
@@ -107,12 +108,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version 
-      hash: 3
+      hash: 25
       segments: 
-      - 0
-      version: "0"
+      - 1
+      - 3
+      - 1
+      version: 1.3.1
 requirements: []
 
 rubyforge_project: capify-ec2