cumuliform 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e4589cd0a6f35898e49b81876b266f3a9822a111
-  data.tar.gz: 7ddd217959b61d317a0ddc0f2def640d2fa51d07
+  metadata.gz: dc898679239945b8548cd8b35fac0135ca1c07d4
+  data.tar.gz: 5e5996b0de7f64ba2deb495dcf306374af28947c
 SHA512:
-  metadata.gz: d1c8a3767dac321236b599bffb8a4c05d3111eeb7acac048a8da941d061dc3b3bfe12fa61150dad15bb590596a7414aa9a04a765c09b2f24d4e8673c36ccc0a0
-  data.tar.gz: 20524b85307eb0fe35233ccb6c3453dbc6d09a4920af248fa0d22c9df8abfc62e37b316a7b1149306153546d3d0f71387f5328087b39efa063c8cbe60e3920f3
+  metadata.gz: a1de59e26464fb7370af9cdac344ba606ababdc27ec608d0324cf976352c4eded31b1e78731d4ed40c4282029deb0f3b15b3e42a96e70d9c06bb782c310100a9
+  data.tar.gz: 5511163114e278987878e18844961a03fd8223fb6e20d328bc1653a194c87f3955ec9b5f74257b49f4fbfcb0561a91adecc0fddebe7fac956d07176bc92c0f3a

data/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+/examples/*.cform

data/README.md

@@ -2,7 +2,24 @@
 
 [![Build Status](https://travis-ci.org/tape-tv/cumuliform.svg?branch=master)](https://travis-ci.org/tape-tv/cumuliform) [![Code Climate](https://codeclimate.com/github/tape-tv/cumuliform/badges/gpa.svg)](https://codeclimate.com/github/tape-tv/cumuliform) [![Test Coverage](https://codeclimate.com/github/tape-tv/cumuliform/badges/coverage.svg)](https://codeclimate.com/github/tape-tv/cumuliform/coverage)
 
-A DSL and library for the generation and reuse of Amazon's AWS CloudFormation templates, extracted from ops and deployment code at tape.tv
+Amazon’s [CloudFormation AWS service][cf] provides a way to describe
+infrastructure stacks using a JSON template. We love CloudFormation, and use it
+a lot, but the JSON templates are hard to write and read, it's very hard to
+reuse things shared between stacks, and it's very easy to make simple typos
+which are not discovered until minutes into stack creation when things fail for
+seemingly crazy reasons.
+
+[cf]: http://aws.amazon.com/cloudformation/
+
+Cumuliform is a tool to help eliminate as many sources of reference errors as
+possible, and to allow easier reuse of template parts between stacks. It
+provides a simple DSL that generates reliably valid JSON and enforces
+referential integrity through convenience wrappers around the common points
+where CloudFormation expects references between resources. provides.
+
+Cumuliform has been extracted from ops and deployment code at [tape.tv][tape]
+
+[tape]: https://www.tape.tv/
 
 ## Installation
 
@@ -20,15 +37,144 @@ Or install it yourself as:
 
     $ gem install cumuliform
 
-## Usage
+# Getting started
+
+You’ll probably want to familiarise yourself with the [CloudFormation getting
+started guide][cf-get-started] if you haven’t already.
+
+[cf-get-started]: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/GettingStarted.html
+
+To quickly recap the key points for template authors:
+
+1. A template is a JSON file containing a single Object (`{}`)
+2. The template object is split into specific sections through top-level
+   properties (resources, parameters, mappings, and outputs).
+3. The things we’re actually interested in are object children of those
+   top-level objects, and the keys (‘logical IDs’ in CloudFormation terms) must
+   be unique across each of the four sections.
+4. Resources, parameters, and the like are just JSON Objects.
+5. CloudFormation provides what it calls ‘Intrinsic Functions’, e.g. `Fn::Ref`
+   to define links and dependencies between your resources.
+6. Because a template is just a JSON object, it’s very easy to accidentally
+   define a resource or parameter with the same logical id more than once, which
+   results in a last-one-wins situation where the object defined latest in the
+   file will obliterate the previously defined one.
+
+Cumuliform provides DSL methods to define objects in each of the four sections,
+helps catch any duplicate logical IDs and provides wrappers for CloudFormation’s
+Intrinsic Functions that enforce referential integrity *before* you upload your
+template and start creating a stack with it.
+
+## The simplest possible template
+
+Let’s define a very simple template consisting of one resource and one parameter
+
+```ruby
+Cumuliform.template do
+  parameter 'AMI' do
+    {
+      Description: 'The AMI id for our template (defaults to the stock Ubuntu 14.04 image in eu-central-1)',
+      Type: 'String',
+      Default: 'ami-accff2b1'
+    }
+  end
+
+  resource 'MyInstance' do
+    {
+      Type: 'AWS::EC2::Instance',
+      Properties: {
+        ImageId: ref('AMI'),
+        InstanceType: 'm3.medium'
+      }
+    }
+  end
+end
+```
+
+Processing the ruby source with cumuliform's command line runner gives us this JSON template:
+
+```sh
+$ cumuliform simplest.rb simplest.cform
+```
+
+```json
+{
+  "Parameters": {
+    "AMI": {
+      "Description": "The AMI id for our template (defaults to the stock Ubuntu 14.04 image in eu-central-1)",
+      "Type": "String",
+      "Default": "ami-accff2b1"
+    }
+  },
+  "Resources": {
+    "MyInstance": {
+      "Type": "AWS::EC2::Instance",
+      "Properties": {
+        "ImageId": {
+          "Ref": "AMI"
+        },
+        "InstanceType": "m3.medium"
+      }
+    }
+  }
+}
+```
+
+# Rake tasks and the Command Line runner
 
-TODO: Write usage instructions here
+Cumuliform provides a very simple command-line runner to turn a `.rb` template
+into JSON:
+
+```sh
+$ cumuliform /path/to/input_template.rb /path/to/output_template.json
+```
+
+It also provides a Rake task generator to create a Rake `rule` task to turn
+`x.rb` into `x.cform`:
+
+```ruby
+require 'cumuliform/rake_task'
+
+Cumuliform::RakeTask.rule '.cform' => '.rb'
+```
+
+To transform `filename.rb` into `filename.cform`:
+
+```sh
+$ rake filename.cform
+```
+
+If you haven't used Rake's `rule` tasks before, this [Rake rules article from
+Avdi Grimm][rules] is a good place to start.
+
+[rules]: http://devblog.avdi.org/2014/04/23/rake-part-3-rules/
+
+You'll almost certainly want something more sophisticated than that. Here's an
+example that declares the standard rule and adds a `FileList` to list the
+targets (CloudFormation templates you want to generate) based on your sources
+(Ruby Cumuliform template files). `rake cform` will transform all `.rb` files
+in the same dir as your `Rakefile` into the corresponding `.cform` files:
+
+```ruby
+require 'cumuliform/rake_task'
+
+Cumuliform::RakeTask.rule '.cform' => '.rb'
+
+TARGETS = Rake::FileList['*.rb'].ext('.cform')
+
+task :cform => TARGETS
+```
 
-## Development
+# Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `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](https://rubygems.org).
+To install this gem onto your local machine, run `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](https://rubygems.org).
 
 ## Contributing
 

data/Rakefile

@@ -6,3 +6,12 @@ begin
 rescue LoadError
 end
 
+EXAMPLES = Rake::FileList.new('examples/**/*.rb')
+EXAMPLE_TARGETS = EXAMPLES.ext('.cform')
+
+$:.unshift(File.expand_path('../lib', __FILE__))
+require 'cumuliform/rake_task'
+
+Cumuliform::RakeTask.rule(".cform" => ".rb")
+
+task :examples => EXAMPLE_TARGETS

