convection 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d7f560ff0230cc8a78bdc3e59c57d2b5befbfe37
-  data.tar.gz: 54969c701ca627f77a22a38a67e70aa43e1c93a8
+  metadata.gz: b3de07eb04f40d2d56959e6df5572e98f8447ce7
+  data.tar.gz: d0925f4ae7e4f4093606a7cf1fb05bb643172bed
 SHA512:
-  metadata.gz: 1db320b7089911c0e28b80709348897131f11f4a15e3529e406c78d09760cb65d0aa8df505e98c1f2d84e707b3383311cc5c044198cc9f5ba25648beb5d3b01d
-  data.tar.gz: 11e1bce3c3781d8899f6ad2c5ac1a0acc6ba1ec3766160c0e1cc0c96f279330831b67121aab7e8173cf5ea55fae9f52ed3d1260be86aa17274a0410be0a9cd95
+  metadata.gz: 69a32d02abbc59d1bdf62703de9cd72ceb8cb8a88c5efc69a4790d2fee51f21c248e976f76eb0ff0db3ea39819136709c807343b04d49a822fa4878798ba4bc2
+  data.tar.gz: dc372422b28b5eab1d908b98cb798cff7b42c54f483b5ce86498d1c408b46f0fa79f703292ee8a7315101d2365897f0438f21c854a3608180b67988416ff5344

data/.ruby-version

@@ -1 +1 @@
-2.2.2
+2.3.0

data/bin/convection

@@ -28,6 +28,34 @@ module Convection
       end
     end
 
+    desc 'delete STACK', 'Delete stack(s) from your cloud'
+    option :stack_group, :type => :string, :desc => 'The name of a stack group defined in your cloudfile to delete'
+    option :stacks, :type => :array, :desc => 'A ordered space separated list of stacks to delete'
+    def delete(stack = nil)
+      @cloud.configure(File.absolute_path(options['cloudfile'], @cwd))
+      print_status = lambda do |event, *errors|
+        say_status(*event.to_thor)
+        errors.flatten.each do |error|
+          say "* #{ error.message }"
+          error.backtrace.each { |b| say "    #{ b }" }
+        end unless errors.nil?
+      end
+
+      stacks = @cloud.stacks_until(stack, options, &print_status)
+      if stacks.empty?
+        say_status(:delete_failed, 'No stacks found matching the provided input (STACK, --stack-group, and/or --stacks).', :red)
+        return
+      end
+      say_status(:delete, "Deleting the following stack(s): #{stacks.map(&:name).join(', ')}", :red)
+
+      confirmation = ask('Are you sure you want to delete the above stack(s)?', limited_to: %w(yes no))
+      if confirmation.eql?('yes')
+        @cloud.delete(stacks, &print_status)
+      else
+        say_status(:delete_aborted, 'Aborted deletion of the above stack(s).', :green)
+      end
+    end
+
     desc 'diff STACK', 'Show changes that will be applied by converge'
     option :verbose, :type => :boolean, :aliases => '--v', :desc => 'Show stack progress'
     option :'very-verbose', :type => :boolean, :aliases => '--vv', :desc => 'Show unchanged stacks'

data/docs/creating-a-custom-resource-collection.md

