Hygroscope is a command line tool for managing the launch of complex CloudFormation stacks in Amazon Web Services.

CloudFormation is a tool for creating and managing Amazon Web Services infrastructure using code. A JSON-formatted template describes the state of a “stack” including such resources as servers, S3 storage buckets, and load balancers. Utilizing the AWS Virtual Private Cloud service, entire software-defined networks can be described and repeatably created, updated, and destroyed using CloudFormation.

CloudFormation is not without its pain points:

• Templates must be written in JSON, which, in addition to being difficult for a human to read, does not support niceties such as inline comments and repeated blocks.
• Launching CloudFormation stacks requires knowledge of the various parameters that need to be provided, and it is difficult to repeatably launch a stack since parameters are not saved in any convenient way.
• There is no easy mechanism to send a payload of data to an instance during stack creation (for instance scripts and recipes to bootstrap an instance).
• Finally, it is difficult to launch stacks that build upon already-existing stacks (i.e. an application stack within an existing VPC stack) because one must manually provide a variety of identifiers (subnets, IP addresses, security groups).

Hygroscope aims to solve each of these specific problems in an opinionated way:

• CF templates are written in YAML and processed using cfoo, which provides a variety of convenience methods that increase readability.
• Hygroscope can interactively prompt for each parameter and save inputted parameters to a file called a paramset. Additional stack launches can make use of existing paramsets, or can use paramsets as the basis and prompt for updated parameters.
• A payload directory, if present, will be packaged and uploaded to S3. Hygroscope will generate and pass to CF a signed time-limited URL for accessing and downloading the payload, or the CloudFormation template can manage an instance profile granting indefinite access to the payload.
• If an existing stack is specified, its outputs will be fetched and passed through as input parameters when launching a new stack.

The latest version of Hygroscope can be installed via RubyGems. The inline help documents each command and its options. The source code for Hygroscope and additional documentation is on GitHub, and a sample template that sets up a “bare VPC” is a good introduction to creating Hygroscopic templates.