data/examples/Rakefile

@@ -0,0 +1,6 @@
+require 'cumuliform'
+
+rule ".cform" => ".rb" do |t|
+  template = eval(File.read(t.source), binding, t.source)
+  File.open(t.name, 'w:utf-8') { |f| f.write(template.to_json) }
+end

data/examples/simplest.rb

@@ -0,0 +1,19 @@
+Cumuliform.template do
+  parameter 'AMI' do
+    {
+      Description: 'The AMI id for our template (defaults to the stock Ubuntu 14.04 image in eu-central-1)',
+      Type: 'String',
+      Default: 'ami-accff2b1'
+    }
+  end
+
+  resource 'MyInstance' do
+    {
+      Type: 'AWS::EC2::Instance',
+      Properties: {
+        ImageId: ref('AMI'),
+        InstanceType: 'm3.medium'
+      }
+    }
+  end
+end

data/exe/cumuliform

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'cumuliform/runner'
+
+Cumuliform::Runner.process(ARGV[0], ARGV[1])

data/lib/cumuliform/rake_task.rb

@@ -0,0 +1,23 @@
+require 'cumuliform/runner'
+
+module Cumuliform
+  module RakeTask
+    extend self
+
+    class TaskLib < Rake::TaskLib
+      include ::Rake::DSL if defined?(::Rake::DSL)
+
+      def define_rule(rule_args)
+        task_body = ->(t, args) {
+          Cumuliform::Runner.process(t.source, t.name)
+        }
+
+        rule(*rule_args, &task_body)
+      end
+    end
+
+    def rule(*args)
+      TaskLib.new.define_rule(args)
+    end
+  end
+end

data/lib/cumuliform/runner.rb

@@ -0,0 +1,21 @@
+require 'cumuliform'
+require 'pathname'
+
+module Cumuliform
+  class Runner
+    def self.process_io(io)
+      mod = Module.new
+      path = io.respond_to?(:path) ? io.path : nil
+      args = [io.read, path].compact
+      template = mod.class_eval(*args)
+    end
+
+    def self.process(input_path, output_path)
+      input_path = Pathname.new(input_path)
+      output_path = Pathname.new(output_path)
+
+      template = process_io(input_path.open)
+      output_path.open('w:utf-8') { |f| f.write(template.to_json) }
+    end
+  end
+end

data/lib/cumuliform/version.rb

@@ -1,3 +1,3 @@
 module Cumuliform
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cumuliform
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Matt Patterson
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-05-27 00:00:00.000000000 Z
+date: 2015-06-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -58,7 +58,8 @@ description: |
   non-existent resources because you have a typo.
 email:
 - matt@reprocessed.org
-executables: []
+executables:
+- cumuliform
 extensions: []
 extra_rdoc_files: []
 files:
@@ -73,12 +74,17 @@ files:
 - bin/console
 - bin/setup
 - cumuliform.gemspec
+- examples/Rakefile
+- examples/simplest.rb
+- exe/cumuliform
 - lib/cumuliform.rb
 - lib/cumuliform/error.rb
 - lib/cumuliform/fragments.rb
 - lib/cumuliform/functions.rb
 - lib/cumuliform/import.rb
 - lib/cumuliform/output.rb
+- lib/cumuliform/rake_task.rb
+- lib/cumuliform/runner.rb
 - lib/cumuliform/version.rb
 homepage: https://www.github.com/tape-tv/cumuliform
 licenses: