aws-cft-tools 0.1.0

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'aws_cft_tools'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/code.json

@@ -0,0 +1,24 @@
+{
+  "version": "2.0.0",
+  "measurementType": { "method": "linesOfCode" },
+  "agency": "SBA",
+  "releases": [
+    {
+      "name": "aws-cft-tools",
+      "repositoryURL": "https://github.com/USSBA/aws-cft-tools",
+      "description": "Command line tools to ease management of AWS infrastructure through CloudFormation",
+      "permissions": {
+        "license": {
+          "name": "Apache v2",
+          "URL": "https://www.apache.org/licenses/LICENSE-2.0"
+        },
+        "usageType": "openSource",
+        "exemptionText": null
+      },
+      "vcs": "git",
+      "laborHours": 1,
+      "tags": ["SBA", "DevOps", "AWS"],
+      "contact": { "email": "Andrew.Davy@sba.gov" }
+    }
+  ]
+}

data/exe/aws-cft

@@ -0,0 +1,176 @@
+#! /usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'aws_cft_tools'
+require 'clamp'
+require 'yaml'
+
+Clamp do
+  option ['-c', '--[no-]check'], :flag, 'only do non-destructive operations to check validity of request'
+  option ['-f', '--file'], 'FILE', 'set configuration file relative to the project root',
+         default: '.aws_cft', attribute_name: :config_file
+  option ['-n', '--[no-]noop'], :flag, 'only do operations that do not require modifying AWS',
+         attribute_name: :noop
+  option ['-p', '--profile'], 'PROFILE', 'set profile', default: 'default'
+  option ['-R', '--region'], 'REGION', 'set AWS region', environment_name: 'AWS_REGION',
+                                                         default: 'us-east-1'
+  option ['-t', '--root'], 'DIRECTORY', 'set infrastructure project root' do |v|
+    Pathname.new(v)
+  end
+  option ['-T', '--tag'], 'NAME:VALUE', 'require a tag have the given value (may be given more than once)',
+         multivalued: true
+  option ['-v', '--[no-]verbose'], :flag, 'verbose narration of actions'
+  option '--version', :flag, 'Show version' do
+    puts AwsCftTools::VERSION
+    exit(0)
+  end
+
+  def default_root
+    Pathname.new(ENV['AWS_CFT_HOME'] || '.')
+  end
+
+  subcommand 'deploy', 'Deploy templates to AWS' do
+    option ['-e', '--environment'], 'ENVIRONMENT', 'set environment on which to operate' # , required: true
+    option ['-r', '--role'], 'ROLE', 'set role filter'
+    option ['-j', '--jobs'], 'INTEGER', 'maximum number of parallel stacks to build simultaneously',
+           default: 1 do |j|
+             if j == '-'
+               65_535
+             else
+               j.to_i
+             end
+           end
+    parameter '[TEMPLATES] ...', 'the templates to deploy'
+
+    def execute
+      AwsCftTools::Runbooks::Deploy.new(
+        with_file_options(
+          environment: environment,
+          role: role,
+          jobs: jobs,
+          templates: templates_list
+        )
+      )._run
+    rescue AwsCftTools::ToolingException => exception
+      puts "Unable to deploy: #{exception}"
+    end
+  end
+
+  subcommand 'diff', 'List differences between templates and AWS' do
+    option '--[no-]color', :flag, 'colorize output', default: $stdout.tty?, attribute_name: :color
+    option ['-e', '--environment'], 'ENVIRONMENT', 'set environment on which to operate'
+    option ['-r', '--role'], 'ROLE', 'set role filter'
+    parameter '[TEMPLATES] ...', 'the templates to diff'
+
+    def execute
+      AwsCftTools::Runbooks::Diff.new(
+        with_file_options(
+          colorize: color?,
+          environment: environment,
+          role: role,
+          templates: templates_list
+        )
+      )._run
+    rescue AwsCftTools::ToolingException => exception
+      puts "Unable to diff: #{exception}"
+    end
+  end
+
+  subcommand 'hosts', 'List running instances' do
+    option ['-e', '--environment'], 'ENVIRONMENT', 'set environment on which to operate'
+    option ['-r', '--role'], 'ROLE', 'set role filter'
+
+    def execute
+      AwsCftTools::Runbooks::Hosts.new(
+        with_file_options(
+          environment: environment,
+          role: role
+        )
+      )._run
+    end
+  end
+
+  subcommand 'images', 'List available AMIs' do
+    option ['-e', '--environment'], 'ENVIRONMENT', 'set environment on which to operate'
+    option ['-r', '--role'], 'ROLE', 'set role filter'
+
+    def execute
+      AwsCftTools::Runbooks::Images.new(
+        with_file_options(
+          environment: environment,
+          role: role
+        )
+      )._run
+    end
+  end
+
+  subcommand 'init', 'Initialize a new infrastructure project' do
+    def execute
+      AwsCftTools::Runbooks::Init.new(with_file_options)._run
+    end
+  end
+
+  subcommand 'retract', 'Retract templates from AWS' do
+    option ['-e', '--environment'], 'STRING', 'set environment on which to operate', required: true
+    option ['-r', '--role'], 'STRING', 'set role filter'
+    parameter '[TEMPLATES] ...', 'the templates to retract'
+
+    def execute
+      AwsCftTools::Runbooks::Retract.new(
+        with_file_options(
+          environment: environment,
+          role: role,
+          templates: templates_list
+        )
+      )._run
+    rescue AwsCftTools::ToolingException => exception
+      puts "Unable to retract: #{exception}"
+    end
+  end
+
+  subcommand 'stacks', 'List deployed stacks in AWS' do
+    option ['-e', '--environment'], 'ENVIRONMENT', 'set environment on which to operate'
+    option ['-r', '--role'], 'ROLE', 'set role filter'
+
+    def execute
+      AwsCftTools::Runbooks::Stacks.new(
+        with_file_options(
+          environment: environment,
+          role: role
+        )
+      )._run
+    end
+  end
+
+  def with_file_options(opts = {})
+    opts = global_options.merge(opts)
+
+    config_file_with_path = root + config_file
+    return opts unless config_file_with_path.exist?
+    config_options = YAML.safe_load(config_file_with_path.read, [Symbol])
+    config_options.merge(opts.reject { |_, v| v.nil? })
+  end
+
+  private
+
+  def global_options
+    {
+      config_file: config_file,
+      profile: profile,
+      root: root,
+      region: region,
+      noop: noop?,
+      check: check?,
+      verbose: verbose?,
+      tags: tag_hash
+    }
+  end
+
+  def tag_hash
+    tag_list.each_with_object({}) do |tag, acc|
+      k, v = tag.split(':', 2)
+      acc[k] = v
+    end
+  end
+end

