kumo_keisei 3.0.4 → 3.0.5.pre.alpha1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: faa37c9fa0f21e7428850a43e4deb25dd50e581d
-  data.tar.gz: d4d3a9d281e1d408f31856eb81501f3d189325c4
+  metadata.gz: 3d3c673fda643f764f36cdf9e17d130deb9004ae
+  data.tar.gz: b861c435acc83e7eb5e875f262d003dce20cc5fc
 SHA512:
-  metadata.gz: a6f893e0c445e9c4d32b647f47cf024ef318aab7a1f2e7a66304fc3a7d42f9620851842afe0476868d7df42f97d3cc2ab36a240d5e36e96371d61a09cebd46ab
-  data.tar.gz: 2c8a5763701b37efff2bd509b5bc4e4d703845b298cbc517a36d156253efed91422df8127939c849c50f09ead95a44d7d87f5a0f156c29ff7e73d920d9e2ec4c
+  metadata.gz: 293edcc0a2b44381720c8e08c7f13a0e57aa34c321fc4eb94e31e93142ccc9b149bdb72c754cab442f75b47d1754394de9bc3b39bb6629ea4c8c9195b40bef81
+  data.tar.gz: 986d62661c2bb354562ee024492606d905a9931d1cb99627906d6232f5517c92c22b41640a05d2a51b999dc5a9ff68931f60e3d705f2a9c02e79cc3dd376a3e4

data/README.md

@@ -22,14 +22,170 @@ Or install it yourself as:
 
 ## Usage
 
