cloudfinder-ec2 0.1.0

data/.gitattributes

@@ -0,0 +1,29 @@
+# Autodetect text files, normalize to LF on commit
+* text=auto
+
+# Explicitly define files which should be LF when checked out and on commit
+*.md    text eol=lf
+*.sh    text eol=lf
+*.rb    text eol=lf diff=ruby
+*.php   text eol=lf diff=php
+*.yml   text eol=lf
+*.sql   text eol=lf
+*.xml   text eol=lf
+*.xsd   text eol=lf
+*.css   text eol=lf
+*.js    text eol=lf
+*.pem   text eol=lf
+LICENSE text eol=lf
+README  text eol=lf
+
+# Declare files that will always have CRLF line endings on checkout (still stored LF)
+*.bat text eol=crlf
+
+# Denote all files that are truly binary and should not be modified.
+*.png    binary
+*.jpg    binary
+*.gif    binary
+*.ttf    binary
+*.swf    binary
+*.zip    binary
+*.sqlite binary

data/.gitignore

@@ -0,0 +1,22 @@
+/.vagrant
+# rcov generated
+coverage
+coverage.data
+
+# rdoc generated
+rdoc
+
+# yard generated
+doc
+.yardoc
+
+# bundler
+.bundle
+
+# jeweler generated
+pkgtmp/
+tmp/
+
+# Don't include Gemfile.lock in gems
+Gemfile.lock
+pkg/

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format documentation
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.1.1

