stackup 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a1cf0223b3b4769f8f08fb90e944721f19911105
-  data.tar.gz: 809c9e18e59c5a0f92b37cd43c33dd30bbda1a1e
+  metadata.gz: ff49d4bc734ae1d359d0727319dfd73bafde86f9
+  data.tar.gz: 79b3705ee2af79a3a268e74b0a589ab2fbe8f107
 SHA512:
-  metadata.gz: b38f0de16a9a86c5f037dae464562c27c246556e9db6bad43a0494b8c305ef159117bac4c275627dfac0284fd0666e1dbe688500829f84836f0c5bc66076ff6a
-  data.tar.gz: 2a933cc8523a7e410e14b43345993157e070f0690286f9498bbe855201c17cd803ee7c98cd5169f2e6a1d8670f31d0a7dd39629f667c0ef5e3c848598fd01988
+  metadata.gz: 5ea9f0efed3b79d32fc842a5a726114a7b5d70731626c355072ebc510e0ff016361e34db90f225ff3ec952cd229411a5d4dabd505901831393c825bc8753d0b7
+  data.tar.gz: d6a435c32e8203114d2f671ac56e66764d044da56b6e1f5c20227a6b80cfc6de2b511079f03538aed79b592efb866d6ddce843de1ac2a7f8b699aefa693895fd

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    stackup (0.2.0)
+    stackup (0.3.0)
       aws-sdk (~> 2.0)
       clamp (~> 1.0)
       console_logger
@@ -62,4 +62,4 @@ DEPENDENCIES
   stackup!
 
 BUNDLED WITH
-   1.10.5
+   1.10.6

data/README.md

