aws-cft-tools 0.1.0

data/lib/aws_cft_tools/client/base.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  class Client
+    ##
+    # = CloudFormation Client
+    #
+    # All of the business logic behind direct interaction with the AWS API for CloudFormation templates
+    # and stacks.
+    #
+    class Base
+      attr_reader :options
+
+      ##
+      #
+      # @param options [Hash] client configuration
+      # @option options [String] :environment the operational environment in which to act
+      # @option options [String] :profile the AWS credential profile to use
+      # @option options [String] :region the AWS region in which to act
+      #
+      def initialize(options = {})
+        @options = options
+      end
+
+      ##
+      # The AWS SDK client object for this part of the AwsCftTools client
+      def aws_client
+        @aws_client ||= begin
+          klass = self.class.aws_client_class
+          klass && klass.new(
+            region: options[:region],
+            profile: options[:profile]
+          )
+        end
+      end
+
+      def self.aws_client_class; end
+    end
+  end
+end

data/lib/aws_cft_tools/client/cft.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  class Client
+    ##
+    # = CloudFormation Client
+    #
+    # All of the business logic behind direct interaction with the AWS API for CloudFormation templates
+    # and stacks.
+    #
+    class CFT < Base
+      require_relative 'cft/changeset_management'
+      require_relative 'cft/stack_management'
+
+      include ChangesetManagement
+      include StackManagement
+
+      ##
+      #
+      # @param options [Hash] client configuration
+      # @option options [String] :environment the operational environment in which to act
+      # @option options [String] :profile the AWS credential profile to use
+      # @option options [String] :region the AWS region in which to act
+      #
+      def initialize(options)
+        super(options)
+      end
+
+      def self.aws_client_class
+        Aws::CloudFormation::Client
+      end
+
+      ##
+      # Lists all exports from stacks in CloudFormation.
+      #
+      # @return [Array<Aws::CloudFormation::Types::Export>]
+      #
+      def exports
+        @exports ||= AWSEnumerator.new(aws_client, :list_exports, {}, &:exports).to_a
+      end
+
+      ##
+      # Lists all of the stacks in CloudFormation that are specific to the selected environment.
+      #
+      # @return [Array<OpenStruct>]
+      #
+      def stacks
+        @stacks ||= all_stacks.select do |stack|
+          tags = stack.tags
+          satisfies_environment(tags) &&
+            satisfies_role(tags) &&
+            satisfies_tags(tags)
+        end
+      end
+
+      ##
+      # List all of the stacks in CloudFormation.
+      #
+      # @return [Array<OpenStruct>]
+      #
+      def all_stacks
+        @all_stacks ||= AWSEnumerator.new(aws_client, :describe_stacks, &method(:map_stacks)).to_a
+      end
+
+      private
+
+      def map_stacks(resp)
+        resp.stacks.map { |stack| Stack.new(stack, aws_client) }
+      end
+
+      def satisfies_environment(tag_set)
+        env = options[:environment]
+        !env || tag_set['Environment'] == env
+      end
+
+      def satisfies_role(tag_set)
+        role = options[:role]
+        !role || tag_set['Role'] == role
+      end
+
+      def satisfies_tags(tag_set)
+        tags = options[:tags]
+        return true unless tags
+        tag_set.all? { |key, value| satisfies_tag(tags, key, value) }
+      end
+
+      def satisfies_tag(tags, key, value)
+        tag = tags[key]
+        !tag || tag == value
+      end
+    end
+  end
+end

