convection 0.0.1

data/lib/convection/version.rb

@@ -0,0 +1,6 @@
+# nodoc
+module Convection
+  VERSION = IO.read(File.expand_path('../../../VERSION', __FILE__)) rescue '0.0.1'
+  SUMMARY = 'A fully generic, modular DSL for AWS CloudFormation'
+  DESCRIPTION = IO.read(File.expand_path('../../../README.md', __FILE__)) rescue ''
+end

metadata

@@ -0,0 +1,375 @@
+--- !ruby/object:Gem::Specification
+name: convection
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- John Manero
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: thor-scmversion
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+- !ruby/object:Gem::Dependency
+  name: aws-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - <
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - <
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: netaddr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+description: |
+  # 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.
+
+  ```
+email:
+- jmanero@rapid7.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rubocop.yml
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- Thorfile
+- convection.gemspec
+- example/iam_role.rb
+- example/s3.rb
+- example/vpc.rb
+- lib/convection.rb
+- lib/convection/control/stack.rb
+- lib/convection/dsl/helpers.rb
+- lib/convection/dsl/intrinsic_functions.rb
+- lib/convection/model/mixin/cidr_block.rb
+- lib/convection/model/mixin/conditional.rb
+- lib/convection/model/mixin/taggable.rb
+- lib/convection/model/template.rb
+- lib/convection/model/template/mapping.rb
+- lib/convection/model/template/output.rb
+- lib/convection/model/template/parameter.rb
+- lib/convection/model/template/resource.rb
+- lib/convection/model/template/resource/aws_ec2_instance.rb
+- lib/convection/model/template/resource/aws_ec2_internet_gateway.rb
+- lib/convection/model/template/resource/aws_ec2_route.rb
+- lib/convection/model/template/resource/aws_ec2_route_table.rb
+- lib/convection/model/template/resource/aws_ec2_security_group.rb
+- lib/convection/model/template/resource/aws_ec2_subnet.rb
+- lib/convection/model/template/resource/aws_ec2_subnet_route_table_association.rb
+- lib/convection/model/template/resource/aws_ec2_vpc.rb
+- lib/convection/model/template/resource/aws_ec2_vpc_gateway_attachment.rb
+- lib/convection/model/template/resource/aws_iam_policy.rb
+- lib/convection/model/template/resource/aws_iam_role.rb
+- lib/convection/model/template/resource/aws_s3_bucket.rb
+- lib/convection/model/template/resource/aws_s3_bucket_policy.rb
+- lib/convection/version.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.14
+signing_key: 
+specification_version: 4
+summary: A fully generic, modular DSL for AWS CloudFormation
+test_files: []