cloudformation-dsl 0.1.0

data/cloudformation-dsl.gemspec

@@ -0,0 +1,37 @@
+# -*- 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-dsl/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "cloudformation-dsl"
+  gem.version       = CloudFormationDSL::VERSION
+  gem.authors       = ["Shawn Smith", "Dave Barcelo", "Morgan Fletcher", "Csongor Gyuricza", "Igor Polishchuk", "Nathaniel Eliot", "Jona Fenocchi", "Tony Cui", 'Ho-Sheng Hsiao']
+  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", 'talktohosh@gmail.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/hosh/cloudformation-dsl-rb"
+
+  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    'json'
+  gem.add_runtime_dependency    'bundler'
+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/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,204 @@
+#!/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> 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)
+
+  # 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
+  #   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 update a stack with new tags or different values for existing tags -- they will be rejected)
+  #
+  tag :MyTag => 'MyValue'
+  tag :MyOtherTag => 'My Value With Spaces'
+
+  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/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-dsl.rb

@@ -0,0 +1,14 @@
+require "cloudformation-dsl/version"
+
+module CloudFormationDSL
+  autoload :Template, 'cloudformation-dsl/template'
+  autoload :Helpers,  'cloudformation-dsl/helpers'
+
+  def self.describe(&block)
+    CloudFormationDSL::Template.new(&block)
+  end
+
+  def self.load_from(filename)
+    CloudFormationDSL::Template.new(filename)
+  end
+end

data/lib/cloudformation-dsl/helpers.rb

@@ -0,0 +1,118 @@
+module CloudFormationDSL
+  module Helpers
+    def load_from_file(filename)
+      file = File.open(filename)
+      # Figure out what the file extension is and process accordingly.
+      case File.extname(filename)
+      when ".rb"; eval(file.read, nil, filename)
+      when ".json"; JSON.load(file)
+      when ".yaml"; YAML::load(file)
+      else
+        raise("Do not recognize extension of #{filename}.")
+      end
+    ensure
+      file.close
+    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
+
+    # Formation helpers
+
+    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 equal(one, two) { :'Fn::Equals' => [one, two] } end
+
+    def fn_not(condition) { :'Fn::Not' => [condition] } end
+
+    def fn_or(*condition_list)
+      case condition_list.length
+      when 0..1 then raise "fn_or needs at least 2 items."
+      when 2..10 then  { :'Fn::Or' => condition_list }
+      else raise "fn_or needs a list of 2-10 items that evaluate to true/false."
+      end
+    end
+
+    def fn_and(*condition_list)
+      case condition_list.length
+      when 0..1 then raise "fn_and needs at least 2 items."
+      when 2..10 then  { :'Fn::And' => condition_list }
+      else raise "fn_and needs a list of 2-10 items that evaluate to true/false."
+      end
+    end
+
+    def fn_if(cond, if_true, if_false) { :'Fn::If' => [cond, if_true, if_false] } end
+
+    def not_equal(one, two) fn_not(equal(one,two)) end
+
+    def select(index, list) { :'Fn::Select' => [ index, list ] } end
+
+    def ref(name) { :Ref => name } end
+
+    def aws_account_id() ref("AWS::AccountId") end
+
+    def aws_notification_arns() ref("AWS::NotificationARNs") end
+
+    def aws_no_value() ref("AWS::NoValue") end
+
+    def aws_stack_id() ref("AWS::StackId") end
+
+    def aws_stack_name() ref("AWS::StackName") end
+
+    # deprecated, for backward compatibility
+    def no_value()
+      warn_deprecated('no_value()', 'aws_no_value()')
+      aws_no_value()
+    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.
+    # Local variables may also be exposed to the string via the `locals` hash.
+    def interpolate(string, locals={})
+      list = []
+      while string.length > 0
+        head, match, string = string.partition(/\{\{.*?\}\}/)
+        list << head if head.length > 0
+        list << eval(match[2..-3], nil, 'interpolated string') 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
+  end
+end