convection 0.2.33 → 0.2.34.pre.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 70262a473c642f00cc51b9077ca02c2617194320
-  data.tar.gz: bba7acb1a3242c6b354a384e9924f33c8a69ce13
+  metadata.gz: 837d14e5ddd6639c86b5c3bb0cf6dd5396919125
+  data.tar.gz: 2079fa841463566dd1b7eacd62a104f1e70d627e
 SHA512:
-  metadata.gz: df10a72ab338b4e6dec65b93942a0577d53db0d88bbe30e820a1536918192a8adee745b016c4067e3973a1bffccac2ee3cf9016d0930e3a52774185e7bca1edc
-  data.tar.gz: 61f8a1e4761e464a1a3a18139c02caa49839d93fb89be9cc68affe13d4baa9dc2bfbbd47cdcea31e442d4e1d154e6878da50dae25304fa09ce6f7850949eb677
+  metadata.gz: 0b3f343979e83ddb138d30d97ae57f5a8da0ee6b90346b9d7966a9b0ccbb8ee7f545eb0536695ad053a5f74cd6309d83b21e31436808bbcf1ec26d9acee9e5a0
+  data.tar.gz: b39d1d06d1a03e41db3fa78cab20d33a2c2f9be94541896af8b3973f5c71486bee3d0c4df4385b0024ca7643980129830210a8f0e6889e242bbdd28a10f776dc

data/.yardopts

@@ -0,0 +1 @@
+-e yard_extensions.rb

