sfn 0.5.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3673b71af607d02ac346e2419e0f3ee10d29e7fb
-  data.tar.gz: 43fd1549a7deed286de8a4c59b9c1b3148700d3e
+  metadata.gz: 1e25f48c5fa80038624e08c5e224e62c740be5a8
+  data.tar.gz: 2a983906bcdb4b5e02d81c9762b1a033c3b4410e
 SHA512:
-  metadata.gz: 3e47a279dc5d53e18674281d2371f0cd72539dd797d2a0e0276813125acc8118ee5087e96278b2bdf960f42147fda969bf1ab855c4b1b5b5f7532a6d85e62e46
-  data.tar.gz: 28ab80f21ef727f319a7c5c3ac685ced8f33c7fadcc5e680b444812957734c49cf13e30d27e18d0944004d91d5065e79b71c9135dbb6df58d6f7f075fa8bc090
+  metadata.gz: 9b41dd94c68cff3b29a487c4d03e86c36d352b4a3403d99787db582d3eaf54e7b2f93418e54398c4dcf8e3083813830cbc24a1a897c70765cce0869c236a5f76
+  data.tar.gz: 230a3ef0bcf85adc1c6fd4bb80617dd2b20ab19de4c6b91b43a319fb2265a3cf9d50b7cee4195b119c787ea68528bd47817c75ccddbfb147670c6dd727974103

data/CHANGELOG.md

@@ -1,11 +1,22 @@
-## v0.5.0
-* Add support for compile time parameters
-
-## v0.4.16
-* Fix apply stack on update command when template provides new parameters
-
-## v0.4.14
-* Add constraint on sparkle_formation library to stay below 1.0 release
+## v1.0.0
+
+_NOTE: This release contains breaking changes! Please review the
+	changes in this release and test your configuration and
+	templates. Changes that may introduce breakage have been
+	labeled below._
+
+* [BREAKING] Update sparkle_formation constraint to 1.0 versions
+* [BREAKING] Default to "deep" style nesting (previous default: "shallow")
+* [BREAKING] Template loading via SparklePacks in place of direct file loading
+* Provide support for shallow and deep stack nesting styles
+* Add support for customized callbacks
+* Fix `--print-only` behavior on `update` command, add to `validate` command
+* On validation of template with nesting, validate all nested templates _and_ root template
+* Display details of all nested stacks on `describe` command
+* Disable automatic stack inspection on failed `create` / `update` command
+* Add support for SparklePacks
+* Add support for AWS stack policies via optional callback
+* And lots of internal refactors!
 
 ## v0.4.12
 * Fix transient uninitialized constant error for update command

data/README.md

@@ -1,8 +1,14 @@
+![SparkleFormation CLI](img/sfn.jpg)
+
 # SparkleFormation CLI
 
 SparkleFormation command line interface for interacting
 with orchestration APIs.
 
