stackit 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2aff5ca524ea49528392a501576e27e9aa944e6c
-  data.tar.gz: c21c2bd9ea0fa51735eb6fc4fe0ef537aed4e6e7
+  metadata.gz: 56031c1ebaca58621ce162ca4fb35b7a0bc29b10
+  data.tar.gz: 323a83ffc79f320216b599be24f81f541fe57c32
 SHA512:
-  metadata.gz: 7a01703e3394799d829b01e4a9b783169df5e6b705d7141e5d78488e147d76061fbc6d5593c390041d129be0237b25fc7f555a7b0e7fb0f2f20cc50b6091b6b8
-  data.tar.gz: 9ea4daf3f9fb5775886d72afd792fdd7e634c32011dcc71d65fef8f26cb637d7496fb230933bbc54b436bdbfec1d190c09043f8ee19808b34f5e2cc3419c7048
+  metadata.gz: b57f90da98d269b8055d399beb6a74620bd3ab57dcdedee83e790972435f872434035fcd36302067a2cc802256d5547588e39d9adebbd1e252097f5721287c05
+  data.tar.gz: 07a4248f7239c20a68637b38ae0a892cca8b95d8229ab87ea5dd52c3e8fafbe36969b75fb4578f7a96e8d479ec29b52f69b13c2b8ebc4974d3595f87786f3c21

data/README.md

@@ -2,6 +2,12 @@
 
 Simple, elegant CloudFormation dependency management.
 
+[CloudFormation parameters](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html) can become cumbersome to manage as your infrastructure scales. At some point, you realize there has to be a better way than specifying parameters on the command line or putting them into files and shell scripts.
+
+StackIT makes it easier to manage the lifecycle of your stacks by allowing you to map values from existing stacks. For example, we can have a VPC stack that defines networking resources that a separate remote access VPN stack references when launched. StackIT will automatically map VPC resource, output and/or parameter values to parameters defined in the VPN template. 
+
+StackIT can also work with parameter files and user defined parameters in conjunction with CloudFormation stacks. This is quite useful if you want to override parameters.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -18,9 +24,90 @@ Or install it yourself as:
 
     $ gem install stackit
 
+## Parameters
+
+Let's take a look at each of the ways to get parameter values into your template.
+
+StackIT uses the following order of precedence when determining which parameter value to pass into your template.
+
+1. File Parameters
+2. Existing CloudFormation Stacks
+3. User Defined Parameters
+
+##### File Parameters
+
+File parameters work just like the default AWS CLI parameters file. Simply specify the path to your JSON parameter file using the `--parameter-file` option.
+
+    stackit create-stack --stack-name mystack --template mytemplate.json --parameter-file mytemplate.parameters
+
+##### Existing CloudFormation Stacks
+
+Your stack can `--depend` on existing stacks. Any resource, output, or parameter whose ID matches a parameter key in the template will automatically have it's value passed into the stack during management.
+
+> Parameter values mapped using `--depends` override parameters defined in the parameter file.
+
+    stackit create-stack --stack-name mystack --template my-template --parameter-file mytemplate.parameters --depends myvpc
+
+##### User Defined Parameters
+
+User defined parameters allow you to define the parameters yourself using the `--parameters` option. 
+
+> User defined parameters override file parameters.
+
 ## Usage
 