data/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing to Convection
+The following document is a list of guidelines for making contributing to the Convection project.
+
+## Table Of Contents
+* [Developing](#developing)
+  * [Branches](#branches)
+
+## Developing
+### Branches
+We strive to use [Semantic Versioning](http://semver.org) as much as possible for convection.
+
+### `master`
+**NOTE**: The `master` branch is fully supported by the convection maintainers.
+
+The latest and greatest code that we intend to release to Rubygems is merged into this branch.
+Today that code happens to be part of the `v0.2.x` minor version since we have not deemed convection feature
+complete (we'll release a `v1.0.0` release at that point).
+
+Backwards incompatible changes until this time *may* be added by bumping the **minor** (not major) version of
+the project. These will be explicitly called out in the release notes for the version that introduced them and if
+possible a deprecation message and compatibility will be kept making users aware of a potential the breaking change in
+the future.

data/README.md

@@ -3,15 +3,8 @@ _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.
 
-## Branches
-We strive to use [Semantic Versioning](http://semver.org) as much as possible for convection.
-
-### `master`
-**NOTE**: The `master` branch is fully supported by the convection maintainers.
-
-The latest and greatest code that we intend to release to Rubygems is merged into this branch.
-Today that code happens to be part of the `v0.2.x` minor version since we have not deemed convection feature complete (we'll release a `v1.0.0` release at that point).
-Backwards incompatible changes until this time *may* be added by bumping the **minor** (not major) version of the project. These will be explicitly called out in the release notes for the version that introduced them and if possible a deprecation message and compatibility will be kept making users aware of a potential the breaking change in the future.
+## Contributing
+Please read our [Contributing guidelines](CONTRIBUTING.md) for more information on contributing to Convection.
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -28,204 +21,24 @@ 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
+##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.
 
-```ruby
-condition 'ThisCondition' do
-  fn_equals( fn_ref('SomeParameter'), 'value_x' )
-end
-
-condition 'ThatCondition' do
-  fn_or(
-    fn_equals( fn_ref('SomeParameter'), 'value_y' ),
-    fn_equals( fn_ref('SomeParameter'), 'value_z' )
-  )
-end
-```
-
-### 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
-```
-
-Using a condition to set a resource property:
-
-```ruby
-resource 'MySQL' do
-  type 'AWS::RDS::DBInstance'
-  ...
-  property 'Iops', fn_if('ThisCondition', '1000', fn_ref('AWS::NoValue'))
-  ...
-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
-```
+###### Diff
+- To display diff between your local changes and the version of your stack in cloud formation of your changes run `convection diff`.
 
-## 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.
+###### Help
+- To print out a list of available cli options with their descriptions run `convection help`.
 
-### 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`
+###### Print
+- To print out the cloud formation template for a specific stack run `convection print my-stack-name`.
 
-* `#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.
+###### Validate
+- To validate your stack is not missing a required resource run `convection validate my-stack-name`.
 
-## Futures
-*
+## 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._

data/Rakefile

@@ -1,8 +1,11 @@
 require 'bundler/gem_tasks'
 require 'rubocop/rake_task'
 require 'rspec/core/rake_task'
+require 'yard'
+require_relative './yard_extensions'
 
 RuboCop::RakeTask.new
 RSpec::Core::RakeTask.new(:spec)
+YARD::Rake::YardocTask.new
 
 task :default => [:spec, :rubocop]

data/docs/adding-new-resource-coverage.md

@@ -0,0 +1,265 @@
+#Adding a CloudFormation resource to Convection
+This guide will document how convection support for AWS::EC2::DHCPOptions was added. This example can be followed to add coverage for other CloudFormation resources
+
+1) Create a new class `convection/lib/convection/model/template/resource/aws_ec2_dhcp_options.rb` See the example below.
+```ruby
+require_relative '../resource'
+
+module Convection
+  module Model
+    class Template
+      class Resource
+        ##
+        # AWS::EC2::DHCPOptions
+        ##
+        class EC2DHCPOptions < Resource
+          type 'AWS::EC2::DHCPOptions'
+        end
+      end
+    end
+  end
+end
+```
+2) Go to the CloudFormation resource documentation and use that as a guide for how you will define the resource properties. Viewing the [DHCPOptions] (http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-dhcp-options.html) api doc we can see that we have several resource properties we will need to handle.
+```json
+{
+   "Type" : "AWS::EC2::DHCPOptions",
+   "Properties" : {
+      "DomainName" : String,
+      "DomainNameServers" : [ String, ... ],
+      "NetbiosNameServers" : [ String, ... ],
+      "NetbiosNodeType" : Number,
+      "NtpServers" : [ String, ... ],
+      "Tags" : [ Resource Tag, ... ]
+   }
+}
+```
+3) Lets define the properties. Map the json key value pairs to ruby. `"DomainName" : String` in json will be defined in our template as `property :domain_name, 'DomainName'`. So with our first property added our new convection resource class will look like
+```ruby
+require_relative '../resource'
+
+module Convection
+  module Model
+    class Template
+      class Resource
+        ##
+        # AWS::EC2::DHCPOptions
+        ##
+        class EC2DHCPOptions < Resource
+          type 'AWS::EC2::DHCPOptions'
+          property :domain_name, 'DomainName'
+        end
+      end
+    end
+  end
+end
+```
+4) You have probably noticed that some of these parameters expect a string array. For those we will add `:type => :list`. See below
+```ruby
+require_relative '../resource'
+
+module Convection
+  module Model
+    class Template
+      class Resource
+        ##
+        # AWS::EC2::DHCPOptions
+        ##
+        class EC2DHCPOptions < Resource
+          type 'AWS::EC2::DHCPOptions'
+          property :domain_name, 'DomainName'
+          property :domain_name_servers, 'DomainNameServers', :type => :list
+          property :netbios_name_servers, 'NetbiosNameServers', :type => :list
+          property :netbios_node_type, 'NetbiosNodeType'
+          property :ntp_servers, 'NtpServers', :type => :list
+        end
+      end
+    end
+  end
+end
+```
+5) To add tag support to the resource add the below block and include
+```ruby
+include Model::Mixin::Taggable
+
+def render(*args)
+  super.tap do |resource|
+    render_tags(resource)
+  end
+end
+```
+6) The completed class should look like the below. Once you are finished developing the class add a yard doc example.
+```ruby
+require_relative '../resource'
+
+module Convection
+  module Model
+    class Template
+      class Resource
+        ##
+        # AWS::EC2::DHCPOptions
+        #
+        # @example
+        #   ec2_dhcp_options 'TestOptions' do
+        #     domain_name 'example.com'
+        #     domain_name_servers  '10.0.0.1', '10.0.0.2'
+        #     netbios_name_servers '10.0.0.1', '10.0.0.2'
+        #     netbios_node_type 1
+        #     ntp_servers '10.0.0.1', '10.0.0.2'
+        #     tag 'Name', 'Test'
+        #   end
+        ##
+        class EC2DHCPOptions < Resource
+          include Model::Mixin::Taggable
+          type 'AWS::EC2::DHCPOptions'
+          property :domain_name, 'DomainName'
+          property :domain_name_servers, 'DomainNameServers', :type => :list
+          property :netbios_name_servers, 'NetbiosNameServers', :type => :list
+          property :netbios_node_type, 'NetbiosNodeType'
+          property :ntp_servers, 'NtpServers', :type => :list
+
+          def render(*args)
+            super.tap do |resource|
+              render_tags(resource)
+            end
+          end
+        end
+      end
+    end
+  end
+end
+```
+7) Unit Tests! Adding tests for resources is simple, create a new test class. `convection/spec/convection/model/template/resource/ec2_dhcp_options_spec.rb`
+8) Set up the basic structure of the class.
+```ruby
+require 'spec_helper'
+
+class Convection::Model::Template::Resource
+  describe DHCPOptions do
+    let(:template) do
+      Convection.template do
+
+
+      end
+    end
+
+  end
+end
+```
+9) Add the mock template. Below is a example
+```ruby
+require 'spec_helper'
+
+class Convection::Model::Template::Resource
+  describe DHCPOptions do
+    let(:template) do
+      Convection.template do
+
+        ec2_dhcp_options 'TestOptions' do
+          domain_name 'example.com'
+          domain_name_servers  '10.0.0.1', '10.0.0.2'
+          netbios_name_servers '10.0.0.1', '10.0.0.2'
+          netbios_node_type 1
+          ntp_servers '10.0.0.1', '10.0.0.2'
+        end
+      end
+    end
+
+  end
+end
+```
+10) Lets add some helper methods to get retrieve our template parameters. See below, NOTE we added the `subject` block and `template_json` method.
+```ruby
+require 'spec_helper'
+
+class Convection::Model::Template::Resource
+  describe EC2DHCPOptions do
+    let(:template) do
+      Convection.template do
+
+        ec2_dhcp_options 'TestOptions' do
+          domain_name 'example.com'
+          domain_name_servers  '10.0.0.1', '10.0.0.2'
+          netbios_name_servers '10.0.0.1', '10.0.0.2'
+          netbios_node_type 1
+          ntp_servers '10.0.0.1', '10.0.0.2'
+        end
+      end
+    end
+
+    subject do
+      template_json
+        .fetch('Resources')
+        .fetch('TestOptions')
+        .fetch('Properties')
+    end
+
+
+    private
+
+    def template_json
+      JSON.parse(template.to_json)
+    end
+  end
+end
+```
+11) Test time, below is our complete spec file with test for the defined parameters. Note in the test where we reference values in the subject object `subject['DomainName']` the hash key we use is the one set in our property block `property :domain_name, 'DomainName'`.
+```ruby
+require 'spec_helper'
+
+class Convection::Model::Template::Resource
+  describe EC2DHCPOptions do
+    let(:template) do
+      Convection.template do
+
+        ec2_dhcp_options 'TestOptions' do
+          domain_name 'example.com'
+          domain_name_servers  '10.0.0.1', '10.0.0.2'
+          netbios_name_servers '10.0.0.1', '10.0.0.2'
+          netbios_node_type 1
+          ntp_servers '10.0.0.1', '10.0.0.2'
+          tag 'Name', 'Test'
+        end
+      end
+    end
+
+    subject do
+      template_json
+        .fetch('Resources')
+        .fetch('TestOptions')
+        .fetch('Properties')
+    end
+
+    it 'sets the DomainName' do
+      expect(subject['DomainName']).to eq('example.com')
+    end
+
+    it 'sets the DomainNameServers' do
+      expect(subject['DomainNameServers']).to match_array(['10.0.0.1', '10.0.0.2'])
+    end
+
+    it 'sets the NetbiosNameServers' do
+      expect(subject['NetbiosNameServers']).to match_array(['10.0.0.1', '10.0.0.2'])
+    end
+
+    it 'sets the NetbiosNodeType' do
+      expect(subject['NetbiosNodeType']).to eq(1)
+    end
+
+    it 'sets the NtpServers' do
+      expect(subject['NtpServers']).to match_array(['10.0.0.1', '10.0.0.2'])
+    end
+
+    it 'sets tags' do
+      expect(subject['Tags']).to include(hash_including('Key' => 'Name', 'Value' => 'Test'))
+    end
+
+    private
+
+    def template_json
+      JSON.parse(template.to_json)
+    end
+  end
+end
+
+```