Cfer is a lightweight toolkit for managing CloudFormation templates.

Read about Cfer here.

Cfer is pre-1.0 software, and may contain bugs or incomplete features. Please see the license for disclaimers.

If you would like support or guidance on Cfer, or CloudFormation in general, I offer DevOps consulting services. Please Contact Bitlancer and we'll be happy to discuss your needs.

Add this line to your application's Gemfile:

gem 'cfer'

And then execute:

$ bundle

Or install it yourself as:

$ gem install cfer

To quickly see Cfer in action, try converging the example stacks:

cfer converge vpc -t examples/vpc.rb --profile [YOUR-PROFILE] --region [YOUR-REGION]
cfer converge instance -t examples/instance.rb --profile [YOUR-PROFILE] --region [YOUR-REGION] --parameters KeyName:[YOUR-EC2-SSH-KEY]

You should see something like this:

Commands:
  cfer converge [OPTIONS] <stack-name>   # Creates or updates a cloudformation stack according to the template
  cfer generate [OPTIONS] <template.rb>  # Generates a CloudFormation template by evaluating a Cfer template
  cfer help [COMMAND]                    # Describe available commands or one specific command
  cfer tail <stack-name>                 # Follows stack events on standard output as they occur

• --profile <profile>: The AWS profile to use (from your ~/.aws/credentials file)
• --region <region>: The AWS region to use
• --verbose: Also print debugging messages

The generate subcommand evaluates the given Ruby script and prints the CloudFormation stack JSON to standard output.

The following options may be used with the generate command:

• --no-pretty-print: Print minified JSON

Creates or updates a CloudFormation stack according to the specified template.

The following options may be used with the converge command:

• --follow (-f): Follows stack events on standard output as the create/update process takes place.
• --stack-file <template.rb>: Reads this file from the filesystem, rather than the default <stack-name>.rb
• --parameters <Key1>:<Value1> <Key2>:<Value2> ...: Specifies input parameters, which will be available to Ruby in the parameters hash, or to CloudFormation by using the Fn::ref function
• --parameter-file <params_file.[yaml|json]: Specifies input parameters from a YAML or JSON file
• --parameter-environment <env_name>: Requires --parameter-file. Merges the specified key in the YAML or JSON file into the root of the parameter file before passing it into the Cfer stack, i.e. to provide different constants for different AWS environments. The priority for parameters is, in ascending order, stack default, file, environment, and command line.
• --on-failure <DELETE|ROLLBACK|DO_NOTHING>: Specifies the action to take when a stack creation fails. Has no effect if the stack already exists and is being updated.
• --stack-policy <filename|URL|JSON string> (-s): Stack policy to apply to the stack in order to control updates; takes a local filename containing the policy, a URL to an S3 object, or a raw JSON string.
• --stack-policy-during-update <filename|URL|JSON string> (-u): Stack policy as in --stack-policy option above, but applied as a temporary override to the permanent policy during stack update.

Prints the latest n stack events, and optionally follows events while a stack is converging.

The following options may be used with the tail command:

• --follow (-f): Follows stack events on standard output as the create/update process takes place.
• --number (-n): Print the last n stack events.

See the examples directory for some examples of complete templates.

Parameters may be defined using the parameter function:

parameter :ParameterName,
  type: 'String',
  default: 'ParameterValue'

Any parameter can be referenced either in Ruby by using the parameters hash:

parameters[:ParameterName]

Parameters can also be used in a CloudFormation reference by using the Fn::ref function:

Fn::ref(:ParameterName)

Resources may be defined using the resource function:

resource :ResourceName, 'AWS::CloudFormation::CustomResource', AttributeName: {:attribute_key => 'attribute_value'} do
  property_name 'property_value'
end

Gets transformed into the corresponding CloudFormation block:

"ResourceName": {
  "Type": "AWS::CloudFormation::CustomResource",
  "AttributeName": {
    "attribute_key": "attribute_value"
  },
  "Properties": {
    "PropertyName": "property_value"
  }
}

Outputs may be defined using the output function:

output :OutputName, Fn::ref(:ResourceName)

Outputs may be retireved from other stacks anywhere in a template by using the lookup_output function.

lookup_output('stack_name', 'output_name')

Templates can get pretty large, and splitting template code into multiple files can help keep things more manageable. The include_template function works in a similar way to ruby's require_relative, but within the context of the CloudFormation stack:

include_template 'ec2.rb'

You can also include multiple files in a single call:

include_template(
  'stack/ec2.rb',
  'stack/elb.rb'
)

The path to included files is relative to the base template file (e.g. the converge command -t option).

Embedding the Cfer SDK involves interacting with two components: The Client and the Stack. The Cfer Client is the interface with the Cloud provider.

The simplest way to use Cfer from Ruby looks similar to the CLI:

  Cfer.converge! '<stack-name>', template: '<template-file>'

This is identical to running cfer converge <stack-name> --template <template-file>, but is better suited to embedding in Rakefiles, chef recipes, or your own Ruby scripts. See the Rakefile in this repository for how this might look.

The Client is a wrapper around Amazon's CloudFormation client from the AWS Ruby SDK. Its purpose is to interact with the CloudFormation API.

Create a new client:

Cfer::Cfn::Client.new(stack_name: <stack_name>)

Cfer::Cfn::Client also accepts options to be passed into the internal Aws::CloudFormation::Client constructor.

Creates or updates the CloudFormation stack to match the input stack object. See below for how to create Cfer stack objects.

client.converge(<stack>)

Yields to the specified block for each CloudFormation event that qualifies given the specified options.

client.tail number: 1, follow: true do |event|
  # Called for each CloudFormation event, as they occur, until the stack enters a COMPLETE or FAILED state.
end

A Cfer stack represents a baked CloudFormation template, which is ready to be converted to JSON.

Create a new stack:

stack = Cfer::stack_from_file(<file>, client: <client>)

stack = Cfer::stack_from_block(client: <client>) do
  # Stack definition goes here
end

This project uses git-flow. Please name branches and pull requests according to that convention.

Always use --no-ff when merging into develop or master.

This project also contains a Code of Conduct, which should be followed when submitting feedback or contributions to this project.

• Branch from develop
• Merge into develop
• Name branch feature/<feature-name>

• Branch from develop
• Merge into develop
• Name branch bugfix/<issue-id>

• Branch from master
• Merge into develop and master
• Name branch hotfix/<issue-id>

• Branch from develop
• Merge into develop and master
• Name branch release/<major.minor>

• parameters hash now includes parameters that are set on the existing stack, but not passed in via CLI during a stack update.
• parameters hash now includes defaults for parameters that were not passed on the CLI during a stack creation.
• Adds a lookup_output function, for looking up outputs of stacks in the same account+region. (See #8)
• Adds provisioning for cfn-init and chef-solo, including resource signaling.
• Adds support for stack policies.
• Cfer no longer validates parameters itself. CloudFormation will throw an error if something is wrong.
• Adds release notes to the README.

• Removes automatic parameter mapping in favor of an explicit function available to resources. (Fixes Issue #8)
• No more double-printing the stack summary when converging a stack with tailing enabled.
• Update demo to only use 2 AZs, since us-west-1 only has two.
• AllowedValues attribute on parameters is now an array, not a CSV string. (Thanks to @rlister)

• Adds support for including other files via include_template function.
• Adds basic Dockerfile