cumuliform 0.5.1 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: abff1bdeb60a617a79f889e191789cc21dee2335
-  data.tar.gz: 8320b16dd011e3155aaeef164a4dce008634e46d
+  metadata.gz: 2078446f4607d50e1623eab3072e964341ab06b2
+  data.tar.gz: 96c0569cfaeb8f991b878364b27defdf210753ef
 SHA512:
-  metadata.gz: 49b1742f90f29be0daacbd3c452cdda449100bc452ec831466661639c8fc28402e2cbdf833a04c5d4cecf1eeee97e4ccd03bf4717943032a4eb2813c407df54c
-  data.tar.gz: 20147ec9d4c9790d2ac5fc5fb78c5f3126582e2ed7c86c698be3bf25b6b7cf49bc625759e7a2e07d93309510fc1dba25f714ca1a2dc573e53eb514cce13f26f4
+  metadata.gz: a0bed284a17feef9d26083b3967579d9d78714229b9992905210bcc626142f864358dd6aeab3b49676f72558c977c4712b13ef56c1e6d5662426201245b8936c
+  data.tar.gz: e67caccb78bc3d10dad37d96e50db5e4d1e88713e863468af79f3c1151e727e1d6c35e159356c50fdf7eea455d271b218f6b7c616bd5cd2b3d130dc94ccc256c

data/.ruby-version

@@ -1 +1 @@
-2.2.2
+2.3

data/CHANGELOG.md

@@ -2,6 +2,11 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## Unreleased
+### Changed
+- Internal refactor of code / file structure to more clearly separate DSL and
+  domain objects
+
 ## [0.5.1] - 2015-12-03
 ### Changed
 - Make some fragment-related functions private

data/README.md

@@ -1,6 +1,6 @@
 # Cumuliform
 
