sparkle-guides 0.1.10 → 0.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 4cf80716c1f462168e5827fca6593c81a6c29bd6
-  data.tar.gz: e31969f4ae18a2978a94ba5e92e438c578235f11
+SHA256:
+  metadata.gz: e2cf461c429c10b2156db909a0cb627c594bda1cc7c86532d6dd8b3920affceb
+  data.tar.gz: df4f1573c99d06439f0fe11b3d80bc238c56105dc35c5b42497a66c6b1455ff7
 SHA512:
-  metadata.gz: 06b6fdae6857a89b78822bd5bf2765e4d59ac0234a6c6080637a6457a80780c6f2aa1c0fe390b9968c799891e57baa0ec10ae106c31b186493ac839a5f471472
-  data.tar.gz: 174df5f00486cdd8acb124ae94c5ae7861128c64a006afaa873fdc500c1692d8f33a6f1e5f01aab87dbf00210c51cd38602ffce315f09db62044ab209b5d4435
+  metadata.gz: facf5eefbb559517c5a68a0d3b8b7abac016196ef6760e3cbdc8c483c668593358eaab39628a319e156cd4db3671e6538bfd3e2c373506f1d35ae64c35403b5f
+  data.tar.gz: 8c9b28db2eb1208c774fc6f9da95cdd43a187f5587b0184a1bbb4e455bdb055a63e64b871a9ffb8ce7669f446c28ecca095a64a82afb280a70c6d36c2f02f82b

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+# v0.1.12
+* Include cross location apply stack example
+* Start tips and tricks
+
 # v0.1.8
 * Update non-default type files with provider flag
 

data/docs/apply-and-nested.md

@@ -1,5 +1,5 @@
 ---
-title: "Stack Interdependencies"
+title: "Stack Dependencies"
 weight: 2
 anchors:
   - title: "Overview"
@@ -10,6 +10,8 @@ anchors:
     url: "#nested-stack-implementation"
   - title: "Apply nested stack"
     url: "#apply-nested-stack"
+  - title: "Cross location"
+    url: "#cross-location"
 ---
 
 ## Overview
@@ -390,3 +392,44 @@ You can destroy the all the `infrastructure` related stacks with the command:
 ~~~
 sfn destroy sparkle-guide-infrastructure
 ~~~
+
+## Cross location
+
+SparkleFormation supports accessing stacks in other locations when using the
+apply stack functionality. This is done by configuring named locations within
+the `.sfn` configuration file and then referencing the location when applying
+the stack. Using this example `.sfn` configuration file:
+
+~~~ruby
+Configuration.new do
+  credentials do
+    provider :aws
+    aws_access_key_id 'KEY'
+    aws_secret_access_key 'SECRET'
+    aws_region 'us-east-1'
+  end
+  locations do
+    west_stacks do
+      provider :aws
+      aws_access_key_id 'KEY'
+      aws_secret_access_key 'SECRET'
+      aws_region 'us-west-2'
+    end
+  end
+end
+~~~
+
+This configuration connects to the AWS API in us-east-1. It also includes configuration
+for connecting to us-west-2 via a named location of `west_stacks`. This allows referencing
+stacks located in us-west-2 when using the apply stack functionality. Assume a new stack
+is being created in us-east-1 (my-stack) and the outputs from other-stack in us-west-2
+should be applied. This can be accomplished with the following command:
+
+~~~
+sfn create my-stack --apply-stack west_stacks__my-stack
+~~~
+
+When the stack is created sfn will first connect to the us-west-2 API and gather the
+outputs from other-stack, then it will connect to us-east-1 to create the new stack.
+
+_NOTE: Custom locations are not required to have a common provider._

data/docs/getting-started.md

@@ -26,8 +26,7 @@ anchors:
 
 ## Requirements
 
-* Ruby (Version `>=` 2.0)
-* Bundler
+* Ruby (Version `>=` 2.3)
 * Provider Credentials
 
 ### Installing Ruby
