cloudformula 1.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 24bc82972e9d49a352e41baa51b21706cd6542d5
+  data.tar.gz: dbb0c9f3404d9c5509ca5cb7d3ecc7b06a494336
+SHA512:
+  metadata.gz: 8cd142edaa41c09a9edbb576dba107de8d27e94c23ccec3afe6783437a42d876abb958544d57051d040b5f8902ee82a7ed1012fa4c9d6422247694beaf7f1602
+  data.tar.gz: b9093780e5397256d3481725703315e4ebcb21343ea98803575abecacb742a9f47b6ca813296ccee8cc8fe2d23bd9aabd3e7e3b5ed65963bd3ac217c55835df5

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.idea/
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1 @@
+--colour

data/.ruby-gemset

@@ -0,0 +1 @@
+cloudformula

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.0.0-p195

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in cloudformula.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Kabam
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,206 @@
+# CloudFormula
+
+CloudFormula is a tool which generates and uploads CloudFormation templates from ERB templates.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'cloudformula'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install cloudformula
+
+## API
+
+[API Documentation](http://rubydoc.info/github/Kabam/cloudformula/master/frames)
+
+## CLI
+
+This gem includes a command-line interface which can generate templates, create and update CloudFormation stacks.
+Type `cloudformula --help` in a console for documentation.
+
+## Basic usage
+
+Generate a template:
+
+```ruby
+template = CloudFormula::Template.new('/path/to/template', { :param1 => 'foo', :param2 => 'bar' })
+template.generate
+```
+
+You can then pass the template to `create_stack`:
+
+```ruby
+stack = CloudFormula.create_stack('us-east-1', 'stack-name', template)
+```
+
+...or to `update_stack`:
+
+```ruby
+CloudFormula.update_stack('us-east-1', 'stack-name', template)
+```
+
+TODO - see api documentation
+
+## Creating templates
+
+Templates are Ruby ERB, which means you have the full power of Ruby available.
+
+### Escaping content
+
+Normally, variables output in your ERB templates using `<%= %>` will be automatically JSON-escaped. You can change
+this behavior by using the `raw` helper. For instance:
+
+```ruby
+<%= raw @foo %>
+```
+
+Note this only works for Strings. If `@foo` is an object that will be implicitly converted to a String, it will still
+be JSON-escaped.
+
+### Partials
+
+Basic partial functionality is available. You can include a partial inside a template as follows:
+
+```ruby
+<%= render 'path/to/template.json.erb', { :param1 => 'value1', :param2 => 'value2', ... } %>
+```
+
+ERB variables are not automatically passed through to partials - you'll have to explicitly pass them.
+
+### Validation
+
+Templates are responsible for their own validations. There are several pre-defined helpers you can use for common
+cases. For the sake of familiarity, we've partially reproduced the helpers in ActiveRecord. See the
+[ActiveRecord Validation Helpers documentation](http://edgeguides.rubyonrails.org/active_record_validations.html#validation-helpers)
+for information on how to use the helpers.
+
+Use pre-defined helpers by creating a Hash named `@validations` in your ERB template. For example:
+
+```ruby
+<%
+@validations = {
+  :param1 => { :presence => true },
+  ...
+}
+%>
+{
+  "AWSTemplateFormatVersion" : "2010-09-09",
+  ...
+}
+```
+
+#### exclusion
+
+Ensures a value is not in the exclusion list.
+
+```ruby
+:exclusion => ['val1']
+```
+
+#### inclusion
+
+Ensures a value is in the inclusion list
+
+```ruby
+:inclusion => ['val1', 'val2']
+```
+
+#### length
+
+Ensures value length
+
+```ruby
+:length => {
+  :minimum => n,
+  :maximum => n,
+  :in|:within => x..y,
+  :is => n
+}
+```
+
+#### format
+
+Ensures a value matches the regex
+
+```ruby
+:format => /regex/
+```
+
+#### numericality
+
+Ensures numeric value constraints
+
+```ruby
+:numericality => {
+  :only_integer => true|false,
+  :equal_to => n,
+  :greater_than => n,
+  :greater_than_or_equal_to => n,
+  :less_than => n,
+  :less_than_or_equal_to => n,
+  :even => true|false,
+  :odd => true|false
+}
+```
+
+#### presence
+
+Ensures a value exists and has a length greater than 0
+
+```ruby
+:presence => true|false
+```
+
+#### Custom validations
+
+You can also write custom validations by raising errors:
+
+```ruby
+<%
+# Validate parameters
+raise 'Required parameter "@foo" is missing.' if @foo.nil? || @foo.empty?
+%>
+```
+
+### Reserved keywords
+
+`parameters` and `source` are reserved keywords and cannot be used as ERB or CloudFormation parameter names.
+
+### CloudFormation stack options
+
+You can specify default stack options within a template. Refer to
+[AWS::CloudFormation::StackCollection.create](http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/CloudFormation/StackCollection.html#create-instance_method)
+at "Options Hash (options)" for a list of options you can set. Note that "parameters" will be overwritten by parameters
+supplied to the create|update_stack methods.
+
+Example of setting the default to not rollback the stack in case of failure:
+```erb
+<%
+@stack_options = { :disable_rollback => true }
+%>
+{
+    ...template...
+}
+```
+
+You can override stack_options if needed by providing a Hash for the override_options parameter when calling
+CloudFormula::CloudFormation#create_stack or CloudFormula::CloudFormation#update_stack
+
+### Security concerns
+
+This gem should not be used with untrusted templates or parameters.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/cloudformula

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+lib = File.expand_path(File.dirname(__FILE__) + '/../lib')
+$LOAD_PATH.unshift(lib) if File.directory?(lib) && !$LOAD_PATH.include?(lib)
+
+require 'cloudformula'
+require 'cloudformula/cli'
+
+args = ARGV.dup
+ARGV.clear
+
+CloudFormula::CLI.run(args)

data/cloudformula.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'cloudformula/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'cloudformula'
+  spec.version       = CloudFormula::VERSION
+  spec.authors       = ['Kabam']
+  spec.summary       = 'CloudFormula is a tool which generates and uploads CloudFormation templates from ERB templates.'
+  spec.description   = spec.summary
+  spec.homepage      = 'https://github.com/Kabam/cloudformula'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'aws-sdk', '~> 1.21.0'
+  spec.add_dependency 'trollop', '~> 2.0'
+
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec', '~> 2.14'
+end

data/integration_tests/.ruby-gemset

@@ -0,0 +1 @@
+cloudformula_integration

data/integration_tests/.ruby-version

@@ -0,0 +1 @@
+ruby-2.0.0-p195

data/integration_tests/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gem 'cloudformula', :path => '../'

data/integration_tests/README.md

@@ -0,0 +1,33 @@
+# CloudFormula Integration Tests
+
+These are simple scripts that fully test functionality of the gem from a user / developer perspective.
+
+## Setup
+
+Provide your AWS security credentials via ENV:
+
+```shell
+export AWS_ACCESS_KEY_ID='...'
+export AWS_SECRET_ACCESS_KEY='...'
+```
+
+Install gems:
+
+```shell
+cd integration_tests
+bundle
+```
+
+## Running
+
+Run all tests from the `integration_tests` directory. These tests may be packaged in the future, but for now they can
+be run individually as follows.
+
+```shell
+ruby testfile.rb
+```
+
+### stack_create_update.rb
+
+This test creates, updates, and deletes an AWS CloudFormation stack. If this test fails, you must manually delete
+the CloudFormation stack "stackalong-cassidy" before attempting to run it again.

data/integration_tests/fixtures/minimal_cf_template.json

@@ -0,0 +1,30 @@
+{
+    "AWSTemplateFormatVersion" : "2010-09-09",
+    "Description" : "Minimal stack for testing",
+
+    "Resources" : {
+        "CfnRole" : {
+            "Type" : "AWS::IAM::Role",
+            "Properties" : {
+                "AssumeRolePolicyDocument" : {
+                    "Statement" : [ {
+                        "Effect" : "Allow",
+                        "Principal" : { "Service" : [ "ec2.amazonaws.com" ] },
+                        "Action" : [ "sts:AssumeRole" ]
+                    } ]
+                },
+                "Path" : "/",
+                "Policies" : [ {
+                    "PolicyName" : "root",
+                    "PolicyDocument" : {
+                        "Statement" : [ {
+                            "Effect" : "Allow",
+                            "Action" : "cloudformation:DescribeStackResource",
+                            "Resource" : "*"
+                        } ]
+                    }
+                } ]
+            }
+        }
+    }
+}

data/integration_tests/fixtures/minimal_cf_template_update.json

@@ -0,0 +1,54 @@
+{
+    "AWSTemplateFormatVersion" : "2010-09-09",
+    "Description" : "Minimal stack for testing",
+
+    "Resources" : {
+        "CfnRole" : {
+            "Type" : "AWS::IAM::Role",
+            "Properties" : {
+                "AssumeRolePolicyDocument" : {
+                    "Statement" : [ {
+                        "Effect" : "Allow",
+                        "Principal" : { "Service" : [ "ec2.amazonaws.com" ] },
+                        "Action" : [ "sts:AssumeRole" ]
+                    } ]
+                },
+                "Path" : "/",
+                "Policies" : [ {
+                    "PolicyName" : "root",
+                    "PolicyDocument" : {
+                        "Statement" : [ {
+                            "Effect" : "Allow",
+                            "Action" : "cloudformation:DescribeStackResource",
+                            "Resource" : "*"
+                        } ]
+                    }
+                } ]
+            }
+        },
+
+        "CfnRole2" : {
+            "Type" : "AWS::IAM::Role",
+            "Properties" : {
+                "AssumeRolePolicyDocument" : {
+                    "Statement" : [ {
+                        "Effect" : "Allow",
+                        "Principal" : { "Service" : [ "ec2.amazonaws.com" ] },
+                        "Action" : [ "sts:AssumeRole" ]
+                    } ]
+                },
+                "Path" : "/",
+                "Policies" : [ {
+                    "PolicyName" : "root",
+                    "PolicyDocument" : {
+                        "Statement" : [ {
+                            "Effect" : "Allow",
+                            "Action" : "cloudformation:DescribeStackResource",
+                            "Resource" : "*"
+                        } ]
+                    }
+                } ]
+            }
+        }
+    }
+}

data/integration_tests/stack_create_update.rb

@@ -0,0 +1,26 @@
+require 'bundler/setup'
+require 'cloudformula'
+
+template_path = File.expand_path('fixtures/minimal_cf_template.json', File.dirname(__FILE__))
+template = CloudFormula::Template.new(template_path)
+
+puts 'Creating...'
+stack = CloudFormula.create_stack('us-west-2', 'stackalong-cassidy', template)
+puts stack.inspect
+
+puts 'Waiting for creation to complete...'
+sleep(1.0) while stack.status == 'CREATE_IN_PROGRESS'
+
+template_path = File.expand_path('fixtures/minimal_cf_template_update.json', File.dirname(__FILE__))
+template = CloudFormula::Template.new(template_path)
+
+puts 'Updating...'
+CloudFormula.update_stack('us-west-2', 'stackalong-cassidy', template)
+
+puts 'Waiting for update to complete...'
+sleep(1.0) while stack.status == 'UPDATE_IN_PROGRESS' || stack.status == 'UPDATE_COMPLETE_CLEANUP_IN_PROGRESS'
+
+puts 'Deleting...'
+stack.delete
+
+puts 'Done.'

data/lib/cloudformula/cli.rb

@@ -0,0 +1,113 @@
+require 'json'
+require 'trollop'
+
+module CloudFormula
+  class CLI
+    def self.run(args)
+      parse_opts = parse_options args
+      subcommand = parse_opts[:subcommand]
+      opts = parse_opts[:opts]
+
+      template = CloudFormula.template opts[:template], parse_parameters(opts[:parameters])
+
+      begin
+        case subcommand
+          when 'generate'
+            puts template.generate
+          when 'create'
+            stack = CloudFormula.create_stack opts[:region], opts[:'stack-name'], template
+            puts stack.inspect
+          when 'update'
+            CloudFormula.update_stack opts[:region], opts[:'stack-name'], template
+        end
+      rescue Exception => e
+        puts "ERROR: #{e.message}\n\nStack trace:\n#{e.backtrace.join("\n    from ")}"
+      end
+    end
+
+    private
+
+    # Parses and validates command-line arguments. Returns the subcommand and its options.
+    # @param [Array] args Command-line arguments (ARGV)
+    # @return [Hash] { :subcommand => "command", :opts => Hash } @see Trollop::Parser#parse for opts structure
+    def self.parse_options(args)
+      parse_top_level args
+      parse_subcommand args
+    end
+
+    # Top-level parser includes global help and subcommand pass-through
+    # @param [Array] args Command-line arguments (ARGV)
+    # @return [Hash] @see Trollop::Parser#parse
+    def self.parse_top_level(args)
+      Trollop::options args do
+        banner CloudFormula::CLI.banner(:top)
+        stop_on %w(generate create update)
+      end
+    end
+
+    # Subcommand parser includes subcommand help and parameter validation
+    # @param [Array] args Command-line arguments (ARGV)
+    # @return [Hash] { :subcommand => "command", :opts => Hash } @see Trollop::Parser#parse for opts structure
+    def self.parse_subcommand(args)
+      cmd = args.shift # get the subcommand
+      Trollop::die "unknown command #{cmd.inspect}" unless ['generate', 'create', 'update'].include?(cmd)
+      cmd_opts = Trollop::options args do
+        banner CloudFormula::CLI.banner(cmd.to_sym)
+        CloudFormula::CLI.opt_definitions(cmd).each { |item| opt *item }
+      end
+      validate_global_opts cmd_opts
+      { :subcommand => cmd, :opts => cmd_opts }
+    end
+
+    # Returns an array defining the command-line options
+    # Each item in the array can be passed directly to `opt` in a parser. Example:
+    #   Trollop::options(args) do
+    #     opt_definitions(subcommand).each { |item| opt *item }
+    #   end
+    # @param [String] subcommand The definitions will be customized appropriately for this value.
+    # @return [Array]
+    def self.opt_definitions(subcommand)
+      defs = [
+          [:parameters, 'Parameters to supply to the template in JSON format. {"var1":"foo","var2":"bar"}', :type => :string],
+          [:template, 'Path to the .json or .json.erb template', :type => :string, :required => true]
+      ]
+      case subcommand
+        when 'create', 'update'
+          defs += [
+              [:'stack-name', 'Name of the CloudFormation stack', :type => :string, :required => true],
+              [:region, 'AWS region. us-east-1, us-west-2, etc. Default us-east-1', :type => :string]
+          ]
+      end
+      defs
+    end
+
+    # Returns the appropriate help banner for the given subcommand
+    # @param [Symbol] subcommand
+    # @return [String]
+    def self.banner(subcommand)
+      case subcommand
+        when :top, :generate, :create, :update
+          file = File.open(File.expand_path("#{subcommand}.txt", "#{File.dirname(__FILE__)}/help"), 'rb')
+          file.read
+        else
+          ''
+      end
+    end
+
+    # Validates options required for all subcommands.
+    # Returns the parsed --parameters value as either a Hash or an Array
+    # @param [Hash] opts
+    # @return [Array|Hash] @see JSON.parse
+    def self.validate_global_opts(opts)
+      Trollop.die :template, "file #{opts[:template]} not found or cannot be read" unless File.file?(opts[:template]) && File.readable?(opts[:template])
+      parse_parameters opts[:parameters]
+    end
+
+    def self.parse_parameters(parameters)
+      return {} if parameters.nil? || parameters.empty?
+      parsed = JSON.parse parameters, :symbolize_names => true rescue Trollop.die :parameters, 'must be valid JSON'
+      Trollop.die :parameters, 'must be a JSON hash' unless parsed.class == Hash
+      parsed
+    end
+  end
+end

data/lib/cloudformula/cloud_formation.rb

@@ -0,0 +1,54 @@
+require 'aws-sdk'
+
+module CloudFormula
+  class CloudFormation
+    class << self
+      # Convenience method which creates a new CloudFormation stack.
+      #
+      # @param [String] region A valid AWS region, e.g. "us-east-1", "us-west-2", etc
+      # @param [String] stack_name
+      # @param [CloudFormula::Template] template
+      # @param [Hash] override_options Optional. Stack options to override. See README.md "CloudFormation stack options" for details
+      # @param [Hash] parameters Optional. Parameters to supply to the template.
+      # @param [String] aws_access_key_id Optional. If not supplied, AWS_ACCESS_KEY_ID must exist in ENV
+      # @param [String] aws_secret_key Optional. If not supplied, AWS_SECRET_ACCESS_KEY must exist in ENV
+      # @return [AWS::CloudFormation::Stack]
+      def create_stack(region, stack_name, template, override_options = {}, parameters = {}, aws_access_key_id = nil, aws_secret_key = nil)
+        validate template
+        cfm = get_cloud_formation region, aws_access_key_id, aws_secret_key
+        cfm.stacks.create(stack_name, template.generate, template.aws_options(override_options, parameters))
+      end
+
+      # Convenience method which updates an existing CloudFormation stack.
+      #
+      # @param [String] region A valid AWS region, e.g. "us-east-1", "us-west-2", etc
+      # @param [String] stack_name
+      # @param [CloudFormula::Template] template
+      # @param [Hash] parameters Optional. Parameters to supply to the template.
+      # @param [String] aws_access_key_id Optional. If not supplied, AWS_ACCESS_KEY_ID must exist in ENV
+      # @param [String] aws_secret_key Optional. If not supplied, AWS_SECRET_ACCESS_KEY must exist in ENV
+      # @return nil
+      def update_stack(region, stack_name, template, parameters = {}, aws_access_key_id = nil, aws_secret_key = nil)
+        validate template
+        cfm = get_cloud_formation region, aws_access_key_id, aws_secret_key
+        stack = cfm.stacks[stack_name]
+        stack.update({ :template => template.generate, :parameters => parameters })
+      end
+
+      private
+
+      # @param [CloudFormula::Template] template
+      def validate(template)
+        raise ArgumentError.new("Invalid template: #{template.inspect}") if !template.is_a?(CloudFormula::Template)
+      end
+
+      def get_cloud_formation(region, aws_access_key_id = nil, aws_secret_key = nil)
+        options = { :region => region }
+        options[:access_key_id] = aws_access_key_id unless aws_access_key_id.nil?
+        options[:secret_access_key] = aws_secret_key unless aws_secret_key.nil?
+        AWS::CloudFormation.new options
+      end
+    end
+  end
+end
+

data/lib/cloudformula/help/create.txt

@@ -0,0 +1,12 @@
+NAME
+  cloudformula create
+
+DESCRIPTION
+  Dynamically generates an AWS CloudFormation template and uses it to create a
+  new CloudFormation stack.
+
+USAGE
+  cloudformula create --stack-name '<stackname>' --template '<template>' \\
+    --parameters '<params>' [--region '<region>']
+
+OPTIONS

data/lib/cloudformula/help/generate.txt

@@ -0,0 +1,10 @@
+NAME
+  cloudformula generate
+
+DESCRIPTION
+  Dynamically generates an AWS CloudFormation template and outputs the result.
+
+USAGE
+  cloudformula generate --template '<template>' --parameters '<params>'
+
+OPTIONS