What is enscalator?

Enscalator is based on bazaarvoice/cloudformation-ruby-dsl and helps cloudforming applications created by AIR at en-japan inc.

Installation

Add this line to your application's Gemfile:

gem 'enscalator'

And then execute:

$ bundle

Or install it yourself as:

$ gem install enscalator

Usage

CLI

$ enscalator -h
Usage: enscalator [arguments]
  -l, --list-templates             List all available templates
  -t, --template=<s>               Template name
  -f, --template-file=<s>          Template filename
  -r, --region=<s>                 AWS Region (default: us-east-1)
  -p, --parameters=<s>             Parameters 'Key1=Value1;Key2=Value2'
  -s, --stack-name=<s>             Stack name
  -z, --private-hosted-zone=<s>    Private hosted zone (e.x. 'default-vpc.internal')
  -g, --public-hosted-zone=<s>     Public hosted zone
  -c, --create-stack               Create the stack
  -u, --update-stack               Update already deployed stack
  -e, --pre-run, --no-pre-run      Use pre-run hooks (default: true)
  -o, --post-run, --no-post-run    Use post-run hooks (default: true)
  -x, --expand                     Print generated JSON template
  -a, --capabilities=<s>           AWS capabilities (default: CAPABILITY_IAM)
  -n, --vpc-stack-name=<s>         VPC stack name (default: default-vpc)
  -d, --availability-zone=<s>      Deploy to specific availability zone (default: all)
  -i, --profile=<s>                Use a specific profile from your credential file
  -h, --help                       Show this message

Examples:

Create new stack with name en-japan-air-vpc in us-west-1

$ enscalator -t VPC -r us-west-1 -s en-japan-air-vpc -d a -c

Note: if you'd like to run enscalator directly inside gem repository, use ./exe/enscalator script.

Autogenerated ssh keys for ec2 instances

All autogenerated ssh keys gets saved to directory corresponding to the selected profile name under user home directory at $HOME/.enscalator, thus:

• when no profile option was given, keys would be saved to $HOME/.enscalator/default
• for specific profile, directory will be created automatically and all keys gets saved under $HOME/.enscalator/%profile_name%

How to write a template

All enscalator templates are stored in lib/enscalator/templates/. Application specific templates can be saved in any file and deployed by enscalator using --template-file.

You'll find the list of helpers you can use in:

• lib/enscalator/richtemplate.rb
• lib/enscalator/core/cf_parameters.rb
• lib/enscalator/core/cf_resources.rb
• lib/enscalator/enapp.rb
• lib/enscalator/helpers.rb (and more generic helpers)

Note: for each template based on EnAppTemplateDSL you'll automatically get autogenerated ResourceSecurityGroup, ApplicationSecurityGroup and load balancer along with ResourceSubnet and ApplicationSubnet for each availability zone (for example, in case of zone a it would be ResourceSubnetA and ApplicationSubnetA and so on). Since this setup relies on presence of VPC of specific setup it is required to deploy VPC template prior to deploying any template based on EnAppTemplateDSL.

Check lib/enscalator/templates/vpc_peering.rb for an example.

How to write a plugin and include it?

Plugins are modules and stored in lib/enscalator/plugins/.
When you want to use your plugin you just have to include PluginName inside your template. See lib/enscalator/plugins/vpc_peering_connection.rb for an example.
Don't forget to require_relative your new plugin in lib/enscalator/plugins.rb.

Plugins supported out of the box:

• AmazonLinux
• AutoScale
• CoreOS
• Couchbase
• Debian
• ElasticBeanstalk
• Elasticache
• ElasticsearchAmazon
• ElasticsearchBitnami
• ElasticsearchOpsworks
• Elb
• NATGateway
• RDS
• Redis
• RethinkDB
• Route53
• Ubuntu
• VPCPeeringConnection

What's pre_run and post_run?

pre_run is a method called BEFORE the template generation. It's a good place to make some calls to the AWS SDK for instance.
post_run is a method called AFTER the stack is created.

Development

To install this gem onto your local machine, run bundle && bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release to create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Documentation

To generate documentation run rake doc ( or bundle exec rake doc )

Contributing

1. Fork it ( https://github.com/en-japan-air/enscalator/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Check if tests failing (rake spec or bundle exec rake spec)
6. Create a new Pull Request