Cfer is a lightweight toolkit for managing CloudFormation templates.
Read about Cfer here.
If you're interested in hearing more about Cfer, and other DevOps automation projects I'm working on, sign up for the Impose Mailing List.
Add this line to your application's Gemfile:
gem 'cfer'
And then execute:
$ bundle
Or install it yourself as:
$ gem install cfer
To quickly see Cfer in action, try converging the example stacks:
cfer converge vpc -t examples/vpc.rb --profile [YOUR-PROFILE] --region [YOUR-REGION]
cfer converge instance -t examples/instance.rb --profile [YOUR-PROFILE] --region [YOUR-REGION] --parameters KeyName:[YOUR-EC2-SSH-KEY]
You should see something like this:
Commands:
cfer converge [OPTIONS] <stack-name> # Converges a cloudformation stack according to the template
cfer generate [OPTIONS] <template.rb> # Generates a CloudFormation template by evaluating a Cfer template
cfer help [COMMAND] # Describe available commands or one specific command
cfer tail <stack-name> # Follows stack events on standard output as they occur
--profile <profile>
: The AWS profile to use (from your~/.aws/credentials
file)--region <region>
: The AWS region to use--verbose
: Also print debugging messages
The generate
subcommand evaluates the given Ruby script and prints the CloudFormation stack JSON to standard output.
The following options may be used with the generate
command:
--no-pretty-print
: Print minified JSON
Creates or updates a CloudFormation stack according to the specified template.
The following options may be used with the converge
command:
--follow
(-f
): Follows stack events on standard output as the create/update process takes place.--stack-file <template.rb>
: Reads this file from the filesystem, rather than the default<stack-name>.rb
--parameters <Key1>:<Value1> <Key2>:<Value2> ...
: Specifies input parameters, which will be available to Ruby in theparameters
hash, or to CloudFormation by using theFn::ref
function--on-failure <DELETE|ROLLBACK|DO_NOTHING>
: Specifies the action to take when a stack creation fails. Has no effect if the stack already exists and is being updated.
Prints the latest n
stack events, and optionally follows events while a stack is converging.
The following options may be used with the tail
command:
--follow
(-f
): Follows stack events on standard output as the create/update process takes place.--number
(-n
): Print the lastn
stack events.
See the examples
directory for some examples of complete templates.
Parameters may be defined using the parameter
function:
parameter :ParameterName,
type: 'String',
default: 'ParameterValue'
A parameter's value may have the form @stack.output
to look up output values from other stacks in the same account and region. This works anywhere a parameter value is specified, including defaults and inputs. (See the SDK section on Cfer Stacks for caveats.)
Any parameter can be referenced either in Ruby by using the parameters
hash:
parameters[:ParameterName]
Parameters can also be used in a CloudFormation reference by using the Fn::ref
function:
Fn::ref(:ParameterName)
Resources may be defined using the resource
function:
resource :ResourceName, 'AWS::CloudFormation::CustomResource', AttributeName: {:attribute_key => 'attribute_value'} do
property_name 'property_value'
end
Gets transformed into the corresponding CloudFormation block:
"ResourceName": {
"Type": "AWS::CloudFormation::CustomResource",
"AttributeName": {
"attribute_key": "attribute_value"
},
"Properties": {
"PropertyName": "property_value"
}
}
Outputs may be defined using the output
function:
output :OutputName, Fn::ref(:ResourceName)
Templates can get pretty large, and splitting template code into multiple
files can help keep things more manageable. The include_template
function works in a similar way to ruby's require_relative
, but
within the context of the CloudFormation stack:
include_template 'ec2.rb'
You can also include multiple files in a single call:
include_template(
'stack/ec2.rb',
'stack/elb.rb'
)
The path to included files is relative to the base template file
(e.g. the converge
command -t
option).
Embedding the Cfer SDK involves interacting with two components: The Client
and the Stack
.
The Cfer Client
is the interface with the Cloud provider.
The simplest way to use Cfer from Ruby looks similar to the CLI:
Cfer.converge! '<stack-name>', template: '<template-file>'
This is identical to running cfer converge <stack-name> --template <template-file>
, but is better suited to embedding in Rakefiles, chef recipes, or your own Ruby scripts.
See the Rakefile in this repository for how this might look.
The Client is a wrapper around Amazon's CloudFormation client from the AWS Ruby SDK. Its purpose is to interact with the CloudFormation API.
Create a new client:
Cfer::Cfn::Client.new(stack_name: <stack_name>)
Cfer::Cfn::Client
also accepts options to be passed into the internal Aws::CloudFormation::Client
constructor.
Creates or updates the CloudFormation stack to match the input stack
object. See below for how to create Cfer stack objects.
client.converge(<stack>)
Yields to the specified block for each CloudFormation event that qualifies given the specified options.
client.tail number: 1, follow: true do |event|
# Called for each CloudFormation event, as they occur, until the stack enters a COMPLETE or FAILED state.
end
A Cfer stack represents a baked CloudFormation template, which is ready to be converted to JSON.
Create a new stack:
stack = Cfer::stack_from_file(<file>, client: <client>)
stack = Cfer::stack_from_block(client: <client>) do
# Stack definition goes here
end
Note: Specifying a client is optional, but if no client is specified, parameter mappings will not occur.
This project uses git-flow. Please name branches and pull requests according to that convention.
Always use --no-ff
when merging into develop
or master
.
This project also contains a Code of Conduct, which should be followed when submitting feedback or contributions to this project.
- Branch from
develop
- Merge into
develop
- Name branch
feature/<feature-name>
- Branch from
develop
- Merge into
develop
- Name branch
bugfix/<issue-id>
- Branch from
master
- Merge into
develop
andmaster
- Name branch
hotfix/<issue-id>
- Branch from
develop
- Merge into
develop
andmaster
- Name branch
release/<major.minor>