A fully generic, modular DSL for AWS CloudFormation
Ruby Shell
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
.github Add both issue and pull request templates Sep 22, 2016
bin Fix lookup of resource in TF state where fuzzy matching used Mar 6, 2018
docs Add TODO to readme for cf resource spec Jul 18, 2017
example Allow overriding the AWS region in the web-service-resource-collectio… Aug 10, 2016
ext Adds resource_generator.sh Feb 24, 2015
lib More changes to pass rubocop Aug 21, 2018
spec Changes to pass rubocop Aug 21, 2018
tmp Add separate file for replace_properties Nov 7, 2016
yard_extensions Fix doc and naming suggestions for elbv2 Oct 28, 2016
.gitignore rds-cluster-support Jun 5, 2018
.rubocop.yml Fix bad module state path in terraform lambda permission state Dec 13, 2017
.rubocop_todo.yml Bump a couple of rubocop metric limits for bin/convection Dec 13, 2017
.ruby-version 👮 Update .rubocop_todo.yml Nov 20, 2017
.travis.yml Only build master branch on-commit, other branches must use PR build Sep 15, 2017
.yardopts Add a .yardopts to load YARD extensions by default Jul 23, 2016
Gemfile 🔒 Fix potentially vulnerable version of rubocop development dependency Nov 20, 2017
LICENSE.md Move LICENSE to LICENSE.md Sep 26, 2016
README.md Symlink README.md to docs/index.md Jul 21, 2016
Rakefile Define the :yard rake task vs. using a custom :yardoc task Jul 21, 2016
Thorfile PoC DSL and Stack control Jan 9, 2015
convection.gemspec Add activesupport dependency to gemfile Dec 4, 2017
yard_extensions.rb Split yard handlers into separate extension files Jul 21, 2016


Convection Build Status

A fully generic, modular DSL for AWS CloudFormation

This gem aims to provide a reusable model for AWS CloudFormation in Ruby. It exposes a DSL for template definition, and a simple, decoupled abstraction of a CloudFormation Stack to compile and apply templates.


Please read our Contributing guidelines for more information on contributing to Convection.


Add this line to your application's Gemfile:

gem 'convection'

And then execute:

$ bundle

Or install it yourself as:

$ gem install convection

##CLI Commands

  • To converge all stacks in your cloudfile run convection converge in the same directory as your cloudfile or use --cloudfiles and specify the path to the cloudfile. If you provide the name of your stack as a additional argument such as convection converge my-stack-name then all stacks above and including the stack you specified will be converged.
  • To converge a stack group run convection converge --stack_group YOUR_STACK_GROUP_NAME
  • To converge a specific stack or a list of stacks run convection converge --stacks stackA stackB ...
  • To converge multiple cloudfiles at the same time run use the --cloudfiles option providing the path to the cloudfiles. Example bundle exec convection converge --cloudfiles us-east-1/Cloudfile eu-central-1/Cloudfile
  • To display a diff between your local changes and the version of your stack in cloud formation of your changes run convection diff.
  • To diff the changes in a stack group run convection diff --stack_group YOUR_STACK_GROUP_NAME
  • To diff the changes for a specific stack or a list of stacks run convection diff --stacks stackA stackB ...
  • To print out a list of available cli options with their descriptions run convection help.
  • To print out the cloud formation template for a specific stack run convection print-template my-stack-name.
  • To validate your stack is not missing a required resource run convection validate my-stack-name.


We highly recommend consulting the getting started guide for a in depth walk through on how to to set up your project and create and deploy a stack. Example stacks and resources are available in the convection/example folder

Additionally you can generate the Ruby API documentation by executing bundle exec rake yard.

TODO: Script to automatically create new AWS resources

Amazon publishes a spec for Cloudformation: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-resource-specification.html

We should create a tool that uses that to create convection resource code.


Convection is distributed under the MIT license - please refer to the LICENSE for more information.