aws-cft-tools 0.1.0

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  module Runbooks
+    class Retract
+      ##
+      # module with methods to manage ordering of templates
+      #
+      module Templates
+        require_relative '../common/templates'
+
+        include Common::Templates
+
+        ##
+        # list the templates in-scope for this retraction
+        #
+        # @return [AwsCftTools::TemplateSet]
+        #
+        def templates
+          @templates ||= filtered_templates(client.templates)
+        end
+
+        ##
+        # List the templates that are available for deletion.
+        #
+        # Templates with known dependents that are not in the set will be removed. Note that this does
+        # not capture dependencies between environments.
+        #
+        # @return [AwsCftTools::TemplateSet]
+        def free_templates
+          set = AwsCftTools::TemplateSet.new(templates.in_folder_order(template_folder_order))
+          client.templates.closed_subset(set).reverse
+        end
+
+        ##
+        # @return [Array<String>]
+        #
+        def template_folder_order
+          options[:template_folder_priorities] || []
+        end
+      end
+    end
+  end
+end

data/lib/aws_cft_tools/runbooks/stacks.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  module Runbooks
+    ##
+    # Images - report on available AMIs
+    #
+    # @example
+    #   % aws-cli stacks              # list all known stacks
+    #   % aws-cli stacks -e QA        # list all known stacks tagged for the QA environment
+    #   % aws-cli stacks -e QA -r App # list all known stacks tagged for the QA environment and App role
+    #
+    class Stacks < Runbook::Report
+      ###
+      # @return [Array<AwsCftTools::Stack>]
+      #
+      def items
+        client.stacks.sort_by(&method(:sort_key))
+      end
+
+      ###
+      # @return [Array<String>]
+      #
+      def columns
+        environment_column + role_column + %w[filename created_at name state]
+      end
+
+      private
+
+      def sort_key(stack)
+        stack.name
+      end
+
+      def environment_column
+        options[:environment] ? [] : ['environment']
+      end
+
+      def role_column
+        options[:role] ? [] : ['role']
+      end
+    end
+  end
+end

data/lib/aws_cft_tools/stack.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  ##
+  # Provides a unified interface for accessing information about deployed CloudFormation templates.
+  #
+  class Stack
+    extend Forwardable
+
+    def initialize(aws_stack, aws_client)
+      @aws_client = aws_client
+      @aws_stack = aws_stack
+    end
+
+    def_delegators :@aws_stack, :description
+    def_delegator :@aws_stack, :stack_name, :name
+    def_delegator :@aws_stack, :creation_time, :created_at
+    def_delegator :@aws_stack, :last_updated_time, :updated_at
+    def_delegator :@aws_stack, :stack_status, :state
+    def_delegator :@aws_stack, :stack_id, :id
+
+    ###
+    # @return [String] the unparsed body of the template definition
+    #
+    def template_source
+      @template ||= begin
+        resp = @aws_client.get_template(stack_name: name,
+                                        template_stage: 'Original')
+        resp.template_body
+      end
+    end
+
+    ##
+    # @return [Hash] dictionary of tag names and values for the stack
+    #
+    def tags
+      @tags ||= @aws_stack.tags.each_with_object({}) { |tag, hash| hash[tag.key] = tag.value }
+    end
+
+    ##
+    # @return [Hash] mapping of output name with output definition
+    def outputs
+      @outputs ||= build_hashes(@aws_stack.outputs || [], &:output_key)
+    end
+
+    ##
+    # @return [Hash] mapping of parameter name to parameter definition
+    #
+    def parameters
+      @parameters ||= build_hashes(@aws_stack.parameters || [], &:parameter_key)
+    end
+
+    ##
+    # @return [String] the environment of the stack
+    #
+    def environment
+      tags['Environment']
+    end
+
+    ##
+    # @return [String] the role of the stack
+    #
+    def role
+      tags['Role']
+    end
+
+    ##
+    # @return [String] the filename of the stack's template source
+    #
+    def filename
+      @filename ||= begin
+        source = tags['Source']
+        source ? source.sub(%r{^/+}, '') : nil
+      end
+    end
+
+    private
+
+    def build_hashes(source, &block)
+      source.map(&block).zip(source).to_h
+    end
+  end
+end

