andy-c-jones / autostacker24

Ruby utility to manage AWS CloudFormation stacks

AutoStacker24

AutoStacker24 is a small ruby module for managing AWS CloudFormation stacks.

In comparison to the original AWS Ruby SDK AutoStacker 24 lets you write simple and convenient automation scripts, especially if you have lots of parameters or dependencies between other stacks.

Create or Update

Stacker.create_or_update_stack(stack_name, template, parameters, parent_stack_name = nil, tags = nil)

Creates or updates the stack depending if it exists or not. It will also wait until the stack operation is eventually finished, handling all status checks for you.

• template: is either the template json data itself or the name of a file containing the template body
• parameters: specify the input parameter as a simple ruby hash. It gets converted to the cumbersome AWS format automatically. The template body will be validated and optionally preprocessed.
• parent_stack_name: this special feature will read the output parameters of an existing stack and merge them to the given parameters. Therefore the new stack can easily reference resources (e.g. VPC Ids or Security Groups) from a parent stack.
• tags: Key-value pairs to associate with this stack. As CloudFormation does not support updating tags AutoStacker24 is injecting the tags to all Resources elements which support it.

Example:

params = {
  ReadThroughput:  25,
  WriteThroughput: 10,
  AmiId:           "ami-4711"
}

tags = [
  { "Key": "Team", "Value": "Kondor"}
]

Stacker.create_or_update_stack('my-stack', 'service-stack.json', params, tags)

For finer control Stacker offers also

• create_stack
• update_stack
• delete_stack
• validate_template
• get_stack_outputs
• get_stack_resources
• find_stack, all_stacks, all_stack_names

Template Preprocessing

1. You can put javascript like comments in your template, even if they are are illegal in pure json. Nevertheless, sometimes it's just handy to have the ability to quickly comment some parts out. AutoStacker24 will remove all comments before passing the template to AWS.

2. Referencing parameters in CloudFormation json can be quite cumbersome, especially if you build long strings. AutoStacker24 gives you a more convenient syntax: Inside a string, you can reference a parameter with the @ symbol without the need for complex Fn::Join and Ref constructs.

3. For the "UserData" property you can reference a file @file://./myscript.sh that gets auto encoded to base64. If you pass a simple string that gets autoencoded.

instead of	just write
"prop": {"Ref": "myVar"}	"prop": "@myVar"
"prop": {"Fn::Join":["-",[ {"Ref":"AWS::StackName"},{"Ref":"tableName"},"test" ]]}	"prop": "@AWS::StackName-@tableName-test"
"prop": "[email protected]"	"prop": "bla@@hullebulle.org"
"UserData": {"Fn:Base": ... }	"UserData": "@file://./myscript.sh"

By default, AutoStacker24 don't preprocess templates. If you want to use this functionality your template must start with a comment:

// AutoStacker24
{
  ...
}

Stacker.template_body(template) will give you the result after preprocessing if you need it for other tools.

Using

Declare a dependency on the gem, preferably in a Gemfile:

gem 'autostacker24'

Use it in your rakefile or Ruby code:

require 'autostacker24'

CLI

You can also use AutoStacker24 in your command line.

To Validate a template:

$ autostacker24 validate --template /path/to/template.json

To see the outcome after AutoStacker preprocessed your template;

$ autostacker24 preprocess --template /path/to/template.json