aws-must 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b89b1de055c4e34d2236dfc4cf7b9e76b1b092ad
-  data.tar.gz: a225139880451b8b2509b1c20e78fa578d585d0d
+  metadata.gz: 8326b8dfa72e7fea5dc9d0b4f20d7f02e2071f50
+  data.tar.gz: 7c2ea2b9ad369395c758e60e1bd655e4c32225be
 SHA512:
-  metadata.gz: 9429a6f6b26fb185849cb335c3ac0cbc8f99ac38a9aa42a40eb3686eb195ed6faff1d6c1eba5ab08d9b49abd8c8e6fa535018ed244c78ec26f6febef8a0759c3
-  data.tar.gz: e9b056172c1fa74ceaa799fcaaebef1908cc5681793e11dbd5cc954d73ce335b0f7ad843b3751237a2ce9c58ae3a1fe8d571c4938edc263b843009dbda21cd4f
+  metadata.gz: 231f3f0d6c8ae16b2cbe73bdbc5a84004c167c2a622c2a69c65338502fc16311545108994c7bb69b8a78fc82c1b1eea538ed73ea56b2872f7b10fa68a1ffe22a
+  data.tar.gz: 5990bcc8e7bcd562356d4c99edce55530458086066cad26900c7e41c0c280cc17058c7ae72b19c89119aeae5e66df667dc6e4bf792ffd971b752d05191b94e9b

data/README.md

@@ -1,4 +1,4 @@
-# aws-must - Minimum Viable Solution to Manage CloudFormation Templates - $Release:0.0.5$
+# aws-must - Minimum Viable Solution to Manage CloudFormation Templates - $Release:0.0.6$
 
 `aws-must` is a tool, which allows separating infrastructure
 configuration and Amazon related syntax in CloudFormation JSON
