Skip to content
Redbubble's wrapper around cloudformation for creating environments
Ruby Shell HTML
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

KumoKeisei Build status Code Climate

A collection of utilities wrapping the libraries for dealing with AWS Cloud Formation.


Add this line to your application's Gemfile:

gem 'kumo_keisei'

And then execute:

$ bundle

Or install it yourself as:

$ gem install kumo_keisei


Basic Usage

The basic usage will give you a CloudFormation stack named {application}-{environment}.

application_name = "myapp"
environment_name = "production"
my_stack =, environment_name)

stack_config = {
  config_path: File.join('/app', 'env', 'config'),
  template_path: File.join('/app', 'env', 'cloudformation', 'myapp.json'),

my_stack.apply! stack_config

Stack Naming

We are using APPNAME-ENVNAME (e.g redbubble-staging) as our naming convention for cloudformation stacks.


You can tune each of the timeouts by passing options to the Stack constructor:

stack_options = {
  confirmation_timeout: 0.5,
  waiter_delay: 20,
  waiter_attempts: 90,
}, environment_name, stack_options)

confirmation_timeout: how long to wait for a user to confirm delete actions waiter_delay: how long to wait between checking Cfn for completion of delete and update actions waiter_attempts: how many times to retry checking that a Cfn delete or update was successful

CloudFormation Templates, Parameter Templates and Configuration Files

The CloudFormation Template is a json file (e.g. app.json) describing a related set of Amazon resources using the CloudFormation DSL. You pass the location by specifying the template_path in the object passed to apply!,

The Parameter Template is a file prescribing the Cfn parameters Embedded Ruby form. It must be in the same folder holding the CloudFormation Template, named {app_name}.yml.erb.

The Configuration Files are a set of files in yml format prescribing configuration values for a given environment. They must be in the folder given by config_path, in the form of {environment}.yml and {environment}_secrets.yml

KumoKi will be used to decrypt the secrets files.

Configuration Hierarchy

Configuration will be loaded from the following sources:

  1. common.yml and common_secrets.yml if they exist.
  2. {environment}.yml and {environment}_secrets.yml or development.yml and development_secrets.yml if environment specific config does not exist.

Injecting Configuration

You can also inject configuration at run time by adding it to the object provided to the apply! call:

stack_config = {
  config_path: File.join('/app', 'env', 'config'),
  template_path: File.join('/app', 'env', 'cloudformation', 'myapp.json'),
  injected_config: {
    'Seed' => random_seed,

Upgrading from KumoKeisei::CloudFormationStack to KumoKeisei::Stack

KumoKeisei::CloudFormationStack is deprecated and should be replaced with a KumoKeisei::Stack which has an environment object (KumoConfig::EnvironmentConfig).

Previously you would pass through cloudformation template and json parameter files directly.


  app_name = "foo"
  environment_name = "staging"
  stack ="#{app_name}-#{environment_name}", "./cloudformation/#{app_name}.json", "./cloudformation/#{environment_name}.json")

With the new Stack object, you need to pass in the location of the template and config:

app_name = "foo"
environment_name = "staging"

stack_config = {
  config_path: File.join('/app', 'env', 'config'),
  template_path: File.join('/app', 'env', 'cloudformation', '#{app_name}.json'),

stack =, environment_name)


Ruby Versions

This gem is tested with Ruby (MRI) versions 1.9.3 and 2.2.3.


  1. Upgrade version in VERSION
  2. Run ./script/release-gem


  1. Fork it ([my-github-username]/kumo_keisei/fork )
  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 a new Pull Request

Testing changes

Automated AWS Integration Tests

You can test the Cloudformation responsibilities of this gem by extending the integration tests at spec/integration.

To run these tests you need a properly configured AWS environment (with AWS_DEFAULT_REGION, AWS_ACCESS_KEY and AWS_SECRET_ACCESS_KEY set) and then run ./script/

If you run this within a Buildkite job then you will have a stack named "kumokeisei-test-$buildnumber" created and torn down for each integration test context. If you run this outside of a Buildkite job then the stack will be named "kumokeisei-test-$username".

You can’t perform that action at this time.