data/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+We love pull requests. Here's a quick guide:
+
+1. Fork the repo, and make your changes.
+
+2. Once you're ready to submit, rebase your branch against our master branch to
+maintain a clean history and ensure you're up to date with all the most recent
+changes.
+
+3. Run the tests. We only take pull requests with passing tests, and it's great
+to know that you have a clean slate: `bundle && rake`
+
+4. Add a test for your change. Only refactoring and documentation changes
+require no new tests. If you are adding functionality or fixing a bug, we need
+a test!
+
+5. Make the test pass.
+
+6. Push to your fork and submit a pull request.
+
+
+At this point you're waiting on us. We like to at least comment on, if not
+accept, pull requests within three business days (and, typically, one business
+day). We may suggest some changes or improvements or alternatives. Your pull request
+will be built by [Travis](https://travis-ci.org/edbookfest/cloudfinder-ec2) first - 
+if the build fails please fix that first.
+
+Some things that will increase the chance that your pull request is accepted,
+taken straight from the Ruby on Rails guide:
+
+* Include tests that fail without your code, and pass with it
+* Update the documentation, the surrounding one, examples elsewhere, guides,
+  whatever is affected by your contribution
+
+Syntax:
+
+* Two spaces, no tabs.
+* No trailing whitespace. Blank lines should not have any space.
+* Prefer &&/|| over and/or.
+* MyClass.my_method(my_arg) not my_method( my_arg ) or my_method my_arg.
+* a = b and not a=b.
+* Follow the conventions you see used in the source already.
+
+And in case we didn't emphasize it enough: we love tests!

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+# Dependencies specified in the gemspec
+gemspec
+
+group :development do
+  gem 'coveralls',  :require => false
+end

data/Guardfile

@@ -0,0 +1,5 @@
+guard :rspec, cmd:'bundle exec rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/cloudfinder-ec2/(.+)\.rb$})     { |m| "spec/cloudfinder-ec2/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/LICENSE.txt

@@ -0,0 +1,29 @@
+Copyright (c) 2015 Edinburgh International Book Festival Ltd, a 
+a company limited by guarantee (no SC 79939) with charitable status 
+(SC 010120). Registered office 5a Charlotte Square, Edinburgh, EH2 4DR.
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are 
+permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list 
+   of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this 
+   list of conditions and the following disclaimer in the documentation and/or other 
+   materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may 
+   be used to endorse or promote products derived from this software without specific 
+   prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
+SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
+OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
+TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,138 @@
+# Cloudfinder::EC2
+
+[![Build Status](https://travis-ci.org/edbookfest/cloudfinder-ec2.png)](https://travis-ci.org/edbookfest/cloudfinder-ec2)
+[![Coverage Status](https://coveralls.io/repos/edbookfest/cloudfinder-ec2/badge.png?branch=master)](https://coveralls.io/r/edbookfest/cloudfinder-ec2)
+[![Gem Version](https://badge.fury.io/rb/cloudfinder-ec2.png)](http://badge.fury.io/rb/cloudfinder-ec2)
+[![Code Climate](https://codeclimate.com/github/edbookfest/cloudfinder-ec2.png)](https://codeclimate.com/github/edbookfest/cloudfinder-ec2)
+[![Dependency Status](https://gemnasium.com/edbookfest/cloudfinder-ec2.png)](https://gemnasium.com/edbookfest/cloudfinder-ec2)
+
+Uses EC2 instance tags to locate all the running instances in a given cluster, grouped by role.
+
+## Tagging your instances
+
+An instance can belong to a single cluster, with a single role. These are identified based on two EC2 tags with the
+keys `cloudfinder-cluster` and the `cloudfinder-role`. Add the tags to your instances using the AWS API, command line
+tools, console, or as part of an auto-scaling-group launch configuration.
+
+## API credentials
+
+cloudfinder-ec2 needs access to a set of AWS credentials with read-only access to your EC2 instances. When running
+on EC2, the best way to provide this is with an instance IAM role. Local AWS credentials files and environment
+variables are also supported. For further information on credential management see the
+[aws-sdk documentation](http://docs.aws.amazon.com/sdkforruby/api/index.html#Credentials)
+
+## Cluster detection
+
+By default, cloudfinder-ec2 will query the EC2 instance metadata API to attempt to detect the name and EC2 region
+of the cluster containing the running instance.
+
+If you are running outside EC2, or want to load details of a different cluster (for example if you are running
+the command on an EC2 server that is not part of the cluster you're interested in) you can specify the cluster
+name and region to load.
+
+If you do not provide a cluster name and region, and you are not on EC2, then the command will fail.
+
+## Usage
+
+### As a shell command
+
+Install the cloudfinder-ec2 binary by adding the gem to your system in the usual way
+(`gem install cloudfinder-ec2`).
+
+Running `cloudfinder-ec2 list` will output a JSON hash of the running cluster, grouped by role, which
+looks something like this:
+
+```json
+{
+  "cluster_name": "production",
+  "roles": {
+    "loadbalancer": [
+      {
+        "instance_id": "i-00000001",
+        "public_ip": "46.137.96.1",
+        "public_dns": "ec2-46-137-96-1.eu-west-1.compute.amazonaws.com",
+        "private_dns": "ip-10-248-183-1.eu-west-1.compute.internal",
+        "private_ip": "10.248.183.1",
+        "role": "loadbalancer"
+      }
+    ],
+    "app-server": [
+      {
+        "instance_id": "i-00000002",
+        "public_ip": "54.74.200.2",
+        "public_dns": "ec2-54-74-200-2.eu-west-1.compute.amazonaws.com",
+        "private_dns": "ip-10-56-18-2.eu-west-1.compute.internal",
+        "private_ip": "10.56.18.2",
+        "role": "app-server"
+      },
+      {
+        "instance_id": "i-00000003",
+        "public_ip": "54.74.200.3",
+        "public_dns": "ec2-54-74-200-3.eu-west-1.compute.amazonaws.com",
+        "private_dns": "ip-10-56-18-3.eu-west-1.compute.internal",
+        "private_ip": "10.56.18.3",
+        "role": "app-server"
+      }
+    ],
+    "db-server": [
+      {
+        "instance_id": "i-00000004",
+        "public_ip": "54.220.216.4",
+        "public_dns": "ec2-54-220-216-4.eu-west-1.compute.amazonaws.com",
+        "private_dns": "ip-10-86-141-4.eu-west-1.compute.internal",
+        "private_ip": "10.86.141.4",
+        "role": "db-server"
+      }
+    ]
+  }
+}
+```
+
+This output is designed to be piped to a file or captured by any other process that needs information about
+the composition of a given cluster.
+
+### As a library
+
+You can also use cloudfinder-ec2 as a gem within your ruby application. Add it to your project's Gemfile, and
+then:
+
+```ruby
+require 'cloudfinder-ec2'
+cluster = Cloudfinder::EC2::Clusterfinder.new.find(cluster_name: 'production', region: 'eu-west-1)
+# returns a Cloudfinder::EC2::Cluster instance with useful methods to interact with your cluster
+
+if cluster.running?
+  puts cluster.list_roles
+  puts cluster.has_role?(:db)
+  puts cluster.list_role_instances(:db)
+end
+```
+
+You can also autodetect the cluster if required. This will throw an exception if the instance metadata is
+not available (eg because you are not on an EC2 instance).
+
+```ruby
+require 'cloudfinder-ec2'
+puts Cloudfinder::EC2::Clusterfinder.new.detect_cluster # {cluster_name: 'production', region: 'eu-west-1'}
+```
+
+### Within a chef recipe
+
+```ruby
+chef_gem 'cloudfinder-ec2'
+require 'cloudfinder-ec2'
+# and use as a library as above
+```
+
+## Limitations
+
+* Exceptions raised by the instance metadata service and/or AWS API are allowed to bubble, there is no
+  retry or recovery within the library.
+* Currently we only fetch a single page of results from the AWS API. If you have more instances that fit
+  in a single describe instances call, you probably need a more sophisticated cluster discovery tool
+* We only search for cluster instances in a single AWS region - again if you have multi-region clusters
+  you may be better with a more sophisticated tool
+
+## Copyright
+
+Copyright (c) 2015 Edinburgh International Book Festival Ltd. See LICENSE.txt for further details.

data/Rakefile

@@ -0,0 +1,18 @@
+#!/usr/bin/env rake
+require 'rubygems'
+require 'bundler/setup'
+require 'rspec/core/rake_task'
+
+# Change to the directory of this file.
+Dir.chdir(File.expand_path("../", __FILE__))
+
+# This installs the tasks that help with gem creation and
+# publishing.
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = "spec/**/*_spec.rb"
+end
+
+task :default => :spec

data/bin/cloudfinder

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+require 'cloudfinder-ec2'
+require 'slop'
+
+opts = Slop.new strict: true, help: true do
+  banner (<<-eos).gsub(/^ +/m, '')
+    Finds running EC2 instances using cloudfinder-cluster and cloudfinder-role tags
+
+    Requires credentials authorised for read-only access to the AWS API - by default
+    will look in:
+
+    * ENV['AWS_ACCESS_KEY_ID'] and ENV['AWS_SECRET_ACCESS_KEY'] (not recommended)
+    * a credentials file at ~/.aws/credentials
+    * an instance's configured IAM role when running on EC2 (recommended)
+
+    Credentials are more fully documented at
+    http://docs.aws.amazon.com/sdkforruby/api/index.html#Credentials
+  eos
+
+  command :list do
+    description 'Output details of the running cluster as JSON'
+    banner      (<<-eos).gsub(/^ +/m, '')
+      Display the details of a running cluster as JSON
+      ------------------------------------------------
+      Usage: cloudfinder-ec2 list [--cluster-name=production] [--region=eu-west-1]
+
+      By default, attempts to autodetect the name and/or region of the cluster from the EC2
+      metadata of this instance. If this is not an EC2 instance this will fail.
+
+      If you specify both the --cluster-name and --region arguments then autodetection will
+      be skipped.
+    eos
+
+    on '--cluster-name', 'Name of the cluster to load instead of autodetecting', argument: :optional
+    on '--region', 'EC2 region to search instead of autodetecting', argument: :optional
+
+    run do |opts|
+      Cloudfinder::EC2::Command::List.factory.execute(
+          cluster_name: opts['cluster-name'],
+          region: opts['region']
+      )
+    end
+  end
+
+  on '--version', 'Display the version' do
+    puts Cloudfinder::EC2::VERSION
+  end
+
+  # Treat running without a command as an error
+  run do
+    raise(Slop::InvalidCommandError, 'ERROR: You must specify the cloudfinder-command to run')
+  end
+
+end
+
+# Run the command
+begin
+  opts.parse
+rescue Slop::Error => e
+  STDERR.puts e.message
+  puts ''
+  puts opts # print help
+end

data/cloudfinder-ec2.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'cloudfinder-ec2/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "cloudfinder-ec2"
+  gem.version       = Cloudfinder::EC2::VERSION
+  gem.authors       = ["Andrew Coulton"]
+  gem.email         = ["andrew@ingenerator.com"]
+  gem.license       = 'BSD-3-Clause'
+  gem.description   = 'Uses EC2 instance tags to locate all the running instances in a given cluster, grouped by role.'
+  gem.summary       = gem.description
+  gem.homepage      = "https://github.com/edbookfest/cloudfinder-ec2"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency 'aws-sdk', '~>2.0'
+  gem.add_dependency 'slop',    '~>3.6'
+
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'guard'
+  gem.add_development_dependency 'guard-rspec'
+end

data/lib/cloudfinder-ec2.rb

@@ -0,0 +1,8 @@
+require 'aws-sdk'
+require 'cloudfinder-ec2/version'
+require 'cloudfinder-ec2/consts'
+require 'cloudfinder-ec2/instance'
+require 'cloudfinder-ec2/cluster'
+require 'cloudfinder-ec2/clusterfinder'
+require 'cloudfinder-ec2/detector'
+require 'cloudfinder-ec2/command/list'

data/lib/cloudfinder-ec2/cluster.rb

@@ -0,0 +1,88 @@
+module Cloudfinder
+  module EC2
+    class Cluster
+
+      attr_reader(:cluster_name)
+
+      # @param [Hash] args containing the cluster name and the instances
+      # @return [Cloudfinder::EC2::Cluster]
+      def initialize(args)
+        @cluster_name = args[:cluster_name]
+        @instances    = args[:instances]
+      end
+
+      # @return [bool]
+      def empty?
+        instances.empty?
+      end
+
+      # @return [bool]
+      def running?
+        !empty?
+      end
+
+      # @param [symbol] role
+      # @return [bool]
+      def has_role?(role)
+        list_roles.include?(role)
+      end
+
+      # @param [string] instance_id
+      # @return [bool]
+      def has_instance?(instance_id)
+        instances.any? { |instance| instance.instance_id == instance_id }
+      end
+
+      def get_instance(instance_id)
+        found_instances = instances.select { |instance| instance.instance_id == instance_id }
+        raise(RangeError, "#{instance_id} is not part of the #{@cluster_name} cluster") if found_instances.empty?
+        found_instances.first
+      end
+
+      # @return [Array<symbol>]
+      def list_roles
+        instances.group_by { |instance| instance.role }.keys
+      end
+
+      # @param [symbol] role
+      # @return [Array<Cloudfinder::EC2::Instance>]
+      def list_role_instances(role)
+        instances.select { |instance| instance.role === role }
+      end
+
+      # Return the current cluster as a simple nested hash, suitable for rendering to JSON or similar
+      #
+      #   {
+      #      cluster_name: 'production',
+      #      roles: {
+      #        db: [
+      #           {instance_id: 'i-00000001', public_ip: '123.456.789.123',...}
+      #        ]
+      #      }
+      #   }
+      #
+      # @return [Hash]
+      def to_hash
+        hash = {
+            cluster_name: @cluster_name,
+            roles:        {}
+        }
+
+        instances.each do |instance|
+          hash[:roles][instance.role] = [] unless hash[:roles][instance.role]
+          hash[:roles][instance.role] << instance.to_hash
+        end
+
+        hash
+      end
+
+      private
+
+      # @return [Array<Cloudfinder::EC2::Instance>]
+      def instances
+        @instances
+      end
+
+    end
+  end
+end