cloudformation-ruby-dsl-addedvars 1.2.4

data/cloudformation-ruby-dsl-addedvars.gemspec

@@ -0,0 +1,42 @@
+# -*- 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-addedvars/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "cloudformation-ruby-dsl-addedvars"
+  gem.version       = Cfn::Ruby::Dsl::VERSION
+  gem.authors       = ["Shawn Smith", "Dave Barcelo", "Morgan Fletcher", "Csongor Gyuricza", "Igor Polishchuk", "Nathaniel Eliot", "Jona Fenocchi", "Tony Cui", 'Troy Ready']
+  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", 'troy@troyready.com']
+  gem.description   = %q{Ruby DSL library that provides a wrapper around the CloudFormation.}
+  gem.summary       = %q{Ruby DSL library that provides a wrapper around the CloudFormation.  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'
+  gem.add_runtime_dependency    'json'
+  gem.add_runtime_dependency    'bundler'
+  gem.add_runtime_dependency    'aws-sdk'
+  gem.add_runtime_dependency    'diffy'
+  gem.add_runtime_dependency    'highline'
+  gem.add_runtime_dependency    'rake'
+end

data/docs/Contributing.md

@@ -0,0 +1,21 @@
+# Contributing
+
+Thanks for your interest in contributing! Here are some things you should know.
+
+## Getting started
+
+To get started:
+
+- fork this project on github
+- create a new branch named after the change you want to make; i.e., `git checkout -b mynewfeature`
+- make your changes and commit them
+- send a pull request to this project from your fork/branch
+
+Once you've sent your pull request, one of the project collaborators will review it and provide feedback. Please accept this commentary as constructive! It is intended as such.
+
+## git
+
+We're opinionated about git. Don't be surprised if we ask you to update your pull request to meet the following standards.
+
+- rebase+squash your branch into a single commit. For clean git history, we'd prefer we merged in just 1 commit that contains the entire set of changes.
+- don't write commit messages longer than 50 characters. See [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/) for some examples of how to achieve this, and why.

data/docs/Releasing.md

@@ -0,0 +1,20 @@
+# Releasing
+
+## Performing releases
+
+0. Merge the desired commits to master. But merge them cleanly! See: [merging](#merging)
+1. Edit and commit the version file in `lib/cloudformation-ruby-dsl-addedvars/version.rb`. Bump the version based on the [version specification](#versioning-specification)
+2. `git push` to origin/master
+3. `rake release`
+
+## Versioning specification
+
+For this project, we will follow the methodology proposed by http://semver.org/spec/v2.0.0.html.
+
+1. Major versions break existing interfaces.
+2. Minor versions are additive only.
+3. Patch versions are for backward-compatible bug fixes.
+
+## Merging
+
+When you use the shiny green "Merge" button on a pull request, github creates a separate commit for the merge (because of the use of the `--no-ff` option). This is noisy and makes git history confusing. Instead of using the green merge button, merge the branch into master using [git-land](https://github.com/bazaarvoice/git-land#git-land) (or manually follow the steps described in the project).

data/examples/cloudformation-ruby-script.rb

@@ -0,0 +1,232 @@
+#!/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-addedvars/cfntemplate'
+require 'cloudformation-ruby-dsl-addedvars/table'
+
+# Note: this is only intended to demonstrate the cloudformation-ruby-dsl-addedvars. 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> update ...'
+            # 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/map.json'
+
+  mapping 'RubyExampleMap', 'maps/map.rb'
+
+  mapping 'YamlExampleMap', 'maps/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/table.txt'
+  mapping 'TableExampleMap',
+      text.get_map({ :column0 => 'foo' }, :column1, :column2, :column3)
+
+  # Shows how to create a table useful for looking up subnets that correspond to a particular env/region for eg. vpc placement.
+  vpc = Table.load 'maps/vpc.txt'
+  mapping 'TableExampleMultimap',
+          vpc.get_multimap({ :visibility => 'private', :zone => ['a', 'c'] }, :env, :region, :subnet)
+
+  # Shows how to use a table for iterative processing.
+  domains = Table.load 'maps/domains.txt'
+  domains.get_multihash(:purpose, {:product => 'demo', :alias => 'true'}, :prefix, :target, :alias_hosted_zone_id).each_pair do |key, value|
+    resource key+'Route53RecordSet', :Type => 'AWS::Route53::RecordSet', :Properties => {
+        :Comment => '',
+        :HostedZoneName => 'bazaarvoice.com',
+        :Name => value[:prefix]+'.bazaarvoice.com',
+        :Type => 'A',
+        :AliasTarget => {
+          :DNSName => value[:target],
+          :HostedZoneId => value[:alias_hosted_zone_id]
+        }
+    }
+  end
+
+
+  # The tag type is a DSL extension; it is not a property of actual CloudFormation templates.
+  #   These tags are excised from the template and used to generate a series of --tag arguments
+  #   which are passed to CloudFormation when a stack is created.
+  #   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 a stack update will do the diff and throw an error on any immutable tags update attempt.
+  #   The tags are propagated to all resources created by the stack, including the stack itself.
+  #   If a resource has its own tag with the same name as CF's it's not overwritten.
+  #
+  # Amazon has set the following restrictions on CloudFormation tags:
+  #   => limit 10
+  # CloudFormation tags declaration examples:
+
+  tag 'My:New:Tag',
+      :Value => 'ImmutableTagValue',
+      :Immutable => true
+
+  tag :MyOtherTag,
+      :Value => 'My Value With Spaces'
+
+  tag(:"tag:name", :Value => 'tag_value', :Immutable => true)
+
+  # Following format is deprecated and not advised. Please declare CloudFormation tags as described above.
+  tag :TagName => 'tag_value'    # It's immutable.
+
+  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 with an interpolated argument.
+      :UserData => base64(interpolate(file('userdata.sh'), time: Time.now)),
+  }
+
+  resource 'InstanceProfile', :Type => 'AWS::IAM::InstanceProfile', :Properties => {
+      # use cfn intrinsic conditional to choose the 2nd value because the expression evaluates to false
+      :Path => fn_if(equal(3, 0), '/unselected/', '/'),
+      :Roles => [ ref('InstanceRole') ],
+  }
+
+  resource 'InstanceRole', :Type => 'AWS::IAM::Role', :Properties => {
+      :AssumeRolePolicyDocument => {
+          :Statement => [
+              {
+                  :Effect => 'Allow',
+                  :Principal => { :Service => [ 'ec2.amazonaws.com' ] },
+                  :Action => [ 'sts:AssumeRole' ],
+              },
+          ],
+      },
+      :Path => '/',
+  }
+
+  # add conditions that can be used elsewhere in the template
+  condition 'myCondition', fn_and(equal("one", "two"), not_equal("three", "four"))
+
+  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/domains.txt

@@ -0,0 +1,4 @@
+purpose             product    prefix                     target                         alias  alias_hosted_zone_id  has_origin_domain  origin_target
+CDN                 demo       code                       dabc123.cloudfront.net         true   Z2FDTNDATAQYW2        false
+Assets              demo       assets                     ddef456.cloudfront.net         true   Z2FDTNDATAQYW2        false
+API                 demo       api                        prod-api                       false                        false              prod-api-origin.whatever.net.

data/examples/maps/map.json

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

data/examples/maps/map.rb

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

data/examples/maps/map.yaml

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

data/examples/maps/more_maps/map1.json

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

data/examples/maps/more_maps/map2.json

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

data/examples/maps/more_maps/map3.json

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

data/examples/maps/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/vpc.txt

@@ -0,0 +1,25 @@
+env    region      zone   visibility   subnet
+qa     us-east-1   a      public       subnet-aaaa
+qa     us-east-1   a      private      subnet-bbbb
+qa     us-east-1   b      public       subnet-cccc
+qa     us-east-1   b      private      subnet-dddd
+qa     us-east-1   c      public       subnet-eeee
+qa     us-east-1   c      private      subnet-ffff
+qa     eu-west-1   a      public       subnet-gggg
+qa     eu-west-1   a      private      subnet-hhhh
+qa     eu-west-1   b      public       subnet-iiii
+qa     eu-west-1   b      private      subnet-jjjj
+qa     eu-west-1   c      public       subnet-kkkk
+qa     eu-west-1   c      private      subnet-llll
+prod   us-east-1   a      public       subnet-mmmm
+prod   us-east-1   a      private      subnet-nnnn
+prod   us-east-1   b      public       subnet-oooo
+prod   us-east-1   b      private      subnet-pppp
+prod   us-east-1   c      public       subnet-qqqq
+prod   us-east-1   c      private      subnet-rrrr
+prod   eu-west-1   a      public       subnet-ssss
+prod   eu-west-1   a      private      subnet-tttt
+prod   eu-west-1   b      public       subnet-uuuu
+prod   eu-west-1   b      private      subnet-vvvv
+prod   eu-west-1   c      public       subnet-wwww
+prod   eu-west-1   c      private      subnet-xxxx

data/examples/userdata.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+echo "put initialization script here"
+echo "the time is {{ locals[:time] }}"
+echo "the aws region is {{ ref('AWS::Region') }}"

data/initial_contributions.md

@@ -0,0 +1,5 @@
+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.
+
+- [Shawn Smith](https://github.com/shawnsmith): initial implementation
+- [Nathaniel Eliot](https://github.com/temujin9): converted from raw library to gem, refactored table code, cleaned and prepared code for open sourcing
+- [Jona Fenocchi](http://github.com/jonaf): added support for CloudFormation tags

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

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

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

@@ -0,0 +1,595 @@
+# 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 'cloudformation-ruby-dsl-addedvars/dsl'
+
+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 'json'
+require 'yaml'
+require 'erb'
+require 'aws-sdk'
+require 'diffy'
+require 'highline/import'
+
+############################# AWS SDK Support
+
+class AwsCfn
+  attr_accessor :cfn_client_instance
+
+  def initialize(args)
+    Aws.config[:region] = args[:region] if args.key?(:region)
+    Aws.config[:credentials] = Aws::SharedCredentials.new(profile_name: args[:aws_profile]) unless args[:aws_profile].nil?
+  end
+
+  def cfn_client
+    if @cfn_client_instance == nil
+        # credentials are loaded from the environment; see http://docs.aws.amazon.com/sdkforruby/api/Aws/CloudFormation/Client.html
+        @cfn_client_instance = Aws::CloudFormation::Client.new(
+        # we don't validate parameters because the aws-ruby-sdk gets a number parameter and expects it to be a string and fails the validation
+        # see: https://github.com/aws/aws-sdk-ruby/issues/848
+        validate_params: false
+      )
+    end
+    @cfn_client_instance
+  end
+end
+
+# utility class to deserialize Structs as JSON
+# borrowed from http://ruhe.tumblr.com/post/565540643/generate-json-from-ruby-struct
+class Struct
+  def to_map
+    map = Hash.new
+    self.members.each { |m| map[m] = self[m] }
+    map
+  end
+
+  def to_json(*a)
+    to_map.to_json(*a)
+  end
+end
+
+############################# Command-line support
+
+# Parse command-line arguments and return the parameters and region
+def parse_args
+  stack_name = nil
+  parameters = {}
+  region     = default_region
+  profile    = nil
+  nopretty   = false
+  ARGV.slice_before(/^--/).each do |name, value|
+    case name
+    when '--stack-name'
+      stack_name = value
+    when '--parameters'
+      parameters = Hash[value.split(/;/).map { |pair| pair.split(/=/, 2) }]  #/# fix for syntax highlighting
+      parameters = $stack_params.merge(parameters) if $stack_params
+    when '--region'
+      region = value
+      # Because of the use of global variables here and below, here we
+      # must ensure the command-line set version isn't overridden
+      $aws_region = nil
+    when '--profile'
+      profile = value
+    when '--nopretty'
+      nopretty = true
+    end
+  end
+  # Allow these same settings to be set without using the command-line flags
+  stack_name ||= $stack_name
+  parameters = $stack_params if parameters == {} && $stack_params
+  profile    ||= $aws_profile
+  region     = $aws_region unless $aws_region == nil
+  [stack_name, parameters, region, profile, nopretty]
+end
+
+def validate_action(action)
+  valid = %w[
+    expand
+    diff
+    validate
+    create
+    update
+    cancel-update
+    delete
+    describe
+    describe-resource
+    get-template
+  ]
+  removed = %w[
+    cfn-list-stack-resources
+    cfn-list-stacks
+  ]
+  deprecated = {
+    "cfn-validate-template"        => "validate",
+    "cfn-create-stack"             => "create",
+    "cfn-update-stack"             => "update",
+    "cfn-cancel-update-stack"      => "cancel-update",
+    "cfn-delete-stack"             => "delete",
+    "cfn-describe-stack-events"    => "describe",
+    "cfn-describe-stack-resources" => "describe",
+    "cfn-describe-stack-resource"  => "describe-resource",
+    "cfn-get-template"             => "get-template"
+  }
+  if deprecated.keys.include? action
+    replacement = deprecated[action]
+    $stderr.puts "WARNING: '#{action}' is deprecated and will be removed in a future version. Please use '#{replacement}' instead."
+    action = replacement
+  end
+  unless valid.include? action
+    if removed.include? action
+      $stderr.puts "ERROR: native command #{action} is no longer supported by cloudformation-ruby-dsl-addedvars."
+    end
+    $stderr.puts "usage: #{$PROGRAM_NAME} <#{valid.join('|')}>"
+    exit(2)
+  end
+  action
+end
+
+def cfn(template)
+  aws_cfn = AwsCfn.new({:region => template.aws_region, :aws_profile => template.aws_profile})
+  cfn_client = aws_cfn.cfn_client
+
+  # Validate the stack action, whether setup via command line or global options
+  action = validate_action( ARGV[0].class == String ? ARGV[0] : $cf_action )
+
+  # 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)
+
+  # Find parameters where extension attribute :UsePreviousValue is true then
+  # remove it from the cfn template since it's sent as a special option.
+  use_prev_val_params = template.excise_parameter_attribute!(:UsePreviousValue)
+
+  # Tag CloudFormation stacks based on :Tags defined in the template.
+  # Remove them from the template as well, so that the template is valid.
+  cfn_tags = template.excise_tags!
+
+  # Find tags where extension attribute `:Immutable` is true then remove it from the
+  # tag's properties hash since it can't be passed to CloudFormation.
+  immutable_tags = template.get_tag_attribute(cfn_tags, :Immutable)
+
+  cfn_tags.each {|k, v| cfn_tags[k] = v[:Value].to_s}
+
+  if action == 'diff' or (action == 'expand' and not template.nopretty)
+    template_string = JSON.pretty_generate(template)
+  else
+    template_string = JSON.generate(template)
+  end
+
+  # Derive stack name from ARGV
+  _, options = extract_options(ARGV[1..-1], %w(--nopretty), %w(--profile --stack-name --region --parameters --tag))
+  # If the first argument is not an option and stack_name is undefined, assume it's the stack name
+  # The second argument, if present, is the resource name used by the describe-resource command
+  if template.stack_name.nil?
+    stack_name = options.shift if options[0] && !(/^-/ =~ options[0])
+    resource_name = options.shift if options[0] && !(/^-/ =~ options[0])
+  else
+    stack_name = template.stack_name
+  end
+
+  case action
+  when 'expand'
+    # Write the pretty-printed JSON template to stdout and exit.  [--nopretty] option writes output with minimal whitespace
+    # example: <template.rb> expand --parameters "Env=prod" --region eu-west-1 --nopretty
+    if template.nopretty
+      puts template_string
+    else
+      puts template_string
+    end
+    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.
+
+    # `diff` operation exit codes are:
+      # 0 - no differences are found. Outputs nothing to make it easy to use the output of the diff call from within other scripts.
+      # 1 - produced by any ValidationError exception (e.g. "Stack with id does not exist")
+      # 2 - there are changes to update (tags, params, template)
+    # If you want output of the entire file, simply use this option with a large number, i.e., -U 10000
+    # In fact, this is what Diffy does by default; we just don't want that, and we can't support passing arbitrary options to diff
+    # because Diffy's "context" configuration is mutually exclusive with the configuration to pass arbitrary options to diff
+    if !options.include? '-U'
+      options.push('-U', '0')
+    end
+
+    # Ensure a stack name was provided
+    if stack_name.empty?
+      $stderr.puts "Error: a stack name is required"
+      exit(false)
+    end
+
+    # describe the existing stack
+    begin
+      old_template_body = cfn_client.get_template({stack_name: stack_name}).template_body
+    rescue Aws::CloudFormation::Errors::ValidationError => e
+      $stderr.puts "Error: #{e}"
+      exit(false)
+    end
+
+    # parse the string into a Hash, then convert back into a string; this is the only way Ruby JSON lets us pretty print a JSON string
+    old_template   = JSON.pretty_generate(JSON.parse(old_template_body))
+    # there is only ever one stack, since stack names are unique
+    old_attributes = cfn_client.describe_stacks({stack_name: stack_name}).stacks[0]
+    old_tags       = old_attributes.tags
+    old_parameters = old_attributes.parameters
+
+    # Sort the tag strings alphabetically to make them easily comparable
+    old_tags_string = old_tags.map { |tag| %Q(TAG "#{tag.key}=#{tag.value}"\n) }.sort.join
+    tags_string     = cfn_tags.map { |k, v| %Q(TAG "#{k.to_s}=#{v}"\n) }.sort.join
+
+    # For any parameters to to UsePreviousValue, ensure here that they don't
+    # show up on the diff report by setting their template value to match the
+    # current stack value
+    template_diff_params = template.parameters
+    use_prev_val_params.each do |p|
+      template_diff_params[p] = (old_parameters.find {|i| i.parameter_key == p}).parameter_value
+    end if !use_prev_val_params.nil?
+
+    # Sort the parameter strings alphabetically to make them easily comparable
+    old_parameters_string = old_parameters.sort! {|pCurrent, pNext| pCurrent.parameter_key <=> pNext.parameter_key }.map { |param| %Q(PARAMETER "#{param.parameter_key}=#{param.parameter_value}"\n) }.join
+    parameters_string     = template_diff_params.sort.map { |key, value| "PARAMETER \"#{key}=#{value}\"\n" }.join
+
+    # set default diff options
+    Diffy::Diff.default_options.merge!(
+      :diff    => "#{options.join(' ')}",
+    )
+    # set default diff output
+    Diffy::Diff.default_format = :color
+
+    tags_diff     = Diffy::Diff.new(old_tags_string, tags_string).to_s.strip!
+    params_diff   = Diffy::Diff.new(old_parameters_string, parameters_string).to_s.strip!
+    template_diff = Diffy::Diff.new(old_template, template_string).to_s.strip!
+
+    if !tags_diff.empty?
+      puts "====== Tags ======"
+      puts tags_diff
+      puts "=================="
+      puts
+    end
+
+    if !params_diff.empty?
+      puts "====== Parameters ======"
+      puts params_diff
+      puts "========================"
+      puts
+    end
+
+    if !template_diff.empty?
+      puts "====== Template ======"
+      puts template_diff
+      puts "======================"
+      puts
+    end
+
+    if tags_diff.empty? && params_diff.empty? && template_diff.empty?
+      exit(true)
+    else
+      exit(2)
+    end
+
+  when 'validate'
+    begin
+      valid = cfn_client.validate_template({template_body: template_string})
+      if valid.successful?
+        puts "Validation successful"
+        exit(true)
+      end
+    rescue Aws::CloudFormation::Errors::ValidationError => e
+      $stderr.puts "Validation error: #{e}"
+      exit(false)
+    end
+
+  when 'create'
+    begin
+
+      # default options (not overridable)
+      create_stack_opts = {
+          stack_name: stack_name,
+          template_body: template_string,
+          parameters: template.parameters.map { |k,v| {parameter_key: k, parameter_value: v}}.to_a,
+          tags: cfn_tags.map { |k,v| {"key" => k.to_s, "value" => v} }.to_a,
+          capabilities: ["CAPABILITY_IAM"],
+      }
+
+      # fill in options from the command line
+      extra_options = parse_arg_array_as_hash(options)
+      create_stack_opts = extra_options.merge(create_stack_opts)
+
+      # create stack
+      create_result = cfn_client.create_stack(create_stack_opts)
+      if create_result.successful?
+        puts create_result.stack_id
+        exit(true)
+      end
+    rescue Aws::CloudFormation::Errors::ServiceError => e
+      $stderr.puts "Failed to create stack: #{e}"
+      exit(false)
+    end
+
+  when 'cancel-update'
+    begin
+      cancel_update_result = cfn_client.cancel_update_stack({stack_name: stack_name})
+      if cancel_update_result.successful?
+        $stderr.puts "Canceled updating stack #{stack_name}."
+        exit(true)
+      end
+    rescue Aws::CloudFormation::Errors::ServiceError => e
+      $stderr.puts "Failed to cancel updating stack: #{e}"
+      exit(false)
+    end
+
+  when 'delete'
+    begin
+      if HighLine.agree("Really delete #{stack_name} in #{cfn_client.config.region}? [Y/n]")
+        delete_result = cfn_client.delete_stack({stack_name: stack_name})
+        if delete_result.successful?
+          $stderr.puts "Deleted stack #{stack_name}."
+          exit(true)
+        end
+      else
+        $stderr.puts "Canceled deleting stack #{stack_name}."
+        exit(true)
+      end
+      rescue Aws::CloudFormation::Errors::ServiceError => e
+        $stderr.puts "Failed to delete stack: #{e}"
+        exit(false)
+    end
+
+  when 'describe'
+    begin
+      describe_stack = cfn_client.describe_stacks({stack_name: stack_name})
+      describe_stack_resources = cfn_client.describe_stack_resources({stack_name: stack_name})
+      if describe_stack.successful? and describe_stack_resources.successful?
+        stacks = {}
+        stack_resources = {}
+        describe_stack_resources.stack_resources.each { |stack_resource|
+          if stack_resources[stack_resource.stack_name].nil?
+            stack_resources[stack_resource.stack_name] = []
+          end
+          stack_resources[stack_resource.stack_name].push({
+            logical_resource_id: stack_resource.logical_resource_id,
+            physical_resource_id: stack_resource.physical_resource_id,
+            resource_type: stack_resource.resource_type,
+            timestamp: stack_resource.timestamp,
+            resource_status: stack_resource.resource_status,
+            resource_status_reason: stack_resource.resource_status_reason,
+            description: stack_resource.description,
+          })
+        }
+        describe_stack.stacks.each { |stack| stacks[stack.stack_name] = stack.to_map.merge!({resources: stack_resources[stack.stack_name]}) }
+        unless template.nopretty
+          puts JSON.pretty_generate(stacks)
+        else
+          puts JSON.generate(stacks)
+        end
+        exit(true)
+      end
+    rescue Aws::CloudFormation::Errors::ServiceError => e
+      $stderr.puts "Failed describe stack #{stack_name}: #{e}"
+      exit(false)
+    end
+
+  when 'describe-resource'
+    begin
+      describe_stack_resource = cfn_client.describe_stack_resource({
+        stack_name: stack_name,
+        logical_resource_id: resource_name,
+      })
+      if describe_stack_resource.successful?
+        unless template.nopretty
+          puts JSON.pretty_generate(describe_stack_resource.stack_resource_detail)
+        else
+          puts JSON.generate(describe_stack_resource.stack_resource_detail)
+        end
+        exit(true)
+      end
+    rescue Aws::CloudFormation::Errors::ServiceError => e
+      $stderr.puts "Failed get stack resource details: #{e}"
+      exit(false)
+    end
+
+  when 'get-template'
+    begin
+      get_template_result = cfn_client.get_template({stack_name: stack_name})
+      template_body = JSON.parse(get_template_result.template_body)
+      if get_template_result.successful?
+        unless template.nopretty
+          puts JSON.pretty_generate(template_body)
+        else
+          puts JSON.generate(template_body)
+        end
+        exit(true)
+      end
+    rescue Aws::CloudFormation::Errors::ServiceError => e
+      $stderr.puts "Failed get stack template: #{e}"
+      exit(false)
+    end
+
+  when 'update'
+
+    # Run CloudFormation command to describe the existing stack
+    old_stack = cfn_client.describe_stacks({stack_name: stack_name}).stacks
+
+    # this might happen if, for example, stack_name is an empty string and the Cfn client returns ALL stacks
+    if old_stack.length > 1
+      $stderr.puts "Error: found too many stacks with this name. There should only be one."
+      exit(false)
+    else
+      # grab the first (and only) result
+      old_stack = old_stack[0]
+    end
+
+    # If updating a stack and some parameters or tags are marked as immutable, set the variable to true.
+    immutables_exist = nil 
+
+    if not immutable_parameters.empty?
+      old_parameters = Hash[old_stack.parameters.map { |p| [p.parameter_key, p.parameter_value]}]
+      new_parameters = template.parameters
+      immutable_parameters.sort.each do |param|
+        if old_parameters[param].to_s != new_parameters[param].to_s && old_parameters.key?(param)
+          $stderr.puts "Error: unable to update immutable parameter " +
+                           "'#{param}=#{old_parameters[param]}' to '#{param}=#{new_parameters[param]}'."
+          immutables_exist = true
+        end
+      end
+    end
+
+    if not immutable_tags.empty?
+      old_cfn_tags = Hash[old_stack.tags.map { |t| [t.key, t.value]}]
+      cfn_tags_ary = Hash[cfn_tags.map { |k,v| [k, v]}]
+      immutable_tags.sort.each do |tag|
+        if old_cfn_tags[tag].to_s != cfn_tags_ary[tag].to_s && old_cfn_tags.key?(tag)
+          $stderr.puts "Error: unable to update immutable tag " +
+                           "'#{tag}=#{old_cfn_tags[tag]}' to '#{tag}=#{cfn_tags_ary[tag]}'."
+          immutables_exist = true
+        end
+      end
+    end
+
+    # Fail if some parameters or tags were marked as immutable.
+    if immutables_exist
+      exit(false)
+    end
+
+    # Compare the sorted arrays of parameters for an exact match and print difference.
+    old_parameters = old_stack.parameters.map { |p| [p.parameter_key, p.parameter_value]}.sort
+    new_parameters = template.parameters.sort
+    if new_parameters != old_parameters
+      puts "\nCloudFormation stack parameters that do not match and will be updated:" +
+               "\n" + (old_parameters - new_parameters).map {|param| "< #{param}" }.join("\n") +
+               "\n" + "---" +
+               "\n" + (new_parameters - old_parameters).map {|param| "> #{param}"}.join("\n")
+    end
+
+    # Compare the sorted arrays of tags for an exact match and print difference.
+    old_cfn_tags = old_stack.tags.map { |t| [t.key, t.value]}.sort
+    cfn_tags_ary = cfn_tags.map { |k,v| [k, v]}.sort
+    if cfn_tags_ary != old_cfn_tags
+      puts "\nCloudFormation stack tags that do not match and will be updated:" +
+               "\n" + (old_cfn_tags - cfn_tags_ary).map {|tag| "< #{tag}" }.join("\n") +
+               "\n" + "---" +
+               "\n" + (cfn_tags_ary - old_cfn_tags).map {|tag| "> #{tag}"}.join("\n")
+    end
+
+    # update the stack
+    begin
+
+      # default options (not overridable)
+      update_stack_opts = {
+          stack_name: stack_name,
+          template_body: template_string,
+          parameters: template.parameters.map { |k,v| {parameter_key: k, parameter_value: v}}.to_a,
+          tags: cfn_tags.map { |k,v| {"key" => k.to_s, "value" => v.to_s} }.to_a,
+          capabilities: ["CAPABILITY_IAM"],
+      }
+
+      # For any parameter previously set to UsePreviousValue, set that option
+      use_prev_val_params.each do |p|
+        index = update_stack_opts[:parameters].index (update_stack_opts[:parameters].find {|k| k[:parameter_key] == p})
+        update_stack_opts[:parameters][index][:use_previous_value] = true
+        update_stack_opts[:parameters][index].delete :parameter_value
+      end if !use_prev_val_params.nil?
+
+      # fill in options from the command line
+      extra_options = parse_arg_array_as_hash(options)
+      update_stack_opts = extra_options.merge(update_stack_opts)
+
+      # update the stack
+      update_result = cfn_client.update_stack(update_stack_opts)
+      if update_result.successful?
+        puts update_result.stack_id
+        exit(true)
+      end
+    rescue Aws::CloudFormation::Errors::ServiceError => e
+      $stderr.puts "Failed to update stack: #{e}"
+      exit(false)
+    end
+
+  end
+end
+
+# extract options and arguments from a command line string
+#
+# Example:
+#
+# desired, unknown = extract_options("arg1 --option withvalue --optionwithoutvalue", %w(--option), %w())
+#
+# puts desired => Array{"arg1", "--option", "withvalue"}
+# puts unknown => Array{}
+#
+# @param args
+#   the Array of arguments (split the command line string by whitespace)
+# @param opts_no_val
+#   the Array of options with no value, i.e., --force
+# @param opts_1_val
+#   the Array of options with exaclty one value, i.e., --retries 3
+# @returns
+#   an Array of two Arrays.
+#   The first array contains all the options that were extracted (both those with and without values) as a flattened enumerable.
+#   The second array contains all the options that were not extracted.
+def extract_options(args, opts_no_val, opts_1_val)
+  opts = []
+  rest = []
+  unless args == nil
+    args = args.clone
+    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
+  end
+  [opts, rest]
+end
+
+# convert an array of option strings to a hash
+# example input: ["--option", "value", "--optionwithnovalue"]
+# example output: {:option => "value", :optionwithnovalue: true}
+def parse_arg_array_as_hash(options)
+  result = {}
+  options.slice_before(/\A--[a-zA-Z_-]\S/).each { |o|
+      key = ((o[0].sub '--', '').gsub '-', '_').downcase.to_sym
+      value = if o.length > 1 then o.drop(1) else true end
+      value = value[0] if value.is_a?(Array) and value.length == 1
+      result[key] = value
+  }
+  result
+end
+
+##################################### Additional dsl logic
+# Core interpreter for the DSL
+class TemplateDSL < JsonObjectDSL
+  def exec!()
+    cfn(self)
+  end
+end
+
+# Main entry point
+def template(&block)
+  stack_name, parameters, aws_region, aws_profile, nopretty = parse_args
+  raw_template(parameters, stack_name, aws_region, aws_profile, nopretty, &block)
+end