data/lib/aws_cft_tools/template.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'erb'
+require 'pathname'
+
+module AwsCftTools
+  ##
+  # The AwsCftTools::Template class wraps a CloudFormation template source to provide support for various
+  # operations by the toolset.
+  #
+  # == CloudFormation Templates
+  #
+  # As much as possible, this tool uses CloudFormation templates as-is and makes as many inferences as
+  # reasonable. However, some things aren't captured in stock template information.
+  #
+  # @note Stacks should be removed ("retracted") from AWS before they are removed from the set of templates.
+  #   Otherwise, they won't be considered in the set of available templates or stacks.
+  #
+  # @todo Fetch templates from deployed stacks and consider them in the dependency tree for removing or
+  #   deploying templates in the repo. Flag stacks with no local source to not be updated on deployment.
+  #
+  # @todo Add ability to init to fetch templates from stacks and put them in files.
+  #
+  # === Allowed Environments
+  #
+  # The environments in which a template should be deployed is provided by the +AllowedValues+ key of the
+  # +Environment+ template parameter.
+  #
+  # @example Allowed Environments
+  #   ---
+  #   Parameters:
+  #     Environment:
+  #       AllowedValues:
+  #         - QA
+  #         - Staging
+  #         - Production
+  #
+  # === Allowed Regions
+  #
+  # A template can be pinned to a particular region or set of regions by providing a list of values for
+  # the +Region+ key in the template metadata. If no such key is present, then the template can be
+  # deployed or otherwise used in all regions.
+  #
+  # @example Allowed Regions
+  #   ---
+  #   Metadata:
+  #     Region:
+  #       - us-east-1
+  #       - us-west-1
+  #
+  # === Explicit Template Dependencies
+  #
+  # As much as possible, dependencies between templates are inferred based on exported and imported
+  # values. However, some templates might depend on another template in a way that isn't captured by
+  # these values. For those dependencies, the templates that should be run first can be listed under the
+  # +DependesOn.Templates+ metadata key.
+  #
+  # @example Explicit Template Dependency
+  #   ---
+  #   Metadata:
+  #     DependsOn:
+  #       Templates:
+  #         - network/peering.yaml
+  #
+  # === Template Parameters
+  #
+  # Rather than require mappings in templates to hold environment-specific values, a template has a
+  # corresponding parameters file that holds the value for the stack parameter for each environment.
+  # This parameters file is in YAML format and passed through ERB before parsing, so it can incorporate
+  # environment variables and other logic into specifying parameter values.
+  #
+  class Template
+    attr_reader :filename
+
+    require_relative 'template/dsl_context'
+    require_relative 'template/file_system'
+    require_relative 'template/metadata'
+    require_relative 'template/properties'
+
+    include FileSystem
+    include Metadata
+    include Properties
+
+    ##
+    # @param filename [String] path to template relative to the +template_dir+ path
+    # @param options [Hash] runbook options
+    # @option options [String] :environment environment in which parameters should be fetched
+    # @option options [String] :parameter_dir directory relative to the +root+ path in which parameter files
+    #   are found
+    # @option options [Pathname] :root path to the root of the project
+    # @option options [String] :template_dir directory relative to the +root+ path in which template sources
+    #   are found
+    #
+    def initialize(filename, options = {})
+      @options = options
+      @filename = filename
+    end
+
+    ##
+    # @return [Array<Hash>] template tags suitable for use in deploying a stack
+    #
+    def tags
+      [
+        { key: 'Environment', value: @options[:environment] },
+        { key: 'Source', value: ('/' + filename.to_s).gsub(%r{/+}, '/') }
+      ] + role_tag
+    end
+
+    ##
+    # @return [Hash] parameters to provide to the AWS client to deploy the template
+    #
+    def stack_parameters
+      {
+        stack_name: name,
+        template_body: template_source_for_aws,
+        parameters: hash_to_param_list(parameters || {}),
+        tags: tags
+      }
+    end
+
+    private
+
+    def role_tag
+      if role
+        [{ key: 'Role', value: role }]
+      else
+        []
+      end
+    end
+
+    def hash_to_param_list(hash)
+      hash.map do |key, value|
+        {
+          parameter_key: key.to_s,
+          parameter_value: value_to_string(value),
+          use_previous_value: !value && value != false || value == ''
+        }
+      end
+    end
+
+    def value_to_string(value)
+      case value
+      when false
+        'false'
+      when true
+        'true'
+      else
+        value ? value.to_s : value
+      end
+    end
+
+    ##
+    # Looks through the template to find instances of +Fn::ImportValue+
+    #
+    def pull_imports(hash)
+      hash.flat_map do |key, value|
+        value ||= key
+        if %w[Fn::ImportValue ImportValue].include?(key)
+          pull_import(value)
+        elsif value.is_a?(Hash) || value.is_a?(Array)
+          pull_imports(value)
+        else
+          []
+        end
+      end
+    end
+
+    def pull_import(value)
+      if value.is_a?(Hash)
+        [value['Fn::Sub'] || value['Sub'] || value]
+      else
+        [value]
+      end
+    end
+  end
+end

data/lib/aws_cft_tools/template/dsl_context.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  class Template
+    ##
+    # Utility module for evaluating ruby dsl templates.
+    #
+    module DSLContext
+      require 'cloudformation-ruby-dsl/cfntemplate'
+      require 'cloudformation-ruby-dsl/spotprice'
+      require 'cloudformation-ruby-dsl/table'
+    end
+  end
+end

