bora 0.9.4 → 1.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 051a9f9d9023048aa57a43f69a4fa40694976b39
-  data.tar.gz: 015a4c14851b8448634116b8363455f728a75117
+  metadata.gz: 0274ebd129ad2e2c1e96f6c93accc024628bb960
+  data.tar.gz: 0b5b69a386da693777967af8692b4ba87cecb648
 SHA512:
-  metadata.gz: 2ddc7cc56506aa31329a61310c6315c5f3b61164c0153ad3e56851e23c91bf21b056c2031e9d6598d1b6f546cebb0589f4ffc2232050bee049e9c1db22ccb1be
-  data.tar.gz: 80ef8eb03d677a97fbf49fbf21625fc9adc8e2c104326dea6337e13462daf6e0ec0f07b95013e34962741154138ca6eb7417e81d07d2cc183fd22afd8397ad2a
+  metadata.gz: 3de20877d9013f467d4fe4a95656586234f6bf9383d40db73b8bb4f118224449683ceb8ba1701a585bc28f8fa51089c6227dc1d34d6c9b142622948f1eddc256
+  data.tar.gz: 48257c8f06b1d56a3d952b40135ae72b7c72ddd472b5da9b0c2a845676e9cdc1e1bb05ec969fd05f48cd313e2110d242e8b2fbd4a8be5270caa1fa6946090109

data/README.md

@@ -1,169 +1,198 @@
 # Bora
 
