AutoStacker24 is a small ruby gem for managing AWS CloudFormation stacks.
It is a thin wrapper around the
AWS Ruby SDK.
It lets you write simple and convenient automation scripts,
especially if you have lots of parameters or dependencies between stacks.
You can use it directly from Ruby code or from the command line.
It enhances CloudFormation templates by parameter expansion in strings and
it is even possible to write templates in YAML which is much friendlier
to humans than JSON. You can use $ autostacker24 convert
to convert existing templates to YAML.
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 bodyparameters
: 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 allResources
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
-
You can put javascript-like comments in your JSON template, even if they are are illegal in pure JSON. AutoStacker24 will strip all comments before passing the template to AWS.
-
You can use YAML for writing your templates. YAML is a data serialization format that is structural identical with JSON but optimized for humans. It has support for comments and long embedded string documents which makes it is especially useful for embedded UserData. Example
-
Referencing parameters and building scripts and config files is quite cumbersome in CloudFormation. AutoStacker24 gives you a more convenient syntax: Inside a string, you can create simple expressions with the
@
symbol that will be expanded to CloudFormation'sFn::Join
,Ref
,Fn::GetAtt
, andFn::FindInMap
constructs. -
For the "UserData" property you can pass a simple string that gets auto encoded to base64. This is especially useful for templates written in yaml. You can reference a file
@{file://./myscript.sh}
that will be read into a simple string, and processed for AutoStacker24 expression expansion.
AutoStacker24 expressions start with the @
symbol, and can be enclosed in
curly braces {}
to delimit them if their length is ambiguous.
expression | gets expanded to |
---|---|
"prop": "@myVar" |
"prop": {"Ref": "myVar"} |
"prop": "@AWS::StackName-@tableName-test" |
"prop": {"Fn::Join":["-",[ {"Ref":"AWS::StackName"},{"Ref":"tableName"},"test" ]]} |
@Resource.Attrib |
{"Fn::GetAtt": ["Resource", "Attrib"]} |
"UserData": "@file://./myscript.sh" |
"UserData": {"Fn:Base64": ... } |
"content" : "@file://./myfile.txt" |
"content": {"Fn::Join":["\n", [<file content>]]} |
@RegionMap[@Region, 32] |
{"Fn::FindInMap": ["RegionMap", {"Ref": "Region"}, "32"]} |
@Region[32] |
{"Fn::FindInMap": ["RegionMap", {"Ref": "Region"}, "32"]} |
"prop": "user@@example.com" |
"prop": "user@example.com" |
Expressions starting with @
are greedy, and will continue until a character
that cannot be part of a valid expression is encountered. In order to limit an
expression, they must be enclosed in curly braces. For example, to have
@Subdomain.example.com
expanded as {"Fn::Join":["",[{"Ref":"Subdomain"},".example.com"]]}
,
it must be written as @{Subdomain}.example.com
to explicitly limit the
expression to a simple reference.
By default, AutoStacker24 does not preprocess templates. If you want to use this functionality your must start your template with a comment:
// AutoStacker24 CloudFormation JSON Template
{
"AWSTemplateFormatVersion": "2010-09-09"
...
}
# AutoStacker24 YAML
AWSTemplateFormatVersion: "2010-09-09"
Description: My Stack
...
Stacker.template_body(template)
will give you the result after preprocessing if you need it for other tools.
Declare a dependency on the gem, preferably in a Gemfile:
gem 'autostacker24'
Use it in your rakefile or Ruby code:
require 'autostacker24'
You can also use AutoStacker24 in your command line.
To convert a valid template from JSON to YAML
$ autostacker24 convert --template /path/to/template.json
To convert a valid template from YAML to JSON
$ autostacker24 convert --template /path/to/template.yaml
To Validate a template:
$ autostacker24 validate --template /path/to/template.json
To see the outcome after AutoStacker24 preprocessed your template as pretty printed json
$ autostacker24 show --template /path/to/template.json
To see the outcome after AutoStacker24 preprocessed your template
$ autostacker24 process --template /path/to/template.json
To create or update a stack
$ autostacker24 update --stack MyStack --template /path/to/template.yaml --region eu-west-1