sfn 3.0.32 → 3.1.0

data/docs/commands.md

@@ -2,12 +2,12 @@
 title: "CLI Commands"
 weight: 4
 anchors:
-  - title: "Lifecycle commands"
-    url: "#lifecycle-commands"
-  - title: "Inspection and Information commands"
-    url: "#inspection-and-information-commands"
-  - title: "Configuration commands"
-    url: "#configuration-commands"
+  - title: "Lifecycle"
+    url: "#lifecycle"
+  - title: "Informational"
+    url: "#informational"
+  - title: "Configuration"
+    url: "#configuration"
 ---
 
 ## SparkleFormation CLI commands
@@ -16,7 +16,7 @@ The `sfn` command provides a collection of subcommands to handle stack
 lifecycles as well as subcommands to aid in inspection of existing
 stacks.
 
-### Lifecycle commands
+### Lifecycle
 
 #### Stack create
 
@@ -172,6 +172,52 @@ Example of stack update:
 
 ![stack update](./images/d_update.png)
 
+#### Stack plan
+
+The `plan` command allows for a stack to be created or updated via `sfn`. It uses the
+planning functionality of the provider to include planning information prior to
+application of the creation/modifications. The `plan` command is currently only
+supported with the AWS provider. When using the `update` command, the plan generation
+uses the internal planner with `sfn` and supports showing resource  for nested stacks.
+This is currently not supported with the remote planning API.
+
+Available options for the `plan` command are similar to the `create` and `update`
+commands. Additionally, available plans can be listed for a given stack:
+
+~~~
+$ sfn plan my-stack --list
+~~~
+
+By default the plan will be created with a default name (`miasma-changeset-STACKNAME`). A
+custom name can be used for the plan:
+
+~~~
+$ sfn plan my-stack --file my_template --plan-name custom-plan-name
+~~~
+
+It is also possible to apply an existing plan for a stack by providing the plan name:
+
+~~~
+$ sfn plan my-stack --plan-name existing-plan-name
+~~~
+
+#### Stack realize
+
+The `realize` command loads an existing plan for a given stack and executes the plan. This
+is useful to allow generating plans and then executing a plan at a later time. For example
+a stack plan can be first generated and not applied:
+
+~~~
+$ sfn plan my-stack --file my_template --plan-only
+~~~
+
+This generates the plan and displays the result but does not apply the changes. The plan
+can then be loaded and applied using the `realize` command:
+
+~~~
+$ sfn realize my-stack
+~~~
+
 #### Stack destroy
 
 Existing stacks can be destroyed via `sfn`:
@@ -209,7 +255,7 @@ Example of stack destroy:
 
 ![stack destroy](./images/d_destroy.png)
 
-### Inspection and Information commands
+### Informational
 
 #### Stack list
 
@@ -386,7 +432,7 @@ is installed on the local system, an image can be generated directly:
 $ sfn graph --file my_template --graph-type png
 ~~~
 
-### Configuration commands
+### Configuration
 
 To aid setup and configuration, `sfn` provides a configuration helper:
 
@@ -399,4 +445,4 @@ one automatically generated for them:
 
 ~~~
 $ sfn conf --generate
-~~~
+~~~

data/docs/usage.md

@@ -76,6 +76,7 @@ in loaded [SparklePacks][sparkle_packs].
 Available template related commands:
 
 * `sfn create`
+* `sfn plan`
 * `sfn update`
 * `sfn validate`
 

data/lib/sfn.rb

@@ -6,6 +6,7 @@ require "sparkle_formation"
 module Sfn
   autoload :ApiProvider, "sfn/api_provider"
   autoload :Callback, "sfn/callback"
+  autoload :Error, "sfn/error"
   autoload :Provider, "sfn/provider"
   autoload :Cache, "sfn/cache"
   autoload :Config, "sfn/config"

data/lib/sfn/command.rb

@@ -21,6 +21,7 @@ module Sfn
     autoload :Plan, "sfn/command/plan"
     autoload :Print, "sfn/command/print"
     autoload :Promote, "sfn/command/promote"
+    autoload :Realize, "sfn/command/realize"
     autoload :Update, "sfn/command/update"
     autoload :Validate, "sfn/command/validate"
 

data/lib/sfn/command/import.rb

@@ -23,7 +23,14 @@ module Sfn
           if entries.size > 1
             valid = false
             until valid
-              answer = ui.ask_question("Import via file system (fs) or remote bucket (remote)?", :default => "remote")
+              if config[:interactive_parameters]
+                answer = ui.ask_question(
+                  "Import via file system (fs) or remote bucket (remote)?",
+                  :default => "remote",
+                )
+              else
+                answer = "remote"
+              end
               valid = true if %w(remote fs).include?(answer)
               entries = [answer]
             end

data/lib/sfn/command/plan.rb

@@ -36,7 +36,12 @@ module Sfn
           if stack && stack.plan
             ui.warn "Found existing plan for this stack"
             begin
