cloudfinder-ec2 0.1.0

data/lib/cloudfinder-ec2/clusterfinder.rb

@@ -0,0 +1,97 @@
+module Cloudfinder
+  module EC2
+    class Clusterfinder
+
+      # Find all the running instances for a named cluster and build them into a cluster object,
+      # grouped by role.
+      #
+      # @param [Hash] query
+      # @option query [string] :cluster_name find instances tagged with this cluster name
+      # @option query [string] :region       EC2 region to search
+      # @return [Cloudfinder::EC2::Cluster]
+      def find(query)
+        validate_arguments(query)
+        @cluster_name = query[:cluster_name]
+        instances     = []
+
+        each_running_instance(query[:region]) do |instance_data|
+          if in_cluster?(instance_data) && has_role?(instance_data)
+            instances << new_instance(instance_data)
+          end
+        end
+
+        Cloudfinder::EC2::Cluster.new(
+            cluster_name: @cluster_name,
+            instances:    instances
+        )
+      end
+
+      private
+      ERR_REGION_REQUIRED       = 'You must provide a :region argument to Instancefinder::find'
+      ERR_CLUSTER_NAME_REQUIRED = 'You must provide a cluster_name argument to Instancefinder::find'
+
+      # @param [Hash] args
+      # @return [nil]
+      def validate_arguments(args)
+        raise(ArgumentError, ERR_REGION_REQUIRED) unless (args[:region])
+        raise(ArgumentError, ERR_CLUSTER_NAME_REQUIRED) unless (args[:cluster_name])
+      end
+
+      # Find and iterate over all instances running in the given region
+      #
+      # @param [string] region
+      # @return [Struct] instance data provided by AWS
+      def each_running_instance(region)
+        ec2    = Aws::EC2::Client.new(region: region)
+        result = ec2.describe_instances(
+            filters: [{ name: 'instance-state-name', values: ['running'] }]
+        )
+
+        result[:reservations].each do |reservation|
+          reservation[:instances].each do |instance_data|
+            yield instance_data
+          end
+        end
+      end
+
+      # @param [Struct] instance
+      # @return [bool]
+      def in_cluster?(instance)
+        find_tag_value(instance, CLUSTER_TAG_NAME) === @cluster_name
+      end
+
+
+      # @param [Struct] instance
+      # @return [bool]
+      def has_role?(instance)
+        instance.tags.any? { |tag| tag[:key] === ROLE_TAG_NAME }
+      end
+
+      # @param [Struct] instance
+      # @return [Cloudfinder::EC2::Instance]
+      def new_instance(instance)
+        Cloudfinder::EC2::Instance.new(
+            instance_id: instance[:instance_id],
+            role:        find_tag_value(instance, ROLE_TAG_NAME).to_sym,
+            public_ip:   instance[:public_ip_address],
+            private_ip:  instance[:private_ip_address],
+            public_dns:  instance[:public_dns_name],
+            private_dns: instance[:private_dns_name],
+        )
+      end
+
+      # @param [Struct] instance
+      # @param [string] tag_key
+      # @return [string]
+      def find_tag_value(instance, tag_key)
+        found_tag = instance.tags.select { |tag| tag[:key] === tag_key }
+        if found_tag.empty?
+          nil
+        else
+          found_tag.first[:value]
+        end
+      end
+
+    end
+  end
+end

data/lib/cloudfinder-ec2/command/list.rb

@@ -0,0 +1,72 @@
+require 'json'
+module Cloudfinder
+  module EC2
+    module Command
+      class List
+
+        # Factory an instance of the list command with concrete dependencies
+        #
+        # @return [Object]
+        def self.factory
+          self.new(
+              Cloudfinder::EC2::Clusterfinder.new,
+              Cloudfinder::EC2::Detector.new,
+              STDOUT,
+              STDERR
+          )
+        end
+
+        # @param [Cloudfinder::EC2::Clusterfinder] finder
+        # @param [Cloudfinder::EC2::Detector] detector
+        # @param [IO] stdout
+        # @param [IO] stderr
+        def initialize(finder, detector, stdout, stderr)
+          @finder = finder
+          @detector = detector
+          @stdout = stdout
+          @stderr = stderr
+        end
+
+        # Locates the roles and instances that make up a cluster, and prints the result to STDOUT
+        # as JSON for consumption by other processes.
+        #
+        # If the cluster_name or region are not provided, it will attempt to detect the cluster
+        # that the current instance belongs to (using the EC2 metadata service) and find other
+        # instances in the same cluster.
+        #
+        # If cluster detection fails, an exception will be thrown
+        #
+        # @param [Hash] query
+        # @option query [string] :cluster_name optionally specify cluster name to find
+        # @option query [string] :region       optionally specify EC2 region to search
+        # @return void
+        def execute(query = {})
+          unless query[:region] && query[:cluster_name]
+            query = autodetect_cluster_or_throw.merge(query)
+          end
+
+          cluster = @finder.find(query)
+          @stdout.puts(JSON.pretty_generate(cluster.to_hash))
+        end
+
+        private
+
+        def autodetect_cluster_or_throw
+          begin
+            return @detector.detect_cluster
+          rescue StandardError => e
+            @stderr.puts('------------------------------------------------------------')
+            @stderr.puts('| Automatic cluster detection error                        |')
+            @stderr.puts('|----------------------------------------------------------|')
+            @stderr.puts('| This instance may not be running on EC2, or there may be |')
+            @stderr.puts('| a temporary issue with the EC2 metadata service. See the |')
+            @stderr.puts('| exception message below for details.                     |')
+            @stderr.puts('------------------------------------------------------------')
+            raise e
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/cloudfinder-ec2/consts.rb