+## Extra Documentation
+
+* [User Documentation](https://sparkleformation.github.io/sfn/UserDocs)
+
 ## API Compatibility
 
 * AWS
@@ -26,7 +32,7 @@ formats:
 ```json
 {
   "credentials": {
-    AWS_CREDENTIALS
+    MIASMA_CREDENTIALS
   },
   "options": {
     "disable_rollback": true
@@ -34,7 +40,7 @@ formats:
 }
 ```
 
-### YAML
+#### YAML
 
 ```yaml
 ---
@@ -44,12 +50,12 @@ formats:
   :disable_rollback: true
 ```
 
-### XML
+#### XML
 
 ```xml
 <configuration>
   <credentials>
-    AWS_CREDENTIALS
+    MIASMA_CREDENTIALS
   </credentials>
   <options>
     <disable_rollback>
@@ -59,17 +65,86 @@ formats:
 </configuration>
 ```
 
-### Ruby
+#### Ruby
 
 ```ruby
 Configuration.new do
   credentials do
-    AWS_CREDENTIALS
+    MIASMA_CREDENTIALS
   end
-  options.disable_rollback true
+  options.on_failure 'nothing'
 end
 ```
 
+### Configuration Options
+
+* `processing` - Enable SparkleFormation processing
+  * Valid: Boolean
+  * Default: `true`
+
+* `apply_nesting` - Style of nested stack processing
+  * Valid: `"shallow"`, `"deep"`
+  * Default: `"deep"`
+
+* `options` - API options for target orchestration API (see miasma)
+  * Valid: `Hash`
+  * Default: none
+
+* `ssh_attempt_users` - List of users to attempt SSH connection on node failure
+  * Valid: `Array<String>`
+  * Default: none
+
+* `identity_file` - Custom SSH identity file to use for connection on node failure
+  * Valid: `String`
+  * Default: none
+
+* `nesting_bucket` - Name of bucket to store nested stack templates
+  * Valid: `String`
+  * Default: none
+
+* `credentials` - API credentials for target orchestration API (see [miasma](https://github.com/miasma-rb/miasma))
+  * Valid: `Hash`
+  * Default: none
+
+* `callbacks` - Callbacks to execute around API calls
+  * Valid: `Hash`
+  * Default: none
+    * `before` - Callbacks to execute before _any_ API call
+      * Valid: `Array<String>`
+      * Default: none
+    * `after` - Callbacks to execute after _any_ API call
+      * Valid: `Array<String>`
+      * Default: none
+    * `before_COMMAND` - Callbacks to execute before specific `COMMAND` API call
+      * Valid: `Array<String>`
+      * Default: none
+    * `after_COMMAND` - Callbacks to execute after specific `COMMAND` API call
+      * Valid: `Array<String>`
+      * Default: none
+    * `template` - Callbacks to execute on template
+      * Valid: `Array<String>`
+      * Default: none
+    * `default` - Callbacks to always execute
+      * Valid: `Array<String>`
+      * Default: none
+    * `require` - List of custom libraries to load
+      * Valid: `Array<String>`
+      * Default: none
+
+* `retry` - Configuration of API request retries
+  * Valid: `Hash`
+  * Default: none
+    * `type` - Type of retry
+      * Valid: `"flat"`, `"linear"`, `"exponential"`
+      * Default: `"exponential"`
+    * `interval` - Base wait interval for retry
+      * Valid: `Numeric`
+      * Default: 5
+    * `max_attempts` - Maximum number of attempts allowed
+      * Valid: `Numeric`
+      * Default: 20
+      * _NOTE_: Set to `nil` for infinite retry
+
 ## Commands
 
 * `sfn list`
@@ -81,45 +156,20 @@ end
 * `sfn inspect`
 * `sfn validate`
 
+_NOTE: All commands respond to `--help` and will provide a full list of valid options._
+
 ### `sfn list`
 
 Provides listing of current stacks and state of each stack.
 
-#### Supported options
-
-* `--attribute ATTR` stack attribute to display
-* `--status STATUS` match stacks with given status
-
 ### `sfn validate`
 
 Validates template with API
 
-#### Supported options
-
-* `--[no-]processing` enable template processing
-* `--file PATH` path to stack template file
-* `--translate PROVIDER` translate template to provider
-* `--[no-]apply-nesting` apply template nesting logic
-* `--nesting-bucket BUCKET` asset store bucket to place nested stack templates
-
 ### `sfn create NAME`
 
 Creates a new stack with the provided name (`NAME`).
 
-#### Supported options
-
-* `--timeout MINUTES` stack creation timeout limit
-* `--[no-]rollback` disable rollback on failure
-* `--capability CAPABILITY` enable capability within API
-* `--notifications ARN` add notification ARN
-* `--print-only` print stack template JSON and exit
-* `--apply-stack NAME` apply existing stack outputs
-* `--[no-]processing` enable template processing
-* `--file PATH` path to stack template file
-* `--translate PROVIDER` translate template to provider
-* `--[no-]apply-nesting` apply template nesting logic
-* `--nesting-bucket BUCKET` asset store bucket to place nested stack templates
-
 #### Apply Stacks
 
 The `--apply-stack` option allows providing the name of an existing
@@ -193,16 +243,6 @@ resources are supported.
 
 Update an existing stack.
 
-#### Supported options
-
-* `--print-only` print stack template JSON and exit
-* `--apply-stack NAME` apply existing stack outputs
-* `--[no-]processing` enable template processing
-* `--file PATH` path to stack template file
-* `--translate PROVIDER` translate template to provider
-* `--[no-]apply-nesting` apply template nesting logic
-* `--nesting-bucket BUCKET` asset store bucket to place nested stack templates
-
 ### `sfn destroy STACK`
 
 Destroy an existing stack.
@@ -232,18 +272,10 @@ stack is "in progress", the polling option will result in
 polling and displaying new events until the stack reaches a
 completed state.
 
-#### Supported options
-
-* `--[no-]poll` poll for new events until completed state reached
-
 ### `sfn describe STACK`
 
 Display resources and outputs of give stack.
 
-#### Supported options
-
-* `--resources` display resources
-* `--outputs` display outputs
 
 ### `sfn inspect STACK`
 
@@ -252,7 +284,7 @@ underlying resource modeling objects provided via the
 [miasma][miasma] library. It also provides extra helpers for
 running common inspection commands.
 
-### Supported options
+### Interesting `inspect` options
 
 * `--nodes` list node addresses within stack
 * `--instance-failure [LOG_FILE]` print log file from failed instance

data/bin/generate_sfn_docs

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+require 'fileutils'
+
+unless(system("yardoc"))
+  $stderr.puts 'ACK: Failed to create docs!'
+  exit -1
+end
+
+FileUtils.mkdir_p('doc/UserDocs')
+
+Dir.glob('docs/**/*').each do |path|
+  next unless File.file?(path)
+  content = File.read(path)
+  rel_path = path.sub(/.*?docs\//, '')
+  new_path = File.join('doc/UserDocs', rel_path)
+  user_doc_root = (['..'] * rel_path.scan('/').size).join('/')
+  unless(user_doc_root.to_s.empty?)
+    user_doc_root << '/'
+  end
+  FileUtils.mkdir_p(File.dirname(new_path))
+  File.open(new_path, 'w') do |file|
+    file.puts content
+  end
+  if(new_path.end_with?('.md'))
+    File.open(new_path.sub('.md', '.html'), 'w') do |file|
+      file.print "<!DOCTYPE html><html><head><title>SparkleFormation CLI User Documentation</title><script src=\"#{user_doc_root}v/0.3.2/marked.js\"></script><script src=\"#{user_doc_root}v/jquery-2.1.3.min.js\"></script><script src=\"#{user_doc_root}v/loader.js\"></script><script src=\"#{user_doc_root}v/highlight.min.js\"></script><link rel=\"stylesheet\" href=\"#{user_doc_root}v/bootstrap.min.css\"></link><link rel=\"stylesheet\" href=\"#{user_doc_root}v/highlight.min.css\"></link><link rel=\"stylesheet\" href=\"#{user_doc_root}v/finalizer.css\"></link>"
+      file.print "</head><body><div class=\"markdown-body\"><div class=\"navbar navbar-top\"><div class=\"navbar-inner\"><div class=\"container\"><div class=\"navbar-brand\"><a href=\"#{user_doc_root}README.html\">SparkleFormation - User documentation</a></div></div></div></div><div class=\"panel panel-default\"><div class=\"panel-body\" id=\"content\"></div></div></div>"
+      file.print "</body></html>"
+    end
+  end
+end
+
+File.open('doc/UserDocs/index.html', 'w') do |file|
+  file.puts '<html><head><meta http-equiv="refresh" content="0; url=README.html" /></head></html>'
+end
+
+puts 'done.'

data/lib/sfn/callback/stack_policy.rb

@@ -0,0 +1,94 @@
+require 'sfn'
+
+module Sfn
+  class Callback
+    class StackPolicy < Callback
+
+      # Policy to apply prior to stack deletion
+      DEFENSELESS_POLICY = {
+        'Statement' => [{
+            'Effect' => 'Allow',
+            'Action' => 'Update:*',
+            'Resource' => '*',
+            'Principal' => '*'
+          }]
+      }
+
+      # @return [Smash] cached policies
+      attr_reader :policies
+
+      # Overload to init policy cache
+      #
+      # @return [self]
+      def initialize(*args)
+        super
+        @policies = Smash.new
+      end
+
+      # Submit all cached policies
+      #
+      # @param args [Hash]
+      def submit_policy(args)
+        ui.info 'Submitting stack policy documents'
+        stack = args[:api_stack]
+        ([stack] + stack.nested_stacks).compact.each do |p_stack|
+          run_action "Applying stack policy to #{ui.color(p_stack.name, :yellow)}" do
+            save_stack_policy(p_stack)
+          end
+        end
+        ui.info 'Stack policy documents successfully submitted!'
+      end
+      alias_method :after_create, :submit_policy
+      alias_method :after_update, :submit_policy
+
+      # Update all policies to allow resource destruction
+      def before_destroy(args)
+        ui.warn 'All policies will be disabled for stack destruction!'
+        ui.confirm 'Continue with stack destruction'
+        stack = args[:api_stack]
+        ([stack] + stack.nested_stacks).compact.each do |p_stack|
+          @policies[p_stack.name] = DEFENSELESS_POLICY
+          run_action "Disabling stack policy for #{ui.color(p_stack.name, :yellow)}" do
+            save_stack_policy(p_stack)
+          end
+        end
+        ui.warn "Policy modification for deletion not currently enabled!"
+      end
+
+      # Generate stack policy for stack and cache for the after hook
+      # to handle
+      #
+      # @param info [Hash]
+      def template(info)
+        if(info[:sparkle_stack])
+          @policies.set(info[:stack_name],
+            info[:sparkle_stack].generate_policy
+          )
+        end
+      end
+
+      # Save the cached policy for the given stack
+      #
+      # @param p_stack [Miasma::Models::Orchestration::Stack]
+      # @return [NilClass]
+      def save_stack_policy(p_stack)
+        result = p_stack.api.request(
+          :path => '/',
+          :method => :post,
+          :form => Smash.new(
+            'Action' => 'SetStackPolicy',
+            'StackName' => p_stack.id,
+            'StackPolicyBody' => MultiJson.dump(
+              @policies.fetch(p_stack.id,
+                @policies.fetch(p_stack.data[:logical_id],
+                  @policies[p_stack.name]
+                )
+              )
+            )
+          )
+        )
+      end
+
+    end
+  end
+end

data/lib/sfn/callback.rb

@@ -0,0 +1,48 @@
+require 'sfn'
+
+module Sfn
+  # Interface for injecting custom functionality
+  class Callback
+
+    autoload :StackPolicy, 'sfn/callback/stack_policy'
+
+    # @return [Bogo::Ui]
+    attr_reader :ui
+    # @return [Smash]
+    attr_reader :config
+
+    # Create a new callback instance
+    #
+    # @param [Bogo::Ui]
+    # @param [Smash] configuration hash
+    # @param [Array<String>] arguments from the CLI
+    # @param [Provider] API connection
+    #
+    # @return [self]
+    def initialize(ui, config, arguments, api)
+      @ui = ui
+      @config = config
+      @arguments = arguments
+      @api = api
+    end
+
+    # Wrap action within status text
+    #
+    # @param msg [String] action text
+    # @yieldblock action to perform
+    # @return [Object] result of yield
+    def run_action(msg)
+      ui.info("#{msg}... ", :nonewline)
+      begin
+        result = yield
+        ui.puts ui.color('complete!', :green, :bold)
+        result
+      rescue => e
+        ui.puts ui.color('error!', :red, :bold)
+        ui.error "Reason - #{e}"
+        raise
+      end
+    end
+
+  end
+end

data/lib/sfn/command/create.rb

@@ -25,7 +25,7 @@ module Sfn
         end
 
         unless(config[:print_only])
-          ui.info "#{ui.color('SparkleFormation:', :bold)} #{ui.color('create', :green)}"
+          ui.info "#{ui.color('Cloud Formation:', :bold)} #{ui.color('create', :green)}"
         end
 
         stack_info = "#{ui.color('Name:', :bold)} #{name}"
@@ -66,32 +66,31 @@ module Sfn
           end
 
           populate_parameters!(stack.template)
-          stack.parameters = config[:parameters]
+          stack.parameters = config_root_parameters
 
           stack.template = translate_template(stack.template)
-          stack.save
 
-        end
-
-        if(stack)
-          if(config[:poll])
-            poll_stack(stack.name)
-            stack = provider.connection.stacks.get(name)
-
-            if(stack.reload.state == :create_complete)
-              ui.info "Stack create complete: #{ui.color('SUCCESS', :green)}"
-              namespace.const_get(:Describe).new({:outputs => true}, [name]).execute!
+          api_action!(:api_stack => stack) do
+            stack.save
+            if(config[:poll])
+              poll_stack(stack.name)
+              stack = provider.connection.stacks.get(name)
+
+              if(stack.reload.state == :create_complete)
+                ui.info "Stack create complete: #{ui.color('SUCCESS', :green)}"
+                namespace.const_get(:Describe).new({:outputs => true}, [name]).execute!
+              else
+                ui.fatal "Create of new stack #{ui.color(name, :bold)}: #{ui.color('FAILED', :red, :bold)}"
+                raise
+              end
             else
-              ui.fatal "Create of new stack #{ui.color(name, :bold)}: #{ui.color('FAILED', :red, :bold)}"
-              ui.info ""
-              namespace.const_get(:Inspect).new({:instance_failure => true}, [name]).execute!
-              raise
+              ui.warn 'Stack state polling has been disabled.'
+              ui.info "Stack creation initialized for #{ui.color(name, :green)}"
             end
-          else
-            ui.warn 'Stack state polling has been disabled.'
-            ui.info "Stack creation initialized for #{ui.color(name, :green)}"
           end
+
         end
+
       end
 
     end

data/lib/sfn/command/describe.rb

@@ -15,18 +15,24 @@ module Sfn
       # Run the stack describe action
       def execute!
         stack_name = name_args.last
-        stack = provider.connection.stacks.get(stack_name)
-        if(stack)
-          display = [].tap do |to_display|
-            AVAILABLE_DISPLAYS.each do |display_option|
-              if(config[display_option])
-                to_display << display_option
+        root_stack = api_action! do
+          provider.connection.stacks.get(stack_name)
+        end
+        if(root_stack)
+          ([root_stack] + root_stack.nested_stacks).compact.each do |stack|
+            ui.info "Stack description of #{ui.color(stack.name, :bold)}:"
+            display = [].tap do |to_display|
+              AVAILABLE_DISPLAYS.each do |display_option|
+                if(config[display_option])
+                  to_display << display_option
+                end
               end
             end
-          end
-          display = AVAILABLE_DISPLAYS.dup if display.empty?
-          display.each do |display_method|
-            self.send(display_method, stack)
+            display = AVAILABLE_DISPLAYS.dup if display.empty?
+            display.each do |display_method|
+              self.send(display_method, stack)
+            end
+            ui.puts
           end
         else
           ui.fatal "Failed to find requested stack: #{ui.color(stack_name, :bold, :red)}"

data/lib/sfn/command/destroy.rb

@@ -29,7 +29,9 @@ module Sfn
           stack = provider.connection.stacks.get(stack_name)
           if(stack)
             nested_stack_cleanup!(stack)
-            stack.destroy
+            api_action!(:api_stack => stack) do
+              stack.destroy
+            end
             ui.info "Destroy request complete for stack: #{ui.color(stack_name, :red)}"
           else
             ui.warn "Failed to locate requested stack: #{ui.color(stack_name, :bold)}"
@@ -42,13 +44,16 @@ module Sfn
             ui.error "Stack polling is not available when multiple stack deletion is requested!"
           end
         end
-        ui.info "  -> Destroyed SparkleFormation#{plural}: #{ui.color(stacks.join(', '), :bold, :red)}"
+        ui.info "  -> Destroyed Cloud Formation#{plural}: #{ui.color(stacks.join(', '), :bold, :red)}"
       end
 
       # Cleanup persisted templates if nested stack resources are included
       def nested_stack_cleanup!(stack)
+        stack.nested_stacks.each do |n_stack|
+          nested_stack_cleanup!(n_stack)
+        end
         nest_stacks = stack.template.fetch('Resources', {}).values.find_all do |resource|
-          resource['Type'] == 'AWS::CloudFormation::Stack'
+          resource['Type'] == stack.api.class.const_get(:RESOURCE_MAPPING).key(stack.class).to_s
         end.each do |resource|
           url = resource['Properties']['TemplateURL']
           if(url)

data/lib/sfn/command/events.rb

@@ -19,32 +19,34 @@ module Sfn
         @stacks << stack
         discover_stacks(stack)
         if(stack)
-          table = ui.table(self) do
-            table(:border => false) do
-              events = get_events
-              row(:header => true) do
-                allowed_attributes.each do |attr|
-                  column attr.split('_').map(&:capitalize).join(' '), :width => ((val = events.map{|e| e[attr].to_s.length}.push(attr.length).max + 2) > 70 ? 70 : val)
-                end
-              end
-              events.each do |event|
-                row do
+          api_action!(:api_stack => stack) do
+            table = ui.table(self) do
+              table(:border => false) do
+                events = get_events
+                row(:header => true) do
                   allowed_attributes.each do |attr|
-                    column event[attr]
+                    column attr.split('_').map(&:capitalize).join(' '), :width => ((val = events.map{|e| e[attr].to_s.length}.push(attr.length).max + 2) > 70 ? 70 : val)
+                  end
+                end
+                events.each do |event|
+                  row do
+                    allowed_attributes.each do |attr|
+                      column event[attr]
+                    end
                   end
                 end
               end
-            end
-          end.display
-          if(config[:poll])
-            while(stack.in_progress?)
-              to_wait = config.fetch(:poll_wait_time, 10).to_f
-              while(to_wait > 0)
-                sleep(0.1)
-                to_wait -= 0.1
+            end.display
+            if(config[:poll])
+              while(stack.in_progress?)
+                to_wait = config.fetch(:poll_wait_time, 10).to_f
+                while(to_wait > 0)
+                  sleep(0.1)
+                  to_wait -= 0.1
+                end
+                stack.reload
+                table.display
               end
-              stack.reload
-              table.display
             end
           end
         else
@@ -64,7 +66,7 @@ module Sfn
           stack.events.all.map do |e|
             e.attributes.merge(:stack_name => stack.name).to_smash
           end
-        end.flatten.compact
+        end.flatten.compact.find_all{|e| e[:time] }
         stack_events.sort do |x,y|
           Time.parse(x[:time].to_s) <=> Time.parse(y[:time].to_s)
         end

data/lib/sfn/command/inspect.rb

@@ -13,12 +13,14 @@ module Sfn
         stack_name = name_args.last
         stack = provider.connection.stacks.get(stack_name)
         ui.info "Stack inspection #{ui.color(stack_name, :bold)}:"
-        outputs = [:attribute, :nodes, :instance_failure].map do |key|
-          if(config.has_key?(key))
-            send("display_#{key}", stack)
-            key
-          end
-        end.compact
+        outputs = api_action!(:api_stack => stack) do
+          [:attribute, :nodes, :instance_failure].map do |key|
+            if(config.has_key?(key))
+              send("display_#{key}", stack)
+              key
+            end
+          end.compact
+        end
         if(outputs.empty?)
           ui.info '  Stack dump:'
           ui.puts MultiJson.dump(