-              ui.confirm "Destroy existing plan?"
+              if config[:load_existing]
+                raise Bogo::Ui::ConfirmationDeclined
+              end
+              if config[:load_existing].nil?
+                ui.confirm "Destroy existing plan"
+              end
               ui.info "Destroying existing plan to generate new plan"
               stack.plan.destroy
             rescue Bogo::Ui::ConfirmationDeclined
@@ -127,56 +132,8 @@ module Sfn
         end
 
         plan = stack.plan || stack.plan_generate
-
-        begin
-          display_plan_information(plan)
-        rescue Bogo::Ui::ConfirmationDeclined
-          stack.reload
-          if (stack.template.nil? || stack.template.empty?) && stack.state == :unknown
-            ui.auto_confirm = false
-            ui.warn "Stack appears to be empty and should be destroyed"
-            ui.confirm "Destroy stack?"
-            stack.destroy
-            poll_stack(stack.name)
-          else
-            ui.confirm "Destroy generated plan?"
-            plan.destroy
-          end
-          raise
-        end
-
-        if config[:merge_api_options]
-          config.fetch(:options, Smash.new).each_pair do |key, value|
-            if stack.respond_to?("#{key}=")
-              stack.send("#{key}=", value)
-            end
-          end
-        end
-
-        begin
-          api_action!(:api_stack => stack) do
-            stack.plan_execute
-            if config[:poll]
-              poll_stack(stack.name)
-              if stack.reload.state == :update_complete || stack.reload.state == :create_complete
-                ui.info "Stack plan apply complete: #{ui.color("SUCCESS", :green)}"
-                namespace.const_get(:Describe).new({:outputs => true}, [name]).execute!
-              else
-                ui.fatal "Update of stack #{ui.color(name, :bold)}: #{ui.color("FAILED", :red, :bold)}"
-                raise "Stack did not reach a successful completion state."
-              end
-            else
-              ui.warn "Stack state polling has been disabled."
-              ui.info "Stack plan apply initialized for #{ui.color(name, :green)}"
-            end
-          end
-        rescue Miasma::Error::ApiError::RequestError => e
-          if e.message.downcase.include?("no updates")
-            ui.warn "No changes detected for stack (#{stack.name})"
-          else
-            raise
-          end
-        end
+        namespace.const_get(:Realize).
+          new(config, [name]).execute!
       end
 
       # Display plan list in table form

data/lib/sfn/command/realize.rb

@@ -0,0 +1,82 @@
+require "sfn"
+
+module Sfn
+  class Command
+    # Realize command
+    class Realize < Command
+      include Sfn::CommandModule::Base
+      include Sfn::CommandModule::Planning
+
+      # Run the stack realize command
+      def execute!
+        name_required!
+        name = name_args.first
+
+        stack_info = "#{ui.color("Name:", :bold)} #{name}"
+        begin
+          stack = provider.stacks.get(name)
+        rescue Miasma::Error::ApiError::RequestError
+          raise Error::StackNotFound,
+            "Failed to locate stack: #{name}"
+        end
+
+        if config[:plan_name]
+          ui.debug "Setting custom plan name - #{config[:plan_name]}"
+          # ensure custom attribute is dirty so we can modify
+          stack.custom = stack.custom.dup
+          stack.custom[:plan_name] = config[:plan_name]
+        end
+
+        ui.info " -> Loading plan information..."
+
+        plan = stack.plan
+        if plan.nil?
+          raise Error::StackPlanNotFound,
+            "Failed to locate plan for stack `#{name}`"
+        end
+
+        display_plan_information(plan)
+
+        return if config[:plan_only]
+
+        if config[:merge_api_options]
+          config.fetch(:options, Smash.new).each_pair do |key, value|
+            if stack.respond_to?("#{key}=")
+              stack.send("#{key}=", value)
+            end
+          end
+        end
+
+        begin
+          api_action!(:api_stack => stack) do
+            stack.plan_execute
+            if config[:poll]
+              poll_stack(stack.name)
+              if [:update_complete, :create_complete].
+                include?(stack.reload.state)
+                ui.info "Stack plan apply complete: " \
+                        "#{ui.color("SUCCESS", :green)}"
+                namespace.const_get(:Describe).
+                  new({:outputs => true}, [name]).execute!
+              else
+                ui.fatal "Update of stack #{ui.color(name, :bold)}: " \
+                         "#{ui.color("FAILED", :red, :bold)}"
+                raise Error::StackStateIncomplete
+              end
+            else
+              ui.warn "Stack state polling has been disabled."
+              ui.info "Stack plan apply initialized for " \
+                      "#{ui.color(name, :green)}"
+            end
+          end
+        rescue Miasma::Error::ApiError::RequestError => e
+          if e.message.downcase.include?("no updates")
+            ui.warn "No changes detected for stack (#{stack.name})"
+          else
+            raise
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sfn/command/update.rb

@@ -112,7 +112,7 @@ module Sfn
             end
             if config[:plan_only]
               ui.info "Plan only mode requested. Exiting."
-              exit 0
+              return
             end
           end
           stack.parameters = config_root_parameters

data/lib/sfn/command_module/planning.rb