-This gem contains Ruby [rake](https://github.com/ruby/rake) tasks that help you work with [CloudFormation](https://aws.amazon.com/cloudformation/) stacks.
-You don't need to use it with rake though - you can use the underlying classes in any Ruby app.
+This Ruby gem contains a command line utility and [rake](https://github.com/ruby/rake) tasks
+that help you define and work with [CloudFormation](https://aws.amazon.com/cloudformation/) stacks.
+
+In a single YAML file you define your templates,
+the stack instances built from those templates (eg: dev, uat, staging, prod, etc),
+and the parameters for those stacks. Parameters can even refer to outputs of other stacks.
+Templates can be written with plain CloudFormation JSON or
+[cfndsl](https://github.com/stevenjack/cfndsl).
+
+Given this config, Bora then provides commands (or Rake tasks) to work with those stacks
+(create, update, delete, diff, etc).
 
 
 ## Installation
 
-Add this line to your application's Gemfile:
+If you're using Bundler, add this line to your application's `Gemfile`:
 
 ```ruby
 gem 'bora'
 ```
 
-And then execute:
+And then run `bundle install`.
 
-    $ bundle
+Alternatively, install directly with `gem install bora`.
 
-Or install it yourself as:
-
-    $ gem install bora
 
 ## Usage
 
 ### Quick Start
 
-Add this to your `Rakefile`
+Create a file `bora.yml` in your home directory, something like this:
+```yaml
+templates:
+  example:
+    template_file: example.json
+    stacks:
+      uat:
+        params:
+          InstanceType: t2.micro
+      prod:
+        params:
+          InstanceType: m4.xlarge
+```
+
+Now run `bora apply example-uat` to create your "uat" stack.
+Bora will wait until the stack is complete (or failed),
+and return stack events to you as they happen.
+To get a full list of available commands, run `bora help`.
+
+Alternatively if you prefer using Rake, add this to your `Rakefile`:
 
 ```ruby
 require 'bora'
-
-Bora::Tasks.new("example", "example.json")
+Bora.new.rake_tasks
 ```
 
-This will give you the following rake tasks
-
-```shell
-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
-```
+Then run `rake stack:example-uat:apply`.
+To get a full list of available tasks run `rake -T`.
 
-You can add as many templates as you like into your Rakefile, simply define an instance of `Bora::Tasks` for each one.
 
-### Task Options
+## File Format Reference
 
-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.
+The example below is a `bora.yml` file showing all available options:
 
-```ruby
-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`](http://ruby-doc.org/stdlib-2.3.0/libdoc/open-uri/rdoc/OpenURI.html) 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`](http://docs.aws.amazon.com/sdkforruby/api/Aws/CloudFormation/Client.html#create_stack-instance_method) and [`update_stack`](http://docs.aws.amazon.com/sdkforruby/api/Aws/CloudFormation/Client.html#update_stack-instance_method) 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
+```yaml
+# A map defining all the CloudFormation templates available.
+# A "template" is effectively a single CloudFormation JSON (or cfndsl template).
+templates:
+  # A template named "app"
+  app:
+    # This template is a plain old CloudFormation JSON file
+    template_file: app.json
 
+    # Optional. An array of "capabilities" to be passed to the CloudFormation API
+    # (see CloudFormation docs for more details)
+    capabilities: [CAPABILITY_IAM]
 
-### Dynamically Generated Templates
-If you are generating your templates dynamically using a DSL such as [cfndsl](https://github.com/stevenjack/cfndsl) you can easily hook this into the Bora tasks by defining a `generate` task within the Bora::Tasks constructor.
+    # A map defining all the "stacks" associated with this template
+    # for example, "uat" and "prod"
+    stacks:
+      # The "uat" stack
+      uat:
+        # The CloudFormation parameters to pass into the stack
+        params:
+          InstanceType: t2.micro
+          AMI: ami-11032472
+
+      # The "prod" stack
+      prod:
+        # Optional. The stack name to use in CloudFormation
+        # If you don't supply this, the name will be the template
+        # name concatenated with the stack name as defined in this file,
+        # eg: "app-prod".
+        stack_name: prod-application-stack
+        params:
+          InstanceType: m4.xlarge
+          AMI: ami-11032472
 
-```ruby
-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
-```
+  # A template named "web"
+  web:
+    # This template is using cfndsl. Bora treats any template ending in
+    # ".rb" as a cfndsl template.
+    template_file: "web.rb"
+    stacks:
+      uat:
+        # The CloudFormation parameters to pass into the stack.
+        # You can define both cfndsl parameters and traditional CloudFormation
+        # parameters here. Cfndsl will receive all of them, but only those
+        # actually defined in the "Parameters" section of the template will be
+        # passed through to CloudFormation when the stack is applied.
+        params:
+          dns_zone: example.com
 
-`cfndsl` comes with a rake task that you can use by embedding it inside the Bora task definition:
+          # You can use complex data structures with cfndsl parameters:
+          users:
+            - id: joe
+              name: Joe Bloggs
+            - id: mary
+              name: Mary Bloggs
 
-```ruby
-require 'bora'
-require 'cfndsl/rake_task'
-
-Bora::Tasks.new("example", "example.json") do |t|
-  CfnDsl::RakeTask.new do |cfndsl_task|
-    cfndsl_task.cfndsl_opts = {
-      files: [{
-        filename: "example.rb",
-        output: "example.json"
-      }]
-    }
-  end
-end
-```
+          # You can refer to outputs of other stacks using "${}" notation too.
+          # See below for further details.
+          app_url: http://${app-uat/outputs/Domain}/api
 
-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`](http://ruby-doc.org/stdlib-2.2.2/libdoc/rake/rdoc/Rake/TaskArguments.html#method-i-extras) functionality:
+          # Traditional CloudFormation parameters
+          InstanceType: t2.micro
+          AMI: ami-11032472
 
-```ruby
-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
+      prod: {}
 ```
-```shell
-$ rake stack:example:apply[arg1_value, arg2_value]
+
+## Parameter Substitution
+
+Bora supports looking up parameter values from other stacks and interpolating them into input parameters.
+At present you can only look up the outputs of other stacks,
+however in the future it may support looking up stack parameters or resources.
+Other future possibilities include looking up values from other services,
+for example AMI IDs.
+
+The format is as follows:
+
+`${<stack_name>/outputs/<output_name>}`
+
+For example:
+```yaml
+params:
+  api_url: http://${api-stack/outputs/Domain}/api
 ```
 
+This will look up the `Domain` output from the stack named `api-stack` and substitute it into the `api_url` parameter.
 
-### API
 
-You can use this gem without using Rake. Most of the logic is implemented in [stack.rb](https://github.com/ampedandwired/bora/blob/master/lib/bora/stack.rb) and is fairly self-explanatory.
+## Command Line
 
-```ruby
-require 'bora'
+Run `bora help` to see all available commands.
 
-stack = Bora::Stack.new("my-stack")
-result = stack.update({template_body: File.read("example.json")}) do |event|
-  puts event
-end
+`bora help [command]` will show you help for a particular command,
+eg: `bora help apply`.
 
-puts "Update #{result ? "succeeded" : "failed"}"
-```
 
-### YAML Configuration - Experimental
-You can define and configure your stacks through YAML too.
-This interface is currently experimental,
-but longer term is likely to become the primary way to use this gem.
-Sample usage is shown below (subject to change).
+## Rake Tasks
 
-Rakefile:
+To use the rake tasks, simply put this in your `Rakefile`:
 ```ruby
-require "bora"
-Bora::RakeTasks.new('templates.yml')
+require 'bora'
+Bora.new.rake_tasks
 ```
 
-templates.yml:
-```yaml
-templates:
-  app:
-    template_file: templates/test.json
-    stacks:
-      dev: {}
-      uat: {}
+To get a full list of available tasks run `rake -T`.
 
-  web:
-    # Templates ending in ".rb" are treated as cfndsl templates
-    template_file: templates/test.rb
-    capabilities: [CAPABILITY_IAM]
-    stacks:
-      dev:
-        # Set stack name explicitly (otherwise would default to "web-dev")
-        stack_name: foo-dev
-        params:
-          # Look up a value from the outputs of the "app-dev"stack
-          app_sg: ${app-dev/outputs/AppSecurityGroup}
-      uat:
-        params:
-          app_sg: foouatdev
 
+## Overriding Stack Parameters from the Command Line
+
+Some commands accept a list of parameters that will override those defined in the YAML file.
+
+If you are using the Bora command line, you can pass these parameters like this:
+
+```bash
+$ bora apply web-uat --params 'instance_type=t2.micro' 'ami=ami-11032472'
 ```
 
+For rake, he equivalent is:
+```bash
+$ rake stack:web-uat:apply[instance_type=t2.micro,ami=ami-11032472]
+```
+
+
+## Related Projects
+The following projects provided inspiration for Bora:
+* [CfnDsl](https://github.com/stevenjack/cfndsl) - A Ruby DSL for CloudFormation templates
+* [CloudFormer](https://github.com/kunday/cloudformer) - Rake tasks for CloudFormation
+* [Cumulus](https://github.com/cotdsa/cumulus) - A Python YAML based tool for working with CloudFormation
+
 
 ## Development
 

data/bora.gemspec

@@ -22,6 +22,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "colorize", "~> 0.7"
   spec.add_dependency "diffy", "~> 3.0"
   spec.add_dependency "rake", "~> 10.0"
+  spec.add_dependency "thor", "~> 0.19"
 
   spec.add_development_dependency "bundler", "~> 1.11"
   spec.add_development_dependency "rspec", "~> 3.0"

data/exe/bora

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'bora/cli'
+
+Bora::Cli.start(ARGV)

data/lib/bora.rb

@@ -1,6 +1,43 @@
+require "yaml"
+require "colorize"
 require "bora/version"
-require "bora/status"
-require "bora/event"
-require "bora/stack"
+require "bora/template"
 require "bora/tasks"
-require "bora/rake_tasks"
+
+class Bora
+  DEFAULT_CONFIG_FILE = "bora.yml"
+
+  def initialize(config_file_or_hash: DEFAULT_CONFIG_FILE, colorize: true)
+    @templates = {}
+    config = load_config(config_file_or_hash)
+    String.disable_colorization = !colorize
+    config['templates'].each do |template_name, template_config|
+      @templates[template_name] = Template.new(template_name, template_config)
+    end
+  end
+
+  def template(name)
+    @templates[name]
+  end
+
+  def stack(stack_name)
+    t = @templates.find { |_, template| template.stack(stack_name) != nil }
+    t ? t[1].stack(stack_name) : nil
+  end
+
+  def rake_tasks
+    @templates.each { |_, t| t.rake_tasks }
+  end
+
+
+  protected
+
+  def load_config(config)
+    if config.class == String
+      return YAML.load_file(config)
+    elsif config.class == Hash
+      return config
+    end
+  end
+
+end

data/lib/bora/cfn/event.rb

@@ -0,0 +1,35 @@
+require 'bora/cfn/status'
+
+class Bora
+  module Cfn
+
+    class Event
+      def initialize(event)
+        @event = event
+        @status = Status.new(@event.resource_status)
+      end
+
+      def method_missing(sym, *args, &block)
+        @event.send(sym, *args, &block)
+      end
+
+      def status_success?
+        @status.success?
+      end
+
+      def status_failure?
+        @status.failure?
+      end
+
+      def status_complete?
+        status_success? || status_failure?
+      end
+
+      def to_s
+        status_reason = @event.resource_status_reason ? " - #{@event.resource_status_reason}" : ""
+        "#{@event.timestamp.getlocal} - #{@event.resource_type} - #{@event.logical_resource_id} - #{@status}#{status_reason}"
+      end
+    end
+
+  end
+end

data/lib/bora/cfn/output.rb

@@ -0,0 +1,24 @@
+class Bora
+  module Cfn
+
+    class Output
+      def initialize(output)
+        @output = output
+      end
+
+      def key
+        @output.output_key
+      end
+
+      def value
+        @output.output_value
+      end
+
+      def to_s
+        desc = @output.description ? " (#{@output.description})" : ""
+        "#{@output.output_key} - #{@output.output_value} #{desc}"
+      end
+    end
+
+  end
+end