cap-ec2 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5a25dd0326b87cea692c5705d43f18f0807e0bd4
+  data.tar.gz: b5ac734c1300be5f7c38d5cc1d3b09da10160a94
+SHA512:
+  metadata.gz: 20b475068cfd99dc4cc37a54a1c3e1ad647d2e032a2bbe625d3a291be8648fcb95b839c056b740403fa49697079193f02b1d3334d4bbf48bf7aab1b2280f23af
+  data.tar.gz: 80d4a7e3694dc689ded905de412c40f1991ccb0f362e5a2637c1daea0df0a509965cc92bd7dc5739e7a143694134002221def62b7c55ef77720af6cc6e09975b

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in capify-v3-ec2.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Andy Sykes
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,206 @@
+# Cap-EC2
+
+Cap-EC2 is used to generate Capistrano namespaces and tasks from Amazon EC2 instance tags, 
+dynamically building the list of servers to be deployed to.
+
+## Notes
+
+Cap-EC2 is only compatible with Capistrano 3.x or later; if you want the Capistrano 2.x version, 
+use [Capify-EC2](https://github.com/forward/capify-ec2). Note that the configuration file (`config/ec2.yml`)
+is not compatible between versions either.
+
+This documentation assumes familiarity with Capistrano 3.x.
+
+A number of features that are in Capify-EC2 are not yet available in Cap-EC2, due to the 
+architectural changes in Capistrano 3.x. The following features are missing (this is not
+an exhaustive list!):
+* rolling deploy (this should be implemented via [SSHKit](https://github.com/capistrano/sshkit))
+* ELB registration/de-registration (not widely used)
+* using IAM roles to provide credentials
+* Variables set by EC2 tags
+* Connecting to instances via SSH using a convenience task
+
+Pull requests for these would be welcomed, as would sending feedback via the Issues on this project about
+features you would like.
+
+## Installation
+
+    gem install cap-ec2
+
+or add the gem to your project's Gemfile.
+
+You will need to create a YAML configuration file at `config/ec2.yml` that looks like the following:
+
+```ruby
+access_key_id: "YOUR ACCESS KEY"
+secret_access_key: "YOUR SECRET KEY"
+regions:
+ - 'eu-west-1'
+```
+
+You also need to add the gem to your Capfile:
+
+```ruby
+require "cap-ec2/capistrano"
+```
+
+## Configuration
+
+Your `config/ec2.yml` file must contain at least the information above (`access_key_id`, `secret_access_key`, `regions`).
+Omitting any of these will raise an exception.
+
+The following are optional settings you can use.
+
+* project_tag
+  
+  If this is defined, Cap-EC2 will look for a tag with this name when searching for instances belong
+  to this project. Cap-EC2 will look for a value which matches the `:application` setting in your
+  `deploy.rb`. The tag name defaults to "Project".
+  
+* stages_tag
+
+  If this is defined, Cap-EC2 will look for a tag with this name to determine which instances belong to
+  a given stage. The tag name defaults to "Stage".
+
+* roles_tag
+
+  If this is defined, Cap-EC2 will look for a tag with this name to determine which instances belong to
+  a given role. The tag name defaults to "Roles". 
+
+## Usage
+
+Imagine you have four servers on EC2 named and tagged as follows:
+
+<table>
+  <tr>
+    <td>'Name' Tag</td>
+    <td>'Roles' Tag</td>
+    <td>'Stages' Tag</td>
+  </tr>
+  <tr>
+    <td>server-1</td>
+    <td>web</td>
+    <td>production</td>
+  </tr>
+  <tr>
+    <td>server-2</td>
+    <td>web,app</td>
+    <td>production</td>
+  </tr>
+  <tr>
+    <td>server-3</td>
+    <td>app,db</td>
+    <td>production</td>
+  </tr>
+  <tr>
+    <td>server-4</td>
+    <td>web,db,app</td>
+    <td>staging</td>
+  </tr>
+</table>
+
+Imagine also that we've called our app "testapp", as defined in `config/deploy.rb` like so:
+
+    set :application, "testapp"
+
+### Defining the roles in `config/deploy/[stage].rb`
+
+To define a role, edit `config/deploy/[stage].rb` and add the following:
+
+    ec2_role :web
+
+Let's say we edited `config/deploy/production.rb`. Adding this configuration to the file would assign
+the role `:web` to any instance that has the following properties:
+* has a tag called "Roles" that contains the string "web"
+* has a tag called "Project" that contains the string "testapp"
+* has a tag called "Stage" that contains the current stage we're executing (in this case, "production")
+
+Looking at the above table, we can see we would match `server-1` and `server-2`. (You can have multiple
+roles in tag separated by commas.)
+
+Now we can define the other roles:
+
+    ec2_role :app
+    ec2_role :db
+
+In the "production" stage, the `:app` role would apply to `server-2` and `server-3`, and the `:db`
+role would apply to `server-3`.
+
+In the "staging" stage, all roles would apply *only* to `server-4`.
+
+### Passing options to roles
+
+You can pass options when defining your roles. The options are *exactly* the same as the options that
+the Capistrano native `role` definition takes, since they are passed straight through to Capistrano.
+For example:
+
+    ec2_role :app,
+      user: 'user_name',
+      ssh_options: {
+        user: 'user_name', # overrides user setting above
+        keys: %w(/home/user_name/.ssh/id_rsa),
+        forward_agent: false,
+        auth_methods: %w(publickey password)
+        password: 'please use keys'
+      }
+
+See the example config files Capistrano builds for you in `config/deploy` for more details.
+
+Note that at the moment there's no way to pass variables in from EC2 tags - but it would be
+trivial to add.
+
+### Tasks and deployment
+
+You can now define your tasks for these roles in exactly the same way as you would if you weren't
+using this gem. 
+
+## Utility tasks
+
+Cap-EC2 adds a few utility tasks to Capistrano for displaying information about the instances that
+you will be deploying to. Note that unlike Capistrano 2.x, all tasks *require* a stage.
+
+### View instances
+
+This command will show you information all the instances your configuration matches for a given stage.
+
+    cap [stage] ec2:status
+
+Example:
+
+    $ cap production ec2:status
+    
+    Num  Name                          ID          Type      DNS              Zone        Roles         Stage
+    00:  server-1-20131030-1144-0      i-abcdefgh  m1.small  192.168.202.248  us-west-2c  banana,apple  production
+    01:  server-2-20131118-1839-0      i-hgfedcba  m1.small  192.168.200.60   us-west-2a  banana        production
+
+### View server names
+
+This command will show you the server names of the instances matching the given stage:
+
+  cap [stage] ec2:server_names
+
+Example:
+
+    $ cap production ec2:server_names
+    server-1-20131030-1144-0
+    server-2-20131118-1839-0 
+
+### View server instance IDs
+  
+This command will show the instance IDs of the instances matching the given stage:
+  
+    cap [stage] ec2:instance_ids
+  
+Example:
+  
+    $ cap production ec2:instance_ids
+    i-abcdefgh
+    i-hgfedcba
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/cap-ec2.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'cap-ec2/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "cap-ec2"
+  spec.version       = CapEC2::VERSION
+  spec.authors       = ["Andy Sykes"]
+  spec.email         = ["github@tinycat.co.uk"]
+  spec.description   = %q{Cap-EC2 is used to generate Capistrano namespaces and tasks from Amazon EC2 instance tags, dynamically building the list of servers to be deployed to.}
+  spec.summary       = %q{Cap-EC2 is used to generate Capistrano namespaces and tasks from Amazon EC2 instance tags, dynamically building the list of servers to be deployed to.}
+  spec.homepage      = "https://github.com/forward3d/cap-ec2"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  
+  spec.add_dependency "aws-sdk"
+  spec.add_dependency "capistrano", ">= 3.0"
+  spec.add_dependency "terminal-table"
+  spec.add_dependency "colored"
+end

data/lib/cap-ec2/capistrano.rb

@@ -0,0 +1,34 @@
+require 'capistrano/setup'
+require 'capistrano/configuration'
+require 'aws-sdk'
+require 'colored'
+require 'terminal-table'
+require 'yaml'
+require_relative 'ec2-handler'
+require_relative 'status-table'
+require_relative 'instance'
+
+# Load extra tasks
+load File.expand_path("../tasks/ec2.rake", __FILE__)
+
+# Monkey patch into Capistrano v3
+
+module Capistrano
+  module TaskEnhancements
+
+    def ec2_handler
+      @ec2_handler ||= CapEC2::EC2Handler.new(env.fetch(:ec2_config, "config/ec2.yml"))
+    end
+    
+    def ec2_role(name, options={})
+      ec2_handler.get_servers_for_role(name).each do |server|
+        env.role(name, server.contact_point, options)
+      end
+    end
+    
+    def env
+      Configuration.env
+    end
+    
+  end
+end

data/lib/cap-ec2/ec2-handler.rb

@@ -0,0 +1,84 @@
+module CapEC2
+  class EC2Handler
+    
+    def initialize(ec2_config = "config/ec2.yml")
+      @ec2_config = YAML.load_file ec2_config
+      @ec2 = {}
+      @ec2_config["regions"].each do |region|
+        @ec2[region] = AWS::EC2.new(
+        access_key_id: @ec2_config["access_key_id"],
+        secret_access_key: @ec2_config["secret_access_key"],
+        region: region
+      )
+      end
+    end
+    
+    def status_table
+      CapEC2::StatusTable.new(
+        defined_roles.map {|r| get_servers_for_role(r)}.flatten.uniq {|i| i.instance_id}
+      )
+    end
+    
+    def server_names
+      puts defined_roles.map {|r| get_servers_for_role(r)}
+                   .flatten
+                   .uniq {|i| i.instance_id}
+                   .map {|i| i.tags["Name"]}
+                   .join("\n")
+    end
+    
+    def instance_ids
+      puts defined_roles.map {|r| get_servers_for_role(r)}
+                   .flatten
+                   .uniq {|i| i.instance_id}
+                   .map {|i| i.instance_id}
+                   .join("\n")
+    end
+    
+    def defined_roles
+      Capistrano::Configuration.env.send(:servers).send(:available_roles)
+    end
+    
+    def stage
+      Capistrano::Configuration.env.fetch(:stage).to_s
+    end
+    
+    def application
+      Capistrano::Configuration.env.fetch(:application).to_s
+    end
+    
+    def project_tag
+      @ec2_config["project_tag"] || "Project"
+    end
+    
+    def roles_tag
+      @ec2_config["roles_tag"] || "Roles"
+    end
+    
+    def stages_tag
+      @ec2_config["stages_tag"] || "Stage"
+    end
+    
+    def tag(tag_name)
+      "tag:#{tag_name}"
+    end
+    
+    def get_servers_for_role(role)
+      servers = []
+      each_region do |ec2|
+        instances = ec2.instances
+          .filter(tag(project_tag), application)
+          .filter(tag(stages_tag), stage)
+        servers << instances.select {|i| i.tags[roles_tag] =~ /,{0,1}#{role}(,|$)/}
+      end
+      servers.flatten
+    end
+    
+    def each_region
+      @ec2.keys.each do |region|
+        yield @ec2[region]
+      end
+    end
+    
+  end
+end

data/lib/cap-ec2/instance.rb

@@ -0,0 +1,11 @@
+# Monkey patch the AWS SDK to return a variable
+# "contact point" we can reach the server on
+module AWS
+  class EC2
+    class Instance
+      def contact_point
+        public_dns_name || public_ip_address || private_ip_address
+      end
+    end
+  end
+end

data/lib/cap-ec2/status-table.rb

@@ -0,0 +1,51 @@
+module CapEC2
+  class StatusTable
+    
+    def initialize(instances)
+      @instances = instances
+      output
+    end
+    
+    def header_row
+      [
+        "Num".bold,
+        "Name".bold,
+        "ID".bold,
+        "Type".bold,
+        "DNS".bold,
+        "Zone".bold,
+        "Roles".bold,
+        "Stage".bold
+      ]
+    end
+    
+    def output
+      table = Terminal::Table.new(
+        :style => {
+          :border_x => "",
+          :border_i => "",
+          :border_y => ""
+        }
+      )
+      table.add_row header_row
+      @instances.each_with_index do |instance,index|
+        table.add_row instance_to_row(instance, index)
+      end
+      puts table.to_s
+    end
+
+    def instance_to_row(instance, index)
+      [
+        sprintf("%02d:", index),
+        instance.tags["Name"].green,
+        instance.id.red,
+        instance.instance_type.cyan,
+        instance.contact_point.blue.bold,
+        instance.availability_zone.magenta,
+        instance.tags["Roles"].yellow,
+        instance.tags["Stage"].yellow
+      ]
+    end
+  end
+end
+

data/lib/cap-ec2/tasks/ec2.rake

@@ -0,0 +1,18 @@
+namespace :ec2 do
+  
+  desc "Show all information about EC2 instances that match this project"
+  task :status do
+    ec2_handler.status_table
+  end
+  
+  desc "Show EC2 server names that match this project"
+  task :server_names do
+    ec2_handler.server_names
+  end
+  
+  desc "Show EC2 instance IDs that match this project"
+  task :instance_ids do
+    ec2_handler.instance_ids
+  end
+  
+end

data/lib/cap-ec2/version.rb

@@ -0,0 +1,3 @@
+module CapEC2
+  VERSION = "0.0.1"
+end

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification
+name: cap-ec2
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Andy Sykes
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2013-12-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  prerelease: false
+  type: :development
+- !ruby/object:Gem::Dependency
+  name: rake
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  prerelease: false
+  type: :development
+- !ruby/object:Gem::Dependency
+  name: aws-sdk
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  prerelease: false
+  type: :runtime
+- !ruby/object:Gem::Dependency
+  name: capistrano
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  prerelease: false
+  type: :runtime
+- !ruby/object:Gem::Dependency
+  name: terminal-table
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  prerelease: false
+  type: :runtime
+- !ruby/object:Gem::Dependency
+  name: colored
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  prerelease: false
+  type: :runtime
+description: Cap-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:
+- github@tinycat.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- cap-ec2.gemspec
+- lib/cap-ec2/capistrano.rb
+- lib/cap-ec2/ec2-handler.rb
+- lib/cap-ec2/instance.rb
+- lib/cap-ec2/status-table.rb
+- lib/cap-ec2/tasks/ec2.rake
+- lib/cap-ec2/version.rb
+homepage: https://github.com/forward3d/cap-ec2
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project:
+rubygems_version: 2.1.9
+signing_key:
+specification_version: 4
+summary: Cap-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: []