@@ -27,8 +27,12 @@ module Sfn
         unless print_plan_result(result, [result.name])
           ui.info "No resources life cycle changes detected in this update!"
         end
-        cmd = self.class.to_s.split("::").last.downcase
-        ui.confirm "Apply this stack #{cmd}?" unless config[:plan_only]
+        if config[:plan_apply]
+          return ui.info "Realizing this stack plan..."
+        elsif config[:plan_only]
+          return
+        end
+        ui.confirm "Realize this stack plan?"
       end
 
       # Print plan information to the UI

data/lib/sfn/command_module/stack.rb

@@ -340,9 +340,17 @@ module Sfn
             end
             if current_value && current_value.to_s != stack_value.to_s
               if config[:parameter_validation] == "default"
-                ui.warn "Nested stack has been altered directly! This update may cause unexpected modifications!"
-                ui.warn "Stack name: #{c_stack.name}. Parameter: #{p_key}. Current value: #{stack_value}. Expected value: #{current_value} (via: #{c_value.inspect})"
-                answer = ui.ask_question("Use current value or expected value for #{p_key} [current/expected]?", :valid => ["current", "expected"])
+                ui.warn "Nested stack has been altered directly! " \
+                        "This update may cause unexpected modifications!"
+                ui.warn "Stack name: #{c_stack.name}. Parameter: #{p_key}. " \
+                        "Current value: #{stack_value}. Expected value: #{current_value} " \
+                        "(via: #{c_value.inspect})"
+                if config[:interactive_parameters]
+                  answer = ui.ask_question("Use current value or expected value for #{p_key} " \
+                  "[current/expected]?", :valid => ["current", "expected"])
+                else
+                  raise Error::InteractionDisabled
+                end
               else
                 answer = config[:parameter_validation]
               end

data/lib/sfn/command_module/template.rb

@@ -588,7 +588,11 @@ module Sfn
           ui.puts "#{output.join("\n")}\n"
           response = nil
           until valid[response]
-            response = ui.ask_question("Enter selection").to_i
+            if config[:interactive_parameters]
+              response = ui.ask_question("Enter selection").to_i
+            else
+              raise Error::InteractionDisabled
+            end
           end
           entry = valid[response]
           if entry[:type] == :collection

data/lib/sfn/config.rb

@@ -38,7 +38,9 @@ module Sfn
     end
 
     # Only values allowed designating bool type
-    BOOLEAN = BOOLEAN_VALUES = [TrueClass, FalseClass]
+    BOOLEAN = BOOLEAN_VALUES = [TrueClass, FalseClass].freeze
+    # Boolean type with nil included
+    TRISTATE_BOOLEAN = (BOOLEAN + [NilClass]).freeze
 
     autoload :Conf, "sfn/config/conf"
     autoload :Create, "sfn/config/create"
@@ -57,6 +59,7 @@ module Sfn
     autoload :Plan, "sfn/config/plan"
     autoload :Print, "sfn/config/print"
     autoload :Promote, "sfn/config/promote"
+    autoload :Realize, "sfn/config/realize"
     autoload :Update, "sfn/config/update"
     autoload :Validate, "sfn/config/validate"
 
@@ -104,6 +107,11 @@ module Sfn
       :description => "Enable debug output",
       :short_flag => "u",
     )
+    attribute(
+      :log, String,
+      :description => "Enable logging with given level",
+      :short_flag => "G",
+    )
     attribute(
       :colors, [TrueClass, FalseClass],
       :description => "Enable colorized output",

data/lib/sfn/config/plan.rb

@@ -17,6 +17,24 @@ module Sfn
         :description => "Custom plan name or ID (not applicable to all providers)",
       )
 
+      attribute(
+        :load_existing, TRISTATE_BOOLEAN,
+        :description => "Load existing plan if exists",
+        :default => nil,
+      )
+
+      attribute(
+        :auto_destroy_stack, TRISTATE_BOOLEAN,
+        :description => "Automatically destroy empty stack",
+        :default => nil,
+      )
+
+      attribute(
+        :auto_destroy_plan, TRISTATE_BOOLEAN,
+        :description => "Automatically destroy generated plan",
+        :default => nil,
+      )
+
       attribute(
         :list, BOOLEAN,
         :description => "List all available plans for stack",

data/lib/sfn/config/realize.rb

@@ -0,0 +1,13 @@
+require "sfn"
+
+module Sfn
+  class Config
+    # Realize command configuration
+    class Realize < Config
+      attribute(
+        :plan_name, String,
+        :description => "Custom plan name or ID",
+      )
+    end
+  end
+end

data/lib/sfn/config/validate.rb

@@ -81,7 +81,14 @@ module Sfn
             result = Smash.new
             v.split(",").each do |item_pair|
               key, value = item_pair.split(/[=:]/, 2)
-              result[key] = value
+              if !result[key]
+                result[key] = value
+                next
+              end
+              if !result.is_a?(Array)
+                result[key] = [result[key]]
+              end
+              result[key] << value
             end
             result
           when Hash