@@ -0,0 +1,6 @@
+module Cloudfinder
+  module EC2
+    CLUSTER_TAG_NAME = 'cloudfinder-cluster'
+    ROLE_TAG_NAME    = 'cloudfinder-role'
+  end
+end

data/lib/cloudfinder-ec2/detector.rb

@@ -0,0 +1,69 @@
+require 'open-uri'
+module Cloudfinder
+  module EC2
+    class Detector
+      EC2_METADATA_TIMEOUT  = 5
+      EC2_METADATA_BASE_URL = 'http://169.254.169.254/latest/meta-data'
+
+      # Detects the cluster for the current instance using the instance metadata service
+      # and the AWS API to fetch tags.
+      #
+      # @return [Hash] with the cluster_name, cluster_role, instance_id and region
+      def detect_cluster
+        initialize_metadata
+        result = {
+            region:       @region,
+            instance_id:  @instance_id,
+            cluster_name: nil,
+            cluster_role: nil
+        }
+
+        find_instance_tags.each do |tag|
+          if tag[:key] === CLUSTER_TAG_NAME
+            result[:cluster_name] = tag[:value]
+          elsif tag[:key] === ROLE_TAG_NAME
+            result[:cluster_role] = tag[:value].to_sym
+          end
+        end
+
+        if result[:cluster_name].nil? || result[:cluster_role].nil?
+          result[:cluster_name] = nil
+          result[:cluster_role] = nil
+        end
+
+        result
+      end
+
+      private
+
+      def initialize_metadata
+        @instance_id = find_instance_id
+        @region      = find_instance_region
+      end
+
+      # @return [Array<Hash>]
+      def find_instance_tags
+        ec2    = Aws::EC2::Client.new(region: @region)
+        result = ec2.describe_tags(filters: [{ name: 'resource-id', values: [@instance_id] }])
+        result[:tags]
+      end
+
+      # @return [string]
+      def find_instance_region
+        zone = get_metadata('/placement/availability-zone')
+        zone[0, zone.length - 1]
+      end
+
+      # @return [string]
+      def find_instance_id
+        get_metadata('/instance-id')
+      end
+
+      # @param [string] path
+      # @return [string]
+      def get_metadata(path)
+        open("#{EC2_METADATA_BASE_URL}#{path}", { read_timeout: EC2_METADATA_TIMEOUT }).read
+      end
+    end
+  end
+end

data/lib/cloudfinder-ec2/instance.rb

@@ -0,0 +1,34 @@
+module Cloudfinder
+  module EC2
+    class Instance
+      attr_reader(:instance_id)
+      attr_reader(:public_ip)
+      attr_reader(:public_dns)
+      attr_reader(:private_ip)
+      attr_reader(:private_dns)
+      attr_reader(:role)
+
+      # @param [Hash<string>] instance attributes
+      def initialize(data)
+        @instance_id = data[:instance_id].freeze
+        @public_ip   = data[:public_ip].freeze
+        @public_dns  = data[:public_dns].freeze
+        @private_ip  = data[:private_ip].freeze
+        @private_dns = data[:private_dns].freeze
+        @role        = data[:role]
+      end
+
+      # @return [Hash<string>]
+      def to_hash
+        {
+            instance_id: @instance_id,
+            public_ip:   @public_ip,
+            public_dns:  @public_dns,
+            private_dns: @private_dns,
+            private_ip:  @private_ip,
+            role:        @role
+        }
+      end
+    end
+  end
+end

data/lib/cloudfinder-ec2/version.rb

@@ -0,0 +1,5 @@
+module Cloudfinder
+  module EC2
+    VERSION = "0.1.0"
+  end
+end

data/spec/cloudfinder-ec2/cluster_spec.rb

