sparkle_formation 2.1.8 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9afdab094c6cd47a509662f18ad290fc743d2ee9
-  data.tar.gz: 20e9e353dae5fa25db4b3415b33622bac16058f8
+  metadata.gz: 1d032f4e99137cc1d2cedff18a9d3cd1d9ed3ffc
+  data.tar.gz: ef8783a42ab4ac91f344db64ee884ec3a568d616
 SHA512:
-  metadata.gz: fe65169a0f63eca6043542891a2f44b90935cd243d2ec56d7fc5b04ca6ad9f18796aa9d11f2d47d8800e9253126121111b9741b38ec6d8885a1b1653e2914312
-  data.tar.gz: 3ad051b35500b4f0782f3e5d41a39b9b1c79fa1efaf76b70eaf4776ce1dd3d00d8c9c12b41aed4ebaada43dfa6bc368895e839b5a1bd4bd91f84140d8628d6aa
+  metadata.gz: 015d1daa74bb173669757e8e88d41f3e43009d6f046668c0f9a45bea175be16743a9007001136172a1e39b6d7f6ab6ba82b1eacf776f0b286c129ac4babc068b
+  data.tar.gz: c43367d2255f83fedc4861303bff7be56349dd636017de2a60e0ccc1c3537e90ac6eb1980ce1f357e6035a072fb4c22de7f2db2d10eef8213caeb16d6ba8cf4e

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+# v3.0.0
+_Major release includes breaking changes!_
+* Builtin provider resources updates (#163)
+ * New Resource and Propery types
+ * Support for conditional logic to determine property modification effect
+* New provider Google (#167)
+* Inject nested stacks using dynamic style insertion (#167)
+* Add sparkle aliases for dumps to allow non-provider formatted template dumps (#167)
+* Allow sparkle pack to load as empty pack (#167)
+* Generate nested stack resource name using key processing style of current context (#167)
+* SparkleFormation#apply_nesting now returns compiled structure not Hash (#167)
+* SparkleFormation#stack_template_extractor now sets compiled structure not Hash (#167)
+* Remove helper method aliasing in Azure module to work on Ruby 2.3 (#170)
+* Implement provider restrictions and naming uniqueness (#169)
+
+_NOTE: If using non-AWS provider, files must be updated to include `:provider` flag._
+
 # v2.1.8
 * Add support for CFN list type with shallow nesting (#150)
 * Fix deprecation warnings on Ruby 2.3 caused by TimeoutError constant

data/docs/README.md

@@ -22,6 +22,7 @@
   - [Nested Stacks](nested-stacks.md)
     - [Shallow Nesting](nested-stacks.md#shallow-nesting)
     - [Deep Nesting](nested-stacks.md#deep-nesting)
+  - [Provider Restrictions](provider-restrictions.md)
   - [Sparkle Packs](sparkle-packs.md)
   - [Stack Policies](stack-policies.md)
   - [Translation](translation.md)

data/docs/helper-methods.md

@@ -155,5 +155,6 @@ 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)
+* [Google helpers](http://sparkleformation.github.io/sparkle_formation/SparkleFormation/SparkleAttribute/Google.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/docs/provider-restrictions.md

@@ -0,0 +1,174 @@
+---
+title: "Provider Restrictions"
+category: "dsl"
+weight: 9
+anchors:
+  - title: "Provider Restrictions"
+    url: "#provider-restrictions"
+  - title: "Setting Provider Restrictions"
+    url: "#setting-provider-restrictions"
+  - title: "Building Block Uniqueness"
+    url: "#building-block-uniqueness"
+  - title: "Sharing Building Blocks"
+    url: "#sharing-building-blocks"
+---
+
+## Provider Restrictions
+
+SparkleFormation supports generating templates for multiple
+orchestration APIs. By default all building blocks are assigned
+`:aws` as a provider. As a template is compiled and building
+block items are requested, the provider restriction is enforced
+during lookup. This restriction helps to enforce correctly structured
+template by only allowing building blocks with like providers to
+interact with each other ensuring a properly compiled template.
+
+## Setting Provider Restriction
+
+Provider restrictions are set using a common pattern among all
+building blocks:
+
+### Template
+
+~~~ruby
+SparkleFormation.new(:my_template, :provider => :azure) do
+  ...
+~~~
+
+### Component
+
+~~~ruby
+SparkleFormation.component(:my_component, :provider => :azure) do
+  ...
+~~~
+
+### Dynamic
+
+~~~ruby
+SparkleFormation.dynamic(:my_dynamic, :provider => :azure) do
+  ...
+~~~
+
+### Registry
+
+~~~ruby
+SfnRegistry.register(:my_item, :provider => :azure) do
+  ...
+~~~
+
+## Building Block Uniqueness
+
+### Name Collision Failure
+
+The uniqueness of a building block is based on the combination of
+the building block's name and defined provider. This allows common
+naming schemes to be applied for multiple providers within the same
+runtime. For example, given a template named `:network` defined
+as:
+
+~~~ruby
+SparkleFormation.new(:network) do
+  ...
+~~~
+
+the uniqueness of this template is defined by `:network` within
+the `:aws` provider (because the `:aws` provider is the default). This
+means that defining another template with the provider explicitly defined
+for `:aws` will fail:
+
+~~~ruby
+SparkleFormation.new(:network, :provider => :aws) do
+  ...
+~~~
+
+The failure is due to the fact that the names of these two templates is
+effectively equivalent.
+
+### Common Name Unique Provider
+
+Using the previous example of a `:network` template, we can define our
+template and explicitly set the provider for clarity:
+
+~~~ruby
+SparkleFormation.new(:network, :provider => :aws) do
+  ...
+~~~
+
+Now if we want to provide a template for a different provider (OpenStack
+for instance) we can use the same template name but specify a different
+target provider:
+
+~~~ruby
+SparkleFormation.new(:network, :provider => :heat) do
+  ...
+~~~
+
+Two templates with a common name (`:network`) now exist within our runtime
+because while the name is common, the providers are different. This functionality
+applies to all the SparkleFormation building blocks and is important for allowing
+a common interface for user interactions while allowing provider specific implementations.
+
+## Sharing Building Blocks
+
+Building blocks may not always need to be restricted to a specific provider. The
+provider value used for building block lookup can be overridden. Using this
+override functionality allows for sharing building blocks between providers. For
+example, lets define a pseudo-template for AWS that sets a value using a registry
+item:
+
+~~~ruby
+SfnRegistry.register(:creator) do
+  'spox'
+end
+~~~
+
+~~~ruby
+SparkleFormation.new(:template) do
+  owner registry!(:creator)
+end
+~~~
+
+Now if the same pseudo-template with a provider set to `:azure` is defined:
+
+~~~ruby
+SparkleFormation.new(:template, :provider => :azure) do
+  owner registry!(:creator)
+end
+~~~
+
+it will fail. The failure is due to the implicitly set provider (`:aws`) on the registry
+item. To allow sharing of the registry item, we _can_ override the lookup to use
+`:aws` as the provider:
+
+~~~ruby
+SparkleFormation.new(:template, :provider => :azure) do
+  owner registry!(:creator, :provider => :aws)
+end
+~~~
+
+but this doesn't make logical sense within the layout as the registry item itself
+isn't restricted to the AWS provider in any way. A better approach would be defining
+a shared provider and using that value for the override. Refactoring would provide
+a registry item:
+
+~~~ruby
+SfnRegistry.register(:creator, :provider => :shared) do
+  'spox'
+end
+~~~
+
+With the provider set, the two templates can now be updated to use the override:
+
+~~~ruby
+SparkleFormation.new(:template) do
+  owner registry!(:creator, :provider => :shared)
+end
+~~~
+
+and:
+
+~~~ruby
+SparkleFormation.new(:template, :provider => :azure) do
+  owner registry!(:creator, :provider => :shared)
+end
+~~~

data/docs/translation.md

@@ -9,6 +9,9 @@ anchors:
     url: "#usage"
 ---
 
+_WARNING: Translations of templates between providers is no longer
+being actively developed._
+
 ## Translation
 
 SparkleFormation has alpha support for template translation from

data/lib/sparkle_formation.rb

@@ -26,6 +26,9 @@ class SparkleFormation
   autoload :Composition, 'sparkle_formation/composition'
   autoload :Error, 'sparkle_formation/error'
   autoload :FunctionStruct, 'sparkle_formation/function_struct'
+  autoload :GoogleStruct, 'sparkle_formation/function_struct'
+  autoload :JinjaExpressionStruct, 'sparkle_formation/function_struct'
+  autoload :JinjaStatementStruct, 'sparkle_formation/function_struct'
   autoload :Provider, 'sparkle_formation/provider'
   autoload :Resources, 'sparkle_formation/resources'
   autoload :Sparkle, 'sparkle_formation/sparkle'

data/lib/sparkle_formation/function_struct.rb

@@ -58,7 +58,11 @@ class SparkleFormation
     # @param val [Integer, String]
     # @return [FunctionStruct]
     def [](val)
-      _set("[#{val}]")
+      if(val.is_a?(::String) && __single_quote_strings)
+        _set("['#{val}']")
+      else
+        _set("[#{val.inspect}]")
+      end
     end
 
     # Override of the dump to properly format eval string
@@ -80,14 +84,14 @@ class SparkleFormation
             arg._dump
           elsif(arg.is_a?(::Symbol))
             "'#{::Bogo::Utility.camel(arg.to_s, false)}'"
-          elsif(arg.is_a?(::String))
+          elsif(arg.is_a?(::String) && __single_quote_strings)
             "'#{arg}'"
           else
             arg.inspect
           end
         end.join(', ')
         unless(_fn_name.to_s.empty?)
-          function_name = args.empty? ? "#{_fn_name}()" : "#{_fn_name}(#{args})"
+          function_name = args.empty? ? "#{_fn_name}#{__empty_argument_list}" : "#{_fn_name}(#{args})"
         end
         internal = _eval_join(
           *[
@@ -95,7 +99,7 @@ class SparkleFormation
             suffix
           ].compact
         )
-        root? ? "[#{internal}]" : internal
+        root? ? "#{__anchor_start}#{internal}#{__anchor_stop}" : internal
       else
         suffix
       end
@@ -122,5 +126,129 @@ class SparkleFormation
       ::SparkleFormation::FunctionStruct
     end
 
+    # @return [String] start character(s) used to anchor function call
+    def __anchor_start
+      '['
+    end
+
+    # @return [String] stop character(s) used to anchor function call
+    def __anchor_stop
+      ']'
+    end
+
+    # @return [String] value to use when argument list is empty
+    def __empty_argument_list
+      '()'
+    end
+
+    # @return [String] dump from root
+    def to_s
+      _root._dump
+    end
+
+    # @return [String] dump from root
+    def inspect
+      _root._dump
+    end
+
+    # @return [TrueClass] enable single quote string generation
+    def __single_quote_strings
+      true
+    end
+
+  end
+
+  # FunctionStruct for jinja expressions
+  class JinjaExpressionStruct < FunctionStruct
+
+    SINGLE_QUOTE_STRINGS = false
+
+    # @return [String] start character(s) used to anchor function call
+    def __anchor_start
+      '{{ '
+    end
+
+    # @return [String] stop character(s) used to anchor function call
+    def __anchor_stop
+      ' }}'
+    end
+
+    # @return [String] value to use when argument list is empty
+    def __empty_argument_list
+      ''
+    end
+
+    # @return [FalseClass] disable single quote string generation
+    def __single_quote_strings
+      false
+    end
+
+    # @return [Class]
+    def _klass
+      ::SparkleFormation::JinjaExpressionStruct
+    end
+
+  end
+
+  # FunctionStruct for jinja statements
+  class JinjaStatementStruct < FunctionStruct
+
+    SINGLE_QUOTE_STRINGS = false
+
+    # @return [String] start character(s) used to anchor function call
+    def __anchor_start
+      '{% '
+    end
+
+    # @return [String] stop character(s) used to anchor function call
+    def __anchor_stop
+      ' %}'
+    end
+
+    # @return [String] value to use when argument list is empty
+    def __empty_argument_list
+      ''
+    end
+
+    # @return [FalseClass] disable single quote string generation
+    def __single_quote_strings
+      false
+    end
+
+    # @return [Class]
+    def _klass
+      ::SparkleFormation::JinjaStatementStruct
+    end
+
+  end
+
+  # FunctionStruct for customized google functions
+  class GoogleStruct < FunctionStruct
+
+    # @return [String] start character(s) used to anchor function call
+    def __anchor_start
+      '$('
+    end
+
+    # @return [String] stop character(s) used to anchor function call
+    def __anchor_stop
+      ')'
+    end
+
+    # @return [String] value to use when argument list is empty
+    def __empty_argument_list
+      ''
+    end
+
+    # @return [FalseClass] disable single quote string generation
+    def __single_quote_strings
+      false
+    end
+
+    # @return [Class]
+    def _klass
+      ::SparkleFormation::GoogleStruct
+    end
+
   end
 end

data/lib/sparkle_formation/provider.rb

@@ -6,6 +6,7 @@ class SparkleFormation
 
     autoload :Aws, 'sparkle_formation/provider/aws'
     autoload :Azure, 'sparkle_formation/provider/azure'
+    autoload :Google, 'sparkle_formation/provider/google'
     autoload :Heat, 'sparkle_formation/provider/heat'
 
   end

data/lib/sparkle_formation/provider/aws.rb

@@ -47,7 +47,7 @@ class SparkleFormation
       # @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
+      # @return [SparkleFormation::SparkleStruct] compiled structure
       def apply_deep_nesting(*args, &block)
         outputs = collect_outputs
         nested_stacks(:with_resource).each do |stack, resource|
@@ -65,7 +65,7 @@ class SparkleFormation
         if(block_given?)
           extract_templates(&block)
         end
-        compile.dump!
+        compile
       end
 
       # Apply shallow nesting. This style of nesting will bubble
@@ -76,7 +76,7 @@ class SparkleFormation
       # @yieldparam resource_name [String] name of stack resource
       # @yieldparam stack [SparkleFormation] nested stack
       # @yieldreturn [String] Remote URL storage for template
-      # @return [Hash]
+      # @return [SparkleFormation::SparkleStruct] compiled structure
       def apply_shallow_nesting(*args, &block)
         parameters = compile[:parameters] ? compile[:parameters]._dump : {}
         output_map = {}
@@ -97,7 +97,7 @@ class SparkleFormation
             compile.outputs output_hash
           end
         end
-        compile.dump!
+        compile
       end
 
       # Extract output to make available for stack parameter usage at the