capify-ec2 1.4.0.pre2 → 1.4.1.pre3

data/Changelog.md

@@ -1,3 +1,14 @@
+## 1.4.1.pre3 (Mar 1, 2013)
+
+Features:
+
+  - Added the ability to automatically deregister and reregister an instance from its associated Elastic Load Balancer when using the rolling deployment feature.
+
+Bugfixes:
+
+  - Instance options are now properly retained when performing a rolling deployment.
+  - Fixed a range of errors in the documentation.
+
 ## 1.4.0.pre2 (Feb 15, 2013)
 
 Features:

data/lib/capify-ec2.rb

@@ -104,6 +104,10 @@ class CapifyEc2
     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
+
   def instance_health(load_balancer, instance)
     elb.describe_instance_health(load_balancer.id, instance.id).body['DescribeInstanceHealthResult']['InstanceStates'][0]['State']
   end
@@ -111,7 +115,7 @@ class CapifyEc2
   def elb
     Fog::AWS::ELB.new(:aws_access_key_id => @ec2_config[:aws_access_key_id], :aws_secret_access_key => @ec2_config[:aws_secret_access_key], :region => @ec2_config[:aws_params][:region])
   end 
-  
+
   def get_load_balancer_by_instance(instance_id)
     hash = elb.load_balancers.inject({}) do |collect, load_balancer|
       load_balancer.instances.each {|load_balancer_instance_id| collect[load_balancer_instance_id] = load_balancer}
@@ -119,7 +123,7 @@ class CapifyEc2
     end
     hash[instance_id]
   end
-  
+
   def get_load_balancer_by_name(load_balancer_name)
     lbs = {}
     elb.load_balancers.each do |load_balancer|
@@ -166,6 +170,49 @@ class CapifyEc2
     end
   end
 
+  def deregister_instance_from_elb_by_dns(server_dns)
+    instance = get_instance_by_dns(server_dns)
+    load_balancer = get_load_balancer_by_instance(instance.id)
+
+    if load_balancer
+      puts "[Capify-EC2] Removing instance from ELB '#{load_balancer.id}'..."
+
+      result = elb.deregister_instances_from_load_balancer(instance.id, load_balancer.id)
+      raise "Unable to remove instance from ELB '#{load_balancer.id}'..." unless result.status == 200
+
+      return load_balancer
+    end
+    false
+  end
+
+  def reregister_instance_with_elb_by_dns(server_dns, load_balancer, timeout)
+    instance = get_instance_by_dns(server_dns)
+
+    sleep 10
+
+    puts "[Capify-EC2] Re-registering instance with ELB '#{load_balancer.id}'..."
+    result = elb.register_instances_with_load_balancer(instance.id, load_balancer.id)
+
+    raise "Unable to re-register instance with ELB '#{load_balancer.id}'..." unless result.status == 200
+
+    state = nil
+
+    begin
+      Timeout::timeout(timeout) do
+        begin
+          state = instance_health(load_balancer, instance)
+          raise "Instance not ready" unless state == 'InService'
+        rescue => e
+          puts "[Capify-EC2] Unexpected response: #{e}..."
+          sleep 1
+          retry
+        end
+      end
+    rescue Timeout::Error => e
+    end
+    state ? state == 'InService' : false
+  end
+
   def instance_health_by_url(dns, port, path, expected_response, options = {})
     protocol = options[:https] ? 'https://' : 'http://'
     uri = URI("#{protocol}#{dns}:#{port}#{path}")
@@ -209,4 +256,4 @@ class CapifyEC2RollingDeployError < Exception
     super(msg)
     @dns = dns
   end
-end
+end

data/lib/capify-ec2/capistrano.rb

@@ -70,26 +70,34 @@ Capistrano::Configuration.instance(:must_exist).load do
       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] ]
+        all_roles[ role[0] ] = {:options => (s.options ||= nil)} unless all_roles[ role[0] ]
       end
     end
 
     successful_deploys = []
     failed_deploys     = []
 
+    # Here outside of the scope of the rescue so we can refer to it if a general exception is raised.
+    load_balancer_to_reregister = nil
+
     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
+        load_balancer_to_reregister = nil # Set to nil again here, to ensure it always starts off nil for every iteration.
+        is_load_balanced = false
+
+        server_roles.each do |a_role|
+          role a_role, server_dns, all_roles[a_role][:options]
+          is_load_balanced = true if all_roles[a_role][:options][:load_balanced]
         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
 
+        load_balancer_to_reregister = capify_ec2.deregister_instance_from_elb_by_dns(server_dns) if is_load_balanced
+        
         # Call the standard 'cap deploy' task with our redefined role containing a single server.
         top.deploy.default
 
@@ -115,6 +123,16 @@ Capistrano::Configuration.instance(:must_exist).load do
           end
 
         end
+
+        if load_balancer_to_reregister
+          reregistered = capify_ec2.reregister_instance_with_elb_by_dns(server_dns, load_balancer_to_reregister, 60)
+          if reregistered
+            puts "[Capify-EC2] Instance registration with ELB '#{load_balancer_to_reregister.id}' successful.".green.bold
+          else
+            puts "[Capify-EC2] Instance registration with ELB '#{load_balancer_to_reregister.id}' failed!".red.bold
+            raise CapifyEC2RollingDeployError.new("ELB registration timeout exceeded", server_dns)
+          end
+        end
    
         puts "[Capify-EC2] Deployment successful to #{instance_dns_with_name_tag(server_dns)}.".green.bold
         successful_deploys << server_dns
@@ -124,16 +142,15 @@ Capistrano::Configuration.instance(:must_exist).load do
       failed_deploys << e.dns
       puts "[Capify-EC2]"
       puts "[Capify-EC2] Deployment aborted due to error: #{e}!".red.bold
