sparkle_formation 1.0.4 → 1.1.0

data/docs/sparkleformation-dsl.md

@@ -0,0 +1,303 @@
+---
+title: "SparkleFormation DSL"
+category: "dsl"
+weight: 2
+anchors:
+  - title: "Behavior"
+    url: "#behavior"
+  - title: "Key Alteration"
+    url: "#key-alteration"
+  - title: "Data Access"
+    url: "#data-access"
+---
+
+## SparkleFormation DSL
+
+The SparkleFormation DSL (domain specific language) is based
+on (and built on top of) the [AttributeStruct](https://github.com/chrisroberts/attribute_struct)
+library. This provides SparkleFormation with its free-form behavior
+and allows immediate support of any template style or API
+updates requiring modifications to existing templates.
+
+For a closer look at the underlying features provided by
+the AttributeStruct library, please refer to the
+[AttributeStruct documentation](https://chrisroberts.github.io/attribute_struct).
+
+### Behavior
+
+The behavior of the SparkleFormation DSL is largely dictated by the
+AttributeStruct library, and as such are not specific to SparkleFormation
+alone. Some optional features of the AttributeStruct library are automatically
+enabled when using SparkleFormation, most notably the automatic camel casing
+of key values.
+
+#### Key Alteration
+
+The default behavior of SparkleFormation is to camel case all Hash keys.
+This is done via:
+
+~~~ruby
+AttributeStruct.camel_keys = true
+~~~
+
+And results in all Hash keys in the resultant compile Hash being converted
+to a camel cased format:
+
+~~~ruby
+SparkleFormation.new(:test) do
+  parameters.creator.default 'spox'
+end
+~~~
+
+The resultant data structure after compiling:
+
+~~~ruby
+{
+  "Parameters": {
+    "Creator": {
+      "Default": "spox"
+    }
+  }
+}
+~~~
+
+In some cases it may be desired to have a key _not_
+be automatically camel cased. Camel casing can be
+disabled via a helper method that is attached to the
+Symbol and String instances:
+
+~~~ruby
+SparkleFormation.new(:test) do
+  parameters.set!(:creator.disable_camel!).default 'spox'
+end
+~~~
+
+The resultant data structure after compiling:
+
+~~~ruby
+{
+  "Parameters": {
+    "creator": {
+      "Default": "spox"
+    }
+  }
+}
+~~~
+
+Depending on the formatting of the target template there
+may be lack of consistency within certain locations. A
+classic example of this inconsistency can be seen in the
+`AWS::CloudFormation::Init` metadata section on compute
+type resources. Within the context of this `Init` section
+the format of the keys change from the standard camel casing
+to a snake cased format. It is possible to handle this by using
+the `disable_camel!` method for all defined keys, but it is
+clunky and reduces the readability of the code.
+
+As the data structure is built when compiling the SparkleFormation
+template state is tracked at each "level" of the data structure.
+When the camel casing is enabled on AttributeStruct, this is merely
+the default behavior and can be overridden, even from within
+the DSL. For example:
+
+~~~ruby
+SparkleFormation.new(:test) do
+  parameters do
+    camel_keys_set!(:auto_disable)
+    creator.default 'spox'
+  end
+  outputs.creator.value ref!(:creator.disable_camel!)
+end
+~~~
+
+The resultant data structure after compiling:
+
+~~~ruby
+{
+  "Parameters": {
+    "creator": {
+      "default": "spox"
+    }
+  },
+  "Outputs": {
+    "Value": {
+      "Ref": "creator"
+    }
+  }
+}
+~~~
+
+This example shows how the behavior of the Hash key modification
+can be altered at a specific context within the data structure.
+New values added (as well as nested) will not the camel casing
+modification applied. The behavior can be adjusted at multiple
+depth locations, and that behavior will persist on re-entry:
+
+~~~ruby
+SparkleFormation.new(:test) do
+  parameters do
+    camel_keys_set!(:auto_disable)
+    creator do
+      camel_keys_set!(:auto_enable)
+      default 'spox'
+    end
+  end
+  outputs.creator.value ref!(:creator.disable_camel!)
+  parameters.creator.type 'String'
+  parameters.author.default 'John Doe'
+end
+~~~
+
+The resultant data structure after compiling:
+
+~~~ruby
+{
+  "Parameters": {
+    "creator": {
+      "Default": "spox",
+      "Type": "String"
+    },
+    "author": {
+      "default": "John Doe"
+    }
+  },
+  "Outputs": {
+    "Value": {
+      "Ref": "creator"
+    }
+  }
+}
+~~~
+
+### Features
+
+#### Data Access
+
+As a SparkleFormation template is compiled it is dynamically
+building the data structure defined by the template. Because
+this data structure is being generated during compilation, the
+template itself has access to this data and can inspect the
+state of the data structure as it exists _at that specific
+time_. This allows for inspecting previously defined data
+and using that data for decision making, or to copy/modify into
+other locations.
+
+##### Local Context Data
+
+When using block style syntax in the DSL an optional parameter
+can be defined for the block. If provided, AttributeStruct will
+pass the local AttributeStruct instance to the block when it
+is executed:
+
+~~~ruby
+SparkleFormation.new(:test) do
+  parameters.creator.default 'spox'
+  parameters do |params|
+    author.default params.creator.default
+  end
+end
+~~~
+
+The resultant data structure after compiling:
+
+~~~ruby
+{
+  "Parameters": {
+    "Creator": {
+      "Default": "spox"
+    },
+    "Author": {
+      "Default": "spox"
+    }
+  }
+}
+~~~
+
+##### Parent Context Data
+
+It is possible to access the parent context data from the current
+context:
+
+~~~ruby
+SparkleFormation.new(:test) do
+  parameters.creator.default 'spox'
+  parameters.author do
+    default parent!.creator.default
+  end
+end
+~~~
+
+The resultant data structure after compiling:
+
+~~~ruby
+{
+  "Parameters": {
+    "Creator": {
+      "Default": "spox"
+    },
+    "Author": {
+      "Default": "spox"
+    }
+  }
+}
+~~~
+
+
+##### Root Context Data
+
+It is possible to access the root context data from the current
+context:
+
+~~~ruby
+SparkleFormation.new(:test) do
+  parameters.creator.default 'spox'
+  parameters.author.default root!.parameters.creator.default
+end
+~~~
+
+The resultant data structure after compiling:
+
+~~~ruby
+{
+  "Parameters": {
+    "Creator": {
+      "Default": "spox"
+    },
+    "Author": {
+      "Default": "spox"
+    }
+  }
+}
+~~~
+
+##### Raw Access
+
+The raw Hash instance holding the data of the current context
+can be reached using the `data!` method:
+
+~~~ruby
+SparkleFormation.new(:test) do
+  parameters.creator.default 'spox'
+  if(data!['Creator'].default == 'spox')
+    parameters.author.default 'xops'
+  end
+end
+~~~
+
+The resultant data structure after compiling:
+
+~~~ruby
+{
+  "Parameters": {
+    "Creator": {
+      "Default": "spox"
+    },
+    "Author": {
+      "Default": "xops"
+    }
+  }
+}
+~~~
+
+> NOTE: Because `data!` returns a Hash instance, no automatic formatting
+> (camel case conversions) will be applied to keys when accessing values.

data/docs/stack-policies.md

@@ -0,0 +1,90 @@
+---
+title: "Stack Policies"
+category: "dsl"
+weight: 8
+anchors:
+  - title: "Template Usage"
+    url: "#template-usage"
+  - title: "Library Usage"
+    url: "#library-usage"
+---
+
+## Stack Policies
+
+AWS CloudFormation includes support for stack policies. These
+policies add an extra layer of control that restricts or allows
+actions to be taken on specific resources within a stack.
+SparkleFormation includes support for extracting inline stack
+policy information from SparkleFormation templates which can
+then be applied to stacks.
+
+* [AWS CFN Stack Policies](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/protect-stack-resources.html)
+
+### Template Usage
+
+Resource policies can be defined within a SparkleFormation
+template. This allows for policies to be programatically generated
+in the same manner as the stack template itself.
+
+~~~ruby
+template = SparkleFormation.new(:test) do
+  resources.my_resource do
+    policy do
+      allow 'Modify'
+      deny 'Replace'
+    end
+  end
+end
+~~~
+
+### Library Usage
+
+SparkleFormation can extract stack policies from a template after
+it has been compiled. Once extracted, the policy can be applied
+to the stack as dictated by the API.
+
+~~~ruby
+template = SparkleFormation.new(:test) do
+  resources.my_resource do
+    policy do
+      allow 'Modify'
+      deny 'Replace'
+    end
+  end
+end
+
+policy = template.generate_policy
+~~~
+
+This generates a policy data structure:
+
+~~~ruby
+{
+  "Statement" => [
+    {
+      "Effect" => "Allow",
+      "Action" => [
+        "Update:*"
+      ],
+      "Resource" => "*",
+      "Principal" => "*"
+    },
+    {
+      "Effect" => "Allow",
+      "Action" => [
+        "Update:Modify"
+      ],
+      "Resource" => "LogicalResourceId/MyResource",
+      "Principal" => "*"
+    },
+    {
+      "Effect" => "Deny",
+      "Action" => [
+        "Update:Replace"
+      ],
+      "Resource" => "LogicalResourceId/MyResource",
+      "Principal" => "*"
+    }
+  ]
+}
+~~~

data/docs/translation.md

@@ -0,0 +1,64 @@
+---
+title: "Translation"
+category: "dsl"
+weight: 9
+anchors:
+  - title: "Supported Translations"
+    url: "#supported-translations"
+  - title: "Usage"
+    url: "#usage"
+---
+
+## Translation
+
+SparkleFormation has alpha support for template translation from
+AWS CFN to target orchestration API template formats.
+
+> NOTE: Translations do not currently support stack nesting functionality
+
+### Supported Translations
+
+Basic support implementations:
+
+* OpenStack
+* Rackspace
+
+### Usage
+
+Translations are based around AWS CFN and then target some
+remote orchestration API (currently Heat and Rackspace). First
+the template must be compiled, then it is passed to the translator
+which converts the CFN specific template to the expected format
+of the target API:
+
+~~~ruby
+sfn = SparkleFormation.new(:my_stack) do
+  ...
+end
+
+cfn_template = sfn.compile.dump!
+translator = SparkleFormation::Translation::Heat.new(cfn_template)
+
+heat_template = translator.translate!
+~~~
+
+In general applications of translators, the implementation will
+first collect optional template parameters prior to translation
+allowing the translator access to parameters that may be required
+in places where the resultant template may not have support for
+dynamic references. These can then be passed to the translator:
+
+~~~ruby
+sfn = SparkleFormation.new(:my_stack) do
+  ...
+end
+
+cfn_template = sfn.compile.dump!
+custom_params = collect_parameters(cfn_template)
+translator = SparkleFormation::Translation::Heat.new(
+  cfn_template,
+  :parameters => custom_params
+)
+
+heat_template = translator.translate!
+~~~