cloudformer 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e5374d2370b4cf58c263fd9f0f606149df56e459
-  data.tar.gz: 40347686eeb0ea31fd459c7d546886565a1d6da2
+  metadata.gz: 94350b9dae02e195dd7365c19ea0a56dd9d155bb
+  data.tar.gz: a08fcc2c9193334db2a83070d9229bfff28abf03
 SHA512:
-  metadata.gz: 4dd4e03d047542cb52fb34d23e01969509760a1817af1a37d4d6ca9e615cb2b83fd8beee301f2af8d1831917d11b3c45b170631176d27851cbd369c6526d5b39
-  data.tar.gz: b9a97ad1c8187425509894f1f1caeece090e0b6069c4cf93c18edfe247ec488e845cffaf41640cf4b745c655ccb2107f5086386e5763cb737e1015ade15a9cc1
+  metadata.gz: 12bdb0def1957cc75ee4161ebd2ecd4b294d38f3096d62b42f2a6ef2a7a48bb1598231ef86dac8342c36a4b746dd354bf461c4a070e913c32a2529f4f09b5f5c
+  data.tar.gz: 5fea38a3eb4390137f2a0cb3214b03fe9c58e9f1d4668bdeea32db7959def4b3f915f41c95c670cddb4e85a6b9d4af4aeecba54941aa108f088976f5a96c454b

data/README.md

