convection 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c0e40b87f41fe55c9ae72164fb2f4bfd6a65b7e6
+  data.tar.gz: 6c2136c2a50025cbc8ab781362717afbd919bde4
+SHA512:
+  metadata.gz: 73e16b10a0ff8accc52f4f50840ce91638d28e83df66b258b6b577f7955733aa471c621054eabd272ac2d62f3dfee6d9c28f4e2494f3cdc948341f7d31f02cf1
+  data.tar.gz: 6170446d0c4ccd1cc348b596529c11917017323df2c25f8983f2ea598f3ccc05fed5c37797c4bb1db90bb457096a43bd46b3008de09ef0fb588d88b21d032c46

data/.gitignore

@@ -0,0 +1,17 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+
+keys
+VERSION

data/.rubocop.yml

@@ -0,0 +1,16 @@
+AllCops:
+ Exclude:
+   - libraries/**/*
+   - spec/**/*
+   - metadata.rb
+
+Encoding:
+ Enabled: false
+LineLength:
+ Enabled: false
+HashSyntax:
+ Enabled: false
+RescueModifier:
+  Enabled: false
+MethodLength:
+  Max: 24

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in convection.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,23 @@
+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/README.md

@@ -0,0 +1,224 @@
+# 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.
+
+## Version 0.0.1
+This is an Alpha release. It is still lacking functionality and testing. We plan to develop/improve features as we begin to use it for our own deployments in the coming months. PRs welcome.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'convection'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install convection
+
+## Template DSL
+The core DSL provides all of the available JSON primatives of CloudFormation in the form of ruby methods. These primatives are used to compose higher-order methods for commonly used definitions:
+
+```ruby
+require 'convection'
+
+## Create a new instance of Convection::Model::Template
+Convection.template do
+  description 'An example template'
+
+  parameter 'InstanceSize' do
+    type 'String'
+    description 'Instance Size'
+    default 'm3.medium'
+
+    allow 'm3.medium'
+    allow 'm3.large'
+    allow 'm3.xlarge'
+  end
+
+  ## The `resource` method can be used to define any resource
+  ## supported by CloudFormation: See http://docs.aws.amazon.com/\
+  ## AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html
+  resource 'AnEC2Instance' do
+    type 'AWS::EC2::Instance'
+    property 'AvailabilityZone', 'us-east-1a'
+    property 'ImageId', 'ami-76e27e1e' ## Ubuntu 14.04 hvm:ebs
+    property 'KeyName', 'test'
+    property 'SecurityGroupIds', ['sg-dd733c41', 'sg-dd738df3']
+    property 'Tags', [{
+      'Key' => 'Name',
+      'Value' => 'test-1'
+    }]
+
+    property 'DisableApiTermination', false
+  end
+
+  ## `ec2_instnce` extends `resource`. The following results in JSON
+  ## identical to that of Resource[AnEC2Instance]
+  ec2_instance 'AnOtherInstance' do
+    availability_zone 'us-east-1a'
+    image_id 'ami-76e27e1e'
+    key_name 'test'
+
+    security_group 'sg-dd733c41'
+    security_group 'sg-dd738df3'
+
+    tag 'Name', 'test-2'
+
+    ## All of the methods of the `resource` primative are available in
+    ## its children:
+    property 'DisableApiTermination', false
+  end
+end.to_json
+```
+
+### Parameters
+http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html
+
+```ruby
+parameter 'InstanceType' do
+  type 'String'
+  description 'Set the thing\'s instance flavor'
+  default 'm3.medium'
+
+  allow 'm3.medium'
+  allow 'm3.large'
+  allow 'm3.xlarge'
+end
+```
+
+### Mappings
+http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/mappings-section-structure.html
+
+```ruby
+mapping 'RegionalAMIs' do
+  item 'us-east-1', 'hvm', 'ami-76e27e1e'
+  item 'us-west-1', 'hvm', 'ami-d5180890'
+  item 'us-east-1', 'pv', 'ami-64e27e0c'
+  item 'us-west-1', 'pv', 'ami-c5180880'
+end
+```
+
+### Conditions
+http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/conditions-section-structure.html
+
+Not implemented yet.
+
+### Resources
+http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resources-section-structure.html
+
+```ruby
+resource 'AnInstance' do
+  type 'AWS::EC2::Instance'
+
+  ## Optional condition reference
+  condition 'SomeCondition'
+
+  ## Add Resource Properties
+  property 'AvailabilityZone', 'us-east-1a'
+  property 'ImageId', 'ami-76e27e1e' ## Ubuntu 14.04 hvm:ebs
+  property 'KeyName', 'test'
+  ...
+end
+```
+
+### Outputs
+http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html
+
+```ruby
+output 'SomeName' do
+  description 'An Important Attribute'
+  value get_att('Resource', 'Attribute')
+
+  ## Optional condition reference
+  condition 'SomeCondition'
+end
+```
+
+### Intrinsic Functions
+http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html
+
+All intrinsic functions are available as helper methods:
+
+ * base64(content)
+ * fn_and(conditions...)
+ * fn_equals(value_1, value_2)
+ * fn_if(condition, value_true, value_false)
+ * fn_not(condition)
+ * fn_or(conditions...)
+ * find_in_map(map_name, key_1, key_2)
+ * get_att(resource, attr_name)
+ * get_azs(region)
+ * join(delimiter, values...)
+ * select(index, objects...)
+ * fn_ref(resource)
+
+```ruby
+ec2_instance "TestInstanceFoo#{ i }" do
+  image_id find_in_map('RegionalAMIs', fn_ref('AWS::Region'), 'hvm')
+  instance_type 'm3.medium'
+  key_name find_in_map('RegionalKeys', fn_ref('AWS::Region'), 'test')
+  security_group fn_ref('LousySecurityGroup')
+  subnet fn_ref("TestSubnet")
+end
+```
+
+## Stack Control
+The `Stack` class provides a state wrapper for CloudFormation Stacks. It tracks the state of the managed stack, and creates/updates accordingly. `Stack` is also region-aware, and can be used within a template to define resources that depend upon availability-zones or other region-specific neuances that cannot be represented as maps or require iteration.
+
+### Class `Convection::Control::Stack`
+* `.new(name, template, options = {})`
+  * _name_ CloudFormation Stack name
+  * _template_ Instance of Convection::Model::Template
+  * _options_ - Hash
+    * _region_ - AWS region, format `us-east-1`. Default us-east-1
+    * _credentials_ - Optional instance of AWS::Credentials. See the [AWS-SDK Documentation](http://docs.aws.amazon.com/sdkforruby/api/frames.html)
+    * _parameters_ - Stack parameters, as a `Hash` of `{ key => value }`
+    * _tags_ - Stack tags, as a `Hash` of `{ key => value }`
+    * _on_failure_ - Create failure action. Default `DELETE`
+    * _capabilities_ - See the [AWS-SDK Documentation](http://docs.aws.amazon.com/sdkforruby/api/Aws/CloudFormation/Client.html#create_stack-instance_method)
+    * Additional options will be passed directly to `create_stack` and `update_stack`
+
+* `#status` - Returns the stack status
+* `#exist?` - Returns true if the stack exists and is not in a DELETED state
+* `#complete?`
+* `#rollback?`
+* `#fail?`
+* `#render` - Populates the provided template with any environment data included in the stack (e.g. availability zones). Returns a `Hash`
+* `#to_json` - Render template and transofrm to a pretty-generated JSON `String`
+* `#apply` - Renter template and create/update CloudFormation Stack
+* `#delete` - Delete CloudFormation Stack
+* `#availability_zones(&block)` - Return an array of strings representing the region's availability zones. Provided codeblock will be called for each AZ.
+
+## 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/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/Thorfile

@@ -0,0 +1,5 @@
+# encoding: utf-8
+
+require 'bundler'
+require 'bundler/setup'
+require 'thor/scmversion'

data/convection.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'convection/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'convection'
+  spec.version       = Convection::VERSION
+  spec.authors       = ['John Manero']
+  spec.email         = ['jmanero@rapid7.com']
+  spec.summary       = Convection::SUMMARY
+  spec.description   = Convection::DESCRIPTION
+  spec.homepage      = ''
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(/^bin\//) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(/^(test|spec|features)\//)
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.7'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'thor-scmversion', '= 1.7.0'
+
+  spec.add_runtime_dependency 'aws-sdk', '< 2'
+  spec.add_runtime_dependency 'netaddr', '~> 1.5.0'
+end

data/example/iam_role.rb

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+# $LOAD_PATH.unshift(File.expand_path('../../lib', __FILE__))
+require 'convection'
+
+##
+# This is a quick example of building out a cloudformation template without
+# extending the underlying DSL.
+#
+# The reason could be anything from the inability to extend the dsl to a feature
+# in AWS has been made availalble but the DSL will be complex - so this is a
+# quick way to get access to those features.
+##
+
+test_iam_role_template = Convection.template do
+  description 'This is an example of a stack representing IAM Roles and Policies.'
+
+  parameter 'Path' do
+    type 'String'
+    default '/'
+  end
+
+  iam_policy 'RolePolicy' do
+    role fn_ref('NewRole')
+    # You can choose between multiple 'role' attributes
+    # or build out an array with multiple values.
+    name 'NewPolicy'
+    # Note the move to fat colons below:
+    policy_document({
+    "Statement"=> [
+        {
+          "Effect"=> "Allow",
+          "Action"=> [
+              "s3:GetObject"
+          ],
+          "Resource"=> [
+              "arn:aws:s3:::some.bucket.name.here/*"
+          ]
+        }
+      ]
+    })
+  end
+
+  iam_role 'NewRole' do
+    path fn_ref('Path')
+    # This is a contrived example of an instance role for aws.
+    assume_role_policy_document({
+      "Statement" => [
+      {
+        "Sid" => "",
+        "Effect" => "Allow",
+        "Principal" => {
+          "Service" => "ec2.amazonaws.com"
+        },
+        "Action" => "sts:AssumeRole"
+      }
+     ]
+   })
+  end
+
+end
+
+puts test_iam_role_template.to_json
+# puts Convection.stack('IAMTestStack', test_iam_role_template, :region => 'us-west-1').apply

data/example/s3.rb

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+require 'convection'
+
+s3_template = Convection.template do
+  description 'Testing S3 bucket definition'
+
+  s3_bucket 'TestBucket' do
+    bucket_name 'convectiontestbucket'
+  end
+end
+
+puts s3_template.to_json
+# puts Convection.stack('S3TestStack', s3_template, :region => 'us-west-1').apply

data/example/vpc.rb

@@ -0,0 +1,85 @@
+#!/usr/bin/env ruby
+require 'convection'
+
+test_template = Convection.template do
+  description 'This is a test stack generated with Convection'
+
+  parameter 'InstanceSize' do
+    type 'String'
+    description 'Instance Size'
+    default 'm3.medium'
+
+    allow 'm3.medium'
+    allow 'm3.large'
+    allow 'm3.xlarge'
+  end
+
+  mapping 'RegionalAMIs' do
+    item 'us-east-1', 'hvm', 'ami-76e27e1e'
+    item 'us-west-1', 'hvm', 'ami-d5180890'
+    item 'us-east-1', 'pv', 'ami-64e27e0c'
+    item 'us-west-1', 'pv', 'ami-c5180880'
+  end
+
+  mapping 'RegionalKeys' do
+    item 'us-east-1', 'test', 'cf-test-keys'
+    item 'us-west-1', 'test', 'cf-test-keys'
+  end
+
+  ## Define the VPC
+  ec2_vpc 'TargetVPC' do
+    network '100.65.0.0/18'
+    subnet_length 25
+
+    ## Add an InternetGateway
+    add_internet_gateway
+
+    ## Add a default routing table
+    public_table = add_route_table('Public', :gateway_route => true)
+
+    ## Define Subnets and Insatnces in each availability zone
+    stack.availability_zones do |zone, i|
+      add_subnet "Test#{ i }" do
+        availability_zone zone
+        associate_route_table public_table
+
+        tag 'Service', 'Foo'
+      end
+    end
+
+    tag 'Name', join('-', 'cf-test-vpc', fn_ref('AWS::StackName'))
+  end
+
+  ec2_security_group 'BetterSecurityGroup' do
+    ingress_rule do
+      cidr_ip '0.0.0.0/0'
+      from 22
+      to 22
+      protocol 'TCP'
+    end
+    egress_rule do
+      cidr_ip '0.0.0.0/0'
+      from 0
+      to 65_535
+      protocol(-1)
+    end
+
+    description 'Allow SSH traffic from all of the places'
+    vpc_id fn_ref('TargetVPC')
+
+    tag 'Name', join('-', fn_ref('AWS::StackName'), 'BetterSecurityGroup')
+  end
+end
+
+# puts test_template.render
+# puts test_template.to_json
+
+# stack_e1 = Convection.stack('TestStackE1B1', test_template, :region => 'us-east-1')
+stack_w1 = Convection.stack('TestStackW1B2', test_template, :region => 'us-west-1')
+
+# puts stack_e1.status
+# puts stack_e1.apply
+puts stack_w1.to_json
+
+puts "Status #{ stack_w1.status }"
+# puts stack_w1.apply