@@ -0,0 +1,164 @@
+describe Cloudfinder::EC2::Cluster do
+  let (:cluster_name) { 'production' }
+  let (:instances) { [] }
+  subject { Cloudfinder::EC2::Cluster.new(cluster_name: cluster_name, instances: instances) }
+
+  shared_examples_for 'cluster' do
+    it 'should have cluster name' do
+      expect(subject.cluster_name).to eq(cluster_name)
+    end
+
+    it 'should include cluster name in hash representation' do
+      expect(subject.to_hash[:cluster_name]).to eq cluster_name
+    end
+  end
+
+  shared_examples_for 'undefined role' do |rolename|
+    it "should not have #{rolename} role" do
+      expect(subject).not_to have_role(rolename)
+    end
+
+    it "should not have #{rolename} in hash representation" do
+      expect(subject.to_hash[:roles]).not_to have_key rolename
+    end
+
+    it "should have empty instances for #{rolename} role" do
+      expect(subject.list_role_instances(rolename)).to be_empty
+    end
+  end
+
+  shared_examples_for 'undefined instance' do |unknown_instance_id|
+    it 'should not have unknown instance' do
+      expect(subject).not_to have_instance(unknown_instance_id)
+    end
+
+    it 'should throw when getting unknown instance'  do
+      expect {subject.get_instance(unknown_instance_id)}.to raise_error(RangeError)
+    end
+  end
+
+  shared_examples_for 'defined role with instances' do |role_name, instance_count|
+    it "should have #{role_name} role" do
+      expect(subject).to have_role(role_name)
+    end
+
+    it "should have #{role_name} in hash representation" do
+      expect(subject.to_hash[:roles]).to have_key role_name
+    end
+
+    it "should have #{instance_count} elements for #{role_name} in hash representation" do
+      expect(subject.to_hash[:roles][role_name].count).to eq instance_count
+    end
+
+    it "should list #{instance_count} instances for the #{role_name} role" do
+      expect(subject.list_role_instances(role_name).count).to eq(instance_count)
+    end
+  end
+
+  shared_examples_for 'running instance in role' do |role_name, instance_index, instance_id|
+    it "should have the #{role_name}:##{instance_index} instance" do
+      expect(subject).to have_instance(instance_id)
+    end
+
+    it "should get instance object for instance id #{instance_id}" do
+      instance = subject.get_instance(instance_id)
+      expect(instance).to be_a Cloudfinder::EC2::Instance
+      expect(instance.instance_id).to eq instance_id
+    end
+
+    it "should return instance object for #{role_name}:##{instance_index}" do
+      instance = subject.list_role_instances(role_name)[instance_index]
+      expect(instance).to be_a Cloudfinder::EC2::Instance
+      expect(instance.instance_id).to eq instance_id
+    end
+
+    it "should list the #{role_name}:##{instance_index} instance for the correct role" do
+      listed_instance = subject.list_role_instances(role_name)[instance_index]
+      expect(listed_instance.instance_id).to eq(instance_id)
+    end
+
+    it "should include #{role_name}:##{instance_index} in hash representation" do
+      instance = subject.get_instance(instance_id)
+      expect(subject.to_hash[:roles][role_name][instance_index]).to eq instance.to_hash
+    end
+  end
+
+  context 'when created with no instances' do
+    include_examples 'cluster'
+    it { should be_empty }
+    it { should_not be_running }
+
+    include_examples('undefined role', :any)
+    include_examples('undefined instance', 'i-0000001')
+
+    it 'should have empty roles list' do
+      expect(subject.list_roles).to be_empty
+    end
+  end
+
+  context 'when created with single db instance' do
+    let (:instances) { [
+        stub_instance(:instance_id => 'i-0000001', :role => :db)
+    ] }
+
+    it { should_not be_empty }
+    it { should be_running }
+    include_examples 'cluster'
+    include_examples('undefined role', :'any other')
+    include_examples('undefined instance', 'i-0000002')
+    include_examples('defined role with instances', :db, 1)
+    include_examples('running instance in role', :db, 0, 'i-0000001')
+
+    it 'should list the db role only' do
+      expect(subject.list_roles).to eq([:db])
+    end
+  end
+
+  context 'when created with multiple db instances' do
+    let (:instances) { [
+        stub_instance(:instance_id => 'i-0000001', :role => :db),
+        stub_instance(:instance_id => 'i-0000002', :role => :db)
+    ] }
+
+    it { should_not be_empty }
+    it { should be_running }
+    include_examples 'cluster'
+    include_examples('undefined role', :'any other')
+    include_examples('undefined instance', 'i-0000003')
+    include_examples('defined role with instances', :db, 2)
+    include_examples('running instance in role', :db, 0, 'i-0000001')
+    include_examples('running instance in role', :db, 1, 'i-0000002')
+
+    it 'should list the db role only' do
+      expect(subject.list_roles).to eq([:db])
+    end
+  end
+
+  context 'when created with multiple db and app instances' do
+    let (:instances) { [
+        stub_instance(:instance_id => 'i-0000001', :role => :db),
+        stub_instance(:instance_id => 'i-0000002', :role => :app),
+        stub_instance(:instance_id => 'i-0000003', :role => :app)
+    ] }
+
+    it { should_not be_empty }
+    it { should be_running }
+    include_examples 'cluster'
+    include_examples('undefined role', :'any other')
+    include_examples('undefined instance', 'i-0000004')
+    include_examples('defined role with instances', :db, 1)
+    include_examples('defined role with instances', :app, 2)
+    include_examples('running instance in role', :db, 0, 'i-0000001')
+    include_examples('running instance in role', :app, 0, 'i-0000002')
+    include_examples('running instance in role', :app, 1, 'i-0000003')
+
+    it 'should list the db and app roles only' do
+      expect(subject.list_roles).to eq([:db, :app])
+    end
+  end
+
+  def stub_instance(data)
+    Cloudfinder::EC2::Instance.new(data)
+  end
+
+end