@@ -6,6 +6,13 @@ templates using [YAML](http://learnxinyminutes.com/docs/yaml) and
 [Mustache templates](https://mustache.github.io/).
 
 
+See blog posts
+[1](https://jarjuk.wordpress.com/2015/06/15/love-aws-part1-5),
+[2](https://jarjuk.wordpress.com/2015/06/15/love-aws-part2-2), and
+[3](https://jarjuk.wordpress.com/2015/06/15/love-aws-part3-2/) for
+background information on this tool.
+
+
 ## The Problem
 
 [Amazon CloudFormation](http://aws.amazon.com/cloudformation/) gives
@@ -53,10 +60,10 @@ above.  With the tool users may
 3. use YAML anchors to express dependencies between infrastructure
    elements.
 
-4. add comments in YAML and Mustache templates. The tool supports
+4. add comments in YAML and Mustache templates. The tool supports a
    simple tag syntax (**++start++**
-   **++close++** -tags) to add documentation to
-   Mustache templates, which can be extracted to a separate document.
+   **++close++** -tags) allowing documentation to
+   be extracted directly from template files.
 
 5. use Mustache partials to get rid of repeating similar sections in
    JSON configuration.
@@ -66,8 +73,9 @@ above.  With the tool users may
 
 ## Installation
 
-Add following line to `Gemfile`
+Add following lines to `Gemfile`
 
+    source 'https://rubygems.org'
 	gem 'aws-must'
 
 
@@ -76,6 +84,8 @@ and run
 	bundle install
 	
 
+**Notice**: requires Ruby version ~> 2.0.
+
 ## Usage
 
 ### CLI  Usage
@@ -134,8 +144,8 @@ run
 **NOTICE:**: The [jq](http://stedolan.github.io/jq/) must be installed
 for diff target to work.
 
-To show html documentation extracted from demo case `i` templates, run
-rake task `demo:html-i`. For example, for demo case `3` run
+To show html documentation extracted from demo case `i`, run rake task
+`demo:html-i`. For example, for demo case `3` run
 
 	rake demo:html-3
 
@@ -148,13 +158,13 @@ line argument `browser`, e.g. `rake demo:html-3[chromium-browser]`.
 
 #### Use Demo to Bootstrap Own Configuration
 
-To create a copy of templates and YAML configuration for demo case
-`i`, run rake task `demo:bootstrap-i`, and pass template and
+To create a copy of templates and YAML configuration for demo case `i`, 
+run rake task `demo:bootstrap-i`, and pass template and
 configuration directories as command line arguments. For example, to
-copy demo case `3` templates to directory `tmp/tmpl`, and
+copy demo case `4` templates to directory `tmp/tmpl`, and
 configurations to directory `tmp/conf`, run
 
-    rake demo:bootstrap-3[tmp/tmpl,tmp/conf]
+    rake demo:bootstrap-4[tmp/tmpl,tmp/conf]
 	
 
 
@@ -170,18 +180,17 @@ Prerequisites:
 * [Install Amazon AWS Command Line Interface](http://docs.aws.amazon.com/cli/latest/userguide/installing.html)
 * [Configure AWS Command Line Interface](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)
 
-To list demo targets, which provision Amazon, run
+To list demo targets provisioning Amazon run
 
 	rake -T demo:stack-create
 
-**NOTICE**: Please, notice the region constraint in the output. Some
-of the templates use fixed AMI configuration, which means that they
-work only if aws -tool defines correct region (typically in set in
-`~/.aws/config` file).
+**NOTICE**: the region constraint in the output. Some of the templates
+use fixed AMI configuration, which means that they work only if aws
+-tool defines correct region (typically in set in `~/.aws/config`
+file).
 
 
-To create a `demo` stack for demo case `i`, for example demo case 7
-run
+To create a `demo` stack for demo case `7` run
 
 	rake  demo:stack-create-7
 	
@@ -193,8 +202,8 @@ To show status of `demo` stack run
 
 	rake  demo:stack-status
 
-EC2 instances created in demo cases `7,8,...` accept ssh
-connections. 
+EC2 instances created in demo cases `7,8,...` accept ssh connections
+via port 22.
 
 Demo target `demo:stack-ssh` locates an ip address from a stack output
 variable given as a parameter, and makes ssh connection to this ip

data/demo/0/root.mustache

@@ -1 +1,13 @@
-{{! empty }}
+{
+  "AWSTemplateFormatVersion" : "2010-09-09",
+  "Description" : "A simple Amazon EC2 instance. Initial copy",
+  "Resources" : {
+    "MyEC2Instance" : {
+      "Type" : "AWS::EC2::Instance",
+      "Properties" : {
+        "ImageId" : "ami-00dae61d",
+        "InstanceType" : "t2.micro"
+      }
+    }
+  }
+}

data/demo/2/conf.yaml

@@ -1,5 +1 @@
--- demo/2 : added description property
-
-
-description: "demo/2: a simple Amazon EC2 instance created using
-             aws-must tool.  Added Description tag in root.mustache"
+description: "demo/2: a simple Amazon EC2 instance created using aws-must tool"

data/demo/{8 → 2}/resources.mustache

@@ -1,28 +1,21 @@
 {{! 
 
+    resources.mustache - fixed resources
+
 ++start++
 
 ## <a id="resources.mustache"></a>resources.mustache <a class='navigator' href='#top'">[top]</a>
 
-Empty template.
-
-**Attributes**: context=  `.`
-
-* none
-
-
-**Actions**:
-
-* no action (i.e. empty template)
+Create an EC2 with following fixed parameters
 
+* `ImageId` : "ami-00dae61d",
+* `InstanceType` : "t2.micro"
 
 ++close++
 
 
 }}
-{{! 
 
-    Moved to YAML
 
     "MyEC2Instance" : {
       "Type" : "AWS::EC2::Instance",
@@ -30,6 +23,4 @@ Empty template.
         "ImageId" : "ami-00dae61d",
         "InstanceType" : "t2.micro"
       }
-    }
-
-}}
+    }

data/demo/2/root.mustache

@@ -1,7 +1,11 @@
 {{!
 
-++start++
 
+==================================================================
+STYLE section
+==================================================================
+
+++start++
 <style>
 h1 {
     color:blue; 
@@ -15,71 +19,26 @@ body {
     background-color: #b0c4de;
 } 
 </style>
+++close++
+}}
 
+{{!
+++start++
 
 # <a id="top">aws-must demo 2 template</a>
 
-## root.mustache
-
-Create an EC2 with following fixed parameters
-
-* `ImageId` : "ami-00dae61d",
-* `InstanceType` : "t2.micro"
-
-Supports only region `eu-central-1`. No ssh connection allowed by
-default.
-
-**Parameters**:
-
-* no parameters
-
-
-## Document Content
-
-This document is generated automically from `aws-must` -demo
-templates. 
-
-
-Output contains markdown syntax between
-**&plus;&plus;start&plus;&plus;** and
-**&plus;&plus;close&plus;&plus;** -tags from the template files. For
-each template, it
-
-* gives a general description of the template
-
-* documents the attribute context e.g. `.` or `./resources/Instance`,
-  and attributes references of the template
-
-* lists template actions, i.e.  output from template, or template
-  inclusion
-
-
-## <a id="root.mustache"></a>root.mustache <a class='navigator' href='#top'">[top]</a>
-
-
-**Attributes**: context= `.`
-
-* `description`: description for the CF template
-
-**Actions**:
-
-* **Description**: `description`
+Create an EC2 with following fixed parnameters `ImageId`
+("ami-00dae61d") and `InstanceType` ("t2.micro")
 
+> resources
 
 ++close++
-
 }}
 
 {
   "AWSTemplateFormatVersion" : "2010-09-09",
   "Description" : "{{description}}",
   "Resources" : {
-    "MyEC2Instance" : {
-      "Type" : "AWS::EC2::Instance",
-      "Properties" : {
-        "ImageId" : "ami-00dae61d",
-        "InstanceType" : "t2.micro"
-      }
-    }
+    {{> resources }}
   }
 }

data/demo/2.old/conf.yaml

@@ -0,0 +1,5 @@
+-- demo/2 : added description property
+
+
+description: "demo/2: a simple Amazon EC2 instance created using
+             aws-must tool.  Added Description tag in root.mustache"

data/demo/2.old/root.mustache

@@ -0,0 +1,85 @@
+{{!
+
+++start++
+
+<style>
+h1 {
+    color:blue; 
+    font-size: 2.5em;
+   }
+h2 {
+      color:blue;
+      font-size: 1.5em;
+   }
+body {
+    background-color: #b0c4de;
+} 
+</style>
+
+
+# <a id="top">aws-must demo 2 template</a>
+
+## root.mustache
+
+Create an EC2 with following fixed parameters
+
+* `ImageId` : "ami-00dae61d",
+* `InstanceType` : "t2.micro"
+
+Supports only region `eu-central-1`. No ssh connection allowed by
+default.
+
+**Parameters**:
+
+* no parameters
+
+
+## Document Content
+
+This document is generated automically from `aws-must` -demo
+templates. 
+
+
+Output contains markdown syntax between
+**&plus;&plus;start&plus;&plus;** and
+**&plus;&plus;close&plus;&plus;** -tags from the template files. For
+each template, it
+
+* gives a general description of the template
+
+* documents the attribute context e.g. `.` or `./resources/Instance`,
+  and attributes references of the template
+
+* lists template actions, i.e.  output from template, or template
+  inclusion
+
+
+## <a id="root.mustache"></a>root.mustache <a class='navigator' href='#top'">[top]</a>
+
+
+**Attributes**: context= `.`
+
+* `description`: description for the CF template
+
+**Actions**:
+
+* **Description**: `description`
+
+
+++close++
+
+}}
+
+{
+  "AWSTemplateFormatVersion" : "2010-09-09",
+  "Description" : "{{description}}",
+  "Resources" : {
+    "MyEC2Instance" : {
+      "Type" : "AWS::EC2::Instance",
+      "Properties" : {
+        "ImageId" : "ami-00dae61d",
+        "InstanceType" : "t2.micro"
+      }
+    }
+  }
+}

data/demo/3/conf.yaml

@@ -1,3 +1,19 @@
+-- demo/2 : added description property
 
-description: "demo/3: a simple Amazon EC2 instance created using aws-must tool. 
-              Resources section created using partial resource.mustache"
+
+description: "demo/3: a simple Amazon EC2 instance created using aws-must tool"
+
+parameters:
+
+        -  Name: InstanceType
+           Type: String
+           Description: EC2 reousrce instance type
+           Value: &Param_InstanceType t2.micro
+
+
+resources:
+
+        -  Instance: 
+                 Name: MyEC2Instance
+                 ImageId: ami-00dae61d
+                 InstanceType: t2.micro

data/demo/3/resource.mustache

@@ -0,0 +1,27 @@
+{{!
+
+    resource.mustache
+
+++start++
+
+## <a id="resource.mustache"></a>resource.mustache <a class='navigator' href='#top'">[top]</a>
+
+Dispatches resource sub-type templates based resource Type propertys
+
+**Attributes**: context=  `./resources`
+
+* `Instance`: sub-document defining an EC instance
+
+
+**Actions**:
+
+* include <a href="#resourceInstance.mustache">resourceInstance.mustache</a> if `Instance` 
+
+> resourceInstance
+
+++close++
+
+
+}}
+
+{{# Instance }}{{> resourceInstance}}{{/ Instance }}

data/demo/3/resourceInstance.mustache

@@ -0,0 +1,32 @@
+{{!
+
+
+++start++
+
+## <a id="resourceInstance.mustache"></a>resourceInstance.mustache <a class='navigator' href='#top'">[top]</a>
+
+Create an EC2 instance
+
+**Attributes**: context=  `./resources/Instance`
+
+* `Name`: name of the EC2 instance to create
+* `ImageId`: AIM id to create
+
+**Actions**:
+
+* **Name**:  `Name`
+* **Type**: 'AWS::EC2::Instance'
+* **ImageId**: `ImageId`
+
+++close++
+
+}}
+
+
+    "{{Name}}" : {
+      "Type" : "AWS::EC2::Instance",
+      "Properties" : {
+        "ImageId" : "{{ImageId}}",
+        "InstanceType" : "{{InstanceType}}"
+      }
+    }{{_comma}}

data/demo/3/resources.mustache

@@ -1,21 +1,19 @@
 {{! 
 
-    resources.mustache - fixed resources
-
 ++start++
 
-## <a id="resources.mustache"></a>resources.mustache <a class='navigator' href='#top'">[top]</a>
-
-Create an EC2 with following fixed parameters
+## resources.mustache
 
-* `ImageId` : "ami-00dae61d",
-* `InstanceType` : "t2.micro"
+Nothing created here
 
 ++close++
 
 
 }}
+{{! 
 
+    Fixed resource 'MyEC2Instance' not used anymore.
+    Use YAML resource configuration instead! 
 
     "MyEC2Instance" : {
       "Type" : "AWS::EC2::Instance",
@@ -23,4 +21,7 @@ Create an EC2 with following fixed parameters
         "ImageId" : "ami-00dae61d",
         "InstanceType" : "t2.micro"
       }
-    }
+    }
+
+}}
+    {{# resources }}{{> resource }}{{/ resources }}

data/demo/3/root.mustache

@@ -1,11 +1,13 @@
 {{!
 
+     root.mustache: root level template, 
 
 ==================================================================
 STYLE section
 ==================================================================
 
 ++start++
+
 <style>
 h1 {
     color:blue; 
@@ -15,12 +17,18 @@ h2 {
       color:blue;
       font-size: 1.5em;
    }
+h3 {
+      color:blue;
+      font-size: 1.5em;
+   }
 body {
     background-color: #b0c4de;
 } 
 </style>
+
 ++close++
 
+
 ==================================================================
 CONTENT section
 ==================================================================
@@ -29,10 +37,8 @@ CONTENT section
 
 # <a id="top">aws-must demo 3 template</a>
 
-Create an EC2 with following fixed parnameters
-
-* `ImageId` : "ami-00dae61d",
-* `InstanceType` : "t2.micro"
+Creates a EC2 instances using YAML configuration defining `ImageId`
+(e.g. ami-00dae61d) and `InstanceType` (e.g. t2.micro).
 
 
 Supports only region `eu-central-1`. No ssh connection allowed by
@@ -40,13 +46,13 @@ default.
 
 **Parameters**:
 
-* no parameters
+* `InstanceType`: EC2 resource instance type, (default: t2.micro)
 
 
 ## Document Content
 
 This document is generated automically from `aws-must` -demo
-templates.
+templates. 
 
 
 Output contains markdown syntax between
@@ -62,40 +68,34 @@ each template, it
 * lists template actions, i.e.  output from template, or template
   inclusion
 
+## <a id="root.mustache"></a>root.mustache <a class='navigator' href='#top'">[top]</a>
 
 
-## <a id="root.mustache"></a>root.mustache <a class='navigator' href='#top'">[top]</a>
+Root template 
 
-Create an EC2 instance
 
 **Attributes**: context= `.`
 
 * `description`: description for the CF template
 
+
 **Actions**:
 
 * **Description**: `description`
 * **include** <a href="#resources.mustache">resources.mustache</a>
+* **for** `resource` **in** `resource` **include** <a href="#resource.mustache">resource.mustache</a>
 
 > resources
+> resource
 
 ++close++
 
-==================================================================
-
 }}
 
 {
   "AWSTemplateFormatVersion" : "2010-09-09",
-
   "Description" : "{{description}}",
-
-
-
   "Resources" : {
-
     {{> resources }}
-
   }
-
 }

data/demo/4/conf.yaml

@@ -1,22 +1,27 @@
--- demo/2 : added description property
+description: "demo/4: A simple Amazon EC2 instance created using aws-must tool"
 
+resources:
 
-description: "demo/4: a simple Amazon EC2 instance created using aws-must tool.
-	     The resource created are in defined in YAML configuration, and
-	     the JSON template should not change."
+        - InstanceSecurityGroup:
+                 Name: &DefaultSG MyDefaultSecurityGroup
+                 IngressCidrIp: "0.0.0.0/0"
 
+        -  Instance: 
+                 Name: &Resource_1 MyEC2Instance
+                 ImageId: ami-00dae61d
+                 InstanceType: t2.micro
+                 SecurityGroup: *DefaultSG
 
-parameters:
 
-        -  Name: InstanceType
-           Type: String
-           Description: EC2 reousrce instance type
-           Value: &Param_InstanceType t2.micro
+outputs:
 
+        -  Name: InstanceId1
+           Description: InstanceId of the newly created EC2 instance
+           Ref:  *Resource_1
 
-resources:
 
-        -  Instance: 
-                 Name: MyEC2Instance
-                 ImageId: ami-00dae61d
-                 InstanceType: t2.micro
+        -  Name: IP1
+           Description: Public IP address of the newly created EC2 instance
+           Attr: 
+                 Ref: *Resource_1
+                 Name: PublicIp

data/demo/{8 → 4}/output.mustache

@@ -5,6 +5,7 @@
 
 ## <a id="output.mustache"></a>output.mustache <a class='navigator' href='#top'">[top]</a>
 
+
 Create one output entry to CloudFormation JSON output section
 
 **Attributes**: context= `./outputs`
@@ -25,8 +26,6 @@ Create one output entry to CloudFormation JSON output section
 * **Value**: **Ref** if `Ref`
 * **Value**: `Attr.Ref`, `Attr.Name` if `Attr`
 
-
-
 ++close++
 
 }}

data/demo/4/resource.mustache

@@ -12,7 +12,6 @@ Dispatches resource sub-type templates based resource Type propertys
 
 * `Instance`: sub-document defining an EC instance
 
-
 **Actions**:
 
 * include <a href="#resourceInstance.mustache">resourceInstance.mustache</a> if `Instance` 
@@ -25,3 +24,4 @@ Dispatches resource sub-type templates based resource Type propertys
 }}
 
 {{# Instance }}{{> resourceInstance}}{{/ Instance }}
+{{# InstanceSecurityGroup }}{{> resourceSecurityGroup}}{{/ InstanceSecurityGroup }}