stackr

Stackr

Create CloudFormation templates using ruby DSL and launch them with a CLI.

TODO

• Add options to create-template to add boilerplate stuff like vpc, instance, etc
• Add tests for cli for all the exception handling

Installation

Add this line to your application's Gemfile:

gem 'stackr'

And then execute:

$ bundle

Or install it yourself as:

$ gem install stackr

Configuration

You must configure your AWS credentials to use stackr. Refer to the ruby aws-sdk.

Usage

Commands:
  stackr create-project PROJECT_NAME  # create stackr project
  stackr create-stack TEMPLATE        # create a stack from TEMPLATE
  stackr create-template TEMPLATE     # create a new template generator
  stackr delete-stack STACK           # delete the stack named STACK
  stackr generate-template TEMPLATE   # write the template json file
  stackr help [COMMAND]               # Describe available commands
  stackr list-stacks                  # list all stacks
  stackr update-stack TEMPLATE        # update the stack created from TEMPLATE
  stackr validate-template TEMPLATE   # Verify template and parameters
  stackr version                      # show version

• Create a project with stackr create-project myproject
• Change directory into your project cd myproject
• cp .env.example .env and edit .env
• source .env
• Create a template with stackr create-template mytemplate
• Edit the new template in templates/mytemplate.rb adding parameters, resources, outputs, etc. See cloudformation-ruby-dsl for tips
• Run stackr generate-template mytemplate and review the json document created at templates/mytemplate.json
• Create a CloudFormation stack from your template using stackr create-stack mytemplate
• List all of your stacks with stackr list-stacks
• Tear your stack down with stackr delete-stack mytemplate

Parameter Mapping

Many times you want to include secrets as stack parameters. These secrets do not belong in your source code. So we hand them in as environment variables.

You can set up a mapping between stack parameters and environment variables using the template parameter_map method.

This example tells stackr to fill in the "Environment" stack parameter with the contents of $ENVIRONMENT when creating or updating the stack.

t.parameter_map = {
  'Environment' => 'ENVIRONMENT'
}

You can use a .env file for your environment variables. It's included in the project .gitignore file.

Environment Map

You may want to use the same template to launch stacks in different environments (e.g. 'dev', 'prd', 'test'). You can edit includes/environment_map.rb to configure your different environments. This is useful when you are creating resources in different VPCs or Regions for different environments.

Breaking Change in Behavior for 2.0.0

In order to support mappings with greater than 64 attributes, we no longer add a mapping for includes/environment_map.rb directly in the template. Instead, we load the environment map into a lookup table and find_in_env simply returns the value it finds in that table. This greatly reduces the size if templates with very large environment maps.

If you want to use the old 1.x deprecated behavior be sure to include this line in the body of your template script and use find_in_env_map() instead of find_in_env()

mapping 'EnvironmentMap', File.join(t.includes_path, 'environment_map.rb')

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/LeafSoftware/stackr.

License

The gem is available as open source under the terms of the MIT License.