A Ruby DSL and helper utilities for building CloudFormation templates dynamically.
This is a fork of bazzarvoice/cloudformation-ruby-dsl. However, that gem does more than simply being a DSL. This fork cuts out the non-DSL feature. It provides:
- Ruby DSL to generate a CloudFormation template described in JSON
- A conversion tool
To upload the template, you use other tools such as the AWS Ruby SDK or Fog/AWS.
Original credits: 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-dsl
to install system-wide.
To use in a specific project, add gem 'cloudformation-dsl'
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.
Below are the various functions currently available in the DSL. See the example script for more usage information.
Everything should be wrapped in the following:
template = CloudFormationDSL.describe do
# ... statements ...
end
Once there, you can get the JSON by calling template.to_json
.
Add the named object to the appropriate collection.
parameter(name, options)
(may be marked :Immutable, which will raise error on a later change)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)
: add tags to the stack, which are inherited by all resources in that stack; can only be used at launchfile(name)
: return the named file as a string, for further useload_from_file(filename)
: load the named file by a given type; currently handles YAML, JSON, and Rubyinterpolate(string)
: embed CFN references into a string ({{ref('Service')}}
) for later interpretation by the CFN engineTable.load(filename)
: load a table from the listed file, which can then be turned into mappings (viaget_map
)