-TODO: Write usage instructions here
+### CLI
+
+StackIT ships with [Thor](http://whatisthor.com/) to provide a command line interface to stack management. Run the `help` command for details.
+
+    # show top level commands
+    stackit help
+
+    # show options for create command
+    stackit help create
+
+##### Create a stack using a parameter file
+
+    stackit create-stack --stack-name mystack --template mytemplate.json --parameter-file mytemplate.parameters
+
+##### Create a stack using `--depends` to reference resource, output and parameter values in the "myvpc" stack
+
+    stackit create-stack --stack-name mystack --template mytemplate.json --depends myvpc
+
+##### Create a stack using user defined parameters
+
+    stackit create-stack --stack-name mystack --template mytemplate.json --parameters param1:value1 param2:value2
+
+##### Create a stack using a parameter file, overriding parameters found in the "myvpc" resource, output or parameters.
+
+    stackit create-stack --stack-name mystack --template mytemplate.json --parameter-file mytemplate.parameters --depends myvpc
+
+##### Create a stack using a parameter file, overriding those parameters with mapped parameters in the "myvpc" stack, and override both of those with user defined parameters.
+
+    stackit create-stack --stack-name mystack --template mytemplate.json --parameter-file mytemplate.parameters --depends myvpc --parameters param1:final_value
+
+##### Mapping Parameters
+
+You may optionally map parameters that don't have matching keys. For example, let's map the value for the "Vpc" resource into the "VpcId" parameter in our VPN stack using the `--parameter-map` option.
+
+    # Maps the "Vpc" resource value in the "myvpc" stack to the "VpcId" parameter in the VPN stack.
+    stackit create-stack --stack-name myvpn --template vpn.json --parameter-file vpn.parameters --depends myvpc --parameter-map VpcId:Vpc
+
+### Library
+
+StackIT can be used as library in your own automation tools.
+
+```ruby
+  ManagedStack.new({
+    template: '/path/to/template.json',
+    stack_name: 'mystack',
+    depends: 'otherstack',
+    user_defined_parameters: {
+      :param1 => 'myvalue',
+      :param2 => 'something else'
+    }
+  }).create!
+```
 
 ## Development
 

data/lib/stackit/cli.rb

@@ -25,7 +25,7 @@ module Stackit
       self.name.gsub(%r{.*::}, '').gsub(%r{^[A-Z]}) { |match| match[0].downcase }.gsub(%r{[A-Z]}) { |match| "-#{match[0].downcase}" }
     end
 
-    desc 'create', 'Creates a new CloudFormation stack'
+    desc 'create-stack', 'Creates a new CloudFormation stack'
     method_option :template, aliases: '-t', desc: 'The cloudformation template', :required => true
     method_option :stack_name, aliases: '-n', desc: 'The stack name. Defaults to the camelized template file name', :required => true
     method_option :stack_policy, :aliases => '-p', :desc => 'A local file system or S3 (HTTPS) path to the stack policy'
@@ -36,7 +36,7 @@ module Stackit
     method_option :wait, :aliases => '-w', type: :boolean, default: false, desc: 'Wait for the stack to enter STATUS_COMPLETE before returning or raise an exception if it times out'
     method_option :force, :desc => 'Force a stack update on unchanged templates'
     method_option :dry_run, :type => :boolean, :default => false, :desc => 'Run all code except AWS API calls'
-    def create
+    def create_stack
       ManagedStack.new({
         template: options[:template],
         stack_name: options[:stack_name],
@@ -52,7 +52,7 @@ module Stackit
       }).create!
     end
 
-    desc 'update', 'Updates an existing CloudFormation stack'
+    desc 'update-stack', 'Updates an existing CloudFormation stack'
     method_option :template, aliases: '-t', desc: 'The cloudformation template', :required => true
     method_option :stack_name, aliases: '-n', desc: 'The stack name. Defaults to the camelized template file name', :required => true
     method_option :stack_policy, :aliases => '-p', :desc => 'A local file system or S3 (HTTPS) path to the stack policy'
@@ -64,7 +64,7 @@ module Stackit
     method_option :wait, :aliases => '-w', type: :boolean, default: false, desc: 'Wait for the stack to enter STATUS_COMPLETE before returning or raise an exception if it times out'
     method_option :force, :desc => 'Force a stack update on unchanged templates'
     method_option :dry_run, :type => :boolean, :default => false, :desc => 'Run all code except AWS API calls'
-    def update
+    def update_stack
       ManagedStack.new({
         template: options[:template],
         stack_name: options[:stack_name],
@@ -81,12 +81,12 @@ module Stackit
       }).update!
     end
 
-    desc 'delete', 'Deletes a CloudFormation stack'
+    desc 'delete-stack', 'Deletes a CloudFormation stack'
     method_option :stack_name, aliases: '-n', desc: 'The stack name. Defaults to the camelized template file name', :required => true
     method_option :retain_resources, :aliases => '-r', :type => :array, :desc => 'Space delimited list of logical resource ids to retain after the stack is deleted'
     method_option :wait, :aliases => '-w', type: :boolean, default: false, desc: 'Wait for the stack to enter STATUS_COMPLETE before returning or raise an exception if it times out'
     method_option :dry_run, :type => :boolean, :default => false, :desc => 'Run all code except AWS API calls'
-    def delete
+    def delete_stack
       ManagedStack.new({
         stack_name: options[:stack_name],
         wait: options[:wait],
@@ -95,7 +95,7 @@ module Stackit
       }).delete!
     end
 
-    desc 'create-keypair', 'Creates a new EC2 keypair'
+    desc 'create-keypair', 'Creates a new EC2 keypair and returns it\'s corresponding private key'
     method_option :name, desc: 'The name of the keypair', :required => true
     def create_keypair
       puts Stackit.aws.ec2.create_key_pair({

data/lib/stackit/stack/managed_stack.rb

@@ -119,7 +119,7 @@ module Stackit
         delete!
         wait_for_stack_to_delete
         notifier.success('Delete successful')
-      elsif exists?
+      elsif exist?
         begin
           update!
           wait_for_stack

data/lib/stackit/version.rb

@@ -1,3 +1,3 @@
 module Stackit
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stackit
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Jeremy Hahn
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-03-31 00:00:00.000000000 Z
+date: 2016-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler