cap-elb 0.0.5 → 0.0.6

data/README.markdown

@@ -39,16 +39,22 @@ If you wish, you can also set other AWS specfic parameters:
 
 	set :aws_params, :region => 'us-east-1'
 	
-In order to define your instance groups, you must specify the security group name, the roles and params:
-Next you will set up your instance sets associated with a named load balancer instance in your AWS account.
-You will call out the load balancer name (e.g. 'lb_webserver'), the capistrano role associated with that load balancer (.e.g. 'web'),
+Setting region is required if you are not using default region 'us-east-1'.
+If your ELB is not in us-east-1, and you do not specify region parameter as above,
+you will get an error indicating that no ELB could be found with that name in that region.
+
+In order to define your instance sets associated with your load balancer based deploys, you must specify the load balancer name, the associated roles for that load balancer and any optional params:
+For example, in deploy.rb, you would enter the load balancer name (e.g. 'lb_webserver'), the capistrano role associated with that load balancer (.e.g. 'web'),
 and any optional params.
 
 	loadbalancer :lb_webserver, :web
 	loadbalancer :lb_appserver, :app
 	loadbalancer :lb_dbserver, :db, :port => 22000
 
-There are two special parameters you can add, :require and :exclude.
+There are two special optional parameters you can add, :require and :exclude. These allow you to exclude instances associated with your named load balancer from the deploy,
+if they meet or fail to meet your :require/:exclude specifications. 
+
+The :require and :exclude parameters work on Amazon EC2 instance metadata.
 
 AWS instances have top level metadata and user defined tag data, and this data can be used by your loadbalancer rule
  to include or exclude certain instances from the instance set.

data/lib/cap-elb/version.rb

@@ -1,5 +1,5 @@
 module Cap
   module Elb
-    VERSION = "0.0.5"
+    VERSION = "0.0.6"
   end
 end

data/lib/cap-elb.rb

@@ -1,5 +1,6 @@
 require 'right_aws'
-require "cap-elb/version"
+require 'aws-sdk' # need for ELB instance getter
+require 'cap-elb/version'
 
 unless Capistrano::Configuration.respond_to?(:instance)
   abort "cap-elb requires Capistrano 2"
@@ -8,32 +9,111 @@ end
 module Capistrano
   class Configuration
     module LoadBalancers
