Humidifier

Humidifier allows you to build AWS CloudFormation (CFN) templates programmatically. CFN stacks and resources are represented as Ruby objects with accessors for all their supported properties. Stacks and resources have to_cf methods that allow you to quickly inspect what will be uploaded.

For the full docs, go to https://localytics.github.io/humidifier/. For local development instructions, see the Development section.

This project does not follow semantic versioning, but instead is linked to AWS' CloudFormation resource specification version since 1.2.1. If there are developmental changes unrelated to bumping the resource specification, then they are released as another number incremented on the end of the resource specification version. As a result, breaking changes are reserved for whenever AWS updates with minor version changes.

Getting started

Stacks are represented by the Humidifier::Stack class. You can set any of the top-level JSON attributes through the initializer. Resources are represented by an exact mapping from AWS resource names to Humidifier resources names (e.g. AWS::EC2::Instance becomes Humidifier::EC2::Instance). Resources have accessors for each JSON attribute. Each attribute can also be set through the initialize, update, and update_attribute methods.

Example usage

stack = Humidifier::Stack.new(name: 'Example-Stack', aws_template_format_version: '2010-09-09')

load_balancer = Humidifier::ElasticLoadBalancing::LoadBalancer.new(
  listeners: [{ load_balancer_port: 80, protocol: 'http', instance_port: 80, instance_protocol: 'http' }]
)
load_balancer.scheme = 'internal'

auto_scaling_group = Humidifier::AutoScaling::AutoScalingGroup.new(min_size: '1', max_size: '20')
auto_scaling_group.update(
  availability_zones: ['us-east-1a'],
  load_balancer_names: [Humidifier.ref('LoadBalancer')]
)

stack.add('LoadBalancer', load_balancer)
stack.add('AutoScalingGroup', auto_scaling_group)
stack.deploy_and_wait

Interfacing with AWS

Once stacks have the appropriate resources, you can query AWS to handle all stack CRUD operations. The operations themselves are intuitively named (i.e. create, update, delete). There are also convenience methods for validating a stack body (valid?), checking the existence of a stack (exists?), and creating or updating based on existence (deploy). The create, update, delete, and deploy methods all have _and_wait corollaries that will cause the main ruby thread to sleep until the operation is complete.

SDK version

Humidifier assumes you have an aws-sdk gem installed when you call these operations. It detects the version of the gem you have installed and uses the appropriate API depending on what is available. If Humidifier cannot find any way to use the AWS SDK, it will warn you on every API call and simply return false.

You can also manually specify the version of the SDK that you want to use, in the case that you have both gems in your load path. In that case, you would specify it on the Humidifier configuration object:

Humidifier.configure do |config|
  config.sdk_version = 1
end

CloudFormation functions

You can use CFN intrinsic functions and references using Humidifier.fn.[name] and Humidifier.ref. Those will build appropriate structures that know how to be dumped to CFN syntax appropriately.

Change Sets

Instead of immediately pushing your changes to CloudFormation, Humidifier also supports change sets. Change sets are a powerful feature that allow you to see the changes that will be made before you make them. To read more about change sets see the announcement article. To use them in Humidifier, Stack has the create_change_set and deploy_change_set methods. The create_change_set method will create a change set on the stack. The deploy_change_set method will create a change set if the stack currently exists, and otherwise will create the stack.

Introspection

To see the template body, you can check the to_cf method on stacks, resources, fns, and refs. All of them will output a hash of what will be uploaded (except the stack, which will output a string representation).

Humidifier itself contains a registry of all possible resources that it supports. You can access it with Humidifier.registry which is a hash of AWS resource name pointing to the class.

Resources have an aws_name method to see how AWS references them. They also contain a props method that contains a hash of the name that Humidifier uses to reference the prop pointing to the appropriate prop object.

Large templates

When templates are especially large (larger than 51,200 bytes), they cannot be uploaded directly through the AWS SDK. You can configure Humidifier to seamlessly upload the templates to S3 and reference them using an S3 URL instead by:

Humidifier.configure do |config|
  config.s3_bucket = 'my.s3.bucket'
  config.s3_prefix = 'my-prefix/' # optional
end

Forcing uploading

You can force a stack to upload its template to S3 regardless of the size of the template. This is a useful option if you're going to be deploying multiple copies of a template or you just generally want a backup. You can set this option on a per-stack basis:

stack.deploy(force_upload: true)

or globally, but setting the configuration option:

Humidifier.configure do |config|
  config.force_upload = true
end

Development

To get started, ensure you have ruby installed, version 2.1 or later. From there, install the bundler gem: gem install bundler and then bundle install in the root of the repository.

Testing

The default rake task runs the tests. Styling is governed by rubocop. The docs are generated with yard. To run all three of these, run:

$ bundle exec rake
$ bundle exec rubocop
$ bundle exec rake yard

Specs

The specs pulled from the CFN docs is saved to CloudFormationResourceSpecification.json. You can update it by running bundle exec rake specs. This script will pull down the latest resource specification to be used with Humidifier.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/localytics/humidifier.

License

The gem is available as open source under the terms of the MIT License.