sparkle_formation 0.2.2 → 0.2.4

data/docs/building-blocks.md

@@ -1,275 +0,0 @@
-## SparkleFormation Building Blocks
-
-Using SparkleFormation for the above template has already saved us
-many keystrokes, but what about reusing SparkleFormation code between
-similar stacks? This is where SparkleFormation concepts like
-components, dynamics, and registries come into play.
-
-### Components
-
-Components are static configuration which can be reused between many
-stack templates. In our example case we have decided that all our
-stacks will need to make use of IAM credentials, so we will create
-a component which allows us to inserts the two IAM resources into any
-template in a resuable fashion. The component, which we will call
-'base' and put in a file called 'base.rb,' would look like this:
-
-```ruby
-SparkleFormation.build do
-  set!('AWSTemplateFormatVersion', '2010-09-09')
-
-  resources.cfn_user do
-    type 'AWS::IAM::User'
-    properties.path '/'
-    properties.policies _array(
-      -> {
-        policy_name 'cfn_access'
-        policy_document.statement _array(
-          -> {
-            effect 'Allow'
-            action 'cloudformation:DescribeStackResource'
-            resource '*' 
-          }
-        )
-      }
-    )
-  end
-
-  resources.cfn_keys do
-    type 'AWS::IAM::AccessKey'
-    properties.user_name ref!(:cfn_user)
-  end
-end
-```
-
-After moving these resources out of the initial template and into a
-component, we will update the template so that the base component is
-loaded on the first line, and the resources it contains are no longer
-present in the template itself:
-
-```ruby
-SparkleFormation.new(:website).load(:base).overrides do
-
-  description 'Supercool Website'
-
-  parameters.web_nodes do
-    type 'Number'
-    description 'Number of web nodes for ASG.'
-    default '2'
-  end
-
-  resources.website_autoscale do
-    type 'AWS::AutoScaling::AutoScalingGroup'
-    properties do
-      availability_zones({'Fn::GetAZs' => ''})
-      launch_configuration_name ref!(:website_launch_config)
-      min_size ref!(:web_nodes)
-      max_size ref!(:web_nodes)
-    end
-  end
-
-  resources.website_launch_config do
-    type 'AWS::AutoScaling::LaunchConfiguration'
-    properties do
-      image_id 'ami-123456'
-      instance_type 'm3.medium'
-    end
-  end
-
-  resources.website_elb do
-    type 'AWS::ElasticLoadBalancing::LoadBalancer'
-    properties do
-      availability_zones._set('Fn::GetAZs', '')
-      listeners _array(
-        -> {
-          load_balancer_port '80'
-          protocol 'HTTP'
-          instance_port '80'
-          instance_protocol 'HTTP'
-        }
-      )
-      health_check do
-        target 'HTTP:80/'
-        healthy_threshold '3'
-        unhealthy_threshold '3'
-        interval '5'
-        timeout '15'
-      end
-    end
-  end
-end
-```
-
-### Dynamics
-
-Like components, dynamics are another SparkleFormation feature which
-enables code reuse between stack templates. Where components are
-static, dynamics are useful for creating unique resources via
-the passing of arguments.
-
-In our example scenario we have decided that we want to use elastic
-load balancer resources in many of our stack templates, we want to
-create a dynamic which makes inserting ELB resources much easier than
-copying the full resource configuration between templates.
-
-The resulting implementation would look something like this:
-
-```ruby
-SparkleFormation.dynamic(:elb) do |_name, _config={}|
-  resources("#{_name}_elb".to_sym) do
-    type 'AWS::ElasticLoadBalancing::LoadBalancer'
-    properties do
-      availability_zones._set('Fn::GetAZs', '')
-      listeners _array(
-        -> {
-          load_balancer_port _config[:load_balancer_port] || '80'
-          protocol _config[:protocol] || 'HTTP'
-          instance_port _config[:instance_port] || '80'
-          instance_protocol _config[:instance_protocol] || 'HTTP'
-        }
-      )
-      health_check do
-        target _config[:target] || 'HTTP:80/'
-        healthy_threshold _config[:healthy_threshold] || '3'
-        unhealthy_threshold _config[:unhealthy_threshold] || '3'
-        interval _config[:interval] || '5'
-        timeout _config[:timeout] || '15'
-      end
-    end
-  end
-end
-```
-
-This dynamic accepts two arguments: `_name` (a string, required) and `_config`
-(a hash, optional). The dynamic will use the values passed in these
-arguments to generate a new ELB resource, and override the default ELB
-properties wherever a corresponding key/value pair is provided in the
-`_config` hash.
-
-Once updated to make use of the new ELB dynamic, our template looks
-like this:
-
-```ruby
-SparkleFormation.new(:website).load(:base).overrides do
-
-  description 'Supercool Website'
-
-  parameters.web_nodes do
-    type 'Number'
-    description 'Number of web nodes for ASG.'
-    default '2'
-  end
-
-  resources.website_autoscale do
-    type 'AWS::AutoScaling::AutoScalingGroup'
-    properties do
-      availability_zones({'Fn::GetAZs' => ''})
-      launch_configuration_name ref!(:website_launch_config)
-      min_size ref!(:web_nodes)
-      max_size ref!(:web_nodes)
-    end
-  end
-
-  resources.website_launch_config do
-    type 'AWS::AutoScaling::LaunchConfiguration'
-    properties do
-      image_id 'ami-123456'
-      instance_type 'm3.medium'
-    end
-  end
-
-  dynamic!(:elb, 'website')
-end
-```
-
-If we wanted to override the default configuration for the ELB,
-e.g. to configure the ELB to listen on and communicate with back-end
-node on port 8080 instead of 80, we can specify these override values
-in the configuration passed to the ELB dynamic:
-
-```ruby
-  dynamic!(:elb, 'website', :load_balancer_port => 8080, :instance_port => 8080)
-```
-
-We're passing three arguments here:
-
-1. `:elb` is the name of the dynamic to insert, as a ruby symbol
-2. A name string (`'website'`), which is passed to `_name` in the
-dynamic. This is prepended to the resource name in the dynamic,
-resulting in a unique resource name.
-3. The ELB ports to configure as key/value pairs. These are passed into the dynamic as
-the `_config` hash.
-
-### Registries
-
-Similar to dynamics, registries are reusable resource configuration
-code which can be reused inside different resource definitions.
-
-Registries are useful for defining properties that may be reused
-between resources of different types. For example, the
-LaunchConfiguration and Instance resource types make use of metadata
-properties which inform both resource types how to bootstrap one or
-more instances.
-
-In our example scenario we would like our new instances to run
-'sudo apt-get update && sudo apt-get upgrade -y' at first boot,
-regardless of whether or not the instances are members of an
-autoscaling group.
-
-Because these resources are of different types, placing the metadata
-required for this task directly inside a dynamic isn't going to work
-quite the way we need. Instead we can put this inside a registry which
-can be inserted into the resources defined in one or more dynamics:
-
-```ruby
-SparkleFormation::Registry.register(:apt_get_update) do
-  metadata('AWS::CloudFormation::Init') do
-    _camel_keys_set(:auto_disable) do
-    commands('01_apt_get_update') do
-      command 'sudo apt-get update'
-    end
-    commands('02_apt_get_upgrade') do
-      command 'sudo apt-get upgrade -y'
-    end
-  end
-end
-```
-
-Now we can insert this registry entry into our existing template, to
-ensure that apt is updated upon provisioning:
-
-```ruby
-SparkleFormation.new(:website).load(:base).overrides do
-
-  description 'Supercool Website'
-
-  parameters.web_nodes do
-    type 'Number'
-    description 'Number of web nodes for ASG.'
-    default 2
-  end
-
-  resources.website_autoscale do
-    type 'AWS::AutoScaling::AutoScalingGroup'
-    properties do
-      availability_zones({'Fn::GetAZs' => ''})
-      launch_configuration_name ref!(:website_launch_config)
-      min_size ref!(:web_nodes)
-      max_size ref!(:web_nodes)
-    end
-  end
-
-  resources.website_launch_config do
-    type 'AWS::AutoScaling::LaunchConfiguration'
-    registry!(:apt_get_update, 'website')
-    properties do
-      image_id 'ami-123456'
-      instance_type 'm3.medium'
-    end
-  end
-
-  dynamic!(:elb, 'website')
-
-  registry!(:apt_get_update, 'website')
-end
-```