data/lib/aws_cft_tools/template/file_system.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module AwsCftTools
+  class Template
+    ##
+    # Manage template and parameter files.
+    #
+    module FileSystem
+      ##
+      # Returns the path to the cloud formation template.
+      #
+      # @return [Pathname]
+      def template_file
+        filename_path(:template_dir, filename)
+      end
+
+      ##
+      # Returns the path to the template parameters file.
+      #
+      # @return [Pathname]
+      def parameter_file
+        filename_path(:parameter_dir, filename)
+      end
+
+      ##
+      # The unparsed source of the template.
+      #
+      # @return [String]
+      def template_source
+        @template_source ||= @options[:template_content] || read_file(template_file)
+      end
+
+      ##
+      # The unparsed source of the parameters file for this template.
+      #
+      # @return [String]
+      def parameters_source
+        @parameters_source ||= @options[:parameters_content] || read_file(parameter_file)
+      end
+
+      private
+
+      def read_file(file)
+        file ? file.read : nil
+      end
+
+      ##
+      # Given the filename relative to the template/parameter root and a symbol indicating which type of
+      # file to point to, returns the full path to the file
+      #
+      # @return [Pathname]
+      def filename_path(dir, filename)
+        # we need to check .yaml, .yml, and .json versions
+        filename = filename.to_s.sub(/\.[^.]*$/, '')
+        base = @options[:root] + @options[dir]
+        %w[.yaml .yml .json .rb].map { |ext| base + (filename + ext) }.detect(&:exist?)
+      end
+    end
+  end
+end

data/lib/aws_cft_tools/template/metadata.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module AwsCftTools
+  class Template
+    ##
+    # Simple derived information about templates.
+    #
+    module Metadata
+      ##
+      # Mapping of filename extensions to content types.
+      #
+      CONTENT_TYPES = {
+        '.json' => 'json',
+        '.rb' => 'dsl',
+        '.yml' => 'yaml',
+        '.yaml' => 'yaml'
+      }.freeze
+
+      ##
+      # The type of template content.
+      #
+      # @return [String] One of +dsl+, +json+, or +yaml+.
+      def template_type
+        content_type(template_file)
+      end
+
+      ##
+      # Queries if the template source looks like a CloudFormation template.
+      #
+      # @return [Boolean]
+      def template?
+        template && template['AWSTemplateFormatVersion']
+      end
+
+      ##
+      # The name of the stack built by this template.
+      #
+      # @return [String]
+      def name
+        @name ||= @options[:environment] + '-' +
+                  filename.to_s.sub(/\.(ya?ml|json|rb)$/, '').split(%r{/}).reverse.join('-')
+      end
+
+      ##
+      # The parsed template as a Ruby data structure.
+      #
+      # @return [Hash]
+      def template
+        @template ||= template_content_for_filename(template_file)
+      end
+
+      ##
+      # The JSON or YAML source that can be submitted to AWS to build the stack.
+      #
+      # @return [String]
+      def template_source_for_aws
+        template_type == 'dsl' ? JSON.pretty_generate(template) : template_source
+      end
+
+      ##
+      # The parsed parameters for this template in the deployment environment.
+      #
+      # @return [Hash]
+      def parameters
+        @parameters ||= parameters_for_filename_and_environment(parameters_source, @options[:environment])
+      end
+
+      private
+
+      def content_type(file)
+        CONTENT_TYPES[file.extname] if file
+      end
+
+      ##
+      # Loads the contents of the full path and returns the content as a Ruby data structure
+      #
+      # @return [String]
+      def template_content_for_filename(file)
+        type = content_type(file)
+        return {} unless type
+        send(:"template_content_for_#{type}!")
+      rescue => exception
+        raise AwsCftTools::ParseException, "Error while parsing #{template_file}: #{exception}"
+      end
+
+      def template_content_for_yaml!
+        YAML.safe_load(template_source, [Date], [], true) || {}
+      end
+
+      def template_content_for_json!
+        JSON.parse(template_source) || {}
+      end
+
+      def template_content_for_dsl!
+        with_environment { JSON.parse(DSLContext.module_eval(template_source).to_json) }
+      end
+
+      ##
+      # Loads the contents of the full path and passes it through ERB before parsing as YAML. Returns
+      # a Ruby structure.
+      #
+      # If no file exists, then a simple hash with the +Environment+ key set.
+      #
+      def parameters_for_filename_and_environment(param_source, env)
+        parameters_for_filename_and_environment!(param_source, env)
+      rescue AwsCftTools::ToolingException
+        raise
+      rescue => exception
+        raise AwsCftTools::ParseException, "Error while reading and parsing #{parameter_file}: #{exception}"
+      end
+
+      def parameters_for_filename_and_environment!(param_source, env)
+        return { Environment: env } unless param_source
+
+        params = YAML.safe_load(process_erb_file(param_source), [], [], true)[env] || {}
+        params.update(Environment: env)
+      end
+
+      def process_erb_file(content)
+        with_environment { ERB.new(content).result }
+      end
+
+      def with_environment
+        return unless block_given?
+        prior = ENV.to_h
+        ENV.update(aws_env)
+        yield
+      ensure
+        ENV.update(prior)
+      end
+
+      def aws_env
+        region = @options[:region]
+        {
+          'AWS_REGION' => region,
+          'EC2_REGION' => region,
+          'AWS_PROFILE' => @options[:profile]
+        }
+      end
+    end
+  end
+end