cloudformation-ruby-dsl 0.4.0

data/cloudformation-ruby-dsl.gemspec

@@ -0,0 +1,36 @@
+# -*- encoding: utf-8 -*-
+
+# Copyright 2013-2014 Bazaarvoice, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'cloudformation-ruby-dsl/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "cloudformation-ruby-dsl"
+  gem.version       = Cfn::Ruby::Dsl::VERSION
+  gem.authors       = ["Shawn Smith", "Dave Barcelo", "Morgan Fletcher", "Csongor Gyuricza", "Igor Polishchuk", "Nathaniel Eliot", "Jona Fenocchi", "Tony Cui"]
+  gem.email         = ["Shawn.Smith@bazaarvoice.com", "Dave.Barcelo@bazaarvoice.com", "Morgan.Fletcher@bazaarvoice.com", "Csongor.Gyuricza@bazaarvoice.com", "Igor.Polishchuk@bazaarvoice.com", "Nathaniel.Eliot@bazaarvoice.com", "Jona.Fenocchi@bazaarvoice.com", "Tony.Cui@bazaarvoice.com"]
+  gem.description   = %q{Ruby DSL library that provides a wrapper around the cfn-cmd.}
+  gem.summary       = %q{Ruby DSL library that provides a wrapper around the cfn-cmd.  Written by [Bazaarvoice](http://www.bazaarvoice.com).}
+  gem.homepage      = "http://github.com/bazaarvoice/cloudformation-ruby-dsl"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = %w{lib bin}
+
+  gem.add_runtime_dependency    'detabulator'
+end

data/examples/cloudformation-ruby-script.rb

@@ -0,0 +1,195 @@
+#!/usr/bin/env ruby
+
+# Copyright 2013-2014 Bazaarvoice, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'bundler/setup'
+require 'cloudformation-ruby-dsl/cfntemplate'
+require 'cloudformation-ruby-dsl/table'
+
+# Note: this is only intended to demonstrate the cloudformation-ruby-dsl. It compiles
+#   and validates correctly, but won't produce a viable Cloudformation stack.
+
+template do
+
+  parameter 'Label',
+            :Description => 'The label to apply to the servers.',
+            :Type => 'String',
+            :MinLength => '2',
+            :MaxLength => '25',
+            :AllowedPattern => '[_a-zA-Z0-9]*',
+            :ConstraintDescription => 'Maximum length of the Label parameter may not exceed 25 characters and may only contain letters, numbers and underscores.',
+            # The :Immutable attribute is a Ruby CFN extension.  It affects the behavior of the '<template> cfn-update-stack ...'
+            # operation in that a stack update may not change the values of parameters marked w/:Immutable => true.
+            :Immutable => true
+
+  parameter 'InstanceType',
+            :Description => 'EC2 instance type',
+            :Type => 'String',
+            :Default => 'm2.xlarge',
+            :AllowedValues => %w(t1.micro m1.small m1.medium m1.large m1.xlarge m2.xlarge m2.2xlarge m2.4xlarge c1.medium c1.xlarge),
+            :ConstraintDescription => 'Must be a valid EC2 instance type.'
+
+  parameter 'ImageId',
+            :Description => 'EC2 Image ID',
+            :Type => 'String',
+            :Default => 'ami-255bbc4c',
+            :AllowedPattern => 'ami-[a-f0-9]{8}',
+            :ConstraintDescription => 'Must be ami-XXXXXXXX (where X is a hexadecimal digit)'
+
+  parameter 'KeyPairName',
+            :Description => 'Name of KeyPair to use.',
+            :Type => 'String',
+            :MinLength => '1',
+            :MaxLength => '40',
+            :Default => parameters['Label']
+
+  parameter 'EmailAddress',
+            :Type => 'String',
+            :Description => 'Email address at which to send notification events.'
+
+  mapping 'InlineExampleMap',
+          :team1 => {
+              :name => 'test1',
+              :email => 'test1@example.com',
+          },
+          :team2 => {
+              :name => 'test2',
+              :email => 'test2@example.com',
+          }
+
+  # Generates mappings from external files with various formats.
+  mapping 'JsonExampleMap', 'maps/json_map.json'
+
+  mapping 'RubyExampleMap', 'maps/ruby_map.rb'
+
+  mapping 'YamlExampleMap', 'maps/yaml_map.yaml'
+
+  # Loads JSON mappings dynamically from example directory.
+  Dir.entries('maps/more_maps').each_with_index do |path, index|
+    next if path == "." or path == ".."
+    mapping "ExampleMap#{index - 1}", "maps/more_maps/#{path}"
+  end
+
+  # Selects all rows in the table which match the name/value pairs of the predicate object and returns a
+  # set of nested maps, where the key for the map at level n is the key at index n in the specified keys,
+  # except for the last key in the specified keys which is used to determine the value of the leaf-level map.
+  text = Table.load 'maps/text_table.txt'
+  mapping 'TableExampleMap',
+      text.get_map({ :column0 => 'foo' }, :column1, :column2, :column3)
+
+  # The tag type is a Ruby CFN extension. These tags are excised from the template and used to generate a series of --tag arguments
+  #   which are passed to cfn-cmd. They do not ultimately appear in the expanded Cloudformation template. The diff subcommand will
+  #   compare tags with the running stack and identify any changes, but cfn-update-stack will do the diff and throw an error on any
+  #   changes. The tags are propagated to all resources created by the stack, including the stack itself.
+  #
+  # Amazon has set the following restrictions on CloudFormation tags:
+  #   => limit 10
+  #   => immutable (you may not cfn-update-stack with new tags or different values for existing tags -- they will be rejected)
+  #
+  # Additionally, cfn-cmd throws an error if your tag value contains spaces. This limitation will be lifted when we move from cfn-cmd
+  #   to the new unified CLI.
+  tag :MyTag => 'MyValue'
+
+  resource 'SecurityGroup', :Type => 'AWS::EC2::SecurityGroup', :Properties => {
+      :GroupDescription => 'Lets any vpc traffic in.',
+      :SecurityGroupIngress => {:IpProtocol => '-1', :FromPort => '0', :ToPort => '65535', :CidrIp => "10.0.0.0/8"}
+  }
+
+  resource "ASG", :Type => 'AWS::AutoScaling::AutoScalingGroup', :Properties => {
+      :AvailabilityZones => 'us-east-1',
+      :HealthCheckType => 'EC2',
+      :LaunchConfigurationName => ref('LaunchConfig'),
+      :MinSize => 1,
+      :MaxSize => 5,
+      :NotificationConfiguration => {
+          :TopicARN => ref('EmailSNSTopic'),
+          :NotificationTypes => %w(autoscaling:EC2_INSTANCE_LAUNCH autoscaling:EC2_INSTANCE_LAUNCH_ERROR autoscaling:EC2_INSTANCE_TERMINATE autoscaling:EC2_INSTANCE_TERMINATE_ERROR),
+      },
+      :Tags => [
+          {
+              :Key => 'Name',
+              # Grabs a value in an external map file.
+              :Value => find_in_map('TableExampleMap', 'corge', 'grault'),
+              :PropagateAtLaunch => 'true',
+          },
+          {
+              :Key => 'Label',
+              :Value => parameters['Label'],
+              :PropagateAtLaunch => 'true',
+          }
+      ],
+  }
+
+  resource 'EmailSNSTopic', :Type => 'AWS::SNS::Topic', :Properties => {
+      :Subscription => [
+          {
+              :Endpoint => ref('EmailAddress'),
+              :Protocol => 'email',
+          },
+      ],
+  }
+
+  resource 'WaitConditionHandle', :Type => 'AWS::CloudFormation::WaitConditionHandle', :Properties => {}
+
+  resource 'WaitCondition', :Type => 'AWS::CloudFormation::WaitCondition', :DependsOn => 'ASG', :Properties => {
+      :Handle => ref('WaitConditionHandle'),
+      :Timeout => 1200,
+      :Count => "1"
+  }
+
+  resource 'LaunchConfig', :Type => 'AWS::AutoScaling::LaunchConfiguration', :Properties => {
+      :ImageId => parameters['ImageId'],
+      :KeyName => ref('KeyPairName'),
+      :IamInstanceProfile => ref('InstanceProfile'),
+      :InstanceType => ref('InstanceType'),
+      :InstanceMonitoring => 'false',
+      :SecurityGroups => [ref('SecurityGroup')],
+      :BlockDeviceMappings => [
+          {:DeviceName => '/dev/sdb', :VirtualName => 'ephemeral0'},
+          {:DeviceName => '/dev/sdc', :VirtualName => 'ephemeral1'},
+          {:DeviceName => '/dev/sdd', :VirtualName => 'ephemeral2'},
+          {:DeviceName => '/dev/sde', :VirtualName => 'ephemeral3'},
+      ],
+      # Loads an external userdata script.
+      :UserData => base64(interpolate(file('userdata.sh'))),
+  }
+
+  resource 'InstanceProfile', :Type => 'AWS::IAM::InstanceProfile', :Properties => {
+      :Path => '/',
+      :Roles => [ ref('InstanceRole') ],
+  }
+
+  resource 'InstanceRole', :Type => 'AWS::IAM::Role', :Properties => {
+      :AssumeRolePolicyDocument => {
+          :Statement => [
+              {
+                  :Effect => 'Allow',
+                  :Principal => { :Service => [ 'ec2.amazonaws.com' ] },
+                  :Action => [ 'sts:AssumeRole' ],
+              },
+          ],
+      },
+      :Path => '/',
+  }
+
+  output 'EmailSNSTopicARN',
+          :Value => ref('EmailSNSTopic'),
+          :Description => 'ARN of SNS Topic used to send emails on events.'
+
+  output 'MappingLookup',
+          :Value => find_in_map('TableExampleMap', 'corge', 'grault'),
+          :Description => 'An example map lookup.'
+
+end.exec!

data/examples/maps/json_map.json

@@ -0,0 +1,9 @@
+{
+    "Mappings": {
+        "bar": {
+            "foo": "bar"
+        }
+    }
+
+}
+

data/examples/maps/more_maps/map1.json

@@ -0,0 +1,8 @@
+{
+    "Mappings": {
+        "john": {
+            "gregory": "smith"
+        }
+    }
+
+}

data/examples/maps/more_maps/map2.json

@@ -0,0 +1,8 @@
+{
+    "Mappings": {
+        "gregory": {
+            "smith": "john"
+        }
+    }
+
+}

data/examples/maps/more_maps/map3.json

@@ -0,0 +1,8 @@
+{
+    "Mappings": {
+        "smith": {
+            "john": "gregory"
+        }
+    }
+
+}

data/examples/maps/ruby_map.rb

@@ -0,0 +1,5 @@
+{
+  'Mappings' => {
+    'blah' => { 'baz' => 'blah' }
+  }
+}

data/examples/maps/text_table.txt

@@ -0,0 +1,5 @@
+column0     column1     column2     column3     column4
+foo         baz         qux                     quux
+foo         corge       grault      garply
+bar         waldo       fred
+bar         plugh       xyzzy       thud

data/examples/maps/yaml_map.yaml

@@ -0,0 +1,5 @@
+---
+Mappings:
+  blah:
+    foo:
+      bar: yo

data/examples/userdata.sh

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+echo "put initialization script here"

data/initial_contributions.md

@@ -0,0 +1,3 @@
+Several people were instrumental in building this project during its incubation stage. Because the process of open sourcing involved squashing the repository to remove confidential information, some of their contributions have been lost from the history that Github displays.
+
+- [Nathaniel Eliot](https://github.com/temujin9): converted from raw library to gem, refactored table code, cleaned and prepared code for open sourcing

data/lib/cloudformation-ruby-dsl.rb

@@ -0,0 +1,2 @@
+require "cloudformation-ruby-dsl/version"
+

data/lib/cloudformation-ruby-dsl/cfntemplate.rb

@@ -0,0 +1,406 @@
+# Copyright 2013-2014 Bazaarvoice, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+unless RUBY_VERSION >= '1.9'
+  # This script uses Ruby 1.9 functions such as Enumerable.slice_before and Enumerable.chunk
+  $stderr.puts "This script requires ruby 1.9+.  On OS/X use Homebrew to install ruby 1.9:"
+  $stderr.puts "  brew install ruby"
+  exit(2)
+end
+
+require 'rubygems'
+require 'csv'
+require 'json'
+require 'yaml'
+require 'erb'
+
+# A custom converter to replace the String "(nil)" with NilClass
+CSV::Converters[:nil_to_nil] = lambda do |field|
+  field && field == '(nil)' ? nil : field
+end
+
+############################# Command-line and "cfn-cmd" Support
+
+# Parse command-line arguments based on cfn-cmd syntax (cfn-create-stack etc.) and return the parameters and region
+def cfn_parse_args
+  parameters = {}
+  region = 'us-east-1'
+  ARGV.slice_before(/^--/).each do |name, value|
+    next unless value
+    case name
+    when '--parameters'
+      parameters = Hash[value.split(/;/).map { |pair| pair.split(/=/, 2) }]
+    when '--region'
+      region = value
+    end
+  end
+  [parameters, region]
+end
+
+def cfn_cmd(template)
+  action = ARGV[0]
+  unless %w(expand diff cfn-validate-template cfn-create-stack cfn-update-stack).include? action
+    $stderr.puts "usage: #{$PROGRAM_NAME} <expand|diff|cfn-validate-template|cfn-create-stack|cfn-update-stack>"
+    exit(2)
+  end
+  unless (ARGV & %w(--template-file --template-url)).empty?
+    $stderr.puts "#{File.basename($PROGRAM_NAME)}:  The --template-file and --template-url command-line options are not allowed."
+    exit(2)
+  end
+
+  # Find parameters where extension attribute :Immutable is true then remove it from the
+  # cfn template since we can't pass it to CloudFormation.
+  immutable_parameters = template.excise_parameter_attribute!(:Immutable)
+
+  # Tag CloudFormation stacks based on :Tags defined in the template
+  cfn_tags = template.excise_tags!
+  # The command line string looks like: --tag "Key=key; Value=value" --tag "Key2=key2; Value2=value"
+  cfn_tags_options = cfn_tags.sort.map { |tag| ["--tag", "Key=%s; Value=%s" % tag.split('=')] }.flatten
+
+  template_string = JSON.pretty_generate(template)
+
+  # example: <template.rb> cfn-create-stack my-stack-name --parameters "Env=prod" --region eu-west-1
+  # Execute the AWS CLI cfn-cmd command to validate/create/update a CloudFormation stack.
+  temp_file = File.absolute_path("#{$PROGRAM_NAME}.expanded.json")
+  File.write(temp_file, template_string)
+
+  cmdline = ['cfn-cmd'] + ARGV + ['--template-file', temp_file] + cfn_tags_options
+
+  case action
+  when 'expand'
+    # Write the pretty-printed JSON template to stdout.
+    # example: <template.rb> expand --parameters "Env=prod" --region eu-west-1
+    puts template_string
+    
+    exit(true)
+
+  when 'diff'
+    # example: <template.rb> diff my-stack-name --parameters "Env=prod" --region eu-west-1
+    # Diff the current template for an existing stack with the expansion of this template.
+
+    # The --parameters and --tag options were used to expand the template but we don't need them anymore.  Discard.
+    _, cfn_options = extract_options(ARGV[1..-1], %w(), %w(--parameters --tag))
+
+    # Separate the remaining command-line options into options for 'cfn-cmd' and options for 'diff'.
+    cfn_options, diff_options = extract_options(cfn_options, %w(),
+      %w(--stack-name --region --parameters --connection-timeout -I --access-key-id -S --secret-key -K --ec2-private-key-file-path -U --url))
+
+    # If the first argument is a stack name then shift it from diff_options over to cfn_options.
+    if diff_options[0] && !(/^-/ =~ diff_options[0])
+      cfn_options.unshift(diff_options.shift)
+    end
+
+    # Run CloudFormation commands to describe the existing stack
+    cfn_options_string           = cfn_options.map { |arg| "'#{arg}'" }.join(' ')
+    old_template_string          = exec_capture_stdout("cfn-cmd cfn-get-template #{cfn_options_string}")
+    old_stack_attributes         = exec_describe_stack(cfn_options_string)
+    old_tags_string              = old_stack_attributes["TAGS"]
+    old_parameters_string        = old_stack_attributes["PARAMETERS"]
+
+    # Sort the tag strings alphabetically to make them easily comparable
+    old_tags_string = (old_tags_string || '').split(';').sort.map { |tag| %Q(TAG "#{tag}"\n) }.join
+    tags_string     = cfn_tags.sort.map { |tag| "TAG \"#{tag}\"\n" }.join
+
+    # Sort the parameter strings alphabetically to make them easily comparable
+    old_parameters_string = (old_parameters_string || '').split(';').sort.map { |param| %Q(PARAMETER "#{param}"\n) }.join
+    parameters_string     = template.parameters.sort.map { |key, value| "PARAMETER \"#{key}=#{value}\"\n" }.join
+
+    # Diff the expanded template with the template from CloudFormation.
+    old_temp_file = File.absolute_path("#{$PROGRAM_NAME}.current.json")
+    new_temp_file = File.absolute_path("#{$PROGRAM_NAME}.expanded.json")
+    File.write(old_temp_file, old_tags_string + old_parameters_string + old_template_string)
+    File.write(new_temp_file, tags_string + parameters_string + %Q(TEMPLATE  "#{template_string}\n"\n))
+
+    # Compare templates
+    system(*["diff"] + diff_options + [old_temp_file, new_temp_file])
+
+    File.delete(old_temp_file)
+    File.delete(new_temp_file)
+
+    exit(true)
+
+  when 'cfn-validate-template'
+    # The cfn-validate-template command doesn't support --parameters so remove it if it was provided for template expansion.
+    _, cmdline = extract_options(cmdline, %w(), %w(--parameters --tag))
+
+  when 'cfn-update-stack'
+    # Pick out the subset of cfn-update-stack options that apply to cfn-describe-stacks.
+    cfn_options, other_options = extract_options(ARGV[1..-1], %w(),
+      %w(--stack-name --region --connection-timeout -I --access-key-id -S --secret-key -K --ec2-private-key-file-path -U --url))
+
+    # If the first argument is a stack name then shift it over to cfn_options.
+    if other_options[0] && !(/^-/ =~ other_options[0])
+      cfn_options.unshift(other_options.shift)
+    end
+
+    # Run CloudFormation command to describe the existing stack
+    cfn_options_string = cfn_options.map { |arg| "'#{arg}'" }.join(' ')
+    old_stack_attributes = exec_describe_stack(cfn_options_string)
+
+    # If updating a stack and some parameters are marked as immutable, fail if the new parameters don't match the old ones.
+    if not immutable_parameters.empty?
+      old_parameters_string = old_stack_attributes["PARAMETERS"]
+      old_parameters = Hash[(old_parameters_string || '').split(';').map { |pair| pair.split('=', 2) }]
+      new_parameters = template.parameters
+
+      immutable_parameters.sort.each do |param|
+        if old_parameters[param].to_s != new_parameters[param].to_s
+          $stderr.puts "Error: cfn-update-stack may not update immutable parameter " +
+                           "'#{param}=#{old_parameters[param]}' to '#{param}=#{new_parameters[param]}'."
+          exit(false)
+        end
+      end
+    end
+
+    # Tags are immutable in CloudFormation.  The cfn-update-stack command doesn't support --tag options, so remove
+    # the argument (if it exists) and validate against the existing stack to ensure tags haven't changed.
+    # Compare the sorted arrays for an exact match
+    old_cfn_tags = old_stack_attributes['TAGS'].split(';').sort rescue [] # Use empty Array if .split fails
+    if cfn_tags != old_cfn_tags
+      $stderr.puts "CloudFormation stack tags do not match and cannot be updated. You must either use the same tags or create a new stack." +
+                      "\n" + (old_cfn_tags - cfn_tags).map {|tag| "< #{tag}" }.join("\n") +
+                      "\n" + "---" +
+                      "\n" + (cfn_tags - old_cfn_tags).map {|tag| "> #{tag}"}.join("\n")
+      exit(false)
+    end
+    _, cmdline = extract_options(cmdline, %w(), %w(--tag))
+  end
+
+  # Execute command cmdline
+  unless system(*cmdline)
+    $stderr.puts "\nExecution of 'cfn-cmd' failed.  To facilitate debugging, the generated JSON template " +
+                     "file was not deleted.  You may delete the file manually if it isn't needed: #{temp_file}"
+    exit(false)
+  end
+
+  File.delete(temp_file)
+
+  exit(true)
+end
+
+def exec_describe_stack cfn_options_string
+  csv_data = exec_capture_stdout("cfn-cmd cfn-describe-stacks #{cfn_options_string} --headers --show-long")
+  CSV.parse_line(csv_data, :headers => true, :converters => :nil_to_nil)
+end
+
+def exec_capture_stdout command
+  stdout = `#{command}`
+  unless $?.success?
+    $stderr.puts stdout unless stdout.empty?  # cfn-cmd sometimes writes error messages to stdout
+    exit(false)
+  end
+  stdout
+end
+
+def extract_options(args, opts_no_val, opts_1_val)
+  args = args.clone
+  opts = []
+  rest = []
+  while (arg = args.shift) != nil
+    if opts_no_val.include?(arg)
+      opts.push(arg)
+    elsif opts_1_val.include?(arg)
+      opts.push(arg)
+      opts.push(arg) if (arg = args.shift) != nil
+    else
+      rest.push(arg)
+    end
+  end
+  [opts, rest]
+end
+
+############################# Generic DSL
+
+class JsonObjectDSL
+  def initialize(&block)
+    @dict = {}
+    instance_eval &block
+  end
+
+  def value(values)
+    @dict.update(values)
+  end
+
+  def default(key, value)
+    @dict[key] ||= value
+  end
+
+  def to_json(*args)
+    @dict.to_json(*args)
+  end
+
+  def print()
+    puts JSON.pretty_generate(self)
+  end
+end
+
+############################# CloudFormation DSL
+
+# Main entry point
+def template(&block)
+  TemplateDSL.new(&block)
+end
+
+# Core interpreter for the DSL
+class TemplateDSL < JsonObjectDSL
+  attr_reader :parameters, :aws_region
+
+  def initialize()
+    @parameters, @aws_region = cfn_parse_args
+    super
+  end
+
+  def exec!()
+    cfn_cmd(self)
+  end
+
+  def parameter(name, options)
+    default(:Parameters, {})[name] = options
+    @parameters[name] ||= options[:Default]
+  end
+
+  # Find parameters where the specified attribute is true then remove the attribute from the cfn template.
+  def excise_parameter_attribute!(attribute)
+    marked_parameters = []
+    @dict.fetch(:Parameters, {}).each do |param, options|
+      if options.delete(attribute.to_sym) or options.delete(attribute.to_s)
+        marked_parameters << param
+      end
+    end
+    marked_parameters
+  end
+
+  def mapping(name, options)
+    # if options is a string and a valid file then the script will process the external file.
+    default(:Mappings, {})[name] = \
+      if options.is_a?(Hash); options
+      elsif options.is_a?(String); load_from_file(options)['Mappings']
+      else; raise("Options for mapping #{name} is neither a string or a hash.  Error!")
+    end
+  end
+
+  def load_from_file(filename)
+    file = File.open(filename)
+
+    begin
+      # Figure out what the file extension is and process accordingly.
+      contents = case File.extname(filename)
+        when ".rb"; eval(file.read)
+        when ".json"; JSON.load(file)
+        when ".yaml"; YAML::load(file)
+        else; raise("Do not recognize extension of #{filename}.")
+      end
+    ensure
+      file.close
+    end
+    contents
+  end
+
+  def excise_tags!
+    tags = []
+    @dict.fetch(:Tags, {}).each do | tag_name, tag_value |
+      tags << "#{tag_name}=#{tag_value}"
+    end
+    @dict.delete(:Tags)
+    tags
+  end
+
+  def tag(tag)
+    tag.each do | name, value |
+      default(:Tags, {})[name] = value
+    end
+  end
+
+  def condition(name, options) default(:Conditions, {})[name] = options end
+
+  def resource(name, options) default(:Resources, {})[name] = options end
+
+  def output(name, options) default(:Outputs, {})[name] = options end
+
+  def find_in_map(map, key, name)
+    # Eagerly evaluate mappings when all keys are known at template expansion time
+    if map.is_a?(String) && key.is_a?(String) && name.is_a?(String)
+      # We don't know whether the map was built with string keys or symbol keys.  Try both.
+      def get(map, key) map[key] || map.fetch(key.to_sym) end
+      get(get(@dict.fetch(:Mappings).fetch(map), key), name)
+    else
+      { :'Fn::FindInMap' => [ map, key, name ] }
+    end
+  end
+end
+
+def base64(value) { :'Fn::Base64' => value } end
+
+def find_in_map(map, key, name) { :'Fn::FindInMap' => [ map, key, name ] } end
+
+def get_att(resource, attribute) { :'Fn::GetAtt' => [ resource, attribute ] } end
+
+def get_azs(region = '') { :'Fn::GetAZs' => region } end
+
+def join(delim, *list)
+  case list.length
+    when 0 then ''
+    when 1 then list[0]
+    else join_list(delim,list)
+  end
+end
+
+# Variant of join that matches the native CFN syntax.
+def join_list(delim, list) { :'Fn::Join' => [ delim, list ] } end
+
+def select(index, list) { :'Fn::Select' => [ index, list ] } end
+
+def ref(name) { :Ref => name } end
+
+def no_value() ref("AWS::NoValue") end
+
+# Read the specified file and return its value as a string literal
+def file(filename) File.read(File.absolute_path(filename, File.dirname($PROGRAM_NAME))) end
+
+# Interpolates a string like "NAME={{ref('Service')}}" and returns a CloudFormation "Fn::Join"
+# operation to collect the results.  Anything between {{ and }} is interpreted as a Ruby expression
+# and eval'd.  This is especially useful with Ruby "here" documents.
+def interpolate(string)
+  list = []
+  while string.length > 0
+    head, match, string = string.partition(/\{\{.*?\}\}/)
+    list << head if head.length > 0
+    list << eval(match[2..-3]) if match.length > 0
+  end
+
+  # Split out strings in an array by newline, for visibility
+  list = list.flat_map {|value| value.is_a?(String) ? value.lines.to_a : value }
+  join('', *list)
+end
+
+def join_interpolate(delim, string)
+  $stderr.puts "join_interpolate(delim,string) has been deprecated; use interpolate(string) instead"
+  interpolate(string)
+end
+
+# This class is used by erb templates so they can access the parameters passed
+class Namespace
+  attr_accessor :params
+  def initialize(hash)
+    @params = hash
+  end
+  def get_binding
+    binding
+  end
+end
+
+# Combines the provided ERB template with optional parameters
+def erb_template(filename, params = {})
+  ERB.new(file(filename), nil, '-').result(Namespace.new(params).get_binding)
+end