Bora

This gem contains Ruby rake tasks that help you work with CloudFormation stacks. You don't need to use it with rake though - you can use the underlying classes in any Ruby app.

Installation

Add this line to your application's Gemfile:

gem 'bora'

And then execute:

$ bundle

Or install it yourself as:

$ gem install bora

Usage

Quick Start

Add this to your Rakefile

require 'bora'

Bora::Tasks.new("example", "example.json")

This will give you the following rake tasks

rake stack:example:apply             # Creates (or updates) the 'example' stack
rake stack:example:current_template  # Shows the current template for 'example' stack
rake stack:example:delete            # Deletes the 'example' stack
rake stack:example:diff              # Diffs the new template with the 'example' stack's current template
rake stack:example:events            # Outputs the latest events from the 'example' stack
rake stack:example:new_template      # Shows the new template for 'example' stack
rake stack:example:outputs           # Shows the outputs from the 'example' stack
rake stack:example:recreate          # Recreates (deletes then creates) the 'example' stack
rake stack:example:status            # Displays the current status of the 'example' stack
rake stack:example:validate          # Checks the 'example' stack's template for validity

You can add as many templates as you like into your Rakefile, simply define an instance of Bora::Tasks for each one.

Task Options

When you define the Bora tasks, you can pass in a number of options that control how Bora works and what gets passed to CloudFormation. The available options are shown below with their default values.

Bora::Tasks.new("example", "example.json") do |t|
  t.stack_options = {}
  t.colorize = true
end

• example.json - this is a URL to your template. It can be anything openable by Ruby's open-uri library (eg: a local file or http/https URL), or an s3:// URL. This parameter is optional - if you don't supply it, you must specify either template_body or template_url in the stack_options (see below).
• stack_options - A hash of options that are passed directly to the CloudFormation create_stack and update_stack APIs. If you specified a template URL in the constructor you don't need to supply template_body or `template_url here (you will get an error if you do).
• colorize - A boolean that controls whether console output is colored or not

Dynamically Generated Templates

If you are generating your templates dynamically using a DSL such as cfndsl you can easily hook this into the Bora tasks by defining a generate task within the Bora::Tasks constructor.

Bora::Tasks.new("example", "example.json") do |t|
  desc "Generates the template"
  task :generate do
    # Generate your template and write it into "example.json" here
  end
end

If you need to pass parameters from the rake command line through to your generate method, you can do so by using Rake's args.extras functionality:

Bora::Tasks.new("example", "example.json") do |t|
  task :generate do |t, args|
    arg1, arg2 = args.extras
    # Generate your template and write it into "example.json" here
  end
end

$ rake stack:example:apply[arg1_value, arg2_value]

API

You can use this gem without using Rake. Most of the logic is implemented in stack.rb and is fairly self-explanatory.

require 'bora'

stack = Bora::Stack.new("my-stack")
result = stack.update({template_body: File.read("example.json")}) do |event|
  puts event
end

puts "Update #{result ? "succeeded" : "failed"}"

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Contributing

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