@@ -0,0 +1,148 @@
+# Creating a custom resource collection
+**NOTE**: Examples in this file can be found in `example/web-service-resource-collection`.
+
+This guide will walk you through creating a custom resource collection.
+
+For the purpose of this guide we'll create a resource collection to provision a web server listening on port 80 with security group ingress rules to only allow specific CIDR ranges.
+
+## Attach your custom resource collection to the Template DSL
+The below code snippet does the following:
+* Defines `WebService` as a subclass of `Convection::Model::Template::ResourceCollection` (this provides a standard initialize function and mixins in convection helper functions).
+* Defines `Template#web_service` which can later be called in the Convection template configuration.
+
+```ruby
+class WebService < Convection::Model::Template::ResourceCollection
+  # Attach this class to the Template DSL with the method name "web_service".
+  attach_to_dsl(:web_service)
+end
+```
+
+## Override `ResourceCollection#execute`
+When rendering resource collections convection internally calls `#run_definition` to resolve the configuration block passed in during template definition. After this call `#execute` is called. This method should be overridden for resource collections to call other [basic] convection resources.
+
+```ruby
+class WebService < Convection::Model::Template::ResourceCollection
+  # ...
+
+  def execute
+    # Preserve scope by exposing a local "web_service" variable.
+    web_service = self
+    generate_security_groups(web_service)
+    generate_ec2_instance(web_service)
+  end
+
+  def generate_ec2_instance(web_service)
+    # TODO: Actually generate the ec2 instance resource!
+  end
+
+  def generate_security_groups(web_service)
+    # TODO: Actually generate the ec2 security group resource!
+  end
+end
+```
+
+### Generating a security group for our web service
+The below code can be used to generate a security group with a few tags and ingress rules defined for TCP over port 80 on any CIDR range in a CSV list from the `ALLOWED_CIDR_RANGES` environment variable.
+
+```ruby
+def cidr_ranges
+  return ENV['ALLOWED_CIDR_RANGES'].split(/[, ]+/) if ENV.key?('ALLOWED_CIDR_RANGES')
+
+  raise ArgumentError, "You must export $ALLOWED_CIDR_RANGES to diff/converge #{stack.cloud_name}."
+end
+
+def generate_security_groups(web_service)
+  ec2_security_group "#{web_service.name}SecurityGroup" do
+    description "EC2 Security Group for the #{web_service.name} web service."
+
+    web_service.cidr_ranges.each do |range|
+      ingress_rule(:tcp, 80, range)
+    end
+
+    tag 'Name', "sg-#{web_service.name}-#{stack.cloud}".downcase
+    tag 'Service', web_service.name
+    tag 'Stack', stack.cloud
+
+    with_output
+  end
+end
+```
+
+### Generating a web server running on port 80
+#### Create an EC2 instance
+##### Support defining the image ID and instance user data via the template DSL
+```ruby
+class WebService < Convection::Model::Template::ResourceCollection
+  # ...
+
+  attribute :ec2_instance_image_id
+  attribute :user_data
+end
+```
+
+##### Generate the EC2 instance resource
+```ruby
+def generate_ec2_instance(web_service)
+  ec2_instance "#{name}Frontend" do
+    image_id web_service.ec2_instance_image_id
+    security_group fn_ref("#{web_service.name}SecurityGroup")
+
+    tag 'Name', "#{web_service.name}Frontend"
+    tag 'Stack', stack.cloud
+
+    user_data base64(web_service.user_data)
+
+    with_output 'Hostname', get_att(name, 'PublicDnsName') do
+      description 'The public hostname of this web service.'
+    end
+
+    with_output 'HttpEndpoint', join('', 'http://', get_att(name, 'PublicDnsName')) do
+      description 'The URL to visit this web service at.'
+    end
+  end
+end
+```
+
+## Define your convection template using your resource collection
+### Call your custom resource like any other resource
+```ruby
+require_relative '../path/to/your/resources/web_service.rb'
+
+EXAMPLE_DOT_ORG = Convection.template do
+  description 'An example website to demonstrate using custom resource collections.'
+
+  web_service 'ExampleDotOrg' do
+    # Set the instance ID attribute so the instance can be converged.
+    ec2_instance_image_id 'ami-45026036' # ubuntu <3!
+
+    user_data <<~USER_DATA
+      #!/bin/bash
+      echo 'Hello World!'
+    USER_DATA
+  end
+end
+```
+
+### Set the user data up as a shell script to install nginx
+A quick and simple way to expose an HTTP server on port 80 is to install nginx.
+
+You can do this with the bash script embedded as user data in your template like so:
+```ruby
+user_data <<~USER_DATA
+  #!/bin/bash
+  apt-get update
+  apt-get install -y unzip curl nginx
+  service nginx start
+  update-rc.d nginx defaults
+USER_DATA
+```
+
+## Converge your template
+1. Export your AWS credentials.
+2. Export the `ALLOWED_CIDR_RANGES` we use for setting our ingress rules.
+  * This should be set to your external IP address so the instance allows connections from your machine.
+3. Run `convection diff` to show what will be converged.
+4. Run `convection converge` to deploy your stack.
+5. Open the stack outputs section CloudFormation for this stack.
+6. Click on the HttpEndpoint value.
+7. Look at the "Welcome to nginx!" page.

data/docs/template.html

@@ -102,6 +102,7 @@
               <li class="list-group-item"><a href="/{{NAME}}/deleting-stacks">Deleting Stacks</a></li>
               <li class="list-group-item"><a href="/{{NAME}}/canceling-stack-updates">Canceling Stack Updates</a></li>
               <li class="list-group-item"><a href="/{{NAME}}/adding-new-resource-coverage">Adding New Resource Coverage</a></li>
+              <li class="list-group-item"><a href="/{{NAME}}/creating-a-custom-resource-collection">Creating a custom resource collection</a></li>
               <li class="list-group-item"><a href="/{{NAME}}/stackgroups">Stackgroups</a></li>
 
             </ul>

data/example/web-service-resource-collection/Cloudfile

@@ -0,0 +1,10 @@
+# Cloudfile
+require_relative './templates/example_dot_org.rb'
+
+user = ENV['USER'] || 'anon'
+aws_region = ENV['AWS_REGION'] || 'us-east-1'
+
+name "#{user}-web-service-example"
+region aws_region
+
+stack 'example-org', Templates::EXAMPLE_DOT_ORG

data/example/web-service-resource-collection/resources/web_service.rb

@@ -0,0 +1,63 @@
+require 'convection'
+
+class WebService < Convection::Model::Template::ResourceCollection
+  attach_to_dsl(:web_service)
+
+  attribute :ec2_instance_image_id
+  attribute :user_data
+
+  def execute
+    web_service = self
+
+    generate_security_groups(web_service)
+    generate_ec2_instance(web_service)
+  end
+
+  def cidr_ranges
+    @cidr_ranges ||= allowed_csv_ranges.split(/[, ]+/)
+  end
+
+  # Resource generator methods
+
+  def generate_ec2_instance(web_service)
+    ec2_instance "#{name}Frontend" do
+      image_id web_service.ec2_instance_image_id
+      security_group fn_ref("#{web_service.name}SecurityGroup")
+
+      tag 'Name', "#{web_service.name}Frontend"
+      tag 'Stack', stack.cloud
+
+      user_data base64(web_service.user_data)
+
+      with_output 'Hostname', get_att(name, 'PublicDnsName') do
+        description 'The public hostname of this web service.'
+      end
+
+      with_output 'HttpEndpoint', join('', 'http://', get_att(name, 'PublicDnsName')) do
+        description 'The URL to visit this web service at.'
+      end
+    end
+  end
+
+  def generate_security_groups(web_service)
+    ec2_security_group "#{web_service.name}SecurityGroup" do
+      description "EC2 Security Group for the #{web_service.name} web service."
+
+      web_service.cidr_ranges.each do |range|
+        ingress_rule(:tcp, 80, range)
+      end
+
+      tag 'Name', "sg-#{web_service.name}-#{stack.cloud}".downcase
+      tag 'Service', web_service.name
+      tag 'Stack', stack.cloud
+
+      with_output
+    end
+  end
+
+  def allowed_csv_ranges
+    return ENV['ALLOWED_CIDR_RANGES'] if ENV.key?('ALLOWED_CIDR_RANGES')
+
+    raise ArgumentError, "You must export $ALLOWED_CIDR_RANGES to diff/converge #{stack.cloud_name}."
+  end
+end

data/example/web-service-resource-collection/templates/example_dot_org.rb

@@ -0,0 +1,20 @@
+require 'convection'
+require_relative '../resources/web_service.rb'
+
+module Templates
+  EXAMPLE_DOT_ORG = Convection.template do
+    description 'An example website to demonstrate using custom resource collections.'
+
+    web_service 'ExampleDotOrg' do
+      ec2_instance_image_id 'ami-45026036'
+
+      user_data <<~USER_DATA
+        #!/bin/bash
+        apt-get update
+        apt-get install -y unzip curl nginx
+        service nginx start
+        update-rc.d nginx defaults
+      USER_DATA
+    end
+  end
+end