@@ -1,6 +1,20 @@
-# Cloudformer
+# CloudFormer
+
+Cloudformer attempts to simplify AWS Cloudformation stack creation process in ruby projects by providing reusable rake tasks to perform common operations such as apply(create/update), delete, recreate on stack along with validations on templates. Task executions which enforce a stack change will wait until ROLLBACK/COMPLETE or DELETE is signalled on the stack (useful in continuous deployment environments to wait until deployment is successful). Refer [examples section](#example) for more information.
+
+The list of rake tasks provided are:
+
+```
+
+rake apply           # Apply Stack with Cloudformation script and parameters(And wait till complete - supports updates)
+rake delete          # Delete stack from CloudFormation(And wait till stack is complete)
+rake events          # Get the recent events from the stack
+rake outputs         # Get the outputs of stack
+rake recreate        # Recreate stack(runs delete & apply)
+rake status          # Get the deployed app status
+
+```
 
-TODO: Write a gem description
 
 ## Installation
 
@@ -16,9 +30,182 @@ Or install it yourself as:
 
     $ gem install cloudformer
 
-## Usage
+## AWS Environment configuration
+
+Cloudformer depends on the aws-sdk gem to query AWS API. You will need to export AWS configuration to environment variables to your .bashrc/.bash_profile or your build server:
+
+    export AWS_ACCESS_KEY=your access key
+    export AWS_REGION=ap-southeast-2
+    export AWS_SECRET_ACCESS_KEY=your secret access key
+
+
+## Configuration
+
+You can add cloudformer tasks to your project by adding the following to your rake file:
+
+	require 'cloudformer'
+    Cloudformer::Tasks.new("earmark") do |t|
+      t.template = "cloudformation/cloudformation.json"
+      t.parameters = parameters
+    end
+
+where `cloudformation/cloudformation.json` is the stack json file and parameters is a hash of parameters used in the template.
+For a template which takes the following parameters: 
+  
+    "Parameters": {
+      "PackageUrl": {
+        "Type": "String"
+      },
+      "PackageVersion": {
+        "Type": "String"
+      }
+    }
+  
+the parameter hash(Ruby Object) would look like:
+
+    {
+      "PackageUrl" => "http://localhost/app.rpm",
+      "PackageVersion" => "123"  
+    }  
+
+If you have a template with no parameters, pass an empty hash `{}` instead.
+
+## Example
+
+Here is a simple Cloudformation Stack(Code available in the samples directory) with a Single EC2 Server:
+
+    {
+      "AWSTemplateFormatVersion": "2010-09-09",
+      "Description": "Cloudformer - Demo App",
+      "Parameters": {
+        "AmiId": {
+          "Type": "String"
+        }
+        },
+        "Resources": {
+          "ApplicationServer": {
+            "Type": "AWS::EC2::Instance",
+            "Properties": {
+              "ImageId": {
+                "Ref": "AmiId"
+                },
+                "InstanceType": "t1.micro",
+                "Monitoring": "false"
+            }
+          }
+        },
+        "Outputs": {
+          "Server": {
+            "Value": {
+              "Fn::GetAtt": [
+                "ApplicationServer",
+                "PrivateIp"
+              ]
+            }
+          }
+        }
+    }
+    
+Then, in your Rakefile add, 
+
+    require 'cloudformer/tasks'
+
+    Cloudformer::Tasks.new("app") do |t|
+      t.template = "basic_template.json"
+      #AMI Works in Sydney region only, ensure you supply the right AMI.
+      t.parameters = {"AmiId" => "ami-8da439b7"}
+    end
+
+You should then see following commands:
+
+    rake apply     # Apply Stack with Cloudformation script and parameters
+    rake delete    # Delete stack from CloudFormation
+    rake events    # Get the recent events from the stack
+    rake outputs   # Get the outputs of stack
+    rake recreate  # Recreate stack
+    rake status    # Get the deployed app status
+
+Running `rake status` gives us:
+
+    ===============================================
+      app - Not Deployed
+    ================================================
+
+Running `rake apply` will create an environment or update existing depending on the nature of action requested in parameters:
+
+    Initializing stack creation...
+    ==================================================================================================
+    2013-10-24 07:55:24 UTC - AWS::CloudFormation::Stack - CREATE_IN_PROGRESS - User Initiated
+    2013-10-24 07:55:36 UTC - AWS::EC2::Instance - CREATE_IN_PROGRESS -
+    2013-10-24 07:55:37 UTC - AWS::EC2::Instance - CREATE_IN_PROGRESS - Resource creation Initiated
+    2013-10-24 07:56:25 UTC - AWS::EC2::Instance - CREATE_COMPLETE -
+    2013-10-24 07:56:26 UTC - AWS::CloudFormation::Stack - CREATE_COMPLETE -
+    ==================================================================================================
+
+Running `rake apply` again gives us:
+    
+    No updates are to be performed.
+
+To remove the stack `rake delete` gives us:
+
+    ==============================================================================================
+    Attempting to delete stack - app
+    ==============================================================================================
+    2013-10-24 07:55:24 UTC - AWS::CloudFormation::Stack - CREATE_IN_PROGRESS - User Initiated
+    2013-10-24 07:55:36 UTC - AWS::EC2::Instance - CREATE_IN_PROGRESS -
+    2013-10-24 07:55:37 UTC - AWS::EC2::Instance - CREATE_IN_PROGRESS - Resource creation Initiated
+    2013-10-24 07:56:25 UTC - AWS::EC2::Instance - CREATE_COMPLETE -
+    2013-10-24 07:56:26 UTC - AWS::CloudFormation::Stack - CREATE_COMPLETE -
+    2013-10-24 07:58:54 UTC - AWS::CloudFormation::Stack - DELETE_IN_PROGRESS - User Initiated
+    2013-10-24 07:58:56 UTC - AWS::EC2::Instance - DELETE_IN_PROGRESS -
+
+Attempts to delete a non-existing stack will result in:
+
+    ==============================================
+    Attempting to delete stack - app
+    ==============================================
+    Stack not up.
+    ==============================================
+
+To recreate the stack use `rake recreate`:
+  
+    =================================================================================================
+    Attempting to delete stack - app
+    =================================================================================================
+    2013-10-24 08:04:11 UTC - AWS::CloudFormation::Stack - CREATE_IN_PROGRESS - User Initiated
+    2013-10-24 08:04:22 UTC - AWS::EC2::Instance - CREATE_IN_PROGRESS -
+    2013-10-24 08:04:23 UTC - AWS::EC2::Instance - CREATE_IN_PROGRESS - Resource creation Initiated
+    2013-10-24 08:05:12 UTC - AWS::EC2::Instance - CREATE_COMPLETE -
+    2013-10-24 08:05:13 UTC - AWS::CloudFormation::Stack - CREATE_COMPLETE -
+    2013-10-24 08:05:52 UTC - AWS::CloudFormation::Stack - DELETE_IN_PROGRESS - User Initiated
+    2013-10-24 08:06:02 UTC - AWS::EC2::Instance - DELETE_IN_PROGRESS -
+    Stack deleted successfully.
+    Initializing stack creation...
+    =================================================================================================
+    2013-10-24 08:06:31 UTC - AWS::CloudFormation::Stack - CREATE_IN_PROGRESS - User Initiated
+    2013-10-24 08:06:52 UTC - AWS::EC2::Instance - CREATE_IN_PROGRESS -
+    2013-10-24 08:06:54 UTC - AWS::EC2::Instance - CREATE_IN_PROGRESS - Resource creation Initiated
+    2013-10-24 08:07:41 UTC - AWS::EC2::Instance - CREATE_COMPLETE -
+    =================================================================================================
+    =================================================================================================
+    Server -  - 172.31.3.52
+    =================================================================================================
+
+To see the stack outputs `rake outputs`:
+    
+    ==============================
+    Server -  - 172.31.3.52
+    ============================== 
 
-TODO: Write usage instructions here
+To see recent events on the stack `rake events`:
+    
+    ==================================================================================================
+    2013-10-24 08:06:31 UTC - AWS::CloudFormation::Stack - CREATE_IN_PROGRESS - User Initiated
+    2013-10-24 08:06:52 UTC - AWS::EC2::Instance - CREATE_IN_PROGRESS -
+    2013-10-24 08:06:54 UTC - AWS::EC2::Instance - CREATE_IN_PROGRESS - Resource creation Initiated
+    2013-10-24 08:07:41 UTC - AWS::EC2::Instance - CREATE_COMPLETE -
+    2013-10-24 08:07:43 UTC - AWS::CloudFormation::Stack - CREATE_COMPLETE -
+    ==================================================================================================
 
 ## Contributing
 

data/cloudformer.gemspec

@@ -8,9 +8,9 @@ Gem::Specification.new do |spec|
   spec.version       = Cloudformer::VERSION
   spec.authors       = ["Arvind Kunday"]
   spec.email         = ["hi@kunday.com"]
-  spec.description   = %q{Rake helper tasks for Cloudformation}
-  spec.summary       = %q{Helper tools for aws cloudformation}
-  spec.homepage      = ""
+  spec.description   = %q{Cloudformation tasks for apply(create/update), delete, recreate on stack along with validations on templates}
+  spec.summary       = %q{Cloudformer attempts to simplify AWS Cloudformation stack creation process in ruby projects by providing reusable rake tasks to perform common operations such as apply(create/update), delete, recreate on stack along with validations on templates.}
+  spec.homepage      = "https://github.com/kunday/cloudformer"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files`.split($/)

data/lib/cloudformer.rb

@@ -1,4 +1,6 @@
 require "cloudformer/version"
+require "cloudformer/stack"
+require "cloudformer/tasks"
 
 module Cloudformer
   # Your code goes here...

data/lib/cloudformer/stack.rb

@@ -1,3 +1,5 @@
+require 'aws-sdk'
+
 class Stack
   attr_accessor :stack, :name, :deployed
   def initialize(stack_name)

data/lib/cloudformer/tasks.rb

@@ -28,14 +28,17 @@ module Cloudformer
    def define_create_task
      desc "Apply Stack with Cloudformation script and parameters."
      task :apply do
-       p template
        @stack.apply(template, parameters)
      end
    end
    def define_delete_task
      desc "Delete stack from CloudFormation"
      task :delete do
-       @stack.delete
+      begin
+        @stack.delete
+      rescue
+        puts "Stack deleted successfully."
+      end
      end
    end
    def define_status_task

data/lib/cloudformer/version.rb

@@ -1,3 +1,3 @@
 module Cloudformer
-  VERSION = "0.0.2"
+  VERSION = "0.0.4"
 end

data/samples/Rakefile

@@ -0,0 +1,7 @@
+require 'cloudformer'
+
+Cloudformer::Tasks.new("app") do |t|
+  t.template = "basic_template.json"
+  #AMI Works in Sydney region only, ensure you supply the right AMI.
+  t.parameters = {"AmiId" => "ami-8da439b7"}
+end

data/samples/basic_template.json

@@ -0,0 +1,31 @@
+{
+  "AWSTemplateFormatVersion": "2010-09-09",
+  "Description": "Cloudformer - Demo App",
+  "Parameters": {
+    "AmiId": {
+      "Type": "String"
+    }
+    },
+    "Resources": {
+      "ApplicationServer": {
+        "Type": "AWS::EC2::Instance",
+        "Properties": {
+          "ImageId": {
+            "Ref": "AmiId"
+            },
+            "InstanceType": "t1.micro",
+            "Monitoring": "false"
+        }
+      }
+    },
+    "Outputs": {
+      "Server": {
+        "Value": {
+          "Fn::GetAtt": [
+            "ApplicationServer",
+            "PrivateIp"
+          ]
+        }
+      }
+    }
+}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cloudformer
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors:
 - Arvind Kunday
@@ -52,7 +52,8 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: Rake helper tasks for Cloudformation
+description: Cloudformation tasks for apply(create/update), delete, recreate on stack
+  along with validations on templates
 email:
 - hi@kunday.com
 executables: []
@@ -69,7 +70,9 @@ files:
 - lib/cloudformer/stack.rb
 - lib/cloudformer/tasks.rb
 - lib/cloudformer/version.rb
-homepage: ''
+- samples/Rakefile
+- samples/basic_template.json
+homepage: https://github.com/kunday/cloudformer
 licenses:
 - MIT
 metadata: {}
@@ -92,5 +95,7 @@ rubyforge_project:
 rubygems_version: 2.0.6
 signing_key: 
 specification_version: 4
-summary: Helper tools for aws cloudformation
+summary: Cloudformer attempts to simplify AWS Cloudformation stack creation process
+  in ruby projects by providing reusable rake tasks to perform common operations such
+  as apply(create/update), delete, recreate on stack along with validations on templates.
 test_files: []