-[![Gem Version](https://badge.fury.io/rb/cumuliform.svg)](http://badge.fury.io/rb/cumuliform) [![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)
+[![Gem Version](https://badge.fury.io/rb/cumuliform.svg)](http://badge.fury.io/rb/cumuliform) [![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) [![Documentation](https://inch-ci.org/github/tape-tv/cumuliform.svg?branch=master)]
 
 Amazon’s [CloudFormation AWS service][cf] provides a way to describe
 infrastructure stacks using a JSON template. We love CloudFormation, and use it
@@ -772,11 +772,376 @@ And the output:
 ```
 
 ## Importing other templates
-_TODO_
+If you want to share complete resources, or fragments, between different
+templates then you can import one template into another. All the imported
+template's resources will be available to you, and you can override template
+parts (i.e. a parameter) or even fragments simply be defining them again in the
+importing template.
+
+To import a template, you simply `require` it as you would any other ruby file,
+and then use Cumuliform's `import` method to import it.
+
+This is easier to explain with an example. Take this very simple example,
+defining a single `AWS::EC2::Instance` in a `resource`, and a `parameter` that
+controls the AMI it uses:
+
+```ruby
+BaseTemplate = 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
+```
+
+It generates the following JSON (as expected):
+
+```
+{
+  "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"
+      }
+    }
+  }
+}
+```
+
+Say we to change the default AMI parameter but reuse everything else. We can
+import that template and redefine the `parameter`:
+
+```ruby
+require_relative './import-base.rb'
+
+Cumuliform.template do
+  import BaseTemplate
+
+  parameter 'AMI' do
+    {
+      Description: 'A different AMI',
+      Type: 'String',
+      Default: 'ami-DIFFERENT'
+    }
+  end
+end
+```
+
+That produces the following JSON:
+
+```
+{
+  "Parameters": {
+    "AMI": {
+      "Description": "A different AMI",
+      "Type": "String",
+      "Default": "ami-DIFFERENT"
+    }
+  },
+  "Resources": {
+    "MyInstance": {
+      "Type": "AWS::EC2::Instance",
+      "Properties": {
+        "ImageId": {
+          "Ref": "AMI"
+        },
+        "InstanceType": "m3.medium"
+      }
+    }
+  }
+}
+```
+
+There are a couple of very important points to note: First, we have to
+`require` the base template (exactly as you require any ruby file). Second, we
+have to assign the result of calling `Cumuliform.template` to a constant so
+that it is available once we've required the file.
+
+In the importing template, once we have `require`d the base template, we pass
+the constant containing the base template to the `import` DSL method.
+
+## Importing fragments
+Fragments defined in a template are also available when imported. You can
+override fragments in the importing template as you would override a resource.
+
+Here's a base template that defines several fragments (shown with the JSON it
+generates).
+
+```ruby
+FragmentBaseTemplate = Cumuliform.template do
+  def_fragment(:ami_param) do |opts|
+    parameter 'AMI' do
+      {
+        Description: 'AMI id',
+        Type: 'String',
+        Default: opts[:ami_id]
+      }
+    end
+  end
+
+  def_fragment(:instance_type) do |opts|
+    parameter 'InstanceType' do
+      {
+        Description: 'InstanceType',
+        Type: 'String',
+        Default: opts[:type],
+        AllowedValues: ['t2.small', 't2.medium', 't2.large']
+      }
+    end
+  end
+
+  def_fragment(:instance) do |opts|
+    resource 'MyInstance' do
+      {
+        Type: 'AWS::EC2::Instance',
+        Properties: {
+          ImageId: ref('AMI'),
+          InstanceType: ref('InstanceType')
+        }
+      }
+    end
+  end
+
+  fragment(:ami_param, ami_id: 'ami-accff2b1')
+  fragment(:instance_type, type: 't2.medium')
+  fragment(:instance)
+end
+```
+
+```
+{
+  "Parameters": {
+    "AMI": {
+      "Description": "AMI id",
+      "Type": "String",
+      "Default": "ami-accff2b1"
+    },
+    "InstanceType": {
+      "Description": "InstanceType",
+      "Type": "String",
+      "Default": "m4.medium",
+      "AllowedValues": [
+        "t2.small",
+        "t2.medium",
+        "t2.large"
+      ]
+    }
+  },
+  "Resources": {
+    "MyInstance": {
+      "Type": "AWS::EC2::Instance",
+      "Properties": {
+        "ImageId": {
+          "Ref": "AMI"
+        },
+        "InstanceType": {
+          "Ref": "InstanceType"
+        }
+      }
+    }
+  }
+}
+```
+
+An importing template can use, or override, the fragments exactly as with any
+other resource:
+
+```ruby
+require_relative './import-fragments-base.rb'
+
+Cumuliform.template do
+  import FragmentBaseTemplate
+
+  def_fragment(:instance_type) do |opts|
+    parameter 'InstanceType' do
+      {
+        Description: 'InstanceType',
+        Type: 'String',
+        Default: opts[:type],
+        AllowedValues: ['m3.medium', 'm4.large', 'm4.xlarge']
+      }
+    end
+  end
+
+  fragment(:instance_type, type: 'm3.medium')
+end
+```
+
+```
+{
+  "Parameters": {
+    "AMI": {
+      "Description": "AMI id",
+      "Type": "String",
+      "Default": "ami-accff2b1"
+    },
+    "InstanceType": {
+      "Description": "InstanceType",
+      "Type": "String",
+      "Default": "m3.medium",
+      "AllowedValues": [
+        "m3.medium",
+        "m4.large",
+        "m4.xlarge"
+      ]
+    }
+  },
+  "Resources": {
+    "MyInstance": {
+      "Type": "AWS::EC2::Instance",
+      "Properties": {
+        "ImageId": {
+          "Ref": "AMI"
+        },
+        "InstanceType": {
+          "Ref": "InstanceType"
+        }
+      }
+    }
+  }
+}
+```
+
+We redefined the fragment so the allowed values for instance type allowed the
+instance type we wanted to use. (Using the fragments in the base template is a
+bit weird, and not really recommended - it's included here to warn you...)
+
+
+## Assigning templates to constants, namespaces, and processing
+The `Cumuliform.template` method returns a template object directly. So, to
+make a template that can be imported into another template you need to assign
+it to a variable or constant.
+
+If you want to be able to directly process your base templates (instead of only
+using them by importing them into another template), then you also need to make
+sure your file returns the template when it's run. The runner works by
+`class_eval`ing your template file as a string and expecting that the result of
+that call will be an instance of `Cumuliform::Template`. If you use namespaces
+for your template objects (as you might if you have several base templates)
+then you need to be careful of that: the last line in your template must be
+something that returns the template. If you're nesting within modules, then the
+call to `module` will return `nil`, not the template. Instead, return the
+template as the last line:
+
+```
+module Stacks
+  Base = Cumuliform.template do
+    ...
+  end
+end
+
+Stacks::Base
+```
 
 ## Helpers
-_TODO_
+Because templates are actually instances, not classes or modules, you can't
+simply `include` a mixin module. Cumuliform provides a `helpers` DSL method
+that allows you pass in modules, or block containing helper methods, that will
+be made available to the template:
+
+```ruby
+Cumuliform.template do
+  helpers do
+    def ami
+      'ami-accff2b1'
+    end
+  end
+
+  resource 'MyInstance' do
+    {
+      Type: 'AWS::EC2::Instance',
+      Properties: {
+        ImageId: ami,
+        InstanceType: 'm3.medium'
+      }
+    }
+  end
+end
+```
+
+Which evaluates to:
+
+```
+{
+  "Resources": {
+    "MyInstance": {
+      "Type": "AWS::EC2::Instance",
+      "Properties": {
+        "ImageId": "ami-accff2b1",
+        "InstanceType": "m3.medium"
+      }
+    }
+  }
+}
+```
+
+Or using a module:
+
+```ruby
+module AmiHelper
+  def ami
+    'ami-accff2b1'
+  end
+end
+
+Cumuliform.template do
+  helpers AmiHelper
+
+  resource 'MyInstance' do
+    {
+      Type: 'AWS::EC2::Instance',
+      Properties: {
+        ImageId: ami,
+        InstanceType: 'm3.medium'
+      }
+    }
+  end
+end
+```
+
+Which also evaluates to:
+
+```
+{
+  "Resources": {
+    "MyInstance": {
+      "Type": "AWS::EC2::Instance",
+      "Properties": {
+        "ImageId": "ami-accff2b1",
+        "InstanceType": "m3.medium"
+      }
+    }
+  }
+}
+```
 
+Helper methods are not able to access any methods on the template (like
+`resource`), they're really for wrapping complex external calls (for example, a
+class that fetches an API token you need to use in your template).
 
 # Development
 

data/examples/block-helper.rb

@@ -0,0 +1,17 @@
+Cumuliform.template do
+  helpers do
+    def ami
+      'ami-accff2b1'
+    end
+  end
+
+  resource 'MyInstance' do
+    {
+      Type: 'AWS::EC2::Instance',
+      Properties: {
+        ImageId: ami,
+        InstanceType: 'm3.medium'
+      }
+    }
+  end
+end

data/examples/import-base.rb

@@ -0,0 +1,19 @@
+BaseTemplate = 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