cfer 0.5.0.pre.rc4 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 920b540c1393d65eca22f5058ef46209581064a3
-  data.tar.gz: 305ea70aebc10866edf04d318581002a0d6d23ed
+  metadata.gz: 78cb715113442fbbec2fa9c33e2e243bd048960c
+  data.tar.gz: f48b5126eebba1e069e2a26f8de51d9fc5f49d80
 SHA512:
-  metadata.gz: a0641e4b71578c1eca5891ceeff60caa79a065462627efc8abd44ae9065b7ec71024c1f4f8f811efb709f06bccd95128a9aa2e3f289dcd8ed042a06d3f6fc46b
-  data.tar.gz: 44f48d246f170fb5f6af197c606fdc40927de89c858ae83577ddb35260e5307975b2e59df80acbc146ba454693924708d6c3cb8ec253c9970acbe5bd5f70cd1d
+  metadata.gz: 16f2f7eec9dab63812568214952a1aee5668a9553c4c9156346f9a8dffe43e07a6a63e0667bb8491ce9d225493a631c5132af794afb5679bb43afd69896bfa9d
+  data.tar.gz: c4978b1220c8ce036a6fb4b2b96d695af2cd39b79a18e50371a58434102c8803df735ca18c0625a494c6d58bd798a6de0a82c855c6ce42bdd3fc89ae251319a5

data/.codeclimate.yml

@@ -12,6 +12,8 @@ engines:
     enabled: true
   rubocop:
     enabled: true
+    exclude_fingerprints:
+      - 9d7be17b9e5e786560cf0df662f55736
 ratings:
   paths:
   - "**.inc"

data/.travis.yml

@@ -14,6 +14,7 @@ branches:
   - develop
 script:
 - bundle exec rspec
+- bundle exec codeclimate-test-reporter
 - bundle exec yard
 addons:
   code_climate:

data/Gemfile

@@ -7,8 +7,9 @@ group :test do
   gem 'rspec'
   gem 'rspec-mocks'
   gem 'guard-rspec'
-  gem 'coveralls', require: false
-  gem "codeclimate-test-reporter", require: nil
+  gem 'simplecov'
+  gem 'rubocop', '~> 0.47.1'
+  gem "codeclimate-test-reporter", "~> 1.0.0"
 end
 
 group :debug do

data/README.md

@@ -9,7 +9,7 @@
 
 Cfer is a lightweight toolkit for managing CloudFormation templates.
 
-Read about Cfer [here](http://tilmonedwards.com/2015/07/28/cfer.html).
+Read about Cfer [here](https://github.com/seanedwards/cfer/blob/master/examples/vpc.md).
 
 ## Support
 
@@ -247,5 +247,5 @@ This project also contains a [Code of Conduct](https://github.com/seanedwards/cf
 
 # Release Notes
 
-[Change Log](https://github.com/seanedwards/cfer/CHANGELOG.md)
+[Change Log](https://github.com/seanedwards/cfer/blob/master/CHANGELOG.md)
 

data/bin/cfer

@@ -6,7 +6,7 @@ module Cfer
   DEBUG = false
 end
 
-require 'cfer'
+require 'cfer/cli'
 
 
 Cfer::Cli::main(ARGV)

data/examples/vpc.md

@@ -0,0 +1,194 @@
+When I first encountered AWS CloudFormation, I was appalled by the format for about ten minutes. This is the criticism of it that I've heard most often: the unwieldy syntax makes it unapproachable. Writing it by hand is worse than lunch meetings. I don't disagree.
+
+However, I think CloudFormation makes a pretty decent intermediate language. Users of Elasic Beanstalk might notice a bunch of CloudFormation stacks in their account, all containing some kind of Amazon-produced EB magic. This is where CloudFormation excels: Machine-generated infrastructure.
+
+To that end, I took a couple weekends and wrote [Cfer](https://github.com/seanedwards/cfer), a DSL for generating CloudFormation templates in Ruby. [I'm](http://chrisfjones.github.io/coffin/) [not](https://github.com/bazaarvoice/cloudformation-ruby-dsl) [the](https://github.com/stevenjack/cfndsl) [only](https://github.com/Optaros/cloud_builder) [one](https://github.com/rapid7/convection) [doing](https://github.com/cloudtools/troposphere) [this](https://cfn-pyplates.readthedocs.org/en/latest/). But I'll run through an example template, which will help you build a basic VPC in AWS, and at the same time, address some of the features of Cfer that might make CloudFormation a little more appealing to you.
+
+If you find the format of this post difficult to follow, you can see this same example as a fully functional template in [examples/vpc.rb](https://github.com/seanedwards/cfer/blob/develop/examples/vpc.rb)
+
+
+This template creates the following resources for a basic beginning AWS VPC setup:
+
+1. A VPC
+2. A route table to control network routing
+3. An Internet gateway to route traffic to the public internet
+4. 3 subnets, one in each of the account's first 3 availability zones
+5. A default network route to the IGW
+6. Associated plumbing resources to link it all together
+
+## Template Parameters
+
+Template parameters allow you to use the same template to build multiple similar instances of parts of your infrastructure. Parameters may be defined using the `parameter` function:
+
+```ruby
+parameter :VpcName, default: 'Example VPC'
+```
+
+Resources are created using the `resource` function, accepting the following arguments:
+
+1. The resource name (string or symbol)
+2. The resource type. See the AWS CloudFormation docs for the [available resource types](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html).
+
+
+## The VPC Resource
+
+The VPC is the foundation of your private network in AWS.
+
+```ruby
+resource :vpc, 'AWS::EC2::VPC' do
+```
+
+Each line within the resource block sets a single property. These properties are simply camelized using the ActiveSupport gem's `camelize` function. This means that the `cidr_block` function will set the `CidrBlock` property.
+
+```ruby
+cidr_block '172.42.0.0/16'
+```
+
+Following this pattern, `enable_dns_support` sets the `EnableDnsSupport` property.
+
+```ruby
+enable_dns_support true
+enable_dns_hostnames true
+instance_tenancy 'default'
+```
+
+The `tag` function is available on all resources, and adds keys to the resource's `Tags` property. It accepts the following arguments:
+
+1. Tag name (symbol or string)
+2. Tag value
+
+```ruby
+tag :DefaultVpc, true
+```
+
+Parameters are required at template generation time, and therefore may be referenced using the `parameters` hash anywhere in a template. This will render the parameter value as a string constant in the CloudFormation JSON output.
+
+```ruby
+tag :Name, parameters[:VpcName]
+```
+
+Finally, we can finish this resource by closing the block that we started when we called the `resource` function.
+
+```ruby
+end
+```
+
+## The Internet Gateway
+
+Instances in your VPC will need to be able to access the internet somehow, and an internet gateway is the mechanism for making this happen. Let's create one.
+
+If there are no properties to set on a resource, the `do..end` block may be omitted entirely
+
+```ruby
+resource :defaultigw, 'AWS::EC2::InternetGateway'
+```
+
+## Attaching the Gateway
+
+For a gateway to be routable, it needs to be attached to a specific VPC using a "VPC Gateway Attachment" resource.
+
+`Fn::ref` serves the same purpose as CloudFormation's `{"Ref": ""}` intrinsic function.
+
+```ruby
+resource :vpcigw, 'AWS::EC2::VPCGatewayAttachment' do
+  vpc_id Fn::ref(:vpc)
+  internet_gateway_id Fn::ref(:defaultigw)
+end
+```
+
+## The Route Table
+
+A VPC also needs a route table. Every VPC comes with a default route table, but I like to create my own resources so that they're all expressed in the template.
+
+```ruby
+resource :routetable, 'AWS::EC2::RouteTable' do
+  vpc_id Fn::ref(:vpc)
+end
+```
+
+## The Default Route
+
+We also have to set up a default route, so that any traffic that the VPC doesn't recognize gets routed off to the internet gateway.
+
+The `resource` function accepts one additional parameter that was not addressed above: the options hash. Additional options passed here will be placed inside the resource, but outside the `Properties` block. In this case, we've specified that the default route explicitly depends on the VPC Internet Gateway.
+
+As of this writing, this is actually a required workaround for this template. The gateway must be attached to the VPC before a route can be created to it, but since the gateway attachment isn't actually referenced anywhere in this resource, we need to explicitly declare that dependency.
+
+```ruby
+resource :defaultroute, 'AWS::EC2::Route', DependsOn: [:vpcigw] do
+  route_table_id Fn::ref(:routetable)
+  gateway_id Fn::ref(:defaultigw)
+  destination_cidr_block '0.0.0.0/0'
+end
+```
+
+## The Subnets
+
+Naturally, you'll also need networks. Like the route table, I like to create my own so that I have control of their configuration inside the template.
+
+Notice `Fn::select`, `Fn::get_azs` and `AWS::region` in this snippet. These all map to the CloudFormation functions and variables of the same name.
+
+We'll use Ruby to create three identical subnets:
+
+```ruby
+(1..3).each do |i|
+```
+
+The subnets themselves will be in the first three availability zones of the account. A more sophisticated template might want to handle this differently.
+
+```ruby
+resource "subnet#{i}", 'AWS::EC2::Subnet' do
+  availability_zone Fn::select(i, Fn::get_azs(AWS::region))
+  cidr_block "172.42.#{i}.0/24"
+  vpc_id Fn::ref(:vpc)
+end
+```
+
+Now the subnet needs to be associated with the route table, so that hosts in the subnet are able to access the rest of the network and the internet.
+
+```ruby
+resource "srta#{i}".to_sym, 'AWS::EC2::SubnetRouteTableAssociation' do
+  subnet_id Fn::ref("subnet#{i}")
+  route_table_id Fn::ref(:routetable)
+end
+```
+
+We can use the `output` function to output the subnet IDs we've just created. We'll go over how Cfer makes this useful in part 2 of this post.
+
+```ruby
+output "subnetid#{i}", Fn::ref("subnet#{i}")
+```
+
+And of course, end the iteration block.
+
+```ruby
+end
+```
+
+
+Finally, let's output the VPC ID too, since we'll probably need that in other templates.
+
+```ruby
+output :vpcid, Fn::ref(:vpc)
+```
+
+## Converging the Stack
+
+Now that you have your template ready, you'll be able to use Cfer to create or update a CloudFormation stack:
+
+{% highlight bash %}
+cfer converge vpc -t examples/vpc.rb --profile ${AWS_PROFILE} --region ${AWS_REGION}
+```
+
+Which should produce something like this.
+
+![Cfer Demo]({{ site.url }}/images/cfer/cfer-demo.gif)
+
+Use `cfer help` to get more usage information, or check `README.md` and `Rakefile` in the source repository to see how to embed Cfer into your own projects.
+
+## In Part 2...
+
+In part 2, we'll go over some additional features of Cfer. If you want a preview, you can check out the [instance.rb](https://github.com/seanedwards/cfer/blob/develop/examples/instance.rb) example, which covers how you can use Cfer to create security groups, instances with automated provisioning, and how to automatically look up outputs from other stacks.
+
+Cfer can be found on [GitHub](https://github.com/seanedwards/cfer) and [RubyGems](https://rubygems.org/gems/cfer) and is MIT licensed. Pull requests are welcome.
+

data/lib/cfer.rb

@@ -64,7 +64,7 @@ module Cfer
       cfn = options[:aws_options] || {}
 
       cfn_stack = options[:cfer_client] || Cfer::Cfn::Client.new(cfn.merge(stack_name: stack_name))
-      raise Cfer::Util::CferError, "No such template file: #{tmpl}" unless File.exists?(tmpl) || options[:cfer_stack]
+      raise Cfer::Util::CferError, "No such template file: #{tmpl}" unless File.exist?(tmpl) || options[:cfer_stack]
       stack =
         options[:cfer_stack] ||
           Cfer::stack_from_file(tmpl,
@@ -126,7 +126,7 @@ module Cfer
       when 'table', nil
         puts "Status: #{cfn_stack[:stack_status]}"
         puts "Description: #{cfn_stack[:description]}" if cfn_stack[:description]
-        puts "Created with Cfer version: #{Semantic::Version.new(cfer_version_str).to_s} (current: #{Cfer::SEMANTIC_VERSION.to_s})" if cfer_version
+        puts "Created with Cfer version: #{Semantic::Version.new(cfer_version_str)} (current: #{Cfer::SEMANTIC_VERSION.to_s})" if cfer_version
         puts ""
         def tablify(list, type)
           list ||= []
@@ -165,7 +165,7 @@ module Cfer
       cfn = options[:aws_options] || {}
 
       cfn_stack = options[:cfer_client] || Cfer::Cfn::Client.new(cfn)
-      raise Cfer::Util::CferError, "No such template file: #{tmpl}" unless File.exists?(tmpl) || options[:cfer_stack]
+      raise Cfer::Util::CferError, "No such template file: #{tmpl}" unless File.exist?(tmpl) || options[:cfer_stack]
       stack = options[:cfer_stack] || Cfer::stack_from_file(tmpl,
         options.merge(client: cfn_stack, parameters: generate_final_parameters(options))).to_h
       puts render_json(stack, options)
@@ -333,7 +333,6 @@ end
 %w{
 version.rb
 block.rb
-cli.rb
 config.rb
 
 util/error.rb

data/lib/cfer/block.rb

@@ -36,7 +36,7 @@ module Cfer
 
     def include_file(file)
       Preconditions.check(file).is_not_nil
-      raise Cfer::Util::FileDoesNotExistError, "#{file} does not exist." unless File.exists?(file)
+      raise Cfer::Util::FileDoesNotExistError, "#{file} does not exist." unless File.exist?(file)
 
       case File.extname(file)
       when '.json'

data/lib/cfer/cfn/client.rb

@@ -121,7 +121,6 @@ module Cfer::Cfn
       stack_options[:timeout_in_minutes] = options[:timeout] if options[:timeout]
 
       stack_options.merge! parse_stack_policy(:stack_policy, options[:stack_policy])
-      stack_options.merge! parse_stack_policy(:stack_policy_during_update, options[:stack_policy_during_update])
 
       stack_options.merge! template_options
 
@@ -133,6 +132,7 @@ module Cfer::Cfn
           if options[:change]
             create_change_set stack_options.merge change_set_name: options[:change], description: options[:change_description], parameters: update_params
           else
+            stack_options.merge! parse_stack_policy(:stack_policy_during_update, options[:stack_policy_during_update])
             update_stack stack_options.merge parameters: update_params
           end
           :updated

data/lib/cfer/cli.rb

@@ -1,3 +1,4 @@
+require 'cfer'
 require 'cri'
 require 'rainbow'
 require 'table_print'

data/lib/cfer/console.rb

@@ -5,7 +5,7 @@ module Cfer
   DEBUG = true
 end
 
-require "cfer"
+require "cfer/cli"
 
 Cfer::LOGGER.level = Logger::DEBUG
 

data/lib/cfer/core/functions.rb

@@ -20,14 +20,6 @@ module Cfer::Core::Functions
     {"Fn::Select" => [i, o]}
   end
 
-  def base64(v)
-    {"Fn::Base64" => v}
-  end
-
-  def condition(cond)
-    {"Condition" => cond}
-  end
-
   def and(*conds)
     {"Fn::And" => conds}
   end
@@ -52,35 +44,31 @@ module Cfer::Core::Functions
     {"Fn::GetAZs" => region}
   end
 
-  def account_id
-    Fn::ref 'AWS::AccountId'
+  def sub(str, vals = {})
+    {"Fn::Sub" => [str, vals]}
   end
 
   def notification_arns
-    Fn::ref 'AWS::NotificationARNs'
-  end
-
-  def no_value
-    Fn::ref 'AWS::NoValue'
-  end
-
-  def region
-    Fn::ref 'AWS::Region'
-  end
-
-  def stack_id
-    Fn::ref 'AWS::StackId'
-  end
-
-  def stack_name
-    Fn::ref 'AWS::StackName'
+    ref 'AWS::NotificationARNs'
   end
 end
 
 module Cfer::Core::Functions::AWS
   extend Cfer::Core::Functions
+
+  def self.method_missing(sym, *args)
+    method = sym.to_s.camelize
+    raise "AWS::#{method} does not accept arguments" unless args.empty?
+    ref "AWS::#{method}"
+  end
 end
 
 module Cfer::Core::Functions::Fn
   extend Cfer::Core::Functions
+
+  def self.method_missing(sym, *args)
+    method = sym.to_s.camelize
+    raise "Fn::#{method} requires one argument" unless args.size == 1
+    { "Fn::#{method}" => args.first }
+  end
 end

data/lib/cfer/core/hooks.rb

@@ -2,14 +2,14 @@ module Cfer::Core
   # Provides support for hooking into resource types, and evaluating code before or after properties are set
   module Hooks
     def pre_block
-      self.class.pre_hooks.each do |hook|
-        instance_eval &hook
+      self.class.pre_hooks.sort { |a, b| (a[:nice] || 0) <=> (b[:nice] || 0) }.each do |hook|
+        Docile.dsl_eval(self, &hook[:block])
       end
     end
 
     def post_block
-      self.class.post_hooks.each do |hook|
-        instance_eval &hook
+      self.class.post_hooks.sort { |a, b| (a[:nice] || 0) <=> (b[:nice] || 0) }.each do |hook|
+        Docile.dsl_eval(self, &hook[:block])
       end
     end
 
@@ -18,12 +18,12 @@ module Cfer::Core
     end
 
     module ClassMethods
-      def before(&block)
-        self.pre_hooks << block
+      def before(options = {}, &block)
+        self.pre_hooks << options.merge(block: block)
       end
 
-      def after(&block)
-        self.post_hooks << block
+      def after(options = {}, &block)
+        self.post_hooks << options.merge(block: block)
       end
 
       def pre_hooks

data/lib/cfer/core/resource.rb

@@ -22,6 +22,7 @@ module Cfer::Core
     # @param options [Hash] An arbitrary set of additional properties to be added to this tag, for example `PropagateOnLaunch` on `AWS::AutoScaling::AutoScalingGroup`
     def tag(k, v, **options)
       self[:Properties][:Tags] ||= []
+      self[:Properties][:Tags].delete_if { |kv| kv["Key"] == k }
       self[:Properties][:Tags].unshift({"Key" => k, "Value" => v}.merge(options))
     end
 
@@ -53,14 +54,14 @@ module Cfer::Core
 
       # Registers a hook that will be run before properties are set on a resource
       # @param type [String] The type of resource, for example `AWS::EC2::Instance`
-      def before(type, &block)
-        resource_class(type).pre_hooks << block
+      def before(type, options = {}, &block)
+        resource_class(type).pre_hooks << options.merge(block: block)
       end
 
       # Registers a hook that will be run after properties have been set on a resource
       # @param type [String] The type of resource, for example `AWS::EC2::Instance`
-      def after(type, &block)
-        resource_class(type).post_hooks << block
+      def after(type, options = {}, &block)
+        resource_class(type).post_hooks << options.merge(block: block)
       end
     end
   end

data/lib/cfer/version.rb

@@ -1,5 +1,5 @@
 module Cfer
-  VERSION = "0.5.0-rc4"
+  VERSION = "0.5.0"
 
   begin
     require 'semantic'

data/lib/cferext/aws/iam/policy_generator.rb

@@ -26,6 +26,10 @@ module CferExt
       end
 
       module WithPolicyDocument
+        def policy_document(doc = nil, &block)
+          doc = CferExt::AWS::IAM.generate_policy(&block) if doc == nil
+          self[:Properties][:PolicyDocument] = doc
+        end
       end
 
       module WithPolicies

data/lib/cferext/aws/route53/record_dsl.rb

@@ -0,0 +1,11 @@
+require 'docile'
+
+Cfer::Core::Resource.extend_resource "AWS::Route53::RecordSetGroup" do
+  %w{a aaaa cname mx ns ptr soa spf srv txt}.each do |type|
+    define_method type.to_sym do |name, records, options = {}|
+      self[:Properties][:RecordSets] ||= []
+      self[:Properties][:RecordSets] << options.merge(Type: type.upcase, Name: name, ResourceRecords: [ records ].flatten)
+    end
+  end
+end
+

data/lib/cferext/cfer/stack_validation.rb

@@ -38,7 +38,7 @@ Cfer::Core::Stack.extend_stack do
   end
 end
 
-Cfer::Core::Stack.after do
+Cfer::Core::Stack.after(nice: 100) do
   begin
     validate_stack!(self)
   rescue Cfer::Util::CferValidationError => e

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cfer
 version: !ruby/object:Gem::Version
-  version: 0.5.0.pre.rc4
+  version: 0.5.0
 platform: ruby
 authors:
 - Sean Edwards
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-10-05 00:00:00.000000000 Z
+date: 2017-03-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: docile
@@ -223,6 +223,7 @@ files:
 - doc/cfer-demo.gif
 - examples/common/instance_deps.rb
 - examples/instance.rb
+- examples/vpc.md
 - examples/vpc.rb
 - lib/cfer.rb
 - lib/cfer/block.rb
@@ -244,6 +245,7 @@ files:
 - lib/cferext/aws/iam/policy_generator.rb
 - lib/cferext/aws/kms/key.rb
 - lib/cferext/aws/rds/db_instance.rb
+- lib/cferext/aws/route53/record_dsl.rb
 - lib/cferext/cfer/stack_validation.rb
 homepage: https://github.com/seanedwards/cfer
 licenses:
@@ -263,9 +265,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.2.5
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.5.1