sparkle_formation 1.0.4 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5a7ac537659ebf74662bbcfff4803d88c1dedfc8
-  data.tar.gz: f87846f1473c7b2557121b125243829dad134edd
+  metadata.gz: 607eb52a5d461c5cf623e017888bb5dc113a3c7e
+  data.tar.gz: 45401a5dabb03744b24777538a9548a8ea0e06f0
 SHA512:
-  metadata.gz: 8710305f6ca7f5e96e987c87c2896451641d3a9469f5c0d3c1bb1a283b6c7ed1a09759979d014fd447862c689eb815b870ac7462d4c10a106b1659623eb8e7b3
-  data.tar.gz: 903bbd84d290e38b3273858dd16260e866c95a62085d4d12441c6b6ff007b1412f18f421ccd03d12d22398f878a39527943458893db0ef1f7f24e33550a7a857
+  metadata.gz: 565402fe9c3256b0ddcd028c4a1244350796d46d951c97d214f2d97ee7d532709b05654fb26f4a3b503e7316577d7745258f5944d7c2a07b6c1f362c838c6176
+  data.tar.gz: fe0d0a5f94ddaf1b5eac0a68840b980fb82990ccb388630ed9723c4e4ea10e9e88810767128b974824d28014e6289f06033c7628c213e1d5155e79dadc8f94ed

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## v1.1.0
+* Add support for compile time parameters
+* Fix usage of deprecated `SparkleFormation.insert` method
+* Propagate parent stack parameter when output required output is in parent stack
+
 ## v1.0.4
 * Fixes on testing (#66 #67 #68 thanks @matschaffer)
 * Properly handle JSON templates within packs (#72)

data/docs/README.md

@@ -0,0 +1,28 @@
+## Table of Contents
+
+- [Getting Started](overview.md#getting-started)
+  - [Installation](overview.md#installation)
+- [The DSL](sparkleformation-dsl.md)
+  - [Behavior](sparkleformation-dsl.md#behavior)
+  - [Features](sparkleformation-dsl.md#features)
+- [Building Blocks](building-blocks.md)
+  - [Components](building-blocks.md#components)
+  - [Dynamics](building-blocks.md#dynamics)
+  - [Registry](building-blocks.md#registry)
+  - [Templates](building-blocks.md#templates)
+- [Template Anatomy](anatomy.md)
+  - [Base Attributes](anatomy.md#base-attributes)
+  - [Parameters](anatomy.md#parameters)
+  - [Mappings](anatomy.md#mappings)
+  - [Conditions](anatomy.md#conditions)
+  - [Resources](anatomy.md#resources)
+  - [Outputs](anatomy.md#outputs)
+- Library Features
+  - [Helper Methods](helper-methods.md)
+  - [Nested Stacks](nested-stacks.md)
+    - [Shallow Nesting](nested-stacks.md#shallow-nesting)
+    - [Deep Nesting](nested-stacks.md#deep-nesting)
+  - [Sparkle Packs](sparkle-packs.md)
+  - [Stack Policies](stack-policies.md)
+  - [Translation](translation.md)
+  - [Compile Time Parameters](compile-time-parameters.md)

data/docs/anatomy.md

@@ -0,0 +1,205 @@
+---
+title: "Template Anatomy"
+category: "dsl"
+weight: 4
+anchors:
+  - title: "Parameters"
+    url: "#parameters"
+  - title: "Mappings"
+    url: "#mappings"
+  - title: "Conditions"
+    url: "#conditions"
+  - title: "Resources"
+    url: "#resources"
+  - title: "Outputs"
+    url: "#outputs"  
+---
+
+## Template Anatomy
+
+The anatomy of a template is dependent on the specific implementation that is
+targeted. Due to the freeform nature of the SparkleFormation DSL any orchestration
+API accepting a serialized document to describe resources is inherently supported.
+Due to that fact, this document will focus directly on the AWS CloudFormation
+style template as it is the most widely implemented.
+
+### AWS CloudFormation in SparkleFormation
+
+- [Base Attributes](#base-attributes)
+- [Parameters](#parameters)
+- [Mappings](#mappings)
+- [Conditions](#conditions)
+- [Resources](#resources)
+- [Outputs](#outputs)
+
+#### Base Attributes
+
+All templates must begin with the expected API version and may include a description
+and or metadata:
+
+~~~ruby
+SparkleFormation.new(:template) do
+  set!('AWSTemplateFormatVersion', '2010-09-09')
+  description 'My New Stack'
+  metadata.instances.description 'Awesome instances'
+end
+~~~
+
+* [Format Version](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/format-version-structure.html)
+* [Description](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-description-structure.html)
+* [Metadata](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/metadata-section-structure.html)
+
+#### Parameters
+
+Parameters are named variables available within the template that users may
+provide customized values when creating or updating a stack. This allows
+"runtime" modifications to occur when the template is evaluated by the API.
+
+~~~ruby
+SparkleFormation.new(:template) do
+  parameters do
+    creator do
+      type 'String'
+      default ENV['USER']
+    end
+  end
+end
+~~~
+
+* [Parameters](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html)
+
+#### Mappings
+
+Mappings are a nested key/value store. They provide an easy way to dynamically
+specify what value should be used based on context available when the template
+is evaluated by the API.
+
+~~~ruby
+SparkleFormation.new(:template) do
+  mappings.platforms.set!('us-west-2'._no_hump) do
+    centos6 'ami-b6bdde86'
+    centos7 'ami-c7d092f7'
+  end
+end
+~~~
+
+These can then be referenced using the `map!` helper method:
+
+~~~ruby
+SparkleFormation.new(:template) do
+  dynamic!(:ec2_instance, :foobar) do
+    properties.image_id map!(:platforms, region!, :centos7)
+  end
+end
+~~~
+
+* [Mappings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/mappings-section-structure.html)
+* [Fn::FindInMap](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-findinmap.html)
+
+#### Conditions
+
+Named conditions are defined in this section and then referenced
+elsewhere in the template. Conditions can be used to customize resource
+properties values or to allow/restrict the creation of resources and
+outputs.
+
+
+~~~ruby
+SparkleFormation.new(:template) do
+  parameters.creator do
+    type 'String'
+    default 'spox'
+  end
+  conditions do
+    creator_is_spox equals!(ref!(:creator), 'spox')
+  end
+end
+~~~
+
+This condition can then be used to provide a custom value for a property:
+
+~~~ruby
+SparkleFormation.new(:template) do
+  parameters.creator do
+    type 'String'
+    default 'spox'
+  end
+  conditions do
+    creator_is_spox equals!(ref!(:creator), 'spox')
+  end
+  dynamic!(:ec2_instance, :fubar).properties do
+    key_name if!(:creator_is_spox, 'spox-key', 'default')
+  end
+end
+~~~
+
+The condition can also be used to restrict the creation of a resource:
+
+~~~ruby
+SparkleFormation.new(:template) do
+  parameters.creator do
+    type 'String'
+    default 'spox'
+  end
+  conditions do
+    creator_is_spox equals!(ref!(:creator), 'spox')
+  end
+  dynamic!(:ec2_instance, :fubar) do
+    on_condition :creator_is_spox
+  end
+end
+~~~
+
+* [Conditions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/conditions-section-structure.html)
+* [Condition Functions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-conditions.html)
+
+#### Resources
+
+Resources are the infrastructure items and configurations to be
+provisioned by the orchestration API:
+
+~~~ruby
+SparkleFormation.new(:template) do
+  resources.my_instance do
+    type 'AWS::EC2::Instance'
+    properties do
+      key_name 'default'
+      ...
+    end
+  end
+end
+~~~
+
+* [Resources](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resources-section-structure.html)
+
+#### Outputs
+
+Outputs are resultant values from the provisioned infrastructure stack.
+It generally contains information about specific resource attributes.
+
+~~~ruby
+SparkleFormation.new(:template) do
+  outputs do
+    instance_address do
+      description 'Public IP of my instance'
+      value attr!(:my_instance, :public_ip)
+    end
+  end
+end
+~~~
+
+Conditions can also be applied on outputs:
+
+~~~ruby
+SparkleFormation.new(:template) do
+  outputs do
+    instance_address do
+      description 'Public IP of my instance'
+      value attr!(:my_instance, :public_ip)
+      on_condition! :my_condition
+    end
+  end
+end
+~~~
+
+* [Outputs](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resources-section-structure.html)

data/docs/building-blocks.md

@@ -0,0 +1,360 @@
+---
+title: "SparkleFormation Building Blocks"
+category: "dsl"
+weight: 3
+anchors:
+  - title: "Components"
+    url: "#components"
+  - title: "Dynamics"
+    url: "#dynamics"
+  - title: "Registry"
+    url: "#registry"
+  - title: "Templates"
+    url: "#templates"
+---
+
+## SparkleFormation Building Blocks
+
+### Building Blocks
+
+SparkleFormation provides a collection of building blocks to
+assist in applying [DRY][1] concepts to template generation. The
+building blocks provided by SparkleFormation are:
+
+- [Components](#components)
+- [Dynamics](#dynamics)
+- [Registry](#registry)
+- [Templates](#templates)
+
+### Components
+
+Components are static pieces of template that are inserted once.
+They do not provide any dynamic functionality and are intended
+for common static content. Components are the second set of items
+loaded during template compilation and are evaluated in the order
+defined.
+
+An example component for an AWS CloudFormation based implementation
+may contain the template versioning information and a common stack
+output value:
+
+~~~ruby
+SparkleFormation.component(:common) do
+  set!('AWSTemplateFormatVersion', '2010-09-09')
+
+  outputs.creator do
+    description 'Stack creator'
+    value ENV['USER']
+  end
+end
+~~~
+
+There are two supported ways of creating components:
+
+* Path based components
+* Name based components
+
+#### Path based components
+
+Path based components are components that infer their name based on
+the base name of a file. These types of components use the `SparkleFormation.build`
+method, which does not accept a name argument. For example:
+
+~~~ruby
+# components/common.rb
+SparkleFormation.build do
+   ...
+end
+~~~
+
+The name of this component will be `common`.
+
+#### Name based components
+
+Name based components are components whose names are explicitly
+defined. These types of components use the `SparkleFormation.component`
+method, which accepts a name argument. For example:
+
+~~~ruby
+# components/my-common-component.rb
+SparkleFormation.component(:core) do
+  ...
+end
+~~~
+
+The name of this component will be `core` as it is explicitly provided
+when creating the component. These name based components are specifically
+geared towards usage in "sparkle packs" or any other implementations where
+a single file may provide multiple components or building blocks, or where
+the file name may be required to be different from the name of the component.
+
+### Dynamics
+
+Dynamics are reusable blocks of code that can be applied multiple times
+within the same template to provide multiple discrete sets of content.
+They provide the ability to refactor common template content out into
+reusable and configurable dynamics that can then be re-inserted using
+customized naming structures. Dynamics _always_ explicitly define their
+name when creating unlike components which optionally supports explict
+naming.
+
+Dynamics are registered blocks which accept two parameters:
+
+1. Name for the dynamic call
+2. Configuration Hash for the dynamic call
+
+Here is an example dynamic:
+
+~~~ruby
+# dynamics/node.rb
+SparkleFormation.dynamic(:node) do |_name, _config={}|
+  unless(_config[:ssh_key])
+    parameters.set!("#{_name}_ssh_key".to_sym) do
+      type 'String'
+    end
+  end
+  dynamic!(:ec2_instance, _name).properties do
+    key_name _config[:ssh_key] ? _config[:ssh_key] : ref!("#{_name}_ssh_key".to_sym)
+  end
+end
+~~~
+
+*NOTE: The underscore (`_`) prefix on the parameter names are simply a convention
+and not required. It is a convention to make it easier to identify variables
+used within the dynamic, and its usage is completely author dependent.*
+
+The dynamic defines two parameters: `_name` and `_config`. The `_config`
+parameter is defaulted to an empty Hash allowing the dynamic call to optionally
+accept a configuration Hash. With this dynamic in place, it can be called
+multiple times within a template:
+
+~~~ruby
+SparkleFormation.new(:node_stack) do
+  dynamic!(:node, :fubar)
+  dynamic!(:node, :foobar, :ssh_key => 'default')
+end
+~~~
+
+#### Builtin Dynamics
+
+SparkleFormation includes a lookup of known AWS resources which can be accessed
+using the `dynamic!` method. This lookup is provided simply as a convenience
+to speed development and compact implementations. When a builtin is inserted,
+it will automatically set the `type` of the resource and evaluate an optionally
+provided block within the resource. The following templates will generate
+equivalent results when compiled:
+
+~~~ruby
+SparkleFormation.new(:with_dynamic) do
+  dynamic!(:ec2_instance, :fubar).properties.key_name 'default'
+end
+~~~
+
+~~~ruby
+SparkleFormation.new(:without_dynamic) do
+  resources.fubar_ec2_instance do
+    type 'AWS::EC2::Instance'
+    properties.key_name 'default'
+  end
+end
+~~~
+
+##### Builtin Lookup Behavior
+
+Builtin lookups are based on the resource type. Resource matching is performed
+using a *suffix based* match. When searching for matching types, the _first_
+match is used. For example:
+
+~~~ruby
+SparkleFormation.new(:class_only) do
+  dynamic!(:instance, :foobar)
+end
+~~~
+
+When the lookup is performed, this will match the `AWS::EC2::Instance` resource.
+This may not be the correct match, however, since there is also an
+`AWS::OpsWorks::Instance` resource type. The correct lookup can be forced (if
+the `OpsWorks` resource is the desired resource) by providing the namespace
+prefix:
+
+~~~ruby
+SparkleFormation.new(:with_namespace) do
+  dynamic!(:opsworks_instance, :foobar)
+end
+~~~
+
+This can also be taken a step further by including the `AWS` namespace as well:
+
+~~~ruby
+SparkleFormation.new(:with_namespace) do
+  dynamic!(:aws_opsworks_instance, :foobar)
+end
+~~~
+
+but will likely be a bit superfluous. It is also important to note the name
+of the generated resource is dependent on the value of the first parameter.
+The resultant resource names from the above three examples will be:
+
+* FoobarInstance
+* FoobarOpsworksInstance
+* FoobarAwsOpsworksInstance
+
+The value used for the suffix of the resource name can be provided with
+the `dynamic!` call:
+
+~~~ruby
+SparkleFormation.new(:with_namespace) do
+  dynamic!(:aws_opsworks_instance, :foobar,
+    :resource_suffix_name => :instance
+  )
+end
+~~~
+
+which will result in a resource name: `FoobarInstance`
+
+##### Dynamic Return Context
+
+When defining custom dynamics, the result of the dynamic block is important.
+A dynamic can make multiple modifications to a template when inserted. For
+example, addition of parameters, resources, and/or outputs. It is important
+to use the values returned from the dynamic block to prevent surprises.
+When the `dynamic!` is called and provided a block, the block is evaluated
+within the context returned from the `dynamic!`.
+
+For example, this is an improper implementation of a dynamic:
+
+~~~ruby
+SparkleFormation.dynamic(:bad_dynamic) do |_name, _config|
+  dynamic!(:ec2_instance, _name)
+  outputs do
+    address.value attr!("#{_name}_ec2_instance".to_sym, :public_ip)
+  end
+end
+~~~
+
+If a template attempts to use this dynamic and make an override modification
+to the instance:
+
+~~~ruby
+SparkleFormation.new(:failed_template) do
+  dynamic!(:bad_dynamic, :foobar) do
+    properties.key_name 'default'
+  end
+end
+~~~
+
+The `properties.key_name` will be evaluated within the context of the `outputs`
+because it is the returned value of the dynamic block. Instead the dynamic should
+return the context of the referenced resource (if applicable). To make the
+dynamic act as expected, the resource must be returned from the block.
+
+~~~ruby
+SparkleFormation.dynamic(:good_dynamic) do |_name, _config|
+  _resource = dynamic!(:ec2_instance, _name)
+  outputs do
+    address.value attr!("#{_name}_ec2_instance".to_sym, :public_ip)
+  end
+  _resource
+end
+~~~
+
+This will ensure the instance resource is the context returned. The blocks provided
+will work as expected:
+
+~~~ruby
+SparkleFormation.new(:successful_template) do
+  dynamic!(:good_dynamic, :foobar) do
+    properties.key_name 'default'
+  end
+end
+~~~
+
+##### Dynamic Lookup Behavior
+
+Dynamics can be loaded from multiple locations. When SparkleFormation performs
+a dynamic lookup, the following locations are checked in order of precedence:
+
+1. Implementation local `dynamics` directory
+2. SparklePack dynamics with reverse load order precedence
+3. Builtin dynamics lookup table
+
+### Registry
+
+Registry entries are lightweight dynamics that are useful for storing items that
+may be used in multiple locations. For example, the valid sizes of an instance
+within an infrastructure will generally be restricted to a specific list.
+This list can be stored within a registry to provide a single point of
+contact for any changes:
+
+~~~ruby
+SfnRegistry.register(:instance_sizes) do
+  [
+    'm3.large',
+    'm3.medium',
+    't2.medium'
+  ]
+end
+SfnRegistry.register(:instance_size_default){ 'm3.medium' }
+~~~
+
+With the array registered as `registry!(:instance_sizes)`, we can now reference it:
+
+~~~ruby
+SparkleFormation.new(:instance_stack) do
+  parameters.instance_size do
+    type 'String'
+    allowed_values registry!(:instance_sizes)
+    default registry!(:instance_size_default)
+  end
+end
+~~~
+
+### Templates
+
+Templates are the files that pull all the building blocks together to produce
+a final data structure that will be serialized into a document. This data structure
+can be submitted to an orchestration API.
+
+There are three stages of template compilation:
+
+1. Evaluate optional block given on instantiation
+2. Evaluate any loaded components
+3. Evaluate `override` block
+
+#### Instantiation Block
+
+A block provided on instantiation is the first block evaluated:
+
+~~~ruby
+SparkleFormation.new(:my_template) do
+  dynamic!(:ec2_instance, :foobar)
+end
+~~~
+
+#### Loaded Components
+
+Components are evaluated in the order they are added to the template via
+the `load` method:
+
+~~~ruby
+SparkleFormation.new(:my_template) do
+  dynamic!(:ec2_instance, :foobar)
+end.load(:common, :special)
+~~~
+
+On compilation, this will evaluate the instantiation block first, the `common`
+component second, and finally the `special` component.
+
+#### Overrides
+
+Override blocks are the final blocks evaluated during compilation:
+
+~~~ruby
+SparkleFormation.new(:my_template) do
+  dynamic!(:ec2_instance, :foobar)
+end.load(:common, :special).overrides do
+  resources.foobar_ec2_instance.properties.key_name 'default'
+end
+~~~
+
+[1]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself