sparkle_formation 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 885773b23288e446fbafd4bf227fefd8fab90689
-  data.tar.gz: 1fff2fde513ea68af8368e08c4bbc6aeb8af861e
+  metadata.gz: a3733e20ff2e0df836b9e519da638cd1ae5dd570
+  data.tar.gz: 42e65f5894748ff4dcd38641ee39499ffb39a6e1
 SHA512:
-  metadata.gz: 4005c93381322a6f94e9e0c09ce33d8f77360d5a416f70a592bb75ecd72e4b024643944fffb1b9b52cc3e6b98cd0cc7bc98de78d1ed4c4fbc18bb0752036a25d
-  data.tar.gz: 1c6586660a632bf5c9d721e41ba88bab78ee8d696d697fccf8779a2a785dac3d7fc0efe86f0e3c57883b42d07011fd1e63dd0603f25c9c016d31d6f98eb2bb29
+  metadata.gz: c85ee17f6bdd54cfcf73dde7c31c33baf1fc46f7dcaa6f2c229a60be15bfbfb5314b19e34f0580fc37cb1c25db88115b32851d70868eafff8d2edf93b691dfac
+  data.tar.gz: 17aade1f53fe09ab6eec1ca52dc780ce74a2ccdd5d530bc6371f78c0c48246b76fc99f9baa3b9e0d74e67538c9212dd2ffa59d20a30e4a333bbdfe8f9b42a410

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+# v2.0.0
+* Fix sparkle pack usage in nested stacks (#140)
+* Update value processing in attribute helpers for consistent behavior
+* Extraction and isolation of provider specific functionalities (#138)
+* Added provider support for Azure (#138)
+* Added provider support for Heat (#138)
+* Added provider support for Rackspace (#139)
+* Enforce minimum supported Ruby version
+
 # v1.2.0
 * Fix pack registration helper method
 * Provide easy access to Kernel.method (#122)

data/bin/generate_sparkle_docs

@@ -1,18 +1,33 @@
 #!/usr/bin/env ruby
 require 'fileutils'
 
-unless(system("yardoc"))
-  $stderr.puts 'ACK: Failed to create docs!'
-  exit -1
+['yard', 'redcarpet', 'github-markup'].each do |item|
+  begin
+    require item
+  rescue LoadError
+    $stderr.puts "Failed to load required library `#{item}`. To fix: `gem install #{item}` or include within bundle"
+    exit -1
+  end
+end
+
+doc_path = File.join(Dir.pwd, 'doc')
+FileUtils.mkdir_p(doc_path)
+
+Dir.chdir(File.dirname(File.dirname(__FILE__))) do
+  unless(system("yardoc -o #{doc_path}"))
+    $stderr.puts 'Failed to successfully run `yardoc`. Unable to generate documentation!'
+    exit -1
+  end
 end
 
-FileUtils.mkdir_p('doc/UserDocs')
+user_docs_path = File.join(Dir.pwd, 'doc', 'UserDocs')
+FileUtils.mkdir_p(user_docs_path)
 
-Dir.glob('docs/**/*').each do |path|
+Dir.glob(File.join(File.dirname(File.dirname(__FILE__)), 'docs', '**', '*')) do |path|
   next unless File.file?(path)
   content = File.read(path)
   rel_path = path.sub(/.*?docs\//, '')
-  new_path = File.join('doc/UserDocs', rel_path)
+  new_path = File.join(user_docs_path, rel_path)
   user_doc_root = (['..'] * rel_path.scan('/').size).join('/')
   unless(user_doc_root.to_s.empty?)
     user_doc_root << '/'

data/docs/helper-methods.md

@@ -15,8 +15,8 @@ anchors:
     url: "#output-to-stdout"
   - title: "Raise Exceptions"
     url: "#raise-exceptions"
-  - title: "AWS Helpers"
-    url: "#aws-helpers"
+  - title: "Provider specific helpers"
+    url: "#provider-specific-heleprs"
 ---
 
 ## Helper methods
@@ -123,60 +123,37 @@ end
 
 ### Generation Helpers
 
-#### AWS Helpers
+#### Provider specific helpers
 
-Data generation helpers are available for all the AWS
-intrinsic functions and pseudo parameters:
-
-
-##### Base intrinsic functions
-
-* `base64!(VAL)`
-* `find_in_map!(A, B, C)`
-* `attr!(RESOURCE, ATTRIBUTE)`
-* `azs!(REGION)`
-* `join!(VAL1, VAL2, ...)`
-* `select!(INDEX, ITEM)`
-* `ref!(NAME)`
-
-##### Pseudo Parameters
-
-* `account_id!`
-* `notification_arns!`
-* `no_value!`
-* `region!`
-* `stack_id!`
-* `stack_name!`
-
-##### Conditional functions
-
-AWS CFN supports runtime conditions. Helpers for building conditions:
-
-* `and!(VAL1, VAL2, ...)`
-* `equals!(VAL1, VAL2)`
-* `not!(VAL)`
-* `or!(VAL1, VAL2, ...)`
-* `condition!(CONDITION_NAME)`
-
-Helpers for using conditions:
-
-* `if!(CONDITION_NAME)`
+SparkleFormation includes provider specific helpers based on the
+provider defined when instantiating the SparkleFormation template
+instance. For example:
 
 ~~~ruby
-SparkleFormation.new(:test) do
-...
-  some_value if!(:my_condition, TRUE_VALUE, FALSE_VALUE)
-...
+SparkleFormation.new(:my_stack, :provider => :aws) do
+  ...
+  output.instance_id.value ref!(:my_instance)
 end
 ~~~
 
-* `on_condition!(CONDITION_NAME)`
+will make the AWS specific helper functions available within this
+template instance. If the provider specified Azure, then the Azure
+specific helper methods would be available:
 
 ~~~ruby
-SparkleFormation.new(:test) do
-...
-  resources.my_cool_resource do
-    on_condition!(:stack_is_cool)
-...
+SparkleFormation.new(:my_stack, :provider => :azure) do
+  ...
+  outputs.instance_id do
+    type 'string'
+    value reference_id(:my_instance)
+  end
 end
 ~~~
+
+To see all the available helpers for specific providers, refer
+to the library documentation:
+
+* [AWS helpers](http://sparkleformation.github.io/sparkle_formation/SparkleFormation/SparkleAttribute/Aws.html)
+* [Azure helpers](http://sparkleformation.github.io/sparkle_formation/SparkleFormation/SparkleAttribute/Azure.html)
+* [HEAT helpers](http://sparkleformation.github.io/sparkle_formation/SparkleFormation/SparkleAttribute/Heat.html)
+* [Rackspace helpers](http://sparkleformation.github.io/sparkle_formation/SparkleFormation/SparkleAttribute/Rackspace.html)

data/lib/sparkle_formation.rb

@@ -24,8 +24,11 @@ require 'attribute_struct'
 class SparkleFormation
   autoload :Aws, 'sparkle_formation/aws'
   autoload :Error, 'sparkle_formation/error'
+  autoload :FunctionStruct, 'sparkle_formation/function_struct'
+  autoload :Provider, 'sparkle_formation/provider'
   autoload :Resources, 'sparkle_formation/resources'
   autoload :Sparkle, 'sparkle_formation/sparkle'
+  autoload :SparklePack, 'sparkle_formation/sparkle'
   autoload :SparkleCollection, 'sparkle_formation/sparkle_collection'
   autoload :SparkleAttribute, 'sparkle_formation/sparkle_attribute'
   autoload :SparkleStruct, 'sparkle_formation/sparkle_struct'

data/lib/sparkle_formation/error.rb

@@ -16,12 +16,20 @@ class SparkleFormation
         @name = opts[:name] if opts
       end
 
+      # Pack related items
       class Dynamic < NotFound; end
       class Component < NotFound; end
       class Registry < NotFound; end
       class Template < NotFound; end
 
+      # Template internals
+      class Resource < NotFound; end
+
     end
+
+    # Deprecation error
+    class Deprecated < Error; end
+
   end
 
 end

data/lib/sparkle_formation/function_struct.rb

@@ -0,0 +1,123 @@
+require 'sparkle_formation'
+
+class SparkleFormation
+
+  # SparkleFormation customized AttributeStruct targeted at defining
+  # strings of code for remote evaulation
+  class FunctionStruct < AttributeStruct
+
+    # @return [String] name of function
+    attr_reader :_fn_name
+    # @return [Array<Object>] function argument list
+    attr_reader :_fn_args
+
+    # Create a new FunctionStruct instance
+    #
+    # @param f_name [String] name of function
+    # @param args [Array<Object>] argument list
+    # @return [self]
+    def initialize(f_name=nil, *args)
+      super()
+      @_fn_name = f_name.to_s
+      @_fn_args = args
+      @_fn_args.map! do |l_arg|
+        if(l_arg.is_a?(_klass))
+          l_arg = l_arg._root
+          l_arg._parent(self)
+        end
+        l_arg
+      end
+    end
+
+    # @return [False] functions are never nil
+    def nil?
+      false
+    end
+
+    # @return [TrueClass, FalseClass] is root struct
+    def root?
+      _parent.nil?
+    end
+
+    # Override to provide expected behavior when arguments are passed
+    # to a function call
+    #
+    # @param name [String, Symbol] method name
+    # @param args [Object<Array>] argument list
+    # @return [Object]
+    def method_missing(name, *args)
+      if(args.empty?)
+        super
+      else
+        @table['_function_'] = _klass_new(name, *args)
+      end
+    end
+
+    # Set accessor directly into table data
+    #
+    # @param val [Integer, String]
+    # @return [FunctionStruct]
+    def [](val)
+      _set("[#{val}]")
+    end
+
+    # Override of the dump to properly format eval string
+    #
+    # @return [String]
+    def _dump
+      unless(@table.empty?)
+        key, value = @table.first
+        suffix = _eval_join(
+          *[
+            key == '_function_' ? nil : key,
+            !value.nil? ? value._dump : nil
+          ].compact
+        )
+      end
+      if(_fn_name)
+        args = _fn_args.map do |arg|
+          if(arg.respond_to?(:_dump))
+            arg._dump
+          elsif(arg.is_a?(::Symbol))
+            "'#{::Bogo::Utility.camel(arg.to_s, false)}'"
+          elsif(arg.is_a?(::String))
+            "'#{arg}'"
+          else
+            arg.inspect
+          end
+        end.join(', ')
+        internal = _eval_join(
+          *[
+            args.empty? ? _fn_name : "#{_fn_name}(#{args})",
+            suffix
+          ].compact
+        )
+        root? ? "[#{internal}]" : internal
+      else
+        suffix
+      end
+    end
+
+    # Join arguments into a string for remote evaluation
+    #
+    # @param args [Array<String>]
+    # @return [String]
+    def _eval_join(*args)
+      args = args.compact
+      args.delete_if(&:empty?)
+      args.slice(1, args.size).to_a.inject(args.first) do |memo, item|
+        if(item.start_with?('['))
+          memo += item
+        else
+          memo += ".#{item}"
+        end
+      end
+    end
+
+    # @return [Class]
+    def _klass
+      ::SparkleFormation::FunctionStruct
+    end
+
+  end
+end

data/lib/sparkle_formation/provider.rb

@@ -0,0 +1,12 @@
+require 'sparkle_formation'
+
+class SparkleFormation
+  # Provider specific implementation namespace
+  module Provider
+
+    autoload :Aws, 'sparkle_formation/provider/aws'
+    autoload :Azure, 'sparkle_formation/provider/azure'
+    autoload :Heat, 'sparkle_formation/provider/heat'
+
+  end
+end

data/lib/sparkle_formation/provider/aws.rb

@@ -0,0 +1,201 @@
+require 'sparkle_formation'
+
+class SparkleFormation
+  module Provider
+    # AWS specific implementation
+    module Aws
+
+      # @return [String] Type string for AWS CFN stack resource
+      def stack_resource_type
+        'AWS::CloudFormation::Stack'
+      end
+
+      # Generate policy for stack
+      #
+      # @return [Hash]
+      def generate_policy
+        statements = []
+        compile.resources.keys!.each do |r_name|
+          r_object = compile.resources[r_name]
+          if(r_object['Policy'])
+            r_object['Policy'].keys!.each do |effect|
+              statements.push(
+                'Effect' => effect.to_s.capitalize,
+                'Action' => [r_object['Policy'][effect]].flatten.compact.map{|i| "Update:#{i}"},
+                'Resource' => "LogicalResourceId/#{r_name}",
+                'Principal' => '*'
+              )
+            end
+            r_object.delete!('Policy')
+          end
+        end
+        statements.push(
+          'Effect' => 'Allow',
+          'Action' => 'Update:*',
+          'Resource' => '*',
+          'Principal' => '*'
+        )
+        Smash.new('Statement' => statements)
+      end
+
+      # Apply deeply nested stacks. This is the new nesting approach and
+      # does not bubble parameters up to the root stack. Parameters are
+      # isolated to the stack resource itself and output mapping is
+      # automatically applied.
+      #
+      # @yieldparam stack [SparkleFormation] stack instance
+      # @yieldparam resource [AttributeStruct] the stack resource
+      # @yieldparam s_name [String] stack resource name
+      # @yieldreturn [Hash] key/values to be merged into resource properties
+      # @return [Hash] dumped stack
+      def apply_deep_nesting(*args, &block)
+        outputs = collect_outputs
+        nested_stacks(:with_resource).each do |stack, resource|
+          unless(stack.nested_stacks.empty?)
+            stack.apply_deep_nesting(*args)
+          end
+          stack.compile.parameters.keys!.each do |parameter_name|
+            if(output_name = output_matched?(parameter_name, outputs.keys))
+              next if outputs[output_name] == stack
+              stack_output = stack.make_output_available(output_name, outputs)
+              resource.properties.parameters.set!(parameter_name, stack_output)
+            end
+          end
+        end
+        if(block_given?)
+          extract_templates(&block)
+        end
+        compile.dump!
+      end
+
+      # Apply shallow nesting. This style of nesting will bubble
+      # parameters up to the root stack. This type of nesting is the
+      # original and now deprecated, but remains for compat issues so any
+      # existing usage won't be automatically busted.
+      #
+      # @yieldparam resource_name [String] name of stack resource
+      # @yieldparam stack [SparkleFormation] nested stack
+      # @yieldreturn [String] Remote URL storage for template
+      # @return [Hash]
+      def apply_shallow_nesting(*args, &block)
+        parameters = compile[:parameters] ? compile[:parameters]._dump : {}
+        output_map = {}
+        nested_stacks(:with_resource, :with_name).each do |_stack, stack_resource, stack_name|
+          remap_nested_parameters(compile, parameters, stack_name, stack_resource, output_map)
+        end
+        extract_templates(&block)
+        compile.parameters parameters
+        if(args.include?(:bubble_outputs))
+          outputs_hash = Hash[
+            output_map do |name, value|
+              [name, {'Value' => {'Fn::GetAtt' => value}}]
+            end
+          ]
+          if(compile.outputs)
+            compile._merge(compile._klass_new(outputs_hash))
+          else
+            compile.outputs output_hash
+          end
+        end
+        compile.dump!
+      end
+
+      # Extract output to make available for stack parameter usage at the
+      # current depth
+      #
+      # @param output_name [String] name of output
+      # @param outputs [Hash] listing of outputs
+      # @reutrn [Hash] reference to output value (used for setting parameter)
+      def make_output_available(output_name, outputs)
+        bubble_path = outputs[output_name].root_path - root_path
+        drip_path = root_path - outputs[output_name].root_path
+        bubble_path.each_slice(2) do |base_sparkle, ref_sparkle|
+          next unless ref_sparkle
+          base_sparkle.compile.outputs.set!(output_name).set!(
+            :value, base_sparkle.compile.attr!(
+              ref_sparkle.name, "Outputs.#{output_name}"
+            )
+          )
+        end
+        if(bubble_path.empty?)
+          if(drip_path.size == 1)
+            parent = drip_path.first.parent
+            if(parent && parent.compile.parameters.data![output_name])
+              return compile.ref!(output_name)
+            end
+          end
+          raise ArgumentError.new "Failed to detect available bubbling path for output `#{output_name}`. " <<
+            'This may be due to a circular dependency! ' <<
+            "(Output Path: #{outputs[output_name].root_path.map(&:name).join(' > ')} " <<
+            "Requester Path: #{root_path.map(&:name).join(' > ')})"
+        end
+        result = compile.attr!(bubble_path.first.name, "Outputs.#{output_name}")
+        if(drip_path.size > 1)
+          parent = drip_path.first.parent
+          drip_path.unshift(parent) if parent
+          drip_path.each_slice(2) do |base_sparkle, ref_sparkle|
+            next unless ref_sparkle
+            base_sparkle.compile.resources[ref_sparkle.name].properties.parameters.set!(output_name, result)
+            ref_sparkle.compile.parameters.set!(output_name){ type 'String' } # TODO: <<<<------ type check and prop
+            result = compile.ref!(output_name)
+          end
+        end
+        result
+      end
+
+      # Extract parameters from nested stacks. Check for previous nested
+      # stack outputs that match parameter. If match, set parameter to use
+      # output. If no match, check container stack parameters for match.
+      # If match, set to use ref. If no match, add parameter to container
+      # stack parameters and set to use ref.
+      #
+      # @param template [Hash] template being processed
+      # @param parameters [Hash] top level parameter set being built
+      # @param stack_name [String] name of stack resource
+      # @param stack_resource [Hash] duplicate of stack resource contents
+      # @param output_map [Hash] mapping of output names to required stack output access
+      # @return [TrueClass]
+      # @note if parameter has includes `StackUnique` a new parameter will
+      #   be added to container stack and it will not use outputs
+      def remap_nested_parameters(template, parameters, stack_name, stack_resource, output_map)
+        stack_parameters = stack_resource.properties.stack.compile.parameters
+        unless(stack_parameters.nil?)
+          stack_parameters._dump.each do |pname, pval|
+            if(pval['StackUnique'])
+              check_name = [stack_name, pname].join
+            else
+              check_name = pname
+            end
+            if(parameters.keys.include?(check_name))
+              if(parameters[check_name]['Type'] == 'CommaDelimitedList')
+                new_val = {'Fn::Join' => [',', {'Ref' => check_name}]}
+              else
+                new_val = {'Ref' => check_name}
+              end
+              template.resources.set!(stack_name).properties.parameters.set!(pname, new_val)
+            elsif(output_map[check_name])
+              template.resources.set!(stack_name).properties.parameters.set!(
+                pname, 'Fn::GetAtt' => output_map[check_name]
+              )
+            else
+              if(pval['Type'] == 'CommaDelimitedList')
+                new_val = {'Fn::Join' => [',', {'Ref' => check_name}]}
+              else
+                new_val = {'Ref' => check_name}
+              end
+              template.resources.set!(stack_name).properties.parameters.set!(pname, new_val)
+              parameters[check_name] = pval
+            end
+          end
+        end
+        unless(stack_resource.properties.stack.compile.outputs.nil?)
+          stack_resource.properties.stack.compile.outputs.keys!.each do |oname|
+            output_map[oname] = [stack_name, "Outputs.#{oname}"]
+          end
+        end
+        true
+      end
+
+    end
+  end
+end