sparkle_formation 0.2.0 → 0.2.2

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

@@ -0,0 +1,25 @@
+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

@@ -0,0 +1,23 @@
+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

@@ -0,0 +1,30 @@
+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

@@ -0,0 +1,88 @@
+{
+  "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

@@ -0,0 +1,74 @@
+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

@@ -0,0 +1,41 @@
+## 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

@@ -0,0 +1,32 @@
+## 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

@@ -0,0 +1,82 @@
+## 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`
+                             

data/docs/resource-reference.md

@@ -0,0 +1,49 @@
+## Resource Reference
+
+This is a best-effort list of commonly used cloudformation resources and their
+availability/feature set in supported cloud providers. This list does
+not cover everything that may be offered by a specific provider, and
+is not intended as a comparison of cloud providers.
+
+#### Auto Scaling Groups
+
+|Provider    |Available |Caveats & Limitations                                                        |
+|------------|----------|-----------------------------------------------------------------------------|
+|AWS         |Yes       |EC2 Classic and VPC use mutually exclusive properties.                       |
+|Rackspace   |Yes       |Autoscaling will not replace lost instances, only does policy based scaling. |
+
+#### Compute Instances
+
+|Provider    |Available |Caveats & Limitations                                                        |
+|------------|----------|-----------------------------------------------------------------------------|
+|AWS         |Yes       |                                                                             |
+|Rackspace   |Yes       |                                                                             |
+
+#### Load Balancers
+
+|Provider    |Available |Caveats & Limitations                                                        |
+|------------|----------|-----------------------------------------------------------------------------|
+|AWS         |Yes       |Security Group Ingress is not automatic. Must be defined separately.         |
+|Rackspace   |Yes       |Multiple ports generates new template resources.                             |
+
+#### Security Groups
+
+|Provider    |Available |Caveats & Limitations                                                        |
+|------------|----------|-----------------------------------------------------------------------------|
+|AWS         |Yes       |                                                                             |
+|Rackspace   |No        |                                                                             |
+
+#### Storage
+
+|Provider    |Available |Caveats & Limitations                                                        |
+|------------|----------|-----------------------------------------------------------------------------|
+|AWS         |Yes       |                                                                             |
+|Rackspace   |No        |                                                                             |
+
+
+#### Stack Users
+
+|Provider    |Available |Caveats & Limitations                                                        |
+|------------|----------|-----------------------------------------------------------------------------|
+|AWS         |Yes       |                                                                             |
+|Rackspace   |No        |                                                                             |

data/lib/sparkle_formation/sparkle_formation.rb

@@ -154,7 +154,7 @@ class SparkleFormation
     #
     # @param name [String, Symbol] name of dynamic
     # @param args [Hash] dynamic metadata
-    # @param args [Hash] :parameters description of _config parameters
+    # @option args [Hash] :parameters description of _config parameters
     # @example
     #   metadata describes dynamic parameters for _config hash:
     #   :item_name => {:description => 'Defines item name', :type => 'String'}

data/lib/sparkle_formation/translation/heat.rb

@@ -3,6 +3,66 @@ class SparkleFormation
     # Translation for Heat (HOT)
     class Heat < Translation
 
+      # Translate stack definition
+      #
+      # @return [TrueClass]
+      # @note this is an override to return in proper HOT format
+      # @todo still needs replacements of functions and pseudo-params
+      def translate!
+        super
+        cache = MultiJson.load(MultiJson.dump(translated))
+        # top level
+        cache.each do |k,v|
+          translated.delete(k)
+          translated[snake(k).to_s] = v
+        end
+        # params
+        cache.fetch('Parameters', {}).each do |k,v|
+          translated['parameters'][k] = Hash[
+            v.map do |key, value|
+              if(key == 'Type')
+                [snake(key).to_s, value.downcase]
+              elsif(key == 'AllowedValues')
+                # @todo fix this up to properly build constraints
+                ['constraints', [{'allowed_values' => value}]]
+              else
+                [snake(key).to_s, value]
+              end
+            end
+          ]
+        end
+        # resources
+        cache.fetch('Resources', {}).each do |r_name, r_value|
+          translated['resources'][r_name] = Hash[
+            r_value.map do |k,v|
+              [snake(k).to_s, v]
+            end
+          ]
+        end
+        # outputs
+        cache.fetch('Outputs', {}).each do |o_name, o_value|
+          translated['outputs'][o_name] = Hash[
+            o_value.map do |k,v|
+              [snake(k).to_s, v]
+            end
+          ]
+        end
+        translated.delete('awstemplate_format_version')
+        translated['heat_template_version'] = '2013-05-23'
+        # no HOT support for mappings, so remove and clean pseudo
+        # params in refs
+        if(translated['resources'])
+          translated['resources'] = dereference_processor(translated['resources'], ['Fn::FindInMap', 'Ref'])
+          translated['resources'] = rename_processor(translated['resources'])
+        end
+        if(translated['outputs'])
+          translated['outputs'] = dereference_processor(translated['outputs'], ['Fn::FindInMap', 'Ref'])
+          translated['outputs'] = rename_processor(translated['outputs'])
+        end
+        translated.delete('mappings')
+        true
+      end
+
       # Custom mapping for block device
       #
       # @param value [Object] original property value
@@ -49,7 +109,19 @@ class SparkleFormation
             if(files = config['files'])
               files.each do |key, args|
                 if(args['source'])
-                  args['source'].replace("\"#{args['source']}\"")
+                  if(args['source'].is_a?(String))
+                    args['source'].replace("\"#{args['source']}\"")
+                  else
+                    args['source'] = {
+                      'Fn::Join' => [
+                        "", [
+                          "\"",
+                          args['source'],
+                          "\""
+                        ]
+                      ]
+                    }
+                  end
                 end
               end
             end
@@ -126,6 +198,17 @@ class SparkleFormation
         }
       }
 
+      REF_MAPPING = {
+        'AWS::StackName' => 'OS::stack_name',
+        'AWS::StackId' => 'OS::stack_id',
+        'AWS::Region' => 'OS::stack_id' # @todo i see it set in source, but no function. wat
+      }
+
+      FN_MAPPING = {
+        'Fn::GetAtt' => 'get_attr',
+        'Fn::Join' => 'list_join'  # @todo why is this not working?
+      }
+
     end
   end
 end