aws-cft-tools 0.1.0

data/lib/aws_cft_tools/runbook/report.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'table_print'
+
+module AwsCftTools
+  class Runbook
+    ##
+    # A subclass of the Runbook designed for reporting out status or other information about resources.
+    #
+    class Report < Runbook
+      def run
+        tp(items, columns)
+      end
+
+      ###
+      # @return [Array<Object>]
+      #
+      def items
+        []
+      end
+
+      ###
+      # @return [Array<String>]
+      #
+      def columns
+        []
+      end
+    end
+  end
+end

data/lib/aws_cft_tools/runbooks.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  ##
+  # Namespace for runbooks
+  #
+  module Runbooks
+    require_relative 'runbooks/deploy'
+    require_relative 'runbooks/diff'
+    require_relative 'runbooks/hosts'
+    require_relative 'runbooks/images'
+    require_relative 'runbooks/init'
+    require_relative 'runbooks/retract'
+    require_relative 'runbooks/stacks'
+  end
+end

data/lib/aws_cft_tools/runbooks/common/changesets.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  module Runbooks
+    module Common
+      ##
+      # Changesets - operations on changesets in the deploy runbook
+      #
+      module Changesets
+        private
+
+        # @todo store this somewhere so we can have an "active" changeset to be reviewed and committed.
+        #
+        def changeset_set
+          @changeset_set ||= SecureRandom.hex(16)
+        end
+
+        ##
+        # provide a tabular report of changeset actions
+        #
+        def narrate_changes(changes)
+          tp(
+            changes.map(&:to_narrative),
+            %i[action logical_id physical_id type replacement scopes]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/aws_cft_tools/runbooks/common/templates.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  module Runbooks
+    module Common
+      ##
+      # Templates - operations on templates in multiple runbooks
+      #
+      module Templates
+        private
+
+        def filtered_templates(set)
+          filtered_by_environment(
+            filtered_by_role(
+              filtered_by_selection(options[:templates], set)
+            )
+          )
+        end
+
+        def filtered_by_role(set)
+          set.select { |template| template.role?(options[:role]) }
+        end
+
+        def filtered_by_environment(set)
+          set.select { |template| template.environment?(options[:environment]) }
+        end
+
+        def filtered_by_selection(templates, set)
+          if templates && templates.any?
+            set.select { |template| templates.include?(template.filename.to_s) }
+          else
+            set
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws_cft_tools/runbooks/deploy.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module AwsCftTools
+  module Runbooks
+    ##
+    # Deploy - manage CloudFormation stack deployment
+    #
+    # @example
+    #   % aws-cft deploy -e QA               # deploy all templates to the QA environment
+    #   % aws-cft deploy -e Staging -n -v    # narrate the templates that would be used for Staging
+    #   % aws-cft deploy -e Production -c -v # narrate the changes that would go into Production
+    #
+    class Deploy < Runbook
+      require_relative 'common/changesets'
+      require_relative 'common/templates'
+      require_relative 'deploy/reporting'
+      require_relative 'deploy/stacks'
+      require_relative 'deploy/templates'
+      require_relative 'deploy/threading'
+
+      extend Forwardable
+
+      include Common::Changesets
+      include Common::Templates
+      include Reporting
+      include Stacks
+      include Templates
+      include Threading
+
+      def_delegators :client, :images
+      def_delegator  :client, :all_stacks, :stacks
+
+      def run
+        run_reports
+
+        detail 'Updating template parameters...'
+        update_parameters
+
+        process_templates(options[:jobs] || 1)
+      end
+
+      private
+
+      def process_templates(slice_size)
+        templates_in_folder_order.each_slice(slice_size, &method(:process_slice))
+      end
+
+      def process_slice(templates)
+        old_stdout = $stdout
+        threads = create_threads(templates) { |template| process_template(template) }
+        threads.map(&:thread).map(&:join)
+        puts threads.map(&:output).map(&:string)
+      ensure
+        $stdout = old_stdout # just in case!
+      end
+
+      def process_template(template)
+        is_update = deployed_templates.include?(template)
+        operation("#{is_update ? 'Updating' : 'Creating'}: #{template.name}") do
+          exec_template(template: template, type: is_update ? :update : :create)
+        end
+      end
+
+      def exec_template(params) # template:, type:
+        checking { exec_template_check(**params) }
+        doing { exec_template_for_real(**params) }
+      end
+
+      def exec_template_check(template:, type:)
+        narrate_changes(client.send(:"changes_on_stack_#{type}", template, changeset_set))
+      rescue Aws::CloudFormation::Errors::ValidationError => error
+        puts "Error checking #{template.filename}: #{error.message}"
+      end
+
+      def exec_template_for_real(template:, type:)
+        client.send(:"#{type}_stack", template)
+      rescue Aws::CloudFormation::Errors::ValidationError => error
+        raise AwsCftTools::CloudFormationError, "Error processing #{template.filename}: #{error}"
+      end
+
+      ##
+      # update_parameters - notate templates with region and image id as appropriate
+      #
+      def update_parameters
+        templates.each { |template| update_template_with_image_id(template) }
+      end
+
+      ##
+      # the set of templates corresponding to deployed CloudFormation stacks
+      #
+      def deployed_templates
+        @deployed_templates ||= templates_in_folder_order.select do |template|
+          deployed_stack_names.include?(template.name)
+        end
+      end
+
+      ##
+      # the set of templates with no corresponding deployed CloudFormation stack
+      #
+      def new_templates
+        @new_templates ||= templates_in_folder_order - deployed_templates
+      end
+    end
+  end
+end

data/lib/aws_cft_tools/runbooks/deploy/reporting.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'table_print'
+
+module AwsCftTools
+  module Runbooks
+    class Deploy
+      ##
+      # module with various reporting functions for deployment
+      #
+      module Reporting
+        private
+
+        def run_reports
+          report_available_images
+          report_undefined_variables
+
+          detail do
+            tp(templates, ['filename'])
+          end
+        end
+
+        ##
+        # report_available_images - provide tabular report of available images
+        #
+        def report_available_images
+          detail('Available Images') { tp(report_available_images_data) }
+        end
+
+        def report_available_images_data
+          available_images.map { |role_env, ami| role_env.split(/:/).reverse + [ami] }
+                          .compact
+                          .sort
+                          .map { |role_env_ami| %w[role environment ami].zip(role_env_ami).to_h }
+        end
+
+        ##
+        # report_undefined_image - provide list of undefined imports that block stack deployment
+        #
+        def report_undefined_variables
+          vars = templates_in_folder_order.undefined_variables
+          return unless vars.any?
+          puts '*** Unable to update or create templates.'
+          puts 'The following variables are referenced but not defined: ', vars
+          exit 1 # TODO: convert to a raise
+        end
+      end
+    end
+  end
+end

data/lib/aws_cft_tools/runbooks/deploy/stacks.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  module Runbooks
+    class Deploy
+      ##
+      # Stacks - operations on stacks in the deploy runbook
+      #
+      module Stacks
+        private
+
+        ##
+        # Provides the next environment to look at if the current one fails.
+        #
+        # This is mainly used to find an AMI that is appropriate for the environment. Since we want
+        # to be able to promote AMIs from one environment to the next without rebuilding them, we
+        # should use the AMI that is most appropriate even if it's not tagged with the environment
+        # in scope.
+        #
+        # This can be configured in the configuration file with the +:environment_successors+ key.
+        #
+        def successor_environment(env)
+          (options[:environment_successors] || {})[env]
+        end
+
+        ##
+        # list the available images by role and environment
+        #
+        # An image for a role/environment is the most recent AMI tagged with that role and environment.
+        #
+        def available_images
+          @available_images ||= images.sort_by(&:created_at).each_with_object({}) do |image, mapping|
+            key = image_key(image)
+            mapping[key] = image.image_id if key != ':'
+          end
+        end
+
+        def image_key(image)
+          (image.environment || '') + ':' + (image.role || '')
+        end
+
+        ##
+        # retrieve the appropriate AMI identifier for an environment/role
+        #
+        # This takes into account environment succession (see #successor_environment) to find the
+        # best image for an environment/role as determined by #available_images.
+        #
+        def find_image(role, env)
+          key = "#{env}:#{role}"
+          image = available_images[key]
+          return image if image
+          next_env = successor_environment(env)
+          find_image(role, next_env) if next_env
+        end
+
+        ##
+        # list the template files containing `Region` metadata
+        #
+        def files_with_region_param
+          @files_with_region_param ||=
+            templates.select { |template| template.allowed_regions.any? }.map(&:filename)
+        end
+
+        ##
+        # list the template source filenames for deployed stacks
+        #
+        # This returns the filename as reported by the `Source` tag on the CloudFormation stack.
+        #
+        def deployed_stack_names
+          stacks.map(&:name).compact
+        end
+
+        ##
+        # list the filenames of all of the in-scope templates
+        #
+        def files
+          templates.map(&:filename)
+        end
+
+        ##
+        # add `ImageId` parameter to templates as-needed
+        #
+        def update_template_with_image_id(template)
+          params = template.parameters
+          params.each do |key, value|
+            update_params_with_image_id(params, key, value)
+          end
+        end
+
+        def update_params_with_image_id(params, key, value)
+          return unless value.is_a?(Hash)
+          role = value['Role']
+          image = find_image(role, options[:environment])
+          params[key] = image if role
+          report_undefined_image(role) if role && !image
+        end
+
+        ##
+        # utility function to create an error message about undefined AMIs
+        #
+        def report_undefined_image(role)
+          puts format('Unable to find image for %s suitable for %s',
+                      role,
+                      options[:environment])
+        end
+      end
+    end
+  end
+end

data/lib/aws_cft_tools/runbooks/deploy/templates.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  module Runbooks
+    class Deploy
+      ##
+      # module with methods to manage ordering of templates
+      #
+      module Templates
+        ##
+        # list the templates in-scope for this deployment
+        #
+        def templates
+          @templates ||= begin
+            candidates = client.templates
+
+            candidates.closure(
+              filtered_templates(
+                candidates
+              )
+            )
+          end
+        end
+
+        def template_folder_order
+          options[:template_folder_priorities] || []
+        end
+
+        private
+
+        def templates_in_folder_order
+          templates.in_folder_order(template_folder_order)
+        end
+      end
+    end
+  end
+end

data/lib/aws_cft_tools/runbooks/deploy/threading.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  module Runbooks
+    class Deploy
+      ##
+      # module with methods to manage threading
+      #
+      module Threading
+        private
+
+        # FIXME: things don't always work out well when capturing output
+        #        for now, we don't, and output gets mangled a bit when running with
+        #        multiple jobs in parallel
+        def with_captured_stdout(capture)
+          old_stdout = $stdout
+          old_table_io = TablePrint::Config.io
+          TablePrint::Config.io = $stdout = capture
+          yield
+        ensure
+          $stdout = old_stdout
+          TablePrint::Config.io = old_table_io
+        end
+
+        def create_threads(list, &_block)
+          list.map { |item| threaded_process { yield item } }
+        end
+
+        def threaded_process(&block)
+          output = StringIO.new
+          thread = Thread.new { with_captured_stdout(output, &block) }
+          OpenStruct.new(output: output, thread: thread)
+        end
+      end
+    end
+  end
+end