-
+      puts "[Capify-EC2] Note: Instance '#{instance_dns_with_name_tag(e.dns)}' was removed from the ELB '#{load_balancer_to_reregister.id}' and should be manually checked and reregistered.".red.bold if load_balancer_to_reregister
     rescue => e
       failed_deploys << roles.values.first.servers.first.host
       puts "[Capify-EC2]"
       puts "[Capify-EC2] Deployment aborted due to error: #{e}!".red.bold
-
+      puts "[Capify-EC2] Note: Instance '#{instance_dns_with_name_tag(roles.values.first.servers.first.host)}' was removed from the ELB '#{load_balancer_to_reregister.id}' and should be manually checked and reregistered.".red.bold if load_balancer_to_reregister
     else
       puts "[Capify-EC2]"
       puts "[Capify-EC2] Rolling deployment completed.".green.bold  
-
     end
 
     puts "[Capify-EC2]"

data/lib/capify-ec2/version.rb

@@ -1,6 +1,6 @@
 module Capify
   module Ec2
-    VERSION = "1.4.0.pre2"
+    VERSION = "1.4.1.pre3"
   end
 end
 

data/readme.md

@@ -74,11 +74,32 @@ You will need to create instance tags using the AWS Management Console or API, t
 
 ### Usage
 
-In our examples, imagine that you have three servers on EC2 defined as follows:
+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>
+  </tr>
+  <tr>
+    <td>server-1</td>
+    <td>web</td>
+    <td>cron,resque</td>
+  </tr>
+  <tr>
+    <td>server-2</td>
+    <td>db</td>
+    <td></td>
+  </tr>
+  <tr>
+    <td>server-3</td>
+    <td>web,db,app</td>
+    <td></td>
+  </tr>
+</table>
+
 
-    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
 
@@ -253,7 +274,7 @@ cap web app deploy
 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}
+ec2_roles :name=>"web", :options => {:default=>true}
 ```
 
 Then run:
@@ -265,8 +286,8 @@ cap deploy
 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}
-ec2_roles {:name=>"db", :options{:default=>true}
+ec2_roles :name=>"web", :options => {:default=>true}
+ec2_roles :name=>"db", :options => {:default=>true}
 ```
 
 
@@ -275,6 +296,8 @@ ec2_roles {:name=>"db", :options{:default=>true}
 
 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.
 
+After deployment a status report is displayed, indicating on which instances deployment succeeded, failed or did not begin. With some failures, further action may need to be taken manually; for example if an instance is removed from an ELB (see the 'Usage with Elastic Load Balancers' section below) and the deployment fails, the instance will not be reregistered with the ELB, for safety reasons.
+
 ##### Usage
 
 To use the rolling deployment feature without a healthcheck, simple run your deployments with the following command:
@@ -298,13 +321,13 @@ cap web db rolling_deploy
 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
-ec2_roles { :name => "web",
-            :variables => { 
-              :healthcheck => {
-                :path   => '/status', 
-                :port   => 80, 
-                :result => 'OK'
-              }
+ec2_roles :name => "web",
+          :variables => { 
+            :healthcheck => {
+              :path   => '/status',
+              :port   => 80, 
+              :result => 'OK'
+            }
           }
 ```
 
@@ -316,36 +339,55 @@ 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:
+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 => { 
-              :healthcheck => {
-                :path    => '/status', 
-                :port    => 80, 
-                :result  => 'OK',
-                :https   => true, 
-                :timeout => 10
-              }
+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
+##### Usage with Elastic Load Balancers
 
-You can use the following commands to deregister and reregister instances in an Elastic Load Balancer.
+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
-cap SERVER_NAME_HERE ec2:deregister_instance
+ec2_roles :name => "web",
+          :variables => {
+            :load_balanced => true
+          }
 ```
 
+In this example, when an instance with the role 'web' is deployed to, Capify-EC2 will attempt to find which ELB the instance is currently registered with and deregister it. The deploy will then proceed as usual. When it is complete, the instance will be reregistered with the same ELB, and the status verified as 'InService' before the deployment is deemed successful. Note: You can only use this feature with instances that are registered with a single ELB, if you have instances registered with multiple ELBs, you are advised not to use this feature.
+
+You can also combine this feature with a Healthcheck like so:
+
 ```ruby
-cap SERVER_NAME_HERE ec2:register_instance -s loadbalancer=ELB_NAME_HERE
+ec2_roles :name => "web",
+          :variables => {
+            :healthcheck => {
+                :path   => '/status',
+                :port   => 80, 
+                :result => 'OK'
+              }
+            :load_balanced => true
+          }
 ```
 
-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).
+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 is not associated with any ELBs, then the behaviour will be skipped silently, even if ':load_balanced' is set to 'true'.
 
 
 
@@ -359,6 +401,22 @@ cap ec2:status
 
 
 
+#### 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
+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).
+
+
+
 #### 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:
@@ -448,4 +506,4 @@ Report Issues/Feature requests on [GitHub Issues](http://github.com/forward/capi
 
 ### Copyright
 
-Copyright (c) 2011, 2012, 2013 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,15 +1,15 @@
 --- !ruby/object:Gem::Specification 
 name: capify-ec2
 version: !ruby/object:Gem::Version 
-  hash: -1103184854
+  hash: 382858687
   prerelease: 6
   segments: 
   - 1
   - 4
-  - 0
+  - 1
   - pre
-  - 2
-  version: 1.4.0.pre2
+  - 3
+  version: 1.4.1.pre3
 platform: ruby
 authors: 
 - Noah Cantor
@@ -18,7 +18,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2013-02-15 00:00:00 Z
+date: 2013-03-01 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: fog