data/lib/aws_cft_tools/client/cft/changeset_management.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  class Client
+    class CFT
+      ##
+      # Provides changeset management functions for the CFT client.
+      #
+      module ChangesetManagement
+        ##
+        # Accepts a template for a stack and tries to create an update changeset for that stack. The stack
+        # must already exist in CloudFormation.
+        #
+        # @param template [AwsCftTools::Template]
+        # @param changeset_set [String] an identifier linking various changesets as part of the same run
+        # @return [Array<AwsCftTools::Change>]
+        #
+        def changes_on_stack_update(template, changeset_set)
+          do_changeset(update_changeset_params(template, changeset_set))
+        end
+
+        ##
+        # Accepts a template for a stack and tries to create a creation changeset for the stack. The stack
+        # must not exist yet in CloudFormation.
+        #
+        # @param template [AwsCftTools::Template]
+        # @param changeset_set [String] an identifier linking various changesets as part of the same run
+        # @return [Array<AwsCftTools::Change>]
+        #
+        def changes_on_stack_create(template, changeset_set)
+          do_changeset(create_changeset_params(template, changeset_set))
+        end
+
+        ##
+        # Accepts a template and creates a mock changeset listing the resources that would be removed if
+        # the stack were deleted. The stack must exist in CloudFormation.
+        #
+        # @param template [AwsCftTools::Template]
+        # @param _changeset_set [Object] ignored to maintain compatibility with the other changeset methods
+        # @return [Array<AwsCftTools::DeletionChange>]
+        #
+        def changes_on_stack_delete(template, _changeset_set)
+          mock_delete_changeset(template)
+        end
+
+        private
+
+        ##
+        # perform the changeset creation/deletion and return the changes that would happen if the
+        # changes moved forward
+        #
+        def do_changeset(params)
+          id = id_params(params)
+
+          aws_client.create_change_set(params)
+
+          aws_client.wait_until(:change_set_create_complete, id)
+
+          mapped_changes(AWSEnumerator.new(aws_client, :describe_change_set, id, &:changes).to_a)
+        rescue Aws::Waiters::Errors::FailureStateError
+          []
+        ensure
+          aws_client.delete_change_set(id)
+        end
+
+        def id_params(params)
+          {
+            change_set_name: params[:change_set_name],
+            stack_name: params[:stack_name]
+          }
+        end
+
+        def update_changeset_params(template, changeset_set)
+          common_changeset_params(template, changeset_set).merge(change_set_type: 'UPDATE')
+        end
+
+        def create_changeset_params(template, changeset_set)
+          common_changeset_params(template, changeset_set).merge(change_set_type: 'CREATE')
+        end
+
+        def mock_delete_changeset(template)
+          # act like we're doing a changeset, but just narrate all of the resources being removed
+          id_params = { stack_name: template.name }
+          mapped_deleted_resources(
+            AWSEnumerator.new(aws_client, :list_stack_resources, id_params, &:stack_resource_summaries).to_a
+          )
+        rescue Aws::CloudFormation::Errors::ValidationError
+          []
+        end
+
+        def common_changeset_params(template, changeset_set)
+          params = template.stack_parameters
+          params.merge(
+            capabilities: %w[CAPABILITY_IAM CAPABILITY_NAMED_IAM],
+            change_set_name: "#{params[:stack_name]}-#{changeset_set}"
+          )
+        end
+
+        def mapped_deleted_resources(resources)
+          resources.map { |resource| AwsCftTools::DeletionChange.new(resource) }
+        end
+
+        def mapped_changes(changes)
+          changes.flat_map { |change| AwsCftTools::Change.new(change) }
+        end
+      end
+    end
+  end
+end