+### Basic Usage
+
+The basic usage will give you a CloudFormation stack named `{application}-{type}-{environment}`. The default type is `nodes`
+
+```ruby
+application_name = "myapp"
+environment_name = "production"
+my_stack = KumoKeisei::Stack.new(stack_name, environment_name)
+
+stack_config = {
+  config_path: File.join('/app', 'env', 'config'),
+  template_path: File.join('/app', 'env', 'cloudformation', 'myapp.json'),
+}
+
+my_stack.apply! stack_config
+```
+
+### Changing the stack type
+
+Specify the `type` in an options object passed to the `KumoKeisei::Stack` constructor. For example the following will give you a `myapp-vpc-production` stack e.g:
+```ruby
+vpc_stack_options = {
+  type: 'vpc'
+}
+vpc_stack = KumoKeisei::Stack.new('myapp', 'production', vpc_stack_options)
+```
+
+### Timeouts
+
+You can tune each of the timeouts by passing options to the Stack constructor:
+```ruby
+stack_options = {
+  confirmation_timeout: 0.5,
+  waiter_delay: 20,
+  waiter_attempts: 90,
+}
+
+KumoKeisei::Stack.new(stack_name, environment_name, stack_options)
+```
+
+*confirmation_timeout*: how long to wait for a user to confirm delete actions
+*waiter_delay*: how long to wait between checking Cfn for completion of delete and update actions
+*waiter_attempts*: how many times to retry checking that a Cfn delete or update was successful
+
+### CloudFormation Templates, Parameter Templates and Configuration Files
+
+The **CloudFormation Template** is a json file (e.g. app.json) describing a related set of Amazon resources using the [CloudFormation DSL](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/gettingstarted.templatebasics.html). You pass the location by specifying the `template_path` in the object passed to `apply!`,
+
+The **Parameter Template** is a file prescribing the Cfn parameters [Embedded Ruby](http://www.stuartellis.eu/articles/erb/) form. It must be in the same folder holding the CloudFormation Template, named `{app_name}.yml.erb`.
+
+The **Configuration Files** are a set of files in `yml` format prescribing configuration values for a given environment. They must be in the folder given by `config_path`, in the form of `{environment}.yml` and `{environment}_secrets.yml`
+
+[KumoKi](https://github.com/redbubble/kumo_ki_gem) will be used to decrypt the _secrets_ files.
+
+### Configuration Hierarchy
+
+Configuration will be loaded from the following sources:
+
+1. `common.yml` and `common_secrets.yml` if they exist.
+2. `{environment}.yml` and `{environment}_secrets.yml` or `development.yml` and `development_secrets.yml` if environment specific config does not exist.
+
+### Injecting Configuration
+
+You can also inject configuration at run time by adding it to the object provided to the `apply!` call:
+
+```ruby
+stack_config = {
+  config_path: File.join('/app', 'env', 'config'),
+  template_path: File.join('/app', 'env', 'cloudformation', 'myapp.json'),
+  injected_config: {
+    'Seed' => random_seed,
+  }
+}
+stack.apply!(stack_config)
+```
+
+### Getting the configuration without an `apply!`
+
+If you need to inspect the configuration without applying a stack, call `config`:
+```ruby
+stack_config = {
+  config_path: File.join('/app', 'env', 'config'),
+  template_path: File.join('/app', 'env', 'cloudformation', 'myapp.json'),
+  injected_config: {
+    'Seed' => random_seed,
+  }
+}
+marshalled_config = stack.config(stack_config)
+if marshalled_config('DB_HOST').start_with? '192.' then
+  ...
+```
+
+## Upgrading from `KumoKeisei::CloudFormationStack` to `KumoKeisei::Stack`
+
+`KumoKeisei::CloudFormationStack` is deprecated and should be replaced with a `KumoKeisei::Stack` which encompasses an environment object (`KumoKeisei::EnvironmentConfig`).
+
+Previously you would have to construct your own `EnvironmentConfig` which would marshal it's configuration, then instantiate a `CloudFormationStack` and conduct operations on it.
+
+E.g. `apply-env`:
+```ruby
+require_relative '../env/cloudformation_stack'
+
+environment_name = ARGV.fetch(0) rescue raise("Error! No environment name given!")
+
+stack = CloudFormationStack.new(environment_name)
+stack.apply
+```
+and `environment_config.rb`:
+```ruby
+require 'kumo_keisei'
+
+class CloudFormationStack
+
+  APP_NAME = "fooapp"
+
+  attr_reader :env_name
+
+  def initialize(env_name)
+    @stacks = {}
+    @env_name = env_name
+  end
+
+  def env_vars
+    {}
+  end
+
+  def apply
+    # Inject the VPC and Subnets into the application's environment config
+    foo_config = KumoKeisei::EnvironmentConfig.new(
+      env_name: env_name,
+      config_dir_path: File.expand_path(File.join("..", "..", "env", "config"), __FILE__)
+    )
+
+    foo_stack = create_stack(:foo, foo_config)
+    foo_stack.apply!
+  end
+  ...
+  def create_stack(stack_name, environment_config)
+    raise "Stack '#{ stack_name }' already exists!" if @stacks[stack_name]
+    params_template_erb = params_template(stack_name)
+    stack_values = cf_params_json(get_stack_params(params_template_erb, environment_config))
+    write_stack_params_file(stack_values, stack_name)
+    @stacks[stack_name] = KumoKeisei::CloudFormationStack.new(stack_names[stack_name], "./env/cloudformation/#{stack_name}.json", stack_file_params_file_path(stack_name))
+  end
+  ...
+```
+
+With the new `Stack` object, all you need to do is pass in the location of the template and config as in the above section. New `apply-env`:
 ```ruby
-stack_name = "my_awesome_stack"
-template = "./cloudformation/environment_template.json"
-template_params = "./cloudformation/environments/production/params.json"
+require 'kumo_keisei'
+
+environment_name = ARGV.fetch(0) rescue raise("Error! No environment name given!")
 
-KumoKeisei::CloudFormationStack.new(stack_name, template, template_params).apply!
+stack_config = {
+  config_path: File.join('/app', 'env', 'config'),
+  template_path: File.join('/app', 'env', 'cloudformation', 'fooapp.json'),
+}
+
+stack = KumoKeisei::Stack.new('fooapp', environment_name)
+stack.apply!(stack_config)
 ```
 
+
+
 ## Dependencies
 
 #### Ruby Versions

data/VERSION

@@ -1 +1 @@
-3.0.4
+3.0.5-alpha1

data/lib/kumo_keisei/stack.rb

@@ -4,6 +4,7 @@ module KumoKeisei
   class Stack
     class CreateError < StandardError; end
     class UpdateError < StandardError; end
+    class UsageError < StandardError; end
 
     UPDATEABLE_STATUSES = [
       'UPDATE_ROLLBACK_COMPLETE',
@@ -39,6 +40,9 @@ module KumoKeisei
 
     def apply!(stack_config)
       stack_config.merge!(env_name: @env_name)
+
+      raise UsageError.new('You must provide a :template_path in the stack config hash for an apply! operation') unless stack_config.has_key?(:template_path)
+
       if updatable?
         update!(stack_config)
       else
@@ -76,6 +80,11 @@ module KumoKeisei
       !get_stack.nil?
     end
 
+    def config(stack_config)
+      raise UsageError.new('You must provide a :config_path in the stack config hash to retrieve the stack\'s config') unless stack_config.has_key?(:config_path)
+      environment_config(stack_config).config
+    end
+
     private
 
     def transform_logical_resource_id(id)
@@ -153,7 +162,7 @@ module KumoKeisei
     end
 
     def environment_config(stack_config)
-      params_template_path = File.absolute_path(File.join(File.dirname(stack_config[:template_path]), "#{@app_name}.yml.erb"))
+      params_template_path = stack_config.has_key?(:template_path) ? File.absolute_path(File.join(File.dirname(stack_config[:template_path]), "#{@app_name}.yml.erb")) : nil
       EnvironmentConfig.new(stack_config.merge(params_template_file_path: params_template_path))
     end
 

data/spec/lib/kumo_keisei/stack_spec.rb

@@ -40,6 +40,8 @@ describe KumoKeisei::Stack do
     }
   }
 
+  context "unit tests" do
+
   before do
     allow(KumoKeisei::ConsoleJockey).to receive(:flash_message)
     allow(KumoKeisei::ConsoleJockey).to receive(:write_line).and_return(nil)
@@ -73,6 +75,20 @@ describe KumoKeisei::Stack do
   end
 
   describe "#apply!" do
+    context "when you don't specify the location of the Cfn template" do
+      let(:stack_config) {
+        {
+          config_path: 'config-path',
+          injected_config: { 'VpcId' => 'vpc-id' },
+          env_name: 'non-production'
+        }
+      }
+
+      it "complains" do
+        expect { subject.apply!(stack_config) }.to raise_error(KumoKeisei::Stack::UsageError)
+      end
+    end
+
     context "when the stack is updatable" do
       UPDATEABLE_STATUSES = ['UPDATE_ROLLBACK_COMPLETE', 'CREATE_COMPLETE', 'UPDATE_COMPLETE']
 
@@ -254,15 +270,56 @@ describe KumoKeisei::Stack do
     end
   end
 
-    describe "#type" do
-      it "presumes stacks are of type node if the type is not set" do
-        expect(subject.stack_name).to eq("#{app_name}-nodes-#{environment_name}")
+  describe "#type" do
+    it "presumes stacks are of type node if the type is not set" do
+      expect(subject.stack_name).to eq("#{app_name}-nodes-#{environment_name}")
+    end
+
+    it "embeds the type into the name of the stack if set" do
+      subject = KumoKeisei::Stack.new(app_name, environment_name, { type: "vpc" } )
+      expect(subject.stack_name).to eq("#{app_name}-vpc-#{environment_name}")
+    end
+  end
+
+  describe "#config" do
+    context "when passed a config_path and params_template_file_path" do
+      before do
+        allow(KumoKeisei::EnvironmentConfig).to receive(:new).with(stack_config.merge(params_template_file_path: "#{app_name}.yml.erb")).and_return(double(:environment_config, cf_params: {}, config: { :foo=> 'bar', :baz=> 'qux' }))
       end
 
-      it "embeds the type into the name of the stack if set" do
-        subject = KumoKeisei::Stack.new(app_name, environment_name, { type: "vpc" } )
-        expect(subject.stack_name).to eq("#{app_name}-vpc-#{environment_name}")
+      it "will return the results of the nested KumoKeisei::EnvironmentConfig.config" do
+        expect(subject.config(stack_config)).to eq({:foo=> 'bar', :baz=>'qux'})
       end
     end
 
+    context "when a config_path and nil for params_template_file_path" do
+      let(:stack_config) {
+        {
+          config_path: 'config-path',
+          env_name: 'non-production'
+        }
+      }
+
+      before do
+        allow(KumoKeisei::EnvironmentConfig).to receive(:new).with(stack_config.merge(params_template_file_path: nil)).and_return(double(:environment_config, cf_params: {}, config: { :foo=> 'bar', :baz=> 'qux' }))
+      end
+
+      it "will return the results of the nested KumoKeisei::EnvironmentConfig.config" do
+        expect(subject.config(stack_config)).to eq({:foo=> 'bar', :baz=>'qux'})
+      end
+    end
+
+    context "if not given a stack_config containing a `config_path`" do
+      let(:stack_config) {
+        {
+        }
+      }
+      it "will raise an error" do
+        expect { described_class.new(app_name, environment_name).config(stack_config)}.to raise_error(KumoKeisei::Stack::UsageError)
+      end
+    end
+
+  end
+end
+
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kumo_keisei
 version: !ruby/object:Gem::Version
-  version: 3.0.4
+  version: 3.0.5.pre.alpha1
 platform: ruby
 authors:
 - Redbubble
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-04 00:00:00.000000000 Z
+date: 2016-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk
@@ -130,12 +130,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: A collection of utilities for dealing with AWS Cloud Formation.