@@ -53,8 +52,10 @@ the provider:
 
 * [miasma-aws](https://github.com/miasma-rb/miasma-aws)
 * [miasma-azure](https://github.com/miasma-rb/miasma-azure)
+* [miasma-google](https://github.com/miasma-rb/miasma-google)
 * [miasma-open-stack](https://github.com/miasma-rb/miasma-open-stack)
 * [miasma-rackspace](https://github.com/miasma-rb/miasma-rackspace)
+* [miasma-terraform](https://github.com/miasma-rb/miasma-terraform)
 
 ## Installation
 

data/docs/tips-and-tricks.md

@@ -0,0 +1,128 @@
+---
+title: "Tips and Tricks"
+weight: 3
+anchors:
+  - title: "Stubbing builtins"
+    url: "#stubbing-builtins"
+  - title: "Resource conflicts"
+    url: "#resource-conflicts"
+---
+
+## Stubbing builtins
+
+SparkleFormation provides a number of builtin resources using the
+`dynamic!` helper. These known resources are collected when SparkleFormation
+is released. Because this is a static list of resource types it is
+common for new resources to be introduced within a cloud provider
+and not be available within SparkleFormation. Since the new resource
+types will not be available within SparkleFormation until the next
+release, stubbing the builtin will provide the same behavior as if
+it were included within the builtin list.
+
+For example, lets assume that AWS CloudFormation introduces a new
+resource type named `AWS::JVM::Instance`. To stub this resource a
+new dynamic can be created locally:
+
+~~~ruby
+SparkleFormation.dynamic(:jvm_instance) do |name|
+  resources.set!("#{name}_jvm_instance".to_sym) do
+    type "AWS::JVM::Instance"
+  end
+end
+~~~
+
+With this dynamic defined it will behave the same as if it were
+defined in the builtin list:
+
+~~~ruby
+SparkleFormation.new(:test) do
+  dynamic!(:jvm_instance, :test) do
+    properties.memory 512
+  end
+end
+~~~
+
+which results in:
+
+~~~json
+{
+  "Resources": {
+    "TestJvmInstance": {
+      "Type": "AWS::JVM::Instance",
+      "Properties": {
+        "Memory": 512
+      }
+    }
+  }
+}
+~~~
+
+Once the `AWS::JVM::Instance` becomes available in the builtin
+list within SparkleFormation the custom stub dynamic can be deleted.
+
+## Resource conflicts
+
+Resource conflicts can occur when the same resource name is used
+in multiple resource namespaces. If a template has created resources
+using the `dynamic!` helper and not included the resource's namespace,
+conflicts will occur when the new resource becomes available. An
+example of this is the `AWS::ElasticLoadBalancing::LoadBalancer` resource.
+
+Assume that the following template is in use:
+
+~~~ruby
+SparkleFormation.new(:lb) do
+  dynamic!(:load_balancer, :app)
+end
+~~~
+
+and it generates:
+
+~~~json
+{
+  "Resources": {
+    "AppLoadBalancer": {
+      "Type": "AWS::ElasticLoadBalancing::LoadBalancer"
+    }
+  }
+}
+~~~
+
+Now, AWS releases a new resource with a conflicting name
+`AWS::ElasticLoadBalancingV2::LoadBalancer` and SparkleFormation's internal
+resource list has been updated. When the template is run again, it returns
+an error about conflicting resource names. One solution is to update the
+`dynamic!` call to include the namespace:
+
+~~~ruby
+SparkleFormation.new(:lb) do
+  dynamic!(:elastic_load_balancing_load_balancer, :app)
+end
+~~~
+
+and it will then generate:
+
+~~~json
+{
+  "Resources": {
+    "AppElasticLoadBalancingLoadBalancer": {
+      "Type": "AWS::ElasticLoadBalancing::LoadBalancer"
+    }
+  }
+}
+~~~
+
+This resolves the conflict issue, yet in practice the modification of the
+resource name will likely cause issues in complex templates where the
+resource is being referenced in other locations. To allow templates to
+remain unchanged, a new dynamic can be introduced which will force matching
+of the `:load_balancer` name to the local dynamic:
+
+~~~ruby
+SparkleFormation.dynamic(:load_balancer) do |name|
+  dynamic!(:elastic_load_balancing_load_balancer, name, :resource_name_suffix => :load_balancer)
+end
+~~~
+
+With this dynamic in place, all original templates will continue to behave
+as expected without individual modifications.

data/sparkle-guides.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = 'sparkle-guides'
-  s.version = '0.1.10'
+  s.version = '0.1.12'
   s.summary = 'SparkleFormation Guides'
   s.author = 'Chris Roberts'
   s.email = 'chrisroberts.code@gmail.com'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sparkle-guides
 version: !ruby/object:Gem::Version
-  version: 0.1.10
+  version: 0.1.12
 platform: ruby
 authors:
 - Chris Roberts
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-05-15 00:00:00.000000000 Z
+date: 2019-01-26 00:00:00.000000000 Z
 dependencies: []
 description: SparkleFormation Usage Guides
 email: chrisroberts.code@gmail.com
@@ -20,6 +20,7 @@ files:
 - README.md
 - docs/apply-and-nested.md
 - docs/getting-started.md
+- docs/tips-and-tricks.md
 - sparkle-guides.gemspec
 homepage: http://github.com/sparkleformation/sparkle-guides
 licenses:
@@ -40,8 +41,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 3.0.1
 signing_key: 
 specification_version: 4
 summary: SparkleFormation Guides