data/lib/aws_cft_tools/client/cft/stack_management.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  class Client
+    class CFT
+      ##
+      # Provide stack management functions for the CFT client.
+      #
+      module StackManagement
+        ##
+        # Accepts information about a stack and tries to update that stack. The stack must already
+        # exist in CloudFormation.
+        #
+        # Metadata keys:
+        # - filename (required)
+        # - name
+        # - parameters
+        # - template_file
+        #
+        # If the update would result in no changes, no error is raised. Otherwise, all errors are
+        # raised and halt deployment.
+        #
+        # @param template [AwsCftTools::Template]
+        #
+        def update_stack(template)
+          aws_client.update_stack(update_stack_params(template))
+          # we want to wait for the update to complete before we proceed
+          aws_client.wait_until(:stack_update_complete, stack_name: template.name)
+        rescue Aws::CloudFormation::Errors::ValidationError => exception
+          raise exception unless exception.message.match?(/No updates/)
+        end
+
+        ##
+        # Accepts information about a stack and tries to create the stack. The stack must not exist in
+        # CloudFormation.
+        #
+        # @param template [AwsCftTools::Template]
+        #
+        def create_stack(template)
+          aws_client.create_stack(create_stack_params(template))
+          # we want to wait for the create to complete before we proceed
+          aws_client.wait_until(:stack_create_complete, stack_name: template.name)
+        end
+
+        ##
+        # Accepts information about a stack and tries to remove the stack. The stack must exist in
+        # CloudFormation.
+        #
+        # @param template [AwsCftTools::Template]
+        #
+        def delete_stack(template)
+          aws_client.delete_stack(delete_stack_params(template))
+          aws_client.wait_until(:stack_delete_complete, stack_name: template.name)
+        end
+
+        private
+
+        def update_stack_params(template)
+          common_stack_params(template).merge(
+            use_previous_template: false,
+            # on_failure: "ROLLBACK", # for updating
+          )
+        end
+
+        def create_stack_params(template)
+          common_stack_params(template).merge(
+            on_failure: 'DELETE', # for creation
+          )
+        end
+
+        def delete_stack_params(template)
+          {
+            stack_name: template.name
+          }
+        end
+
+        def common_stack_params(template)
+          template.stack_parameters.merge(
+            capabilities: %w[CAPABILITY_IAM CAPABILITY_NAMED_IAM]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/aws_cft_tools/client/ec2.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  class Client
+    ##
+    # = EC2 Instance Client
+    #
+    # All of the business logic behind direct interaction with the AWS API for EC2 instances and related
+    # resources.
+    #
+    class EC2 < Base
+      ##
+      #
+      # @param options [Hash] client configuration
+      # @option options [String] :environment the operational environment in which to act
+      # @option options [String] :profile the AWS credential profile to use
+      # @option options [String] :region the AWS region in which to act
+      # @option options [String] :role the operational role of the resources under consideration
+      #
+      def initialize(options)
+        super(options)
+      end
+
+      def self.aws_client_class
+        Aws::EC2::Resource
+      end
+
+      ##
+      # Returns a list of running instances filtered by any environment or role specified in the
+      # options passed to the constructor.
+      #
+      # Each instance is represented by a Hash with the following keys:
+      # - private_ip: the private IP address of the instance
+      # - public_ip: the public IP address (if any) of the instance
+      # - instance: the ID of the instance
+      # - role: the value of the `Role` tag if not filtering by role
+      # - environment: the value of the `Environment` tag if not filtering by environment
+      #
+      # @return [Array<OpenStruct>]
+      #
+      def instances
+        @instances ||= aws_client.instances(filters: instance_filters).map do |instance|
+          OpenStruct.new(
+            with_tags(instance, private_ip: instance.private_ip_address,
+                                public_ip: instance.public_ip_address,
+                                instance: instance.instance_id)
+          )
+        end
+      end
+
+      ##
+      # Returns a list of available AMI images filtered by any environment or role specified in the
+      # options passed to the constructor.
+      #
+      # Each image is represented by an OpenStruct with the following keys/methods:
+      # - image_id: the ID of the AMI or image
+      # - type: the type of AMI or image
+      # - public: a flag indicating if the image is public
+      # - created_at: the date/time at which the image was created
+      # - role: the value of the `Role` tag if not filtering by role
+      # - environment: the value of the `Environment` tag if not filtering by environment
+      #
+      # @return [Array<OpenStruct>]
+      #
+      def images
+        @images ||= aws_client.images(owners: ['self'], filters: image_filters).map do |image|
+          OpenStruct.new(
+            with_tags(image, image_id: image.image_id,
+                             type: image.image_type,
+                             public: image.public,
+                             created_at: image.creation_date)
+          )
+        end
+      end
+
+      private
+
+      def instance_filters
+        @instance_filters ||= begin
+          [
+            { name: 'instance-state-name', values: ['running'] }
+          ] + tag_filters
+        end
+      end
+
+      def image_filters
+        @image_filters ||= begin
+          [
+            { name: 'state', values: ['available'] }
+          ] + tag_filters
+        end
+      end
+
+      def tag_filters
+        @tag_filters ||= begin
+          environment_filter +
+            role_filter +
+            arbitrary_tag_filters
+        end
+      end
+
+      def environment_filter
+        tag_filter('Environment', options[:environment])
+      end
+
+      def role_filter
+        tag_filter('Role', options[:role])
+      end
+
+      def arbitrary_tag_filters
+        tags = options[:tags] || []
+        tags.inject([]) do |filter_set, tag_value|
+          tag, value = tag_value
+          filter_set << { name: "tag:#{tag}", values: [value] }
+        end
+      end
+
+      def tag_filter(tag, value)
+        if value
+          [{ name: "tag:#{tag}", values: [value] }]
+        else
+          []
+        end
+      end
+
+      def with_tags(resource, info = {})
+        tags = resource.tags.each_with_object({}) { |tag, collection| collection[tag.key] = tag.value }
+        info.merge(
+          role: tags.delete('Role'),
+          environment: tags.delete('Environment'),
+          tags: tags
+        )
+      end
+    end
+  end
+end