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.