@@ -2,11 +2,21 @@
 
 [![Build Status](https://travis-ci.org/realestate-com-au/stackup.svg?branch=master)](https://travis-ci.org/realestate-com-au/stackup)
 
-Stackup attempts to simplify AWS Cloudformation stack creation process in
-ruby projects by providing executable to perform common operations such
-as apply(create/update), delete, recreate on stack along with validations on
-templates. Operations which enforce a stack change will wait until
-the change is complete.
+Stackup provides a CLI and a simplified Ruby API for dealing with
+AWS CloudFormation stacks.
+
+## Why?
+
+Stackup provides some advantages over using `awscli` or `aws-sdk` directly:
+
+  - It treats stack changes as synchronous, streaming stack events until the
+    stack reaches a stable state.
+
+  - A `Stack#up` facade for `create`/`update` frees you from having to know
+    whether your stack already exists or not.
+
+  - "No-op" operations - deleting a stack that doesn't exist, or updating
+    without a template change - are handled gracefully (i.e. without error).
 
 ## Installation
 
@@ -20,9 +30,9 @@ Most commands operate in the context of a named stack:
 
     $ stackup STACK-NAME ...
 
-Called without stack-name, it will list stacks:
+Called with `--list`, it will list stacks:
 
-    $ stackup
+    $ stackup --list
     foo-bar-test
     zzz-production
 

data/bin/stackup

@@ -10,15 +10,15 @@ require "yaml"
 
 Clamp do
 
-  option "--debug", :flag, "enable debugging"
-
-  option ["-f", "--format"], "FORMAT", "output format", :default => "yaml"
-
   option ["-L", "--list"], :flag, "list stacks" do
     list_stacks
     exit 0
   end
 
+  option ["-Y", "--yaml"], :flag, "output data in YAML format"
+
+  option "--debug", :flag, "enable debugging"
+
   parameter "NAME", "Name of stack", :attribute_name => :stack_name
 
   def run(arguments)
@@ -38,11 +38,10 @@ Clamp do
   end
 
   def format_data(data)
-    case format.downcase
-    when "json"
-      MultiJson.dump(data, :pretty => true)
-    when "yaml"
+    if yaml?
       YAML.dump(data)
+    else
+      MultiJson.dump(data, :pretty => true)
     end
   end
 
@@ -89,8 +88,8 @@ Clamp do
 
     def execute
       options = {}
-      options[:template_body] = load_file(template_file)
-      options[:parameters_file] = load_file(parameters_file) if parameters_file
+      options[:template] = template
+      options[:parameters] = parameters if parameters
       options[:disable_rollback] = disable_rollback?
       report_change do
         stack.create_or_update(options)
@@ -99,12 +98,20 @@ Clamp do
 
     private
 
-    def load_file(file)
-      File.read(file)
+    def load_data(file)
+      YAML.load_file(file)
     rescue Errno::ENOENT
       signal_error "no such file: #{file.inspect}"
     end
 
+    def template
+      @template ||= load_data(template_file)
+    end
+
+    def parameters
+      @parameters ||= load_data(parameters_file) if parameters_file
+    end
+
   end
 
   subcommand ["down", "delete"], "Remove the stack." do
@@ -127,7 +134,23 @@ Clamp do
 
   end
 
-  subcommand "outputs", "Stack outputs." do
+  subcommand "template", "Display stack template." do
+
+    def execute
+      display_data(stack.template)
+    end
+
+  end
+
+  subcommand "parameters", "Display stack parameters." do
+
+    def execute
+      display_data(stack.parameters)
+    end
+
+  end
+
+  subcommand "outputs", "Display stack outputs." do
 
     def execute
       display_data(stack.outputs)
@@ -135,4 +158,12 @@ Clamp do
 
   end
 
+  subcommand "resources", "Display stack resources." do
+
+    def execute
+      display_data(stack.resources)
+    end
+
+  end
+
 end

data/lib/stackup/error_handling.rb

@@ -0,0 +1,32 @@
+require "stackup/errors"
+
+module Stackup
+
+  # Handle +Aws::CloudFormation::Errors::ValidationError+.
+  #
+  module ErrorHandling
+
+    # Invoke an Aws::CloudFormation operation
+    #
+    # If a +ValidationError+ is raised, check the message; there's often
+    # useful information is hidden inside.  If that's the case, convert it to
+    # an appropriate Stackup exception.
+    #
+    def handling_validation_error
+      yield
+    rescue Aws::CloudFormation::Errors::ValidationError => e
+      case e.message
+      when /Stack .* does not exist/
+        raise NoSuchStack, "no such stack"
+      when "No updates are to be performed."
+        raise NoUpdateRequired, "no updates are required"
+      when / can ?not be /
+        raise InvalidStateError, e.message
+      else
+        raise ValidationError, e.message
+      end
+    end
+
+  end
+
+end

data/lib/stackup/errors.rb

@@ -3,16 +3,19 @@ module Stackup
   # Base Stackup Exception class
   class ServiceError < StandardError; end
 
-  # Raised when the specified stack does not exist
-  class NoSuchStack < ServiceError; end
+  # Raised when something else dodgy happened
+  class ValidationError < ServiceError; end
 
-  # Raised to indicate a problem updating a stack
-  class StackUpdateError < ServiceError; end
+  # Raised when the specified stack does not exist
+  class NoSuchStack < ValidationError; end
 
   # Raised if we can't perform that operation now
-  class InvalidStateError < ServiceError; end
+  class InvalidStateError < ValidationError; end
 
   # Raised when a stack is already up-to-date
-  class NoUpdateRequired < StandardError; end
+  class NoUpdateRequired < ValidationError; end
+
+  # Raised to indicate a problem updating a stack
+  class StackUpdateError < ServiceError; end
 
 end

data/lib/stackup/stack.rb

@@ -1,6 +1,7 @@
 require "aws-sdk-resources"
 require "logger"
-require "stackup/error_mapping_proxy"
+require "multi_json"
+require "stackup/error_handling"
 require "stackup/stack_watcher"
 
 module Stackup
@@ -20,7 +21,7 @@ module Stackup
 
     attr_reader :name, :cf_client, :watcher
 
-    # Register a handler for reporting of stack events
+    # Register a handler for reporting of stack events.
     # @param [Proc] event_handler
     #
     def on_event(event_handler = nil, &block)
@@ -29,11 +30,15 @@ module Stackup
       @event_handler = event_handler
     end
 
+    include ErrorHandling
+
     # @return [String] the current stack status
     # @raise [Stackup::NoSuchStack] if the stack doesn't exist
     #
     def status
-      cf_stack.stack_status
+      handling_validation_error do
+        cf_stack.stack_status
+      end
     end
 
     # @return [boolean] true iff the stack exists
@@ -51,11 +56,48 @@ module Stackup
     #   accepts a superset of the options supported by
     #   +Aws::CloudFormation::Stack#update+
     #   (see http://docs.aws.amazon.com/sdkforruby/api/Aws/CloudFormation/Stack.html#update-instance_method)
-    # @return [Symbol] `:created` or `:updated` if successful
+    # @option options [Array<String>] :capabilities (CAPABILITY_IAM)
+    #   list of capabilities required for stack template
+    # @option options [boolean] :disable_rollback (false)
+    #   if true, disable rollback if stack creation fails
+    # @option options [String] :notification_arns
+    #   ARNs for the Amazon SNS topics associated with this stack
+    # @option options [String] :on_failure (DO_NOTHING)
+    #   if stack creation fails: DO_NOTHING, ROLLBACK, or DELETE
+    # @option options [Hash, Array<Hash>] :parameters
+    #   stack parameters, either as a Hash, or as an Array of
+    #   +Aws::CloudFormation::Types::Parameter+ structures
+    # @option options [Array<String>] :resource_types
+    #   resource types that you have permissions to work with
+    # @option options [Hash] :template
+    #   stack template, as Ruby data
+    # @option options [String] :stack_policy_body
+    #   stack policy, as JSON
+    # @option options [String] :stack_policy_url
+    #   location of stack policy
+    # @option options [String] :stack_policy_during_update_body
+    #   temporary stack policy, as JSON
+    # @option options [String] :stack_policy_during_update_url
+    #   location of temporary stack policy
+    # @option options [String] :template_body
+    #   stack template, as JSON
+    # @option options [String] :template_url
+    #   location of stack template
+    # @option options [Integer] :timeout_in_minutes
+    #   stack creation timeout
+    # @option options [boolean] :use_previous_template
+    #   if true, reuse the existing template
+    # @return [Symbol] +:created+ or +:updated+ if successful
     # @raise [Stackup::StackUpdateError] if operation fails
     #
     def create_or_update(options)
       options = options.dup
+      if (template_data = options.delete(:template))
+        options[:template_body] = MultiJson.dump(template_data)
+      end
+      if (parameters = options[:parameters])
+        options[:parameters] = normalise_parameters(parameters)
+      end
       options[:capabilities] ||= ["CAPABILITY_IAM"]
       delete if ALMOST_DEAD_STATUSES.include?(status)
       update(options)
@@ -71,12 +113,14 @@ module Stackup
     #
     # @param [String] template template JSON
     # @param [Array<Hash>] parameters template parameters
-    # @return [Symbol] `:deleted` if successful
+    # @return [Symbol] +:deleted+ if successful
     # @raise [Stackup::StackUpdateError] if operation fails
     #
     def delete
       begin
-        @stack_id = cf_stack.stack_id
+        @stack_id = handling_validation_error do
+          cf_stack.stack_id
+        end
       rescue NoSuchStack
         return nil
       end
@@ -93,7 +137,7 @@ module Stackup
 
     # Cancel update in-progress.
     #
-    # @return [Symbol] `:update_cancelled` if successful
+    # @return [Symbol] +:update_cancelled+ if successful
     # @raise [Stackup::StackUpdateError] if operation fails
     #
     def cancel_update
@@ -106,16 +150,60 @@ module Stackup
       nil
     end
 
+    # Get the current template.
+    #
+    # @return [Hash] current stack template, as Ruby data
+    # @raise [Stackup::NoSuchStack] if the stack doesn't exist
+    #
+    def template
+      handling_validation_error do
+        template_json = cf_client.get_template(:stack_name => name).template_body
+        MultiJson.load(template_json)
+      end
+    end
+
+    # Get the current parameters.
+    #
+    # @return [Hash] current stack parameters
+    # @raise [Stackup::NoSuchStack] if the stack doesn't exist
+    #
+    def parameters
+      handling_validation_error do
+        {}.tap do |h|
+          cf_stack.parameters.each do |p|
+            h[p.parameter_key] = p.parameter_value
+          end
+        end
+      end
+    end
+
+    # Get stack outputs.
+    #
+    # @return [Hash<String, String>] stack outputs
+    # @raise [Stackup::NoSuchStack] if the stack doesn't exist
+    #
+    def outputs
+      handling_validation_error do
+        {}.tap do |h|
+          cf_stack.outputs.each do |o|
+            h[o.output_key] = o.output_value
+          end
+        end
+      end
+    end
+
     # Get stack outputs.
     #
     # @return [Hash<String, String>]
     #   mapping of logical resource-name to physical resource-name
     # @raise [Stackup::NoSuchStack] if the stack doesn't exist
     #
-    def outputs
-      {}.tap do |h|
-        cf_stack.outputs.each do |output|
-          h[output.output_key] = output.output_value
+    def resources
+      handling_validation_error do
+        {}.tap do |h|
+          cf_stack.resource_summaries.each do |r|
+            h[r.logical_resource_id] = r.physical_resource_id
+          end
         end
       end
     end
@@ -124,8 +212,10 @@ module Stackup
 
     def create(options)
       options[:stack_name] = name
+      options.delete(:stack_policy_during_update_body)
+      options.delete(:stack_policy_during_update_url)
       status = modify_stack do
-        ErrorMappingProxy.new(cf).create_stack(options)
+        cf.create_stack(options)
       end
       fail StackUpdateError, "stack creation failed" unless status == "CREATE_COMPLETE"
       :created
@@ -133,6 +223,8 @@ module Stackup
 
     def update(options)
       options.delete(:disable_rollback)
+      options.delete(:on_failure)
+      options.delete(:timeout_in_minutes)
       status = modify_stack do
         cf_stack.update(options)
       end
@@ -153,7 +245,7 @@ module Stackup
 
     def cf_stack
       id_or_name = @stack_id || name
-      ErrorMappingProxy.new(cf.stack(id_or_name))
+      cf.stack(id_or_name)
     end
 
     def event_handler
@@ -170,7 +262,9 @@ module Stackup
     def modify_stack
       watcher = Stackup::StackWatcher.new(cf_stack)
       watcher.zero
-      yield
+      handling_validation_error do
+        yield
+      end
       loop do
         watcher.each_new_event(&event_handler)
         status = self.status
@@ -180,6 +274,16 @@ module Stackup
       end
     end
 
+    def normalise_parameters(arg)
+      return arg unless arg.is_a?(Hash)
+      arg.map do |key, value|
+        {
+          :parameter_key => key,
+          :parameter_value => value
+        }
+      end
+    end
+
   end
 
 end

data/lib/stackup/stack_watcher.rb

@@ -18,6 +18,7 @@ module Stackup
     # Yield all events since the last call
     #
     def each_new_event
+      # rubocop:disable Lint/HandleExceptions
       buffer = []
       stack.events.each do |event|
         break if @processed_event_ids.include?(event.event_id)
@@ -28,7 +29,6 @@ module Stackup
         @processed_event_ids.add(event.event_id)
       end
     rescue Aws::CloudFormation::Errors::ValidationError
-      # okay
     end
 
     # Consume all new events

data/spec/stackup/stack_spec.rb

@@ -76,18 +76,24 @@ describe Stackup::Stack do
 
       let(:template) { "stack template" }
 
+      let(:options) do
+        { :template_body => template }
+      end
+
       def create_or_update
-        stack.create_or_update(:template_body => template)
+        stack.create_or_update(options)
       end
 
-      context "successful" do
+      let(:describe_stacks_responses) do
+        super() + [
+          stack_description("CREATE_IN_PROGRESS"),
+          stack_description(final_status)
+        ]
+      end
 
-        let(:describe_stacks_responses) do
-          super() + [
-            stack_description("CREATE_IN_PROGRESS"),
-            stack_description("CREATE_COMPLETE")
-          ]
-        end
+      let(:final_status) { "CREATE_COMPLETE" }
+
+      context "successful" do
 
         it "calls :create_stack" do
           expected_args = {
@@ -107,12 +113,7 @@ describe Stackup::Stack do
 
       context "unsuccessful" do
 
-        let(:describe_stacks_responses) do
-          super() + [
-            stack_description("CREATE_IN_PROGRESS"),
-            stack_description("CREATE_FAILED")
-          ]
-        end
+        let(:final_status) { "CREATE_FAILED" }
 
         it "raises a StackUpdateError" do
           expect { create_or_update }
@@ -121,6 +122,41 @@ describe Stackup::Stack do
 
       end
 
+      context "with :template as data" do
+
+        let(:options) do
+          { :template => { "foo" => "bar" } }
+        end
+
+        it "converts the template to JSON" do
+          create_or_update
+          expect(cf_client).to have_received(:create_stack)
+            .with(hash_including(:template_body))
+        end
+
+      end
+
+      context "with :parameters as Hash" do
+
+        before do
+          options[:parameters] = { "foo" => "bar" }
+        end
+
+        it "converts them to an Array" do
+          expected_parameters = [
+            {
+              :parameter_key => "foo",
+              :parameter_value => "bar"
+            }
+          ]
+          create_or_update
+          expect(cf_client).to have_received(:create_stack) do |options|
+            expect(options[:parameters]).to eq(expected_parameters)
+          end
+        end
+
+      end
+
     end
 
   end
@@ -202,13 +238,11 @@ describe Stackup::Stack do
       let(:describe_stacks_responses) do
         super() + [
           stack_description("UPDATE_IN_PROGRESS"),
-          final_describe_stacks_response
+          stack_description(final_status)
         ]
       end
 
-      let(:final_describe_stacks_response) do
-        stack_description("UPDATE_COMPLETE")
-      end
+      let(:final_status) { "UPDATE_COMPLETE" }
 
       it "calls :update_stack" do
         expected_args = {
@@ -245,9 +279,7 @@ describe Stackup::Stack do
 
       context "unsuccessful" do
 
-        let(:final_describe_stacks_response) do
-          stack_description("UPDATE_ROLLBACK_COMPLETE")
-        end
+        let(:final_status) { "UPDATE_ROLLBACK_COMPLETE" }
 
         it "raises a StackUpdateError" do
           expect { create_or_update }.to raise_error(Stackup::StackUpdateError)
@@ -300,7 +332,7 @@ describe Stackup::Stack do
             )
           end
 
-          it "calls :delete_stack, then :create_stack first" do
+          it "calls :delete_stack, then :create_stack" do
             create_or_update
             expect(cf_client).to have_received(:delete_stack)
             expect(cf_client).to have_received(:create_stack)

data/stackup.gemspec

@@ -4,9 +4,9 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 Gem::Specification.new do |spec|
 
   spec.name          = "stackup"
-  spec.version       = "0.2.0"
-  spec.authors       = ["Arvind Kunday", "Mike Williams"]
-  spec.email         = ["arvind.kunday@rea-group.com", "mike.williams@rea-group.com"]
+  spec.version       = "0.3.0"
+  spec.authors       = ["Mike Williams", "Arvind Kunday"]
+  spec.email         = ["mike.williams@rea-group.com", "arvind.kunday@rea-group.com"]
   spec.summary       = "Manage CloudFormation stacks"
   spec.homepage      = "https://github.com/realestate-com-au/stackup"
   spec.license       = "MIT"

data/woollyams/parameters.json

@@ -0,0 +1,6 @@
+[
+  {
+    "parameter_key": "ParameterKey",
+    "parameter_value": "ParameterValue"
+  }
+]

data/woollyams/template.yml

@@ -0,0 +1,31 @@
+---
+AWSTemplateFormatVersion: '2010-09-09'
+Description: 'AWS CloudFormation Sample Template S3_Website_Bucket_With_Retain_On_Delete:
+  Sample template showing how to create a publicly accessible S3 bucket configured
+  for website access with a deletion policy of retail on delete. **WARNING** This
+  template creates an S3 bucket that will NOT be deleted when the stack is deleted.
+  You will be billed for the AWS resources used if you create a stack from this template.'
+Resources:
+  S3Bucket:
+    Type: AWS::S3::Bucket
+    Properties:
+      AccessControl: PublicRead
+      WebsiteConfiguration:
+        IndexDocument: index.html
+        ErrorDocument: error.html
+Outputs:
+  WebsiteURL:
+    Value:
+      Fn::GetAtt:
+      - S3Bucket
+      - WebsiteURL
+    Description: URL for website hosted on S3
+  S3BucketSecureURL:
+    Value:
+      Fn::Join:
+      - ''
+      - - https://
+        - Fn::GetAtt:
+          - S3Bucket
+          - DomainName
+    Description: Name of S3 bucket to hold website content

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: stackup
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
-- Arvind Kunday
 - Mike Williams
+- Arvind Kunday
 autorequire: 
 bindir: bin
 cert_chain: []
@@ -69,8 +69,8 @@ dependencies:
         version: '0'
 description: 
 email:
-- arvind.kunday@rea-group.com
 - mike.williams@rea-group.com
+- arvind.kunday@rea-group.com
 executables:
 - stackup
 extensions: []
@@ -106,16 +106,19 @@ files:
 - doc/method_list.html
 - doc/top-level-namespace.html
 - lib/stackup.rb
-- lib/stackup/error_mapping_proxy.rb
+- lib/stackup/error_handling.rb
 - lib/stackup/errors.rb
 - lib/stackup/service.rb
 - lib/stackup/stack.rb
 - lib/stackup/stack_watcher.rb
+- pkg/stackup-0.2.0.gem
 - spec/spec_helper.rb
 - spec/stackup/stack_spec.rb
 - spec/stackup/stack_watcher_spec.rb
 - stackup.gemspec
+- woollyams/parameters.json
 - woollyams/template.json
+- woollyams/template.yml
 homepage: https://github.com/realestate-com-au/stackup
 licenses:
 - MIT
@@ -136,7 +139,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.4.5.1
 signing_key: 
 specification_version: 4
 summary: Manage CloudFormation stacks

data/lib/stackup/error_mapping_proxy.rb

@@ -1,37 +0,0 @@
-require "stackup/errors"
-
-module Stackup
-
-  # An error-mapping proxy for Aws::CloudFormation models.
-  #
-  # It exists to convert certain types of `ValidationError`, where useful
-  # information is hidden inside the "message", to Stackup exceptions.
-  #
-  class ErrorMappingProxy
-
-    def initialize(delegate)
-      @delegate = delegate
-    end
-
-    def method_missing(*args)
-      @delegate.send(*args)
-    rescue Aws::CloudFormation::Errors::ValidationError => e
-      case e.message
-      when "No updates are to be performed."
-        raise NoUpdateRequired, "no updates are required"
-      when /Stack .* does not exist$/
-        raise NoSuchStack, "no such stack"
-      when / can ?not be /
-        raise InvalidStateError, e.message
-      else
-        raise e
-      end
-    end
-
-    def respond_to?(method)
-      @delegate.respond_to?(method)
-    end
-
-  end
-
-end