data/lib/convection/control/cloud.rb

@@ -49,6 +49,20 @@ module Convection
         end
       end
 
+      def stacks_until(last_stack_name, options = {}, &block)
+        stacks = filter_deck(options, &block).values
+        return stacks if last_stack_name.nil?
+
+        last_stack = stacks.find { |stack| stack.name == last_stack_name }
+        unless last_stack
+          block.call(Model::Event.new(:error, "Stacks filter did not include last stack #{ last_stack }", :error)) if block
+          return []
+        end
+
+        last_stack_index = stacks.index(last_stack)
+        stacks[0..last_stack_index]
+      end
+
       def converge(to_stack, options = {}, &block)
         if to_stack && !stacks.include?(to_stack)
           block.call(Model::Event.new(:error, "Undefined Stack #{ to_stack }", :error)) if block
@@ -73,6 +87,27 @@ module Convection
         end
       end
 
+      def delete(stacks, &block)
+        stacks.each do |stack|
+          unless stack.exist?
+            block.call(Model::Event.new(:delete_skipped, "Stack #{ stack.cloud_name } does not exist remotely", :warn))
+            next
+          end
+
+          block.call(Model::Event.new(:deleted, "Delete remote stack #{ stack.cloud_name }", :info)) if block
+          stack.delete(&block)
+
+          if stack.error?
+            block.call(Model::Event.new(:error, "Error deleting stack #{ stack.name }", :error), stack.errors) if block
+            break
+          end
+
+          break unless stack.delete_success?
+
+          sleep rand @cloudfile.splay || 2
+        end
+      end
+
       def diff(to_stack, options = {}, &block)
         if to_stack && !stacks.include?(to_stack)
           block.call(Model::Event.new(:error, "Undefined Stack #{ to_stack }", :error)) if block

data/lib/convection/control/stack.rb

@@ -209,6 +209,17 @@ module Convection
         [CREATE_COMPLETE, ROLLBACK_COMPLETE, UPDATE_COMPLETE, UPDATE_ROLLBACK_COMPLETE].include?(status)
       end
 
+      # @return [Boolean] whether the CloudFormation Stack is in one of
+      #   the several *_COMPLETE states.
+      def delete_complete?
+        DELETE_COMPLETE == status
+      end
+
+      # @return [Boolean] whether the Stack state is now {#delete_complete?} (with no errors present).
+      def delete_success?
+        !error? && delete_complete?
+      end
+
       # @return [Boolean] whether the CloudFormation Stack is in one of
       #   the several *_FAILED states.
       def fail?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: convection
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - John Manero
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-08-08 00:00:00.000000000 Z
+date: 2016-08-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk
@@ -92,6 +92,7 @@ files:
 - convection.gemspec
 - docs/adding-new-resource-coverage.md
 - docs/canceling-stack-updates.md
+- docs/creating-a-custom-resource-collection.md
 - docs/deleting-stacks.md
 - docs/getting-started.md
 - docs/index.md
@@ -100,13 +101,15 @@ files:
 - docs/stackgroups.md
 - docs/stacks.md
 - docs/template.html
-- example/.ruby-version
 - example/demo-cloud/Cloudfile
 - example/getting-started-guide/Cloudfile
 - example/getting-started-guide/vpc.rb
 - example/stacks/Cloudfile
 - example/stacks/tasks/lookup_vpc_task.rb
 - example/stacks/templates/vpc.rb
+- example/web-service-resource-collection/Cloudfile
+- example/web-service-resource-collection/resources/web_service.rb
+- example/web-service-resource-collection/templates/example_dot_org.rb
 - ext/resource_generator.sh
 - lib/convection.rb
 - lib/convection/control/cloud.rb

data/example/.ruby-version

@@ -1 +0,0 @@
-2.2.2