-      # Associate a group of EC2 instances behind a load balancer with a role. In order to use this, you
-      # must use the Load Balancer feature in Amazon EC2 to group your servers
-      # by role.
-      # 
-      # First, specify the load balancer name, then the roles and params:
-      #
-      #   group :webserver, :web
-      #   group :app_myappname, :app
-      #   group "MySQL Servers", :db, :port => 22000
+	    # Associate a group of EC2 instances behind a load balancer with a role to be used for Capistrano tasks. In order to use this, you
+	    # must use the Load Balancer feature in Amazon EC2 to group your servers
+	    # by role.
+	    # 
+	    # In order to use the loadbalancer extension in your capistrano scripts.
+	    # you will need to install the `cap-elb` plugin, then krequire it in your `deploy.rb`:
+
+	    # 	require 'cap-elb'
+
+	    # If you have already been doing capistrano deploys to your AWS instances, you probably already have your
+	    # AWD credentials configured.  Either add your credentials to your ~/.caprc :
+
+	    # 	set :aws_access_key_id, 'YOUR_AWS_ACCESS_KEY_ID'
+	    # 	set :aws_secret_access_key, 'YOUR_AWS_SECRET_ACCESS_KEY'
+
+	    # or, directly in your deploy file:
+
+	    # 	set :aws_access_key_id, 'YOUR_AWS_ACCESS_KEY_ID'
+	    # 	set :aws_secret_access_key, 'YOUR_AWS_SECRET_ACCESS_KEY'
+
+	    # If you wish, you can also set other AWS specfic parameters:
+
+	    # 	set :aws_params, :region => 'us-east-1'
+	    
+	    # In order to define your instance groups, you must specify the security group name, the roles and params.
+	    # Next you will set up your instance sets associated with a named load balancer instance in your AWS account.
+	    # You will call out the load balancer name (e.g. 'lb_webserver'), the capistrano role associated with that load balancer (.e.g. 'web'),
+	    # and any optional params.
+
+	    # 	loadbalancer :lb_webserver, :web
+	    # 	loadbalancer :lb_appserver, :app
+	    # 	loadbalancer :lb_dbserver, :db, :port => 22000
+
+	    # There are two special parameters you can add, :require and :exclude.
+
+	    # AWS instances have top level metadata and user defined tag data, and this data can be used by your loadbalancer rule
+	    #  to include or exclude certain instances from the instance set.
+
+	    # Take the :require keyword; Lets say  we only want to deploy to AWS instances which are in the 'running' state. To do that:
+
+	    # 	loadbalancer :lb_appserver, :app, :require => { :aws_state => "running" }
+
+	    # The server set defined here for role :app are all instances in the loadbalancer 'lb_appserver' with aws_state set to 'running'.
+
+	    # Perhaps you have added tags to your instances, if so, you might want to deploy to only the instances meeting a specific tag value:
+
+	    # 	loadbalancer :lb_appserver, :app, :require => { :aws_state => "running", :tags => {'fleet_color' => "green", 'tier' => 'free'} }
+
+	    # The server set defined here for role :app are all instances in the loadbalancer 'lb_appserver' with aws_state set to 'running',
+	    # and that have the named 2 tags set, with exactly those values for each.  There can be other tags in the instance, but the named tags in the rule must be present
+	    # for the given instance to make it into the server set.
+
+	    # Now consider the :exclude keyword; Lets say we do not want to deploy to AWS instances which are 'micro' sized. To do that:
+	    
+	    # 	loadbalancer :lb_appserver, :app, :exclude => { :aws_instance_type => "t1.micro"  }
+
+	    # You can exclude instances that have certain tags:
+
+	    # 	loadbalancer :lb_appserver, :app, :exclude => { :aws_instance_type => "t1.micro", :tags => {'state' => 'dontdeploy' }  }
+
+	    # When your capistrono script is complete, you can deploy to all instances within the ELB that meet your criteria with:
+
+	    # 	% cap deploy
+
+	    # Here's an example of a task that does a quick list of the instance ids (if any) within the load balancer associated with the 'app' role
+	    # that meets the criteria you laid out in the loadbalancer definition line, 
+	    # add this to your cap deploy file:
+
+	    # 	# run with cap ec2:list
+	    # 	namespace :ec2 do
+	    # 		desc "list instances"
+	    # 		task :list, :roles => :app do
+	    # 			run "hostname"
+	    # 		end
+	    # 	end
+
+	    # This will give you the list of hosts behind the load balancer that meet the criteria.
+	    # 	% cap ec2:list
+
       def loadbalancer (named_load_balancer, *args)
+
+	      aws_config_setup
+
 	      require_arglist = args[1][:require] rescue {}
 	      exclude_arglist = args[1][:exclude] rescue {}
+	      named_region = fetch(:aws_params)[:region] rescue 'us-east-1'
 
 	      # list of all the instances assoc'ed with this account
 	      @ec2_api ||= RightAws::Ec2.new(fetch(:aws_access_key_id), fetch(:aws_secret_access_key), fetch(:aws_params, {}))
 
-	      # fetch a raw list all the load balancers
-	      @elb_api ||= RightAws::ElbInterface.new(fetch(:aws_access_key_id), fetch(:aws_secret_access_key))
+	      # fetch a raw list all the load balancers, this is best done in Amaazons' aws-sdk, as it allows region specification for LBs.
+	      # strangely, RightScale gem doesnt seem to support this.
+	      # i filed a bug with RightScale: https://github.com/rightscale/right_aws/issues/95
+	      @elb_api = AWS::ELB.new
 
 	      # only get the named load balancer
