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

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:

template = CloudFormula::Template.new('/path/to/template', { :param1 => 'foo', :param2 => 'bar' })
template.generate

You can then pass the template to create_stack:

stack = CloudFormula.create_stack('us-east-1', 'stack-name', template)

...or to update_stack:

CloudFormula.update_stack('us-east-1', 'stack-name', template)

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:

<%= 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:

<%= 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. Paths are first tried relative to caller, and then to the source template.

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 for information on how to use the helpers.

Use pre-defined helpers by creating a Hash named @validations in your ERB template. For example:

<%
@validations = {
  :param1 => { :presence => true },
  ...
}
%>
{
  "AWSTemplateFormatVersion" : "2010-09-09",
  ...
}

exclusion

Ensures a value is not in the exclusion list.

:exclusion => ['val1']

inclusion

Ensures a value is in the inclusion list

:inclusion => ['val1', 'val2']

length

Ensures value length

:length => {
  :minimum => n,
  :maximum => n,
  :in|:within => x..y,
  :is => n
}

format

Ensures a value matches the regex

:format => /regex/

numericality

Ensures numeric value constraints

: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

:presence => true|false

Custom validations

You can also write custom validations by raising errors:

<%
# 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 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:

<%
@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

New Releases

  1. Make sure all the rspec and integration tests pass.
  2. Bump the version in lib/cloudformula/version.rb
  3. Build the gem (gem build cloudformula.gemspec)
  4. Smoke test the build ``` $ gem install ./cloudformula-x.y.z.gem Successfully installed cloudformula-x.y.z 1 gem installed

$ irb

require 'cloudformula' => true "[]".try_to_json # should output "\"[]\"" => "\"[]\""

1. Push the gem to RubyGems.org (`gem push cloudformula-x-y-z.gem`)