convection 0.2.33 → 0.2.34.pre.beta.1

data/docs/canceling-stack-updates.md

@@ -0,0 +1,5 @@
+# Canceling Stack Updates
+To cancel a convection converge
+
+1. Kill the converge with control + c.
+2. Following the directions provided here to cancel the update and trigger a rollback. http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn--stack-update-cancel.html

data/docs/deleting-stacks.md

@@ -0,0 +1,5 @@
+# Deleting Convection Stacks
+To delete a convection stack
+
+1. Delete the stack from the Cloudfile and converge.
+2. Follow the directions provided here to delete it from CloudFormation. http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-delete-stack.html

data/docs/getting-started.md

@@ -0,0 +1,904 @@
+# Getting Started #
+
+This guide walks you through the creation of a Convection template that matches
+up with one of [Amazon's VPC Wizard Scenarios][vpc2], creating a VPC with public
+and private subnets.
+
+By the end of this guide you'll have the following resources in your Amazon
+account
+
+* A CloudFormation template describing everything in this guide
+* A VPC with two subnets, one public, one private
+* A NAT router so EC2 instances in the private subnet can reach the internet
+* A security group for the NAT router so you can control access to it
+
+To get started, create the following directory structure for your project. If your region is not us-east-1 then change that to your region. If you have multiple regions create multiple region folders each with their own cloud file.
+```
+my-convection-project/
+├── clouds
+│   └── us-east-1
+└── templates
+```
+In the top level of your convection project create a file "Gemfile" with the following inside.
+```ruby
+gem 'convection'
+```
+
+In the us-east-1 folder open a new file named "Cloudfile" and put the following Ruby
+```ruby
+Dir.glob('./../../templates/**.rb') do |file|
+  require_relative file
+end
+
+region 'us-east-1'
+name 'convection-demo'
+```
+
+Cloudfiles are written using Convection's DSL. The "convection" gem defines
+methods like `region` and `name`. The `region` method tells Convection where
+AWS resources should be created. The `name` method provides a common identifier
+for grouping AWS resources.
+
+The core of Convection's DSL consists of two parts, templates and stacks.
+Templates let you to describe AWS resources in a reusable fashion. Stacks are
+instances of a template in Amazon. We're going to start by creating a template
+and stack to define our VPC.
+
+Update your Cloudfile to look like the one below.
+
+```ruby
+Dir.glob('./../../templates/**.rb') do |file|
+  require_relative file
+end
+
+region 'us-east-1'
+name 'convection-demo'
+
+stack 'vpc', Templates::VPC
+```
+In the templates directory create a vpc.rb file and include the following in it.
+```ruby
+require 'convection'
+
+module Templates
+  VPC = Convection.template do
+    description 'VPC with Public and Private Subnets (NAT)'
+
+  end
+end
+```
+
+The `template` method creates a Convection template. The `description` property
+in the template maps to the "Description" property in a [CloudFormation template][cf-template].
+Assigning the result of the `template` method to the `VPC` variable allows us to
+pass the template to the `stack` method. The `stack` method defines a
+CloudFormation stack in AWS.
+
+This separation between the description of AWS resources (the template) and
+the instantiation of those resources (the stack) makes Convection templates
+flexible.
+
+Now that we've got a Convection template, we can run Convection's diff command
+to compare what's in our template with what's in Amazon. This is a new template,
+so we should only see new resources being created.
+
+```text
+$> convection diff
+
+compare  Compare local state of stack vpc (convection-demo-vpc) with remote template
+ create  .AWSTemplateFormatVersion: 2010-09-09
+ create  .Description: VPC with Public and Private Subnets (NAT)
+```
+
+The first line of output tells us that Convection's comparing our "vpc" stack
+with the remote CloudFormation stack in Amazon. Since this is a new stack,
+Convection prints two more lines telling us it's going to create the stack and
+give it a description.
+
+Now that we know what Convection's going to do, we can ask it to check that
+stack creation will succeed. To do that, we run Convection's validate command.
+
+```text
+$> convection validate vpc
+
+Template format error: At least one Resources member must be defined.
+```
+
+The validate command takes a single argument, the name of the stack to validate.
+We only have the "vpc" stack, so that's what we're validating. Convection
+tells us that our template's not valid. We're missing a resource.
+
+Since we're building a VPC with two subnets, let's add the VPC itself as a
+resource. Our VPC will be of size /23 and use the CIDR block 10.10.10.0/23.
+
+Update your vpc.rb template to look like the one below.
+
+```ruby
+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'
+    end
+  end
+end
+```
+
+The `ec2_vpc` method defines an [AWS::EC2::VPC][cf-vpc] resource in
+Convection. VPC resources require a CIDR block. We set the `network`
+property in our template to the CIDR block we want our VPC to use. Now
+we can validate our template.
+
+```text
+$> convection validate vpc
+
+Template validated successfully
+```
+
+Our template's good, so we'll diff it again to see what's going to change.
+
+```text
+$> convection diff
+
+compare  Compare local state of stack vpc (convection-demo-vpc) with remote template
+ create  .AWSTemplateFormatVersion: 2010-09-09
+ create  .Description: VPC with Public and Private Subnets (NAT)
+ create  .Resources.DemoVPC.Type: AWS::EC2::VPC
+ create  .Resources.DemoVPC.Properties.CidrBlock: 10.10.10.0/23
+```
+
+That looks correct. Convection will create a VPC with a CIDR block of
+10.10.10.0/23.  We can run Convection's converge command to create the VPC in
+Amazon.
+
+```text
+$> convection converge
+
+converge  Stack vpc
+create_in_progress  convection-demo-vpc: (AWS::CloudFormation::Stack) User Initiated
+create_in_progress  DemoVPC: (AWS::EC2::VPC)
+create_in_progress  DemoVPC: (AWS::EC2::VPC) Resource creation Initiated
+create_complete  DemoVPC: (AWS::EC2::VPC)
+create_complete  convection-demo-vpc: (AWS::CloudFormation::Stack)
+```
+
+If we look at the Amazon web console, you can see Convection's created two
+new things for us. There's a CloudFormation stack named "convection-demo-vpc"
+and there's the actual VPC resource, which is currently unnamed.
+
+We can name the VPC resource by tagging it. Setting the `tag` attribute on
+the "DemoVPC" resource in Convection will add a tag to the resource. We'll use
+a combination of the cloud name and the stack name as the tag for the VPC.
+
+Update your vpc.rb template to look like the one below.
+
+```ruby
+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}"
+    end
+  end
+end
+```
+
+We're using a naming convection for resources that includes the cloud name and
+the stack name. That makes it easy to look through the Amazon web console and
+see which resources belong to which Convection managed clouds. Now we run
+the diff command to see the changes Convection will apply.
+
+```text
+$> convection diff
+
+compare  Compare local state of stack vpc (convection-demo-vpc) with remote template
+ create  .Resources.DemoVPC.Properties.Tags.0.Key: Name
+ create  .Resources.DemoVPC.Properties.Tags.0.Value: convection-demo-vpc
+```
+To see what the cloud formation template for your vpc template would look like you can run `convection print vpc`.
+This can help you verify that values referenced under the `stack` namespace are set correctly.
+
+```json
+$> convection print vpc
+{
+  "AWSTemplateFormatVersion": "2010-09-09",
+  "Description": "VPC with Public and Private Subnets (NAT)",
+  "Parameters": {
+  },
+  "Mappings": {
+  },
+  "Conditions": {
+  },
+  "Resources": {
+    "DemoVPC": {
+      "Type": "AWS::EC2::VPC",
+      "Properties": {
+        "CidrBlock": "10.10.10.0/23",
+        "Tags": [
+          {
+            "Key": "Name",
+            "Value": "convection-demo-vpc"
+          }
+        ]
+      }
+    }
+  },
+  "Outputs": {
+  }
+}
+```
+
+Convection's going to add the "Name" tag to the "DemoVPC" resource. That's what
+we want, so we can converge our template.
+
+```text
+$> convection converge
+
+converge  Stack vpc
+update_in_progress  convection-demo-vpc: (AWS::CloudFormation::Stack) User Initiated
+update_in_progress  DemoVPC: (AWS::EC2::VPC)
+update_complete  DemoVPC: (AWS::EC2::VPC)
+update_complete_cleanup_in_progress  convection-demo-vpc: (AWS::CloudFormation::Stack)
+update_complete  convection-demo-vpc: (AWS::CloudFormation::Stack)
+```
+
+Looking at the Amazon web console, we can see that our VPC is now named
+"convection-demo-vpc".
+
+## Creating a private subnet ##
+
+The CIDR block for our VPC is 10.10.10/23. We'll set up a public subnet
+with a CIDR block of 10.10.11.0/24 and a private subnet with a CIDR block of
+10.10.10.0/24. Let's create the private subnet first.
+
+Just like there's an `ec2_vpc` method in Convection for creating a VPC, there's
+also an `ec2_subnet` method for creating a subnet. And like our VPC, our subnet
+will have `network` and `tag` attributes.
+
+Update your vpc.rb template to look like the one below.
+
+```ruby
+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}"
+    end
+
+    ec2_subnet 'PrivateSubnet' do
+      network '10.10.10.0/24'
+      tag 'Name', "#{stack.cloud}-#{stack.name}-private"
+    end
+
+  end
+end
+```
+
+We can run the diff command to see what Convection's going to create.
+
+```text
+$> convection diff
+
+compare  Compare local state of stack vpc (convection-demo-vpc) with remote template
+ create  .Resources.PrivateSubnet.Type: AWS::EC2::Subnet
+ create  .Resources.PrivateSubnet.Properties.CidrBlock: 10.10.10.0/24
+ create  .Resources.PrivateSubnet.Properties.Tags.0.Key: Name
+ create  .Resources.PrivateSubnet.Properties.Tags.0.Value: convection-demo-vpc-private
+```
+
+There's our new private subnet with its CIDR block and "Name" tag. If we look at
+the documentation for the [AWS::EC2::Subnet][cf-subnet] resource, we
+can see it has a required "VpcId" attribute. We can use the Convection's
+`fn_ref` method to get the logical ID of our VPC resource and pass it in to the subnet.
+
+Update your vpc.rb template to look like the one below.
+
+```ruby
+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}"
+    end
+
+    ec2_subnet 'PrivateSubnet' do
+      network '10.10.10.0/24'
+      tag 'Name', "#{stack.cloud}-#{stack.name}-private"
+      vpc fn_ref('DemoVPC')
+    end
+
+  end
+end
+```
+
+Now we can diff the Cloudfile and see that the "VpcId" property's getting set
+on our subnet.
+
+```text
+$> convection diff
+
+compare  Compare local state of stack vpc (convection-demo-vpc) with remote template
+ create  .Resources.PrivateSubnet.Type: AWS::EC2::Subnet
+ create  .Resources.PrivateSubnet.Properties.VpcId.Ref: DemoVPC
+ create  .Resources.PrivateSubnet.Properties.CidrBlock: 10.10.10.0/24
+ create  .Resources.PrivateSubnet.Properties.Tags.0.Key: Name
+ create  .Resources.PrivateSubnet.Properties.Tags.0.Value: convection-demo-vpc-private
+```
+
+Let's converge the Cloudfile, and create a new private subnet in Amazon.
+
+```text
+$> convection converge
+
+converge  Stack vpc
+update_in_progress  convection-demo-vpc: (AWS::CloudFormation::Stack) User Initiated
+create_in_progress  PrivateSubnet: (AWS::EC2::Subnet)
+create_in_progress  PrivateSubnet: (AWS::EC2::Subnet) Resource creation Initiated
+create_complete  PrivateSubnet: (AWS::EC2::Subnet)
+update_complete_cleanup_in_progress  convection-demo-vpc: (AWS::CloudFormation::Stack)
+update_complete  convection-demo-vpc: (AWS::CloudFormation::Stack)
+```
+
+## Creating a public subnet ##
+
+Creating a public subnet is exactly the same as creating a private subnet.
+Use the `ec2_subnet` method to create an [AWS::EC2::Subnet][cf-subnet]
+resource and give it a CIDR block of 10.10.11.0/24. Insert the following convection code into your vpc.rb template to accomplish this.
+
+```ruby
+ec2_subnet 'PublicSubnet' do
+  network '10.10.11.0/24'
+  tag 'Name', "#{stack.cloud}-#{stack.name}-public"
+  vpc fn_ref('DemoVPC')
+end
+```
+
+Looking at the documentation for the [AWS::EC2::Subnet][cf-subnet]
+resource, the major difference between a public and private subnet is
+that Amazon assigns IP addresses to public subnets. Making a subnet public is
+a matter of setting the "MapPublicIpOnLaunch" property to `true`.
+
+Add the below line to your `PublicSubnet` block
+
+```ruby
+public_ips true
+```
+
+Your diff should contain your changes for the public subnet.
+
+```text
+$> convection diff
+
+compare  Compare local state of stack vpc (convection-demo-vpc) with remote template
+ create  .Resources.PublicSubnet.Type: AWS::EC2::Subnet
+ create  .Resources.PublicSubnet.Properties.VpcId.Ref: DemoVPC
+ create  .Resources.PublicSubnet.Properties.CidrBlock: 10.10.11.0/24
+ create  .Resources.PublicSubnet.Properties.MapPublicIpOnLaunch: true
+ create  .Resources.PublicSubnet.Properties.Tags.0.Key: Name
+ create  .Resources.PublicSubnet.Properties.Tags.0.Value: convection-demo-vpc-public
+```
+
+Convection says it will create our public subnet with the "MapPublicIpOnLaunch"
+property set to `true`. It also doesn't show any changes to our private subnet.
+That's what we expect, so we can converge our template.
+
+```text
+$> convection converge
+
+converge  Stack vpc
+update_in_progress  convection-demo-vpc: (AWS::CloudFormation::Stack) User Initiated
+create_in_progress  PublicSubnet: (AWS::EC2::Subnet)
+create_in_progress  PublicSubnet: (AWS::EC2::Subnet) Resource creation Initiated
+create_complete  PublicSubnet: (AWS::EC2::Subnet)
+update_complete_cleanup_in_progress  convection-demo-vpc: (AWS::CloudFormation::Stack)
+update_complete  convection-demo-vpc: (AWS::CloudFormation::Stack)
+```
+
+If we look at our subnets in the Amazon web console, we can see the public
+subnet has the "Auto-assign Public IP" attribute set to "yes" and the private
+subnet has that value set to "no". Any EC2 instances we create in the public
+subnet will automatically get public IP addresses.
+
+## Create a security group for the NAT router ##
+
+Our NAT router is going to live in the public subnet. However, we want to
+restrict access so only EC2 instances in our private subnet can use it. We can
+do this with a security group.
+
+Convection provides an `ec2_security_group` method for creating security groups.
+The [AWS::EC2::SecurityGroup][cf-security-group] resource requires a description
+and a reference to our VPC. We can add the `ec2_security_group` method to our
+Cloudfile with a `description` and `vpc` attribute to create a default security
+group for our NAT router.
+
+Add the below block to your vpc.rb template
+
+```ruby
+ec2_security_group 'NATSecurityGroup' do
+  description 'NAT access for private subnet'
+  vpc fn_ref('DemoVPC')
+  tag 'Name', "#{stack.cloud}-#{stack.name}-nat-security-group"
+end
+```
+
+We'll follow the same pattern we've used before. Diff the Convection template to
+make sure it does what we expect, then converge it. This pattern of diffing then
+converging is useful when paired with code reviews. You can make changes to a
+template, diff it, then have the changes and diff reviewed before you converge.
+
+```text
+$> convection diff
+
+compare  Compare local state of stack vpc (convection-demo-vpc) with remote template
+ create  .Resources.NATSecurityGroup.Type: AWS::EC2::SecurityGroup
+ create  .Resources.NATSecurityGroup.Properties.GroupDescription: NAT access for private subnet
+ create  .Resources.NATSecurityGroup.Properties.VpcId.Ref: DemoVPC
+ create  .Resources.NATSecurityGroup.Properties.Tags.0.Key: Name
+ create  .Resources.NATSecurityGroup.Properties.Tags.0.Value: convection-demo-vpc-nat-security-group
+```
+
+```text
+$> convection converge
+
+converge  Stack vpc
+update_in_progress  convection-demo-vpc: (AWS::CloudFormation::Stack) User Initiated
+create_in_progress  NATSecurityGroup: (AWS::EC2::SecurityGroup)
+create_in_progress  NATSecurityGroup: (AWS::EC2::SecurityGroup) Resource creation Initiated
+create_complete  NATSecurityGroup: (AWS::EC2::SecurityGroup)
+update_complete_cleanup_in_progress  convection-demo-vpc: (AWS::CloudFormation::Stack)
+update_complete  convection-demo-vpc: (AWS::CloudFormation::Stack)
+```
+
+Looking at our new security group in the Amazon web console, we can see it
+doesn't have any inbound rules. Lets update our security group to allow inbound
+web traffic from our private subnet.
+
+Within the `ec2_security_group` method, Convection provides the `ingress_rule`
+helper method for defining inbound rules. The method takes a traffic type, a
+port number, and a block for setting the rule's `source` attribute.
+
+Update the block in your `ec2_security_group` method to look like the one below.
+
+```ruby
+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
+end
+```
+
+This locks down our NAT router so it can only receive requests for web traffic
+from our private subnet. Having ingress rules for ports 443 and 80 allows us to
+handle both HTTPS and HTTP traffic.
+
+By default, Amazon sets an outbound rule on our security group that allows all
+traffic. Since our NAT router only handles web traffic, we can add egress rules
+as well and lock down outbound requests. Convection has an `egress_rule` method
+for setting output traffic rules. It has the same syntax as the `ingress_rule`
+method.
+
+Your vpc.rb template should now look like the one below.
+
+```ruby
+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}"
+    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
+
+  end
+end
+```
+
+Our security group's locked down, so we can diff our template and see what
+changes.
+
+```text
+$> convection diff
+
+compare  Compare local state of stack vpc (convection-demo-vpc) with remote template
+ create  .Resources.NATSecurityGroup.Properties.SecurityGroupIngress.0.IpProtocol: 6
+ create  .Resources.NATSecurityGroup.Properties.SecurityGroupIngress.0.FromPort: 443
+ create  .Resources.NATSecurityGroup.Properties.SecurityGroupIngress.0.ToPort: 443
+ create  .Resources.NATSecurityGroup.Properties.SecurityGroupIngress.0.CidrIp: 10.10.10.0/24
+ create  .Resources.NATSecurityGroup.Properties.SecurityGroupIngress.1.IpProtocol: 6
+ create  .Resources.NATSecurityGroup.Properties.SecurityGroupIngress.1.FromPort: 80
+ create  .Resources.NATSecurityGroup.Properties.SecurityGroupIngress.1.ToPort: 80
+ create  .Resources.NATSecurityGroup.Properties.SecurityGroupIngress.1.CidrIp: 10.10.10.0/24
+ create  .Resources.NATSecurityGroup.Properties.SecurityGroupEgress.0.IpProtocol: 6
+ create  .Resources.NATSecurityGroup.Properties.SecurityGroupEgress.0.FromPort: 443
+ create  .Resources.NATSecurityGroup.Properties.SecurityGroupEgress.0.ToPort: 443
+ create  .Resources.NATSecurityGroup.Properties.SecurityGroupEgress.0.CidrIp: 0.0.0.0/0
+ create  .Resources.NATSecurityGroup.Properties.SecurityGroupEgress.1.IpProtocol: 6
+ create  .Resources.NATSecurityGroup.Properties.SecurityGroupEgress.1.FromPort: 80
+ create  .Resources.NATSecurityGroup.Properties.SecurityGroupEgress.1.ToPort: 80
+ create  .Resources.NATSecurityGroup.Properties.SecurityGroupEgress.1.CidrIp: 0.0.0.0/0
+```
+
+It's exactly what we expect. Looks like it's just the ingress and egress rules,
+so we can converge the template and apply the changes.
+
+```text
+$> convection converge
+
+converge  Stack vpc
+update_in_progress  convection-demo-vpc: (AWS::CloudFormation::Stack) User Initiated
+update_in_progress  NATSecurityGroup: (AWS::EC2::SecurityGroup)
+update_complete  NATSecurityGroup: (AWS::EC2::SecurityGroup)
+update_complete_cleanup_in_progress  convection-demo-vpc: (AWS::CloudFormation::Stack)
+update_complete  convection-demo-vpc: (AWS::CloudFormation::Stack)
+```
+
+## Create the NAT router ##
+
+Now that we've got our security group, we need to set up an EC2 instance that
+will function as a NAT router. We'll be using one of [Amazon's pre-built NAT
+images][nat-instance] since we don't need anything custom. Open up the Amazon
+web console and search for AMIs with the string "amzn-ami-vpc-nat-pv" in their
+name. The most recent one, from March 2015, has ID ami-c02b04a8.
+
+The [AWS::EC2::Instance][cf-ec2] resource handles creating our
+router instance from the given AMI. Since our router provides internet access,
+it needs to be in the public subnet. We also need to disable source/destination
+checking so it can perform network address translation. Finally, we'll make
+sure the instance is in the security group we just created.
+
+Update your vpc.rb template to look like the one below.
+
+```ruby
+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}"
+    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
+
+  end
+end
+```
+
+We can diff our template to see what's going to change.
+
+```text
+$> convection diff
+
+compare  Compare local state of stack vpc (convection-demo-vpc) with remote template
+ create  .Resources.NATInstance.Type: AWS::EC2::Instance
+ create  .Resources.NATInstance.Properties.ImageId: ami-c02b04a8
+ create  .Resources.NATInstance.Properties.SubnetId.Ref: PublicSubnet
+ create  .Resources.NATInstance.Properties.SecurityGroupIds.0.Ref: NATSecurityGroup
+ delete  .Resources.NATInstance.Properties.SourceDestCheck
+ create  .Resources.NATInstance.Properties.Tags.0.Key: Name
+ create  .Resources.NATInstance.Properties.Tags.0.Value: convection-demo-vpc-nat
+```
+
+It's just our NAT router that's new, so let's converge it.
+
+```text
+$> convection converge
+
+converge  Stack vpc
+update_in_progress  convection-demo-vpc: (AWS::CloudFormation::Stack) User Initiated
+create_in_progress  NATInstance: (AWS::EC2::Instance)
+create_in_progress  NATInstance: (AWS::EC2::Instance) Resource creation Initiated
+create_complete  NATInstance: (AWS::EC2::Instance)
+update_complete_cleanup_in_progress  convection-demo-vpc: (AWS::CloudFormation::Stack)
+update_complete  convection-demo-vpc: (AWS::CloudFormation::Stack)
+```
+## Create a route table for the public subnet ##
+
+In order for instances in our public subnet to reach the internet, our VPC needs
+an [AWS::EC2::InternetGateway][cf-internet-gateway] resource. Using stock
+CloudFormation, we'd create the gateway and wire it up to to our VPC with an
+[AWS::EC2::VPCGatewayAttachment][cf-gateway-attachment]. We'd also need a with
+[AWS::EC2::RouteTable][cf-route-table] resource for the gateway with a
+default [AWS::EC2::Route][cf-route] resource that lets it connect to the
+world.
+
+We could use Convection to create each of those resources. However, there's a
+simpler way. Convection provides an `add_route_table` method that can generate
+an internet gateway and wire it up to our VPC.
+
+Update your `ec2_vpc` block to look like the one below. NOTE we added `enable_dns` and `add_route_table`.
+```ruby
+  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
+```
+
+Diffing our template, we can see our VPC will get a Route, RouteTable,
+InternetGateway, and InternetGateway attachment. The route lets the internet
+gateway talk to the world, which is exactly what we want. Notice that we're
+also enabling DNS support and hostnames on our VPC.
+
+```text
+$> convection diff
+
+compare  Compare local state of stack vpc (convection-demo-vpc) with remote template
+ create  .Resources.DemoVPCTableInternetGateway.Type: AWS::EC2::RouteTable
+ create  .Resources.DemoVPCTableInternetGateway.Properties.VpcId.Ref: DemoVPC
+ create  .Resources.DemoVPCTableInternetGateway.Properties.Tags.0.Key: Name
+ create  .Resources.DemoVPCTableInternetGateway.Properties.Tags.0.Value: DemoVPCTableInternetGateway
+ create  .Resources.DemoVPCIGVPCAttachmentDemoVPC.Type: AWS::EC2::VPCGatewayAttachment
+ create  .Resources.DemoVPCIGVPCAttachmentDemoVPC.Properties.VpcId.Ref: DemoVPC
+ create  .Resources.DemoVPCIGVPCAttachmentDemoVPC.Properties.InternetGatewayId.Ref: DemoVPCIG
+ create  .Resources.DemoVPCIG.Type: AWS::EC2::InternetGateway
+ create  .Resources.DemoVPCIG.Properties.Tags.0.Key: Name
+ create  .Resources.DemoVPCIG.Properties.Tags.0.Value: DemoVPCInternetGateway
+ create  .Resources.DemoVPCTableInternetGatewayRouteDefault.Type: AWS::EC2::Route
+ create  .Resources.DemoVPCTableInternetGatewayRouteDefault.Properties.RouteTableId.Ref: DemoVPCTableInternetGateway
+ create  .Resources.DemoVPCTableInternetGatewayRouteDefault.Properties.DestinationCidrBlock: 0.0.0.0/0
+ create  .Resources.DemoVPCTableInternetGatewayRouteDefault.Properties.GatewayId.Ref: DemoVPCIG
+ create  .Resources.DemoVPC.Properties.EnableDnsSupport: true
+ create  .Resources.DemoVPC.Properties.EnableDnsHostnames: true
+```
+
+Everything looks good, so we can converge the stack and create new resources.
+
+```text
+$> convection converge
+
+converge  Stack vpc
+update_in_progress  convection-demo-vpc: (AWS::CloudFormation::Stack) User Initiated
+create_in_progress  DemoVPCIG: (AWS::EC2::InternetGateway)
+create_in_progress  DemoVPCIG: (AWS::EC2::InternetGateway) Resource creation Initiated
+update_in_progress  DemoVPC: (AWS::EC2::VPC)
+update_complete  DemoVPC: (AWS::EC2::VPC)
+create_in_progress  DemoVPCTableInternetGateway: (AWS::EC2::RouteTable)
+create_in_progress  DemoVPCTableInternetGateway: (AWS::EC2::RouteTable) Resource creation Initiated
+create_complete  DemoVPCTableInternetGateway: (AWS::EC2::RouteTable)
+create_complete  DemoVPCIG: (AWS::EC2::InternetGateway)
+create_in_progress  DemoVPCTableInternetGatewayRouteDefault: (AWS::EC2::Route)
+create_in_progress  DemoVPCIGVPCAttachmentDemoVPC: (AWS::EC2::VPCGatewayAttachment)
+create_in_progress  DemoVPCIGVPCAttachmentDemoVPC: (AWS::EC2::VPCGatewayAttachment) Resource creation Initiated
+create_in_progress  DemoVPCTableInternetGatewayRouteDefault: (AWS::EC2::Route) Resource creation Initiated
+create_complete  DemoVPCIGVPCAttachmentDemoVPC: (AWS::EC2::VPCGatewayAttachment)
+create_complete  DemoVPCTableInternetGatewayRouteDefault: (AWS::EC2::Route)
+update_complete_cleanup_in_progress  convection-demo-vpc: (AWS::CloudFormation::Stack)
+update_complete  convection-demo-vpc: (AWS::CloudFormation::Stack)
+```
+Now that we have an internet gateway, we need to associate its route table with
+the public subnet. We can create an
+[AWS::EC2::SubnetRouteTableAssociation][cf-association] resource to do that. The
+`ec2_subnet_route_table_association` method in Convection will do that.
+
+Add the below block to the bottom of your vpc.rb template below your `ec2_instance 'NATInstance'` block.
+
+```ruby
+ec2_subnet_route_table_association 'DemoVPCRouteTable' do
+  route_table fn_ref('DemoVPCTableInternetGateway')
+  subnet fn_ref('PublicSubnet')
+end
+```
+
+Where did the reference to "DemoVPCTableInternetGateway" come from? Convection
+took the name of our VPC "DemoVPC", added "Table" to it, and appended the name
+of our route table "InternetGateway". Looking at the output from our previous
+converge shows the "DemoVPCTableInternetGateway" resource being created. Use
+diff to check that the route table association will be created.
+
+```text
+$> convection diff
+
+compare  Compare local state of stack vpc (convection-demo-vpc) with remote template
+ create  .Resources.DemoVPCRouteTable.Type: AWS::EC2::SubnetRouteTableAssociation
+ create  .Resources.DemoVPCRouteTable.Properties.RouteTableId.Ref: DemoVPCTableInternetGateway
+ create  .Resources.DemoVPCRouteTable.Properties.SubnetId.Ref: PublicSubnet
+```
+
+Now go ahead and converge the stack.
+
+```text
+$> convection converge
+
+converge  Stack vpc
+update_in_progress  convection-demo-vpc: (AWS::CloudFormation::Stack) User Initiated
+create_in_progress  DemoVPCRouteTable: (AWS::EC2::SubnetRouteTableAssociation)
+create_in_progress  DemoVPCRouteTable: (AWS::EC2::SubnetRouteTableAssociation) Resource creation Initiated
+create_complete  DemoVPCRouteTable: (AWS::EC2::SubnetRouteTableAssociation)
+update_complete_cleanup_in_progress  convection-demo-vpc: (AWS::CloudFormation::Stack)
+update_complete  convection-demo-vpc: (AWS::CloudFormation::Stack)
+```
+
+## Create a route table for the private subnet ##
+
+Just like we created a route table for the public subnet, we now need a route
+table for the private subnet. Our route table will reference our VPC and define
+a single route for all traffic from our private instances through our NAT.
+Convection's `ec2_route_table` method can be used to explicitly create a route
+table.
+
+Add the below block to the bottom of your vpc.rb template
+
+```ruby
+ec2_route_table 'PrivateRouteTable' do
+  vpc fn_ref('DemoVPC')
+  route 'PrivateRoute' do
+    destination '0.0.0.0/0'
+    instance fn_ref('NATInstance')
+  end
+end
+```
+
+Now we need to link the private route table to the private subnet. Like we did
+for the public subnet, we can use Convection's `ec2_subnet_route_table_association`
+method.
+
+Add the below to the bottom of your vpc.rb template.
+
+```ruby
+ec2_subnet_route_table_association 'PrivateRouteAssoc' do
+  route_table fn_ref('PrivateRouteTable')
+  subnet fn_ref('PrivateSubnet')
+end
+
+```
+
+Diffing the template shows three new resources, one for the route, one for the
+route table, and one for the subnet association.
+
+```text
+$> convection diff
+
+compare  Compare local state of stack vpc (convection-demo-vpc) with remote template
+ create  .Resources.PrivateRouteTableRoutePrivateRoute.Type: AWS::EC2::Route
+ create  .Resources.PrivateRouteTableRoutePrivateRoute.Properties.RouteTableId.Ref: PrivateRouteTable
+ create  .Resources.PrivateRouteTableRoutePrivateRoute.Properties.DestinationCidrBlock: 0.0.0.0/0
+ create  .Resources.PrivateRouteTableRoutePrivateRoute.Properties.InstanceId.Ref: NATInstance
+ create  .Resources.PrivateRouteTable.Type: AWS::EC2::RouteTable
+ create  .Resources.PrivateRouteTable.Properties.VpcId.Ref: DemoVPC
+ create  .Resources.PrivateRouteAssoc.Type: AWS::EC2::SubnetRouteTableAssociation
+ create  .Resources.PrivateRouteAssoc.Properties.RouteTableId.Ref: PrivateRouteTable
+ create  .Resources.PrivateRouteAssoc.Properties.SubnetId.Ref: PrivateSubnet
+```
+
+Converge the stack and create the new resources.
+
+```text
+$> convection converge
+
+converge  Stack vpc
+update_in_progress  convection-demo-vpc: (AWS::CloudFormation::Stack) User Initiated
+create_in_progress  PrivateRouteTable: (AWS::EC2::RouteTable)
+create_in_progress  PrivateRouteTable: (AWS::EC2::RouteTable) Resource creation Initiated
+create_complete  PrivateRouteTable: (AWS::EC2::RouteTable)
+create_in_progress  PrivateRouteTableRoutePrivateRoute: (AWS::EC2::Route)
+create_in_progress  PrivateRouteAssoc: (AWS::EC2::SubnetRouteTableAssociation)
+create_in_progress  PrivateRouteTableRoutePrivateRoute: (AWS::EC2::Route) Resource creation Initiated
+create_in_progress  PrivateRouteAssoc: (AWS::EC2::SubnetRouteTableAssociation) Resource creation Initiated
+create_complete  PrivateRouteAssoc: (AWS::EC2::SubnetRouteTableAssociation)
+create_complete  PrivateRouteTableRoutePrivateRoute: (AWS::EC2::Route)
+update_complete_cleanup_in_progress  convection-demo-vpc: (AWS::CloudFormation::Stack)
+update_complete  convection-demo-vpc: (AWS::CloudFormation::Stack)
+```
+
+## Where to go from here ##
+
+We used Convection to build an Amazon VPC with public and private subnets,
+complete with a NAT router for handling internet traffic and a security group
+for locking down access. From here we could add bastion servers to get SSH
+access to EC2 instances in the private subnet, or network ACLs to further harden
+the VPC.
+
+Whatever we do, we now have a solid workflow for making infrastructure
+improvements. Make a small change. Diff to see what's going to be updated.
+Converge the change if it looks good.
+
+
+[vpc2]: http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_Scenario2.html
+[cf-template]: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-reference.html
+[cf-vpc]: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-vpc.html
+[cf-subnet]: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-subnet.html
+[ec2-subnet]: https://github.com/rapid7/convection/blob/v0.2/lib/convection/model/template/resource/aws_ec2_subnet.rb
+[cf-ref]: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html
+[cf-ec2]: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-instance.html
+[cf-security-group]: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-security-group.html
+[cf-internet-gateway]: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-internet-gateway.html
+[cf-route-table]: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-route-table.html
+[cf-gateway-attachment]: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-vpc-gateway-attachment.html
+[cf-route]: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-route.html
+[cf-association]: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-subnet-route-table-assoc.html
+[nat-instance]: http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_NAT_Instance.html