TEMPORARY FORK

This gem contains changes not yet suitable for the upstream project. This fork will be retired once a proper implementation of the changes is merged upstream. Discussion likely to continue here and/or here.

END TEMPORARY FORK NOTICE

A Ruby DSL and helper utilities for building CloudFormation templates dynamically.

Written by Bazaarvoice: see the contributors page and the initial contributions for more details.

CloudFormation templates often contain repeated stanzas, information which must be loaded from external sources, and other functionality that would be easier handled as code, instead of configuration.

Consider when a userdata script needs to be added to a CloudFormation template. Traditionally, you would re-write the script by hand in a valid JSON format. Using the DSL, you can specify the file containing the script and generate the correct information at runtime.

:UserData => base64(interpolate(file('userdata.sh')))

Additionally, CloudFormation templates are just massive JSON documents, making general readability and reusability an issue. The DSL allows not only a cleaner format (and comments!), but will also allow the same DSL template to be reused as needed.

Run gem install cloudformation-ruby-dsl-addedvars to install system-wide.

To use in a specific project, add gem 'cloudformation-ruby-dsl-addedvars' to your Gemfile, and then run bundle.

See Releasing.

See Contributing.

To convert existing JSON templates to use the DSL, run

cfntemplate-to-ruby [EXISTING_CFN] > [NEW_NAME.rb]

You may need to preface this with bundle exec if you installed via Bundler.

Make the resulting file executable (chmod +x [NEW_NAME.rb]). It can respond to the following subcommands (which are listed if you run without parameters):

• expand: output the JSON template to the command line (takes optional --nopretty to minimize the output)
• diff: compare an existing stack with your template. Produces following exit codes:

    0 - no differences, nothing to update
    1 - stack does not exist, template Validation error
    2 - there are differences between an existing stack and your template

• validate: run validation against the stack definition
• create: create a new stack from the output
• update: update an existing stack from the output. Produces following exit codes:

    0 - update finished successfully
    1 - no updates to perform, stack doesn't exist, unable to update immutable parameter or tag, AWS ServiceError exception

• cancel-update: cancel updating a stack
• delete: delete a stack (with prompt)
• describe: get output of an existing stack and output it (takes optional --nopretty to minimize output)
• describe-resource: given two arguments: stack-name and logical-resource-id, get output from a stack concerning the specific resource (takes optional --nopretty to minimize output)
• get-template: get entire template output of an existing stack

Below are the various functions currently available in the DSL. See the example script for more usage information.

Add the named object to the appropriate collection.

• parameter(name, options) (may be marked :Immutable, which will raise error on a later change)
  • The special option key :UsePreviousValue can be set to preserve the parameter's existing value during stack updates (e.g. database passwords that won't be saved in revision control).
• mapping(name, options)
• condition(name, conditions)
• resource(name, options)
• output(name, options)

Invoke an intrinsic CloudFormation function.

• base64(value)
• find_in_map(map, key, name)
• get_att(resource, attribute)
• get_azs(region)
• join(delim, *list)
• select(index, list)
• ref(name)

Intrinsic conditionals are also supported, with some syntactic sugar.

• fn_not(condition)
• fn_or(*condition_list)
• fn_and(*condition_list)
• fn_if(condition, value_if_true, value_if_false)
• equal(lhsOperand, rhsOperand)
• not_equal(lhsOperand, rhsOperand)

Reference a CloudFormation pseudo parameter.

• aws_account_id()
• aws_notification_arns()
• aws_no_value()
• aws_region()
• aws_stack_id()
• aws_stack_name()

Additional capabilities for file inclusion, etc.

• tag(tag_name, tag_options_hash): add tags to the stack, which are inherited by all resources in that stack. tag_options_hash includes :Value=>value and :Immutable=>true properties. tag(tag_value_hash) is deprecated and will be removed in a future version.
• file(name): return the named file as a string, for further use
• load_from_file(filename): load the named file by a given type; currently handles YAML, JSON, and Ruby
• interpolate(string): embed CFN references into a string ({{ref('Service')}}) for later interpretation by the CFN engine
• Table.load(filename): load a table from the listed file, which can then be turned into mappings (via get_map)

The tool defaults to region us-east-1. To change this set either EC2_REGION or AWS_DEFAULT_REGION in your environment.

The following (optional) variables can be set in your CloudFormation .rb file (before the template) to avoid needing to set them on the command-line:

• $aws_profile: A string setting the ~/.aws/credentials profile to use
• $aws_region: A string setting the AWS region
• $stack_name: A string containing the stack name
• $stack_params: A hash containing parameter values, e.g. {'EnvironmentName' => 'prod'}