-	      named_elb_instance = @elb_api.describe_load_balancers.delete_if{ |instance| instance[:load_balancer_name] != named_load_balancer.to_s }
+	      named_elb = @elb_api.load_balancers[named_load_balancer]
 
 	      # must exit if no load balancer on record for this account by given name in cap config file
-	      raise Exception, "No load balancer named: #{named_load_balancer.to_s} for aws account with this access key: #{:aws_access_key_id}" if named_elb_instance.empty?
+	      raise Exception, "No load balancer found named: #{named_load_balancer.to_s} for aws account with this access key: #{fetch(:aws_access_key_id)} in this region: #{named_region}" if named_elb.nil?
+	      # probe for a count of the instances, if this raises Exception, load balancer can't be found
+	      named_elb.instances.count rescue raise Exception, "No load balancer found named: #{named_load_balancer.to_s} for aws account with this access key: #{fetch(:aws_access_key_id)} in this region: #{named_region}" 
+	      raise Exception, "No instances within this load balancer: #{named_load_balancer.to_s} for aws account with this access key: #{fetch(:aws_access_key_id)} in this region: #{named_region}" if  named_elb.instances.count == 0
 
-	      elb_ec2_instances = named_elb_instance[0][:instances] rescue {}
+	      elb_ec2_instances = named_elb.instances.map { |i| i.id }  # list of instance ids
 
 	      # get the full instance list for account, this is necessary to subsquently fish out the :dns_name for the instances that survive our reduction steps
 	      account_instance_list = @ec2_api.describe_instances
@@ -55,6 +135,27 @@ module Capistrano
 
       private
 
+      # AWS SDK setup
+      def aws_config_setup()
+
+	      # derive AWS canonical endpoints from given region
+	      # set :ec2_endpoint , 'ec2.us-west-1.amazonaws.com'
+	      # set :elb_endpoint ,'us-west-1.elasticloadbalancing.amazonaws.com'
+
+	      named_region = fetch(:aws_params)[:region] rescue 'us-east-1'
+
+	      ec2_endpoint = "ec2.#{named_region}.amazonaws.com"
+	      elb_endpoint = "#{named_region}.elasticloadbalancing.amazonaws.com"
+
+	      # aws configuration, required separately
+	      AWS.config({
+				 :access_key_id => fetch(:aws_access_key_id),
+				 :secret_access_key => fetch(:aws_secret_access_key),
+				 :ec2_endpoint => ec2_endpoint,
+				 :elb_endpoint => elb_endpoint,
+			 })
+      end
+      
       def any_args_within_instance(instance, exclude_arglist)
 	      exargs = exclude_arglist.clone # must copy since delete transcends scope; if we don't copy, subsequent 'map'ped enum arglists would be side-effected
 	      tag_exclude_state = nil # default assumption
@@ -85,7 +186,7 @@ module Capistrano
 end
 
 # stub for future extensions
- module Cap
-   module Elb
-   end
- end
+ # module Cap
+ #   module Elb
+ #   end
+ # end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cap-elb
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-10-28 00:00:00.000000000Z
+date: 2011-11-04 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: right_aws
-  requirement: &2156273780 !ruby/object:Gem::Requirement
+  requirement: &2156644440 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - =
@@ -21,10 +21,10 @@ dependencies:
         version: 2.1.0
   type: :runtime
   prerelease: false
-  version_requirements: *2156273780
+  version_requirements: *2156644440
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2156273160 !ruby/object:Gem::Requirement
+  requirement: &2156643680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,7 +32,7 @@ dependencies:
         version: '2.6'
   type: :development
   prerelease: false
-  version_requirements: *2156273160
+  version_requirements: *2156643680
 description: Capistrano can perform tasks on the EC2 instances managed by named Amazon
   ELB instances.  Various filters are qvailable to allow EC2 instance top level metadata
   and tags to determine whether the task should be applied on the given instance.