convection 0.2.33 → 0.2.34.pre.beta.1

data/docs/index.md

@@ -0,0 +1,69 @@
+# Convection [![Build Status](https://travis-ci.org/rapid7/convection.svg)](https://travis-ci.org/rapid7/convection)
+_A fully generic, modular DSL for AWS CloudFormation_
+
+This gem aims to provide a reusable model for AWS CloudFormation in Ruby. It exposes a DSL for template definition, and a simple, decoupled abstraction of a CloudFormation Stack to compile and apply templates.
+
+## Contributing
+Please read our [Contributing guidelines](CONTRIBUTING.md) for more information on contributing to Convection.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'convection'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install convection
+
+##CLI Commands
+###### Converging
+- To converge all stacks in your cloudfile run `convection converge`. If you provide the name of your stack as a additional argument such as `convection converge my-stack-name` then all stacks above and including the stack you specified will be converged.
+
+###### Diff
+- To display diff between your local changes and the version of your stack in cloud formation of your changes run `convection diff`.
+
+###### Help
+- To print out a list of available cli options with their descriptions run `convection help`.
+
+###### Print
+- To print out the cloud formation template for a specific stack run `convection print my-stack-name`.
+
+###### Validate
+- To validate your stack is not missing a required resource run `convection validate my-stack-name`.
+
+## Documentation
+We highly recommend consulting the [getting started guide](./docs/getting-started.md) for a in depth walk through on how to to set up your project and create and deploy a stack. Example stacks and resources are available in the [convection/example](https://github.com/rapid7/convection/tree/master/example) folder
+
+## License
+_Copyright (c) 2015 John Manero, Rapid7 LLC._
+
+```
+MIT License
+===========
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+```

data/docs/pygment.css

@@ -0,0 +1,62 @@
+/* Pygment syntax highlighting setup for viewdocs.io */
+.highlight { background: #ffffff; }
+.highlight .pl-bp { color: #999999 } /* Name.Builtin.Pseudo */
+.highlight .pl-c { color: #999988; font-style: italic } /* Comment */
+.highlight .pl-c1 { color: #999988; font-style: italic } /* Comment.Single */
+.highlight .pl-cm { color: #999988; font-style: italic } /* Comment.Multiline */
+.highlight .pl-cp { color: #999999; font-weight: bold } /* Comment.Preproc */
+.highlight .pl-cs { color: #999999; font-weight: bold; font-style: italic } /* Comment.Special */
+.highlight .pl-err { color: #a61717; background-color: #e3d2d2 } /* Error */
+.highlight .pl-gd .x { color: #000000; background-color: #ffaaaa } /* Generic.Deleted.Specific */
+.highlight .pl-gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
+.highlight .pl-ge { font-style: italic } /* Generic.Emph */
+.highlight .pl-gh { color: #999999 } /* Generic.Heading */
+.highlight .pl-gi .x { color: #000000; background-color: #aaffaa } /* Generic.Inserted.Specific */
+.highlight .pl-gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
+.highlight .pl-go { color: #888888 } /* Generic.Output */
+.highlight .pl-gp { color: #555555 } /* Generic.Prompt */
+.highlight .pl-gr { color: #aa0000 } /* Generic.Error */
+.highlight .pl-gs { font-weight: bold } /* Generic.Strong */
+.highlight .pl-gt { color: #aa0000 } /* Generic.Traceback */
+.highlight .pl-gu { color: #800080; font-weight: bold; } /* Generic.Subheading */
+.highlight .pl-il { color: #009999 } /* Literal.Number.Integer.Long */
+.highlight .pl-k { font-weight: bold } /* Keyword */
+.highlight .pl-kc { font-weight: bold } /* Keyword.Constant */
+.highlight .pl-kd { font-weight: bold } /* Keyword.Declaration */
+.highlight .pl-kn { font-weight: bold } /* Keyword.Namespace */
+.highlight .pl-kp { font-weight: bold } /* Keyword.Pseudo */
+.highlight .pl-kr { font-weight: bold } /* Keyword.Reserved */
+.highlight .pl-kt { color: #445588; font-weight: bold } /* Keyword.Type */
+.highlight .pl-m { color: #009999 } /* Literal.Number */
+.highlight .pl-mf { color: #009999 } /* Literal.Number.Float */
+.highlight .pl-mh { color: #009999 } /* Literal.Number.Hex */
+.highlight .pl-mi { color: #009999 } /* Literal.Number.Integer */
+.highlight .pl-mo { color: #009999 } /* Literal.Number.Oct */
+.highlight .pl-na { color: #008080 } /* Name.Attribute */
+.highlight .pl-nb { color: #0086B3 } /* Name.Builtin */
+.highlight .pl-nc { color: #445588; font-weight: bold } /* Name.Class */
+.highlight .pl-ne { color: #990000; font-weight: bold } /* Name.Exception */
+.highlight .pl-nf { color: #990000; font-weight: bold } /* Name.Function */
+.highlight .pl-ni { color: #800080 } /* Name.Entity */
+.highlight .pl-nn { color: #555555 } /* Name.Namespace */
+.highlight .pl-no { color: #008080 } /* Name.Constant */
+.highlight .pl-nt { color: #000080 } /* Name.Tag */
+.highlight .pl-nv { color: #008080 } /* Name.Variable */
+.highlight .pl-o { font-weight: bold } /* Operator */
+.highlight .pl-ow { font-weight: bold } /* Operator.Word */
+.highlight .pl-s { color: #d14 } /* Literal.String */
+.highlight .pl-s1 { color: #d14 } /* Literal.String.Single */
+.highlight .pl-s2 { color: #d14 } /* Literal.String.Double */
+.highlight .pl-sb { color: #d14 } /* Literal.String.Backtick */
+.highlight .pl-sc { color: #d14 } /* Literal.String.Char */
+.highlight .pl-sd { color: #d14 } /* Literal.String.Doc */
+.highlight .pl-se { color: #d14 } /* Literal.String.Escape */
+.highlight .pl-sh { color: #d14 } /* Literal.String.Heredoc */
+.highlight .pl-si { color: #d14 } /* Literal.String.Interpol */
+.highlight .pl-sr { color: #009926 } /* Literal.String.Regex */
+.highlight .pl-ss { color: #990073 } /* Literal.String.Symbol */
+.highlight .pl-sx { color: #d14 } /* Literal.String.Other */
+.highlight .pl-vc { color: #008080 } /* Name.Variable.Class */
+.highlight .pl-vg { color: #008080 } /* Name.Variable.Global */
+.highlight .pl-vi { color: #008080 } /* Name.Variable.Instance */
+.highlight .pl-w { color: #bbbbbb } /* Text.Whitespace */

data/docs/relationship-to-cloudformation.md

@@ -0,0 +1,51 @@
+# Relationship to CloudFormation
+Convection builds on top of the [Amazon CloudFormation](https://aws.amazon.com/cloudformation/) resource managment tooling. Additionally it adds support for providing additional functionalities using thirdparty tools (AWS APIs or otherwise).
+
+## Convection Stacks
+A Convection Stack (see [Convection::Control::Stack][convection-stack-api]) acts as a Ruby wrapper for a CloudFormation stack. When `Convection::Control::Stack#to_json` is called it is rendered into the CloudFormation template format to be pushed to CloudFormation.
+
+Convection adds the notion of state by comparing the remote stack (from CloudFormation) and local stack (rendered from your Ruby DSL template).
+
+## Cloudfiles
+A Cloudfile is used to connect a series of stacks. A Cloudfile requires a name and a region. You can specify multiple stacks to converge for a given "cloud".
+
+### Example
+You may have multiple Cloudfiles for your different regions or for your test/prod environments like so:
+
+#### Environments
+##### `clouds/test-0/Cloudfile`
+```ruby
+name 'test-0'
+region 'us-east-1'
+
+# Mock RDS (create a ec2 mysql server, etc.) in the test environment for quicker turn around.
+stack 'rds', Templates::MOCK_RDS
+```
+
+##### `clouds/prod-0/Cloudfile`
+```ruby
+name 'prod-0'
+region 'us-east-1'
+
+stack 'rds', Templates::RDS
+```
+
+#### Regions
+##### `clouds/us-east-1/Cloudfile`
+```ruby
+name 'prod-0'
+region 'us-east-1'
+
+stack 'cdn', Templates::CDN
+```
+
+##### `clouds/us-west-1/Cloudfile`
+```ruby
+name 'prod-1'
+region 'us-west-1'
+
+# Instead of re-creating a CDN per region create a "cdn mirror" in this region.
+stack 'cdn', Templates::CDN_MIRROR
+```
+
+[convection-stack-api]: http://www.rubydoc.info/gems/convection/Convection/Control/Stack

data/docs/stacks.md

@@ -0,0 +1,86 @@
+# Convection Stacks
+**NOTE**: Examples in this file can be found in `example/stacks`.
+
+### Defining a stack
+Defining a stack is as simple as a few lines of Ruby:
+
+```ruby
+# templates/vpc.rb
+require 'convection'
+
+module Templates
+  VPC = Convection.template do
+    description 'EC2 VPC Test Template'
+
+    ec2_vpc 'TargetVPC' do
+      network '10.10.10.0/23'
+    end
+  end
+end
+```
+
+### Using a defined stack
+```ruby
+# Cloudfile
+require_relative './templates/vpc.rb'
+
+user = ENV['USER'] || 'anon'
+name "#{user}-demo-cloud"
+region 'us-east-1'
+
+stack 'vpc', Templates::VPC
+```
+
+Once evaluated by Convection stacks will be represented as CloudFormation JSON.
+
+### Defining a task to execute on a stack
+A stack has the following life-cycle phases:
+
+1. Before creation (`before_create_task`)
+2. After creation (`after_create_task`)
+3. Before being updated (`before_update_task`)
+4. After being updated (`after_update_task`)
+5. Before deletion (`before_delete_task`)
+6. After deletion (`after_delete_task`)
+
+To define tasks on a stack (using the `VPC` stack defined above for example):
+
+```ruby
+# tasks/lookup_vpc_task.rb
+module Tasks
+  class LookupVpcTask
+    # REQUIRED: Convection expects tasks to respond to #call.
+    def call(stack)
+      @vpc_id = stack.get('vpc', 'id')
+      @result = vpc_found?
+    end
+
+    # REQUIRED: Convection expects tasks to respond to #success?.
+    def success?
+      @result
+    end
+
+    # OPTIONAL: Convection emits the task as `task.to_s` in certain log messages.
+    def to_s
+      return 'VPC lookup' unless @vpc_id
+
+      "VPC lookup of #{@vpc_id.inspect}"
+    end
+
+    private
+
+    def vpc_found?
+      true # XXX: This could be a call to the aws-sdk APIs.
+    end
+  end
+end
+```
+
+You would then change your Cloudfile to give the optional configuration block to the stack declaration:
+```ruby
+# Cloudfile
+stack 'vpc', Templates::VPC do
+  after_create_task Tasks::LookupVpcTask.new
+  after_update_task Tasks::LookupVpcTask.new
+end
+```

data/docs/template.html

@@ -0,0 +1,130 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>{{NAME}} :: viewdocs.io</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta charset="utf-8">
+
+    <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootswatch/3.0.2/yeti/bootstrap.min.css">
+    <link rel="stylesheet" href="http://rapid7.github.io/convection/stylesheets/pygment.css">
+
+    <style>
+      html, body {
+        height: 100%;
+        margin: 0;
+        padding: 0;
+        /* The html and body elements cannot have any padding or margin. */
+      }
+
+      /* Wrapper for page content to push down footer */
+      #wrap {
+        min-height: 100%;
+        height: auto;
+        /* Negative indent footer by its height */
+        margin: 0 auto -60px;
+        /* Pad bottom by footer height */
+        padding: 0 0 60px;
+      }
+
+      /* Set the fixed height of the footer here */
+      footer {
+        height: 60px;
+        background-color: #f5f5f5;
+        padding-top: 9px;
+      }
+
+      footer p {
+        clear: left;
+        margin-bottom: 0;
+      }
+
+      #wrap > .container,.col-sm-3,.col-sm-9 {
+        padding-top: 60px;
+      }
+
+      #side-nav {
+        padding-left: 30px;
+      }
+
+      .navbar-nav>li>iframe {
+        margin-top: 12px;
+      }
+    </style>
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+  <body>
+    <div id="wrap">
+      <div class="navbar navbar-inverse navbar-fixed-top">
+        <div class="container">
+          <div class="navbar-header">
+            <a href="/{{NAME}}/" class="navbar-brand">{{NAME}}</a>
+            <button class="navbar-toggle" type="button" data-toggle="collapse" data-target="#navbar-main">
+              <span class="icon-bar"></span>
+              <span class="icon-bar"></span>
+              <span class="icon-bar"></span>
+            </button>
+          </div>
+          <div class="navbar-collapse collapse" id="navbar-main">
+            <ul class="nav navbar-nav">
+              <li>
+                <a href="https://github.com/{{USER}}/{{NAME}}">View on GitHub</a>
+              </li>
+              <li>
+                <a href="http://www.rubydoc.info/gems/{{NAME}}">View on RubyDoc.info</a>
+              </li>
+              <li>
+                <a href="https://rubygems.org/gems/{{NAME}}">View on RubyGems</a>
+              </li>
+            </ul>
+
+            <ul class="nav navbar-nav navbar-right visible-md visible-lg">
+              <li><iframe src="http://ghbtns.com/github-btn.html?user={{USER}}&repo={{NAME}}&type=watch&count=true" allowtransparency="true" frameborder="0" scrolling="0" width="110" height="20"></iframe></li>
+              <li><iframe src="http://ghbtns.com/github-btn.html?user={{USER}}&repo={{NAME}}&type=fork&count=true" allowtransparency="true" frameborder="0" scrolling="0" width="95" height="20"></iframe></li>
+              <li><iframe src="http://ghbtns.com/github-btn.html?user={{USER}}&type=follow&count=true" allowtransparency="true" frameborder="0" scrolling="0" width="165" height="20"></iframe></li>
+            </ul>
+          </div>
+        </div>
+      </div>
+
+      <div class="row">
+        <div id="side-nav" class="col-sm-3">
+          <div class="bs-component">
+            <ul class="list-group">
+              <li class="list-group-item"><a href="/{{NAME}}/">Home</a></li>
+              <li class="list-group-item"><a href="/{{NAME}}/getting-started">Getting Started</a></li>
+              <li class="list-group-item"><a href="/{{NAME}}/relationship-to-cloudformation">Relationship to CloudFormation</a></li>
+              <li class="list-group-item"><a href="/{{NAME}}/stacks">Stacks</a></li>
+              <li class="list-group-item"><a href="/{{NAME}}/deleting-stacks">Deleting Stacks</a></li>
+              <li class="list-group-item"><a href="/{{NAME}}/canceling-stack-updates">Canceling Stack Updates</a></li>
+              <li class="list-group-item"><a href="/{{NAME}}/adding-new-resource-coverage">Adding New Resource Coverage</a></li>
+
+            </ul>
+          </div>
+        </div>
+
+        <div class="col-sm-9">
+          {{CONTENT}}
+        </div>
+      </div>
+    </div>
+
+    <footer>
+      <div class="container">
+        <div class="row">
+          <div class="col-lg-12">
+            <p>Hosted on <a href="http://viewdocs.io">http://viewdocs.io</a>.</p>
+            <p>Theme based on <a href="http://bootswatch.com/yeti/">Yeti</a> built by <a href="http://thomaspark.me">Thomas Park</a> and adapted to Viewdocs by <a href="http://fabiorehm.com/">Fábio Rehm</a>.</p>
+          </div>
+        </div>
+      </div>
+    </footer>
+
+    <script src="//oss.maxcdn.com/libs/jquery/2.0.3/jquery.min.js"></script>
+    <script src="//netdna.bootstrapcdn.com/bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
+</html>

data/example/getting-started-guide/Cloudfile

@@ -0,0 +1,12 @@
+#See the getting started guide for a description of this file and what it does.
+#to run this file make sure you are following the project layout in the getting started guide
+Dir.glob('./../../templates/**.rb') do |file|
+  require_relative file
+end
+
+require 'convection'
+
+region 'us-east-1'
+name 'convection-demo'
+
+stack 'vpc', Templates::VPC

data/example/getting-started-guide/vpc.rb

@@ -0,0 +1,74 @@
+#See the getting started guide for a description of this file and what it does.
+#to run this file make sure you are following the project layout in the getting started guide
+require 'convection'
+
+module Templates
+  VPC = Convection.template do
+    description 'VPC with Public and Private Subnets (NAT)'
+
+    ec2_vpc 'DemoVPC' do
+      network '10.10.10.0/23'
+      tag 'Name', "#{stack.cloud}-#{stack.name}"
+      enable_dns true
+      add_route_table 'InternetGateway', gateway_route: true
+    end
+
+    ec2_subnet 'PrivateSubnet' do
+      network '10.10.10.0/24'
+      tag 'Name', "#{stack.cloud}-#{stack.name}-private"
+      vpc fn_ref('DemoVPC')
+    end
+
+    ec2_subnet 'PublicSubnet' do
+      network '10.10.11.0/24'
+      tag 'Name', "#{stack.cloud}-#{stack.name}-public"
+      vpc fn_ref('DemoVPC')
+      public_ips true
+    end
+
+    ec2_security_group 'NATSecurityGroup' do
+      description 'NAT access for private subnet'
+      vpc fn_ref('DemoVPC')
+      tag 'Name', "#{stack.cloud}-#{stack.name}-nat-security-group"
+      ingress_rule :tcp, 443 do
+        source '10.10.10.0/24'
+      end
+      ingress_rule :tcp, 80 do
+        source '10.10.10.0/24'
+      end
+      egress_rule :tcp, 443 do
+        source '0.0.0.0/0'
+      end
+      egress_rule :tcp, 80 do
+        source '0.0.0.0/0'
+      end
+    end
+
+    ec2_instance 'NATInstance' do
+      tag 'Name', "#{stack.cloud}-#{stack.name}-nat"
+      image_id 'ami-c02b04a8'
+      subnet fn_ref('PublicSubnet')
+      security_group fn_ref('NATSecurityGroup')
+      src_dst_checks false
+    end
+
+    ec2_subnet_route_table_association 'DemoVPCRouteTable' do
+      route_table fn_ref('DemoVPCTableInternetGateway')
+      subnet fn_ref('PublicSubnet')
+    end
+
+    ec2_route_table 'PrivateRouteTable' do
+      vpc fn_ref('DemoVPC')
+      route 'PrivateRoute' do
+        destination '0.0.0.0/0'
+        instance fn_ref('NATInstance')
+      end
+    end
+
+    ec2_subnet_route_table_association 'PrivateRouteAssoc' do
+      route_table fn_ref('PrivateRouteTable')
+      subnet fn_ref('PrivateSubnet')
+    end
+
+  end
+end