data/docs/examples/cloudformation/components/base.rb

@@ -1,25 +0,0 @@
-SparkleFormation.build do
-  set!('AWSTemplateFormatVersion', '2010-09-09')
-
-  resources.cfn_user do
-    type 'AWS::IAM::User'
-    properties.path '/'
-    properties.policies _array(
-      -> {
-        policy_name 'cfn_access'
-        policy_document.statement _array(
-          -> {
-            effect 'Allow'
-            action 'cloudformation:DescribeStackResource'
-            resource '*' 
-          }
-        )
-      }
-    )
-  end
-
-  resources.cfn_keys do
-    type 'AWS::IAM::AccessKey'
-    properties.user_name ref!(:cfn_user)
-  end
-end

data/docs/examples/cloudformation/dynamics/elb.rb

@@ -1,23 +0,0 @@
-SparkleFormation.dynamic(:elb) do |_name, _config={}|
-  resources("#{_name}_elb".to_sym) do
-    type 'AWS::ElasticLoadBalancing::LoadBalancer'
-    properties do
-      availability_zones._set('Fn::GetAZs', '')
-      listeners _array(
-        -> {
-          load_balancer_port _config[:load_balancer_port] || '80'
-          protocol _config[:protocol] || 'HTTP'
-          instance_port _config[:instance_port] || '80'
-          instance_protocol _config[:instance_protocol] || 'HTTP'
-        }
-      )
-      health_check do
-        target _config[:target] || 'HTTP:80/'
-        healthy_threshold _config[:healthy_threshold] || '3'
-        unhealthy_threshold _config[:unhealthy_threshold] || '3'
-        interval _config[:interval] || '5'
-        timeout _config[:timeout] || '15'
-      end
-    end
-  end
-end

data/docs/examples/cloudformation/templates/website.rb

@@ -1,30 +0,0 @@
-SparkleFormation.new(:website).load(:base).overrides do
-
-  description 'Supercool Website'
-
-  parameters.web_nodes do
-    type 'Number'
-    description 'Number of web nodes for ASG.'
-    default 2
-  end
-
-  resources.website_autoscale do
-    type 'AWS::AutoScaling::AutoScalingGroup'
-    properties do
-      availability_zones({'Fn::GetAZs' => ''})
-      launch_configuration_name ref!(:website_launch_config)
-      min_size ref!(:web_nodes)
-      max_size ref!(:web_nodes)
-    end
-  end
-
-  resources.website_launch_config do
-    type 'AWS::AutoScaling::LaunchConfiguration'
-    properties do
-      image_id 'ami-123456'
-      instance_type 'm3.medium'
-    end
-  end
-
-  dynamic!(:elb, 'website')
-end

data/docs/examples/template_json/website.json

@@ -1,88 +0,0 @@
-{
-  "AWSTemplateFormatVersion": "2010-09-09",
-  "Description": "Supercool Website",
-  "Resources": {
-    "CfnUser": {
-      "Type": "AWS::IAM::User",
-      "Properties": {
-        "Path": "/",
-        "Policies": [
-          {
-            "PolicyName": "cfn_access",
-            "PolicyDocument": {
-              "Statement": [
-                {
-                  "Effect": "Allow",
-                  "Action": "cloudformation:DescribeStackResource",
-                  "Resource": "*"
-                }
-              ]
-            }
-          }
-        ]
-      }
-    },
-    "CfnKeys": {
-      "Type": "AWS::IAM::AccessKey",
-      "Properties": {
-        "UserName": {
-          "Ref": "CfnUser"
-        }
-      }
-    },
-    "WebsiteAutoscale": {
-      "Type": "AWS::AutoScaling::AutoScalingGroup",
-      "Properties": {
-        "AvailabilityZones": {
-          "Fn::GetAZs": ""
-        },
-        "LaunchConfigurationName": {
-          "Ref": "WebsiteLaunchConfig"
-        },
-        "MinSize": {
-          "Ref": "WebNodes"
-        },
-        "MaxSize": {
-          "Ref": "WebNodes"
-        }
-      }
-    },
-    "WebsiteLaunchConfig": {
-      "Type": "AWS::AutoScaling::LaunchConfiguration",
-      "Properties": {
-        "ImageId": "ami-123456",
-        "InstanceType": "m3.medium"
-      }
-    },
-    "WebsiteElb": {
-      "Type": "AWS::ElasticLoadBalancing::LoadBalancer",
-      "Properties": {
-        "AvailabilityZones": {
-          "Fn::GetAZs": ""
-        },
-        "Listeners": [
-          {
-            "LoadBalancerPort": "80",
-            "Protocol": "HTTP",
-            "InstancePort": "80",
-            "InstanceProtocol": "HTTP"
-          }
-        ],
-        "HealthCheck": {
-          "Target": "HTTP:80/",
-          "HealthyThreshold": "3",
-          "UnhealthyThreshold": "3",
-          "Interval": "5",
-          "Timeout": "15"
-        }
-      }
-    }
-  },
-  "Parameters": {
-    "WebNodes": {
-      "Type": "Number",
-      "Description": "Number of web nodes for ASG.",
-      "Default": "2"
-    }
-  }
-}