data/lib/aws-cft-tools.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'aws_cft_tools'

data/lib/aws_cft_tools.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'aws_cft_tools/version'
+
+##
+# = AWS CloudFormation Tools
+#
+# A collection of classes and methods to manage AWS Infrastructure using CloudFormation as the fundamental
+# unit of infrastructure state. Aws::Cft supports JSON, YAML, and DSL templates with minimal decoration
+# to establish dependencies between templates.
+#
+# == Command Line Interface
+#
+# A CLI is provided through the +aws-cft+ command that will run any of the "runbooks" under the
+# +AwsCftTools::Runbooks::+ namespace.
+#
+# To find a complete list of subcommands, run +aws-cft --help+.
+#
+module AwsCftTools
+  require 'aws_cft_tools/errors'
+  require 'aws_cft_tools/aws_enumerator'
+  require 'aws_cft_tools/change'
+  require 'aws_cft_tools/deletion_change'
+  require 'aws_cft_tools/client'
+  require 'aws_cft_tools/dependency_tree'
+  require 'aws_cft_tools/stack'
+  require 'aws_cft_tools/template'
+  require 'aws_cft_tools/template_set'
+  require 'aws_cft_tools/runbook'
+  require 'aws_cft_tools/runbooks'
+end

data/lib/aws_cft_tools/aws_enumerator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  ##
+  # Provides common "closure" of paged results for the CFT client.
+  #
+  class AWSEnumerator < Enumerator
+    #
+    # @param client [Object] The client object used to retrieve the next set of responses.
+    # @param method [Symbol] The method to call on the client object.
+    # @param args [Hash] Any arguments that are the same across calls to the client object.
+    # @yield [Object] The response from calling the +method+ on the +client+.
+    #
+    # @example Enumerating All Stacks
+    #
+    #   aws_client = Aws::CloudFormation::Client.new
+    #   all_stacks = AWSEnumerator.new(aws_client, :describe_stacks, &:stacks).to_a
+    #
+    def initialize(client, method, args = {}, &block)
+      @client = client
+      @method = method
+      @next_token = nil
+      @args = args
+
+      super() do |yielder|
+        run_loop(yielder, &block)
+      end
+    end
+
+    private
+
+    def run_loop(yielder, &block)
+      resp = poll_client
+      loop do
+        process_response(yielder, resp, &block)
+        break unless @next_token
+        resp = poll_client
+      end
+    end
+
+    def process_response(yielder, resp)
+      feed_results(yielder, yield(resp))
+    end
+
+    def poll_client
+      resp = @client.public_send(@method, @args.merge(next_token: @next_token))
+      @next_token = resp.next_token
+      resp
+    end
+
+    def feed_results(yielder, results)
+      results.each { |item| yielder << item }
+    end
+  end
+end

data/lib/aws_cft_tools/change.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module AwsCftTools
+  # Represents a change in a changeset.
+  class Change
+    extend Forwardable
+
+    attr_reader :resource
+
+    # @param change [Aws::CloudFormation::Types::Change] The AWS SDK change object to be wrapped.
+    def initialize(change)
+      @resource = change.resource_change
+    end
+
+    def_delegators :resource, :action, :replacement
+    def_delegator :resource, :logical_resource_id, :logical_id
+    def_delegator :resource, :physical_resource_id, :physical_id
+
+    ###
+    #
+    # @return [String] human readable type of resource being changed
+    #
+    # @example EC2::Network::ACL
+    #
+    #   "ec2 network acl"
+    #
+    def type
+      humanize_camelized(resource.resource_type)
+    end
+
+    ###
+    #
+    # @return [String] a comma-separated list of scopes
+    #
+    def scopes
+      resource.scope.sort.join(', ')
+    end
+
+    ###
+    #
+    # @return [Hash] information useful for creating a tabular report
+    #
+    def to_narrative
+      {
+        action: action,
+        logical_id: logical_id,
+        physical_id: physical_id,
+        type: type,
+        scopes: scopes,
+        replacement: replacement
+      }
+    end
+
+    protected
+
+    def humanize_camelized(string)
+      string.sub(/^AWS::/, '')
+            .gsub(/:+/, ' ')
+            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1 \2')
+            .gsub(/([a-z\d])([A-Z])/, '\1 \2')
+            .downcase
+    end
+  end
+end

data/lib/aws_cft_tools/client.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'aws-sdk'
+require 'forwardable'
+
+module AwsCftTools
+  ##
+  # = AWS Tools Client
+  #
+  # A collection of higher-level business methods built on top of the AWS API.
+  #
+  class Client
+    require_relative 'client/base'
+    require_relative 'client/ec2'
+    require_relative 'client/cft'
+    require_relative 'client/templates'
+
+    extend Forwardable
+
+    ##
+    # Create a new client instance.
+    #
+    # Options are passed on to domain-specific client objects within the +AwsCftTools::Client::+ namespace.
+    #
+    # @param options [Hash] client configuration
+    # @option options [String] :environment Environment with which the client is concerned.
+    # @option options [String] :parameter_dir The location of parameter files within the project.
+    # @option options [String] :profile The profile to use from the shared credentials file.
+    # @option options [String] :region The AWS region in which to operate.
+    # @option options [String] :role The role that resources are attached to.
+    # @option options [Pathname] :root The location of the top-level directory of the project.
+    # @option options [String] :template_dir The location of tmeplate files within the project.
+    #
+    def initialize(options)
+      @client_options = options.merge(client: self)
+    end
+
+    # @!method instances
+    #   @see AwsCftTools::Client::EC2#instances
+    # @!method images
+    #   @see AwsCftTools::Client::EC2#images
+    def_delegators :ec2_client, :instances, :images
+
+    # @!method exports
+    #   @see AwsCftTools::Client::CFT#exports
+    # @!method stacks
+    #   @see AwsCftTools::Client::CFT#stacks
+    # @!method create_stack
+    #   @see AwsCftTools::Client::CFT::StackManagement#create_stack
+    # @!method delete_stack
+    #   @see AwsCftTools::Client::CFT::StackManagement#delete_stack
+    # @!method update_stack
+    #   @see AwsCftTools::Client::CFT::StackManagement#update_stack
+    # @!method all_stacks
+    #   @see AwsCftTools::Client::CFT#all_stacks
+    # @!method changes_on_stack_update
+    #   @see AwsCftTools::Client::CFT::ChangesetManagement#changes_on_stack_update
+    # @!method changes_on_stack_delete
+    #   @see AwsCftTools::Client::CFT::ChangesetManagement#changes_on_stack_delete
+    # @!method changes_on_stack_create
+    #   @see AwsCftTools::Client::CFT::ChangesetManagement#changes_on_stack_create
+    def_delegators :cft_client, :exports, :stacks, :create_stack, :update_stack, :all_stacks,
+                   :changes_on_stack_update, :changes_on_stack_create, :changes_on_stack_delete,
+                   :delete_stack
+
+    # @!method templates
+    #   @see AwsCftTools::Client::Templates#templates
+    def_delegators :template_client, :templates
+
+    private
+
+    def ec2_client
+      @ec2_client ||= AwsCftTools::Client::EC2.new(@client_options)
+    end
+
+    def cft_client
+      @cft_client ||= AwsCftTools::Client::CFT.new(@client_options)
+    end
+
+    def template_client
+      @template_client ||= AwsCftTools::Client::Templates.new(@client_options)
+    end
+  end
+end