SparkleFormation 1.0
Back to the Blog Page

SparkleFormation 1.0

by Chris Roberts | Friday, September 4, 2015

I am pleased to announce the 1.0 release of both the SparkleFormation library and the SparkleFormation CLI (sfn). SparkleFormation is a Ruby library that provides a DSL for programmatically generating serialized template documents consumed by remote orchestration APIs. These releases include multiple implementation refactors providing more stability for existing functionality. They also include a number of new features allowing for a 1.0 release.


SparkleFormation library

Nesting Functionality

The existing nesting functionality was refactored to provide better internal consistency and allow easier reuse. This has not resulted in any visual change outside applications building on top of the library itself. However, this change has allowed for the expansion of new features discussed below.

SparkleFormation CLI

Error Recovery

Thanks to updates within the miasma library, sfn now provides configurable retry logic on read-only API requests. This greatly reduces the number of false failure states that can be seen when polling for a specific state state due to transient, non-fatal errors.

Nested Validation

The validate command will now validate all nested stacks as well as the root stack when performing a validation request. This improved behavior ensures pre-validation is truely representative of the full request.

Expanded Information

The describe command will now provide stack information for all nested stacks defined within the requested stack. Previously describe required a stack to be explicitly requested to provide information which made it cumbersome to quickly view all information of a stack when it included multiple nested stacks.

Print Only

All commands dealing with templates (create, update, and validate) now support the --print-only flag. Previously the --print-only flag was unavailable on the validate command. This change is targeted at making it easier and faster to view a problematic template when having issues successfully running a command.

The --print-only behavior has also been updated for situations where the processed template contains nested stacks. Previously the print only would display the stack resource with a dummy URL inserted for the template location. This was useful for viewing the root stack but difficult when troubleshooting may require viewing nested templates. Now the --print-only behavior will add a new Stack entry in the stack resource which contains the entire template for the nested stack.

Shared Improvements

Both libraries have received a documentation overhaul:

New Features

SparkleFormation library

Deep Nesting Support

Two styles of stack nesting logic are now available within the SparkleFormation libary. The original shallow style and the new deep style. Using the existing shallow style, all parameters of nested stacks would be automatically bubbled to the root stack. While this functionality made management of the stack easier (direct parameter interaction with the root stack) it also hit API limitations very easily as more parameters were introduced from newly nested stacks.

The deep style of nesting does not bubble parameters to the root stack. Instead, it allows for setting parameters directly into the nested stack resources. Automatic output and parameter matching (which is featured in the shallow style) still exists, but with the added support of allowing deeply nested outputs to be automatically bubbled to a shared depth.

Read more about the nesting logic in the SparkleFormation nesting documentation


SparklePacks introduce a method of packaging common SparkleFormation building blocks and templates into a distributable asset (RubyGem) that can be shared for direct use or to provide a foundation on which to build new templates.

Read more about the packs in the SparkleFormation SparklePacks documentation

Stack Policies

AWS CloudFormation has introduced stack policies to help manage the lifecycle of resources defined within a stack. SparkleFormation has added support for defining resource policy rules in-line within a template. These rules can then be extracted and submitted to the API after the creation of the stack.

Read more about policy support in the SparkleFormation stack policy documentation

SparkleFormation CLI


Support for the existing and the new style of nesting are now supported within sfn (shallow and deep). By default, sfn is configured to use the deep nesting style, but can be reverted to the shallow behavior via configuration.

Read more about nesting configuration in the sfn documentation


Support for SparklePacks has integrated into sfn allowing users to distribute and build upon shared SparkleFormation building blocks and templates.

Read more about SparklePack configuration in the sfn configuration documentation


Callbacks provide a way to insert optional or custom functionality into template generation and/or interactions with the remote orchestration API. These are configuration driven and provide access for introducing new features or support that may be required based on use case.

Read more about Callbacks in the sfn callback documentation

Closing Thoughts

The 1.0 release of both SparkleFormation and sfn marks a significant milestone for both projects in terms of functionality and feature set. There is still more to be done (as there always will be) but these releases encompass the base functionality I viewed as required for a proper 1.0 release.

A big thank you to all the people who have raised issues, sent pull requests, and helped me track down and squash bugs in not only the SparkleFormation and sfn code bases, but the supporting libraries as well. You all are awesome and have helped make this 1.0 release a reality.