data/docs/examples/website.rb

@@ -1,74 +0,0 @@
-SparkleFormation.new('website') do
-
-  set!('AWSTemplateFormatVersion', '2010-09-09')
-
-  description 'Supercool Website'
-
-  resources.cfn_user do
-    type 'AWS::IAM::User'
-    properties.path '/'
-    properties.policies _array(
-      -> {
-        policy_name 'cfn_access'
-        policy_document.statement _array(
-          -> {
-            effect 'Allow'
-            action 'cloudformation:DescribeStackResource'
-            resource '*' 
-          }
-        )
-      }
-    )
-  end
-
-  resources.cfn_keys do
-    type 'AWS::IAM::AccessKey'
-    properties.user_name ref!(:cfn_user)
-  end
-
-  parameters.web_nodes do
-    type 'Number'
-    description 'Number of web nodes for ASG.'
-    default 2
-  end
-  
-  resources.website_autoscale do
-    type 'AWS::AutoScaling::AutoScalingGroup'
-    properties do
-      availability_zones({'Fn::GetAZs' => ''})
-      launch_configuration_name ref!(:website_launch_config)
-      min_size ref!(:web_nodes)
-      max_size ref!(:web_nodes)
-    end
-  end
-
-  resources.website_launch_config do
-    type 'AWS::AutoScaling::LaunchConfiguration'
-    properties do
-      image_id 'ami-123456'
-      instance_type 'm3.medium'
-    end
-  end
-
-  resources.website_elb do
-    type 'AWS::ElasticLoadBalancing::LoadBalancer'
-    properties do
-      availability_zones._set('Fn::GetAZs', '')
-      listeners _array(
-        -> {
-          load_balancer_port '80'
-          protocol 'HTTP'
-          instance_port '80'
-          instance_protocol 'HTTP'
-        }
-      )
-      health_check do
-        target 'HTTP:80/'
-        healthy_threshold '3'
-        unhealthy_threshold '3'
-        interval '5'
-        timeout '15'
-      end
-    end
-  end
-end

data/docs/functions.md

@@ -1,41 +0,0 @@
-## Intrinsic Functions
-The following are all intrinsic AWS Cloudformation functions that are
-supported with special syntax in SparkleFormation. Note that these may
-not be implemented for all providers. 
-
-### Ref
-Ref allows you to reference parameter and resource values. We did this
-earlier with the autoscaling group size:
-```ruby
-parameters.web_nodes do
-  type 'Number'
-  description 'Number of web nodes for ASG.'
-  default '2'
-end
-
-...
-
-min_size ref!(:web_nodes)
-```
-It also works for resource names. The following returns the name of
-the launch configuration so we can use it in the autoscaling group
-properties. 
-```ruby
-ref!(:website_launch_config)
-```  
-
-### Join
-A Join combines strings. You can use Refs and Mappings within a Join.
-```ruby
-join!(ref!(:environment), '-', map!(:region_map, ref!('AWS::Region'), :ami))
-```
-Would return 'development-us-east-1', if we built a stack in the
-AWS  Virgnia region and provided 'development' for the environment
-parameter. 
-
-### Attr
-Certain resources attributes can be retrieved directly. To access an
-IAM user's (in this case, :cfn_user) secret key:
-```ruby
-attr!(:cfn_user, :secret_access_key)
-```

data/docs/properties.md

@@ -1,32 +0,0 @@
-## Universal Properties
-
-### Tags
-Tags can be applied to most resources. These make it easy to track
-resource usage across stacks. They may be used for cost tracking as
-well as configuration tools that are cloud-infrastructure aware. Tags
-are provided as key/value pairs within an array. In this example we
-provide the stack name and a contact email:
-
-```ruby
-  resources.website_autoscale do
-    type 'AWS::AutoScaling::AutoScalingGroup'
-    properties do
-      availability_zones({ 'Fn::GetAZs' => '' })
-      tags _array(
-        -> {
-          key 'StackName'
-          value ref!('AWS::StackName'))
-          propagate_at_launch true
-        },
-        -> {
-          key 'ContactEmail'
-          value 'support@hw-ops.com'
-          propagate_at_launch true
-        }
-      )
-      launch_configuration_name ref!(:website_launch_config)
-    end
-```
-
-Please check the relevant reference documentation to confirm that tags
-are available for a specific resource type.

data/docs/provisioning.md

@@ -1,82 +0,0 @@
-## Provisioning SparkleFormations
-
-### JSON Templates
-
-Generating JSON from a SparkleFormation template is as simple as
-calling `SparkleFormation.compile()` on the template file. Here's a simple
-script to output a JSON template from a supplied
-SparkeFormation template:
-
-```ruby
-#!/usr/bin/env ruby
-require 'sparkle_formation'
-require 'json'
-
-puts SparkleFormation.compile(ARGV[0])
-```
-
-The output can be written to a file and uploaded to the provider using
-the method of your choice. 
-
-For a more legible template:
-
-```ruby
-puts JSON.pretty_generate(SparkleFormation.compile(ARGV[0]))
-```
-
-Note: The output from this command may not be usable with cloud providers,
-as the many spaces and newlines may exceed the cloudformation
-character limit. However, it is much easier to read.
-
-### Knife Cloudformation
-knife-cloudformation [knife-cloudformation plugin](https://rubygems.org/gems/knife-cloudformation) is a plugin for
-knife that provisions cloudformation stacks. It can be used with
-SparkleFormation to build stacks without the intermediary steps of
-writing a JSON template to file and uploading the template to the provider.
-
-#### Processing SparkleFormation Templates
-To build a stack directly from a SparkleFormation template, use the
-`create` command with the `--file` and `--processing` flags:
-
-```
-knife cloudformation create my-web-stack --file templates/website.rb --processing
-```
-
-`--file` directs knife to a file under the `cloudformation` directory,
-and `--processing` tells knife to render JSON from the
-SparkleFormation template before passing it to the provider.
-         
-#### Applying Stacks
-You can also apply an existing stack's outputs to the stack you are
-building. Using the `--apply-stack` flag sets parameters to the
-values of any matching outputs.  
-
-Consider that you have built a database stack (`db-stack-01`) that includes an output for the
-database endpoint:
-
-```ruby
-outputs do
-  database_endpoint do
-    value attr!(:database_elb, 'DNSName')
-    description "Database ELB Endpoint for client connections"
-  end
-end
-```
-
-Next, you build a website stack (`web-stack-01`) that needs to connect to the
-database. The SparkleFormation for this stack includes a parameter to
-prompt for the database endpoint:
-
-```ruby
-parameters.database_endpoint do
-  type 'String'
-  description 'Database endpoint to connect to'
-  default 'localhost'
-end
-```
-
-Using knife-cloudformation, you apply the database stack in order to
-automatically provide the correct database endpoint:
-
-`knife cloudformation create web-stack-01 --file templates/website.rb --processing --apply-stack db-stack-01`
-