sparkle-guides 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6ca6dbae97e6ffca7a7acae9ac3c4c2d912a3e55
-  data.tar.gz: 25c8f24c9d55cb47d8ef1e77de7691f2e82959f9
+  metadata.gz: b6d84bfd1702300758e47d0348e9905a0d70c0f8
+  data.tar.gz: c2a02647503ca0fd162e28a3c33bae7cb2c53e81
 SHA512:
-  metadata.gz: 8c99905620769f194128a8d297545a2e6d5be27ac6c96919dfaed3eb8d0a4a7d833fe67064593dc8ea07e03a80e77e15ba1c366e182c1b187b9eb21be46843b7
-  data.tar.gz: af9d5353d8cf60122d6c09c88e2a845b4ad1635bede36a075550949160cca0154dc5143587e0c9997aa91dfcd8d0858f79f32b258088c9e3c90ee9866dd74f85
+  metadata.gz: 824eba256e15ac401704765d07500313c61fa7930637992f9bf793d03978c88e0922b5059e3757f345b21a65af082de1c9f2ea7009684ed23cc5ea9c9d7a4031
+  data.tar.gz: e76f5398b1baa00c49d3abf332662e63c5ca4bcf36474cb9b524daead8418fa9baa690a5f47b124f3e3186f5ded5a414104c18afe682302d7b3cc5e8f17e8d8f

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+# v0.1.4
+* Update file system layout.
+* Fix YAML error on guide header.
+
 # v0.1.2
 * Add apply and nesting guide
 

data/docs/apply-and-nested.md

@@ -0,0 +1,375 @@
+---
+title: "Stack Interdependencies"
+weight: 2
+anchors:
+  - title: "Overview"
+    url: "#overview"
+  - title: "Apply stack"
+    url: "#apply-stack-implementation"
+  - title: "Nested stack"
+    url: "#nested-stack-implementation"
+  - title: "Apply nested stack"
+    url: "#apply-nested-stack"
+---
+
+## Overview
+
+### Apply stack
+
+The SparkleFormation CLI includes functionality to ease the sharing
+of resources between isolated stacks. This functionality enables
+groupings of similar resources which can define logical units of
+a full architecture. The sharing is accomplished using a combination
+of stack outputs and stack parameters. This feature is commonly
+referred to as the _apply stack_ functionality.
+
+One drawback of the _apply stack_ functionality is that it introduces
+dependencies between disparate stacks. These dependencies must be
+manually resolved when resource modifications occur. When an infrastructure
+is composed of few stacks, the _apply stack_ approach can be sufficient
+to manage stack dependencies leaving the user to ensure updates are
+properly applied. For larger implementations composed of many interdependent
+stacks, the _nested stack_ functionality is recommended.
+
+### Nested stack
+
+_Nested stack_ functionality is a generic feature provided by the SparkleFormation
+library which the SparkleFormation CLI then specializes based on the target provider.
+The _nested stack_ functionality utilizes a core feature provided by orchestration
+APIs. This features allows nesting stack resources within a stack allowing a
+parent stack to have many child stacks. By nesting stack resources, the provider
+API will be aware of child stack interdependencies and automatically apply updates
+when resources have been modified. This removes the requirement of stack updates
+being tracked and applied manually.
+
+The behavior of the _nested stack_ functionality is based directly on the
+behavior of the _apply stack_ functionality. This commonality in behavior
+allows for initial testing development using the _apply stack_ functionality
+and, once stable, migrating to _nested stack_ functionality without requiring any
+modifications to existing templates. The commonality also allows for the two
+functionalities to be mixed in practice.
+
+This guide will first display template implementations using the _apply stack_
+functionality. The example templates will then be used to provide a _nested stack_
+implementation.
+
+_NOTE: This guide targets the AWS provider for simplicity to allow focus on the
+features discussed. All providers support this behavior._
+
+## Apply stack implementation
+
+Lets start by defining a simple infrastructure. Our infrastructure will be composed
+of a "network" and a collection of "computes" that utilizes the network. This
+infrastructure can be easily defined within two units:
+
+1. network
+2. computes
+
+Lets start by creating a simple `network` template.
+
+Create a new file: `./sparkleformation/network.rb`
+
+#### Template sparkles AWS
+
+~~~ruby
+SparkleFormation.new(:network) do
+
+  parameters do
+    cidr_prefix do
+      type 'String'
+      default '172.20'
+    end
+  end
+
+  dynamic!(:ec2_vpc, :network) do
+    properties do
+      cidr_block join!(ref!(:cidr_prefix, '.0.0/24'))
+      enable_dns_support true
+      enable_dns_hostnames true
+    end
+  end
+
+  dynamic!(:ec2_dhcp_options, :network) do
+    properties do
+      domain_name join!(region!, 'compute.internal')
+      domain_name_servers ['AmazonProvidedDNS']
+    end
+  end
+
+  dynamic!(:ec2_vpc_dhcp_options_association, :network) do
+    properties do
+      dhcp_options_id ref!(:network_ec2_dhcp_options)
+      vpc_id ref!(:network_ec2_vpc)
+    end
+  end
+
+  dynamic!(:ec2_internet_gateway, :network)
+
+  dynamic!(:ec2_vpc_gateway_attachment, :network) do
+    properties do
+      internet_gateway_id ref!(:network_ec2_internet_gateway)
+      vpc_id ref!(:network_ec2_vpc)
+    end
+  end
+
+  dynamic!(:ec2_route_table, :network) do
+    properties.vpc_id ref!(:network_ec2_vpc)
+  end
+
+  dynamic!(:ec2_route, :network_public) do
+    properties do
+      destination_cidr_block '0.0.0.0/0'
+      gateway_id ref!(:network_ec2_internet_gateway)
+      route_table_id ref!(:network_ec2_route_table)
+    end
+  end
+
+  dynamic!(:ec2_subnet, :network) do
+    properties do
+      availability_zone select!(0, azs!)
+      cidr_block join!(ref!(:cidr_prefix, '.0.0/24'))
+      vpc_id ref!(:network_ec2_vpc)
+    end
+  end
+
+  dynamic!(:ec2_subnet_route_table_association, :network) do
+    properties do
+      route_table_id ref!(:network_ec2_route_table)
+      subnet_id ref!(:network_ec2_subnet)
+    end
+  end
+
+  outputs do
+    network_vpc_id.value ref!(:network_ec2_vpc)
+    network_subnet_id.value ref!(:network_ec2_subnet)
+    network_route_table.value ref!(:network_ec2_route_table)
+    network_cidr.value join!(ref!(:cidr_prefix, '.0.0/24'))
+  end
+
+end
+~~~
+
+Here we have an extremely simple VPC defined for our infrastructure. It is
+important to note the outputs defined within our `network` template. These
+outputs are values that will be required for other resources to effectively
+utilize the VPC. With the `network` template defined, we can create that unit
+of our infrastructure:
+
+~~~
+$ bundle exec sfn create sparkle-guide-network --file network
+~~~
+
+Having successfully built the `network` unit of the infrastructure, we can
+now compose the `computes` template.
+
+Create a new file: `./sparkleformation/computes.rb`
+
+#### Template sparkles AWS
+
+~~~ruby
+SparkleFormation.new(:computes) do
+
+  parameters do
+    ssh_key_name.type 'String'
+    network_vpc_id.type 'String'
+    network_subnet_id.type 'String'
+  end
+
+  dynamic!(:ec2_security_group, :compute) do
+    properties do
+      group_description 'SSH Access'
+      security_group_ingress do
+        cidr_ip '0.0.0.0/0'
+        from_port 22
+        to_port 22
+        ip_protocol 'tcp'
+      end
+      vpc_id ref!(:network_vpc_id)
+    end
+  end
+
+  dynamic!(:ec2_instance, :micro) do
+    properties do
+      image_id 'ami-25c52345'
+      image_type 't2.micro'
+      key_name ref!(:ssh_key_name)
+      network_interfaces array!(
+        ->{
+          device_index 0
+          associate_public_ip_address 'true'
+          subnet_id ref!(:network_subnet_id)
+          group_set [ref!(:compute_ec2_security_group)]
+        }
+      )
+    end
+  end
+
+  dynamic!(:ec2_instance, :small) do
+    properties do
+      image_id 'ami-25c52345'
+      image_type 't2.micro'
+      key_name ref!(:ssh_key_name)
+      network_interfaces array!(
+        ->{
+          device_index 0
+          associate_public_ip_address 'true'
+          subnet_id ref!(:network_subnet_id)
+          group_set [ref!(:compute_ec2_security_group)]
+        }
+      )
+    end
+  end
+
+  outputs do
+    micro_address.value attr!(:micro_ec2_instance, :public_ip)
+    small_address.value attr!(:small_ec2_instance, :public_ip)
+  end
+
+end
+~~~
+
+Our `computes` template will create one micro and one small EC2
+instance and output the public IP addresses of each resource. To
+build the EC2 instances into the VPC created in the `sparkle-guide-network`
+stack we need two pieces of information:
+
+* VPC ID
+* VPC subnet ID
+
+In our `computes` template we define two parameters for the required
+VPC information: `network_vpc_id` and `network_subnet_id`. When we
+create a stack using this template we can copy the output values from the
+`sparkle-guide-network` stack and paste them into these parameters, but
+that is extremely cumbersome. The SparkleFormation CLI instead allows
+"applying" a stack on creation or update.
+
+Notice that the output names in our `network` template match the parameter
+names in our `computes` template.
+
+~~~ruby
+# From ./sparkleformation/network.rb
+  outputs do
+    network_vpc_id.value ref!(:network_ec2_vpc)
+    network_subnet_id.value ref!(:network_ec2_subnet)
+    network_route_table.value ref!(:network_ec2_route_table)
+    network_cidr.value join!(ref!(:cidr_prefix, '.0.0/24'))
+  end
+
+# From ./sparkleformation/computes.rb
+  parameters do
+    ssh_key_name.type 'String'
+    network_vpc_id.type 'String'
+    network_subnet_id.type 'String'
+  end
+~~~
+
+The apply stack functionality will automatically collect outputs from
+the stack names provided and use them to seed the parameters of the
+stack being created or updated. This means instead of having to copy
+and paste the VPC ID and subnet ID values, we can instruct the SparkleFormation
+CLI to automatically use the outputs of our `sparkle-guide-network` stack:
+
+~~~
+$ bundle exec sfn create sparkle-guide-computes --file computes --apply-stack sparkle-guide-network
+~~~
+
+During the create process, the SparkleFormation CLI will prompt for parameters. The
+default values for the VPC ID and subnet ID will be automatically inserted, matching
+the outputs from the `sparkle-guide-network`.
+
+## Nested stack implementation
+
+Now that our infrastructure has been successfully created using disparate stacks, lets
+combine them to create a single `infrastructure` unit composed of sub-units. Using
+nested stacks requires a bucket to store templates. Create a bucket in S3 and then
+add the following to the `.sfn` configuration file:
+
+~~~ruby
+Configuration.new do
+  ...
+  nesting_bucket 'NAME_OF_BUCKET'
+  ...
+end
+~~~
+
+With the required bucket in place and SparkleFormation CLI configured we can
+now create our `infrastructure` template.
+
+Create a new file: `./sparkleformation/infrastructure.rb`
+
+#### Template sparkles AWS
+
+~~~ruby
+SparkleFormation.new(:infrastructure) do
+  nest!(:network, :infra)
+  nest!(:computes, :infra)
+end
+~~~
+
+This new `infrastructure` template is using SparkleFormation's builtin nesting
+functionality to create stack resources within our `infrastructure` template
+composed of our `network` and `computes` template. To see the conceptual result
+of this nesting, we can print the `infrastructure` template:
+
+~~~
+$ bundle exec sfn print --file infrastructure
+~~~
+
+There are a few things of note in this output. First, the `Stack` property is
+not a real resource property. It is used by SparkleFormation for template processing
+and is included in print functions to display the template in its entirety. Next,
+the generated URLs are not real URLs. This is due to the SparkleFormation CLI not
+actually storing the templates in the remote bucket. Lastly, and most importantly,
+the parameters property of the `ComputesInfra` resource.
+
+~~~json
+"Parameters": {
+  "NetworkVpcId": {
+    "Fn::GetAtt": [
+      "NetworkInfra",
+      "Outputs.NetworkVpcId"
+    ]
+  },
+  "NetworkSubnetId": {
+    "Fn::GetAtt": [
+      "NetworkInfra",
+      "Outputs.NetworkSubnetId"
+    ]
+  }
+}
+~~~
+
+SparkleFormation registers outputs when processing templates and will automatically
+map outputs to subsequent stack resource parameters if they match. Cross stack resource
+dependencies are now explicitly defined allowing the orchestration API to automatically
+determine creation order as well as triggering updates when required.
+
+Now we can create our full infrastructure with a single command:
+
+~~~
+$ bundle exec sfn create sparkle-guide-infrastructure --file infrastructure
+~~~
+
+As SparkleFormation processes the nested templates for the `create` command, the SparkleFormation
+CLI will extract the nested templates, store them in the configured nesting bucket, and updates
+the template location URL in the resource.
+
+Using nested templates, `update` commands follow the same behavior as `create` commands. All nested
+templates are extracted and automatically uploaded prior to execution of the `update` request with
+the orchestration API. This results in _all_ nested stacks being automatically updated by the API
+as required based on dependent resource modifications.
+
+## Apply nested stack
+
+Nested stacks can be applied to disparate stacks in the same manner described in the apply
+stack implementation section. When the stack to be applied is a nested stack, SparkleFormation
+CLI will gather outputs from all the nested stacks, and then apply to the target command. This
+means using the `sparkle-guide-infrastructure` stack we previously built can be used for creating
+new `computes` stacks without being nested into the `infrastructure` template.
+
+~~~
+$ bundle exec sfn create sparkle-guide-computes-infra --file computes --apply-stack sparkle-guide-infrastructure
+~~~
+
+The ability to apply nested stacks to disparate stacks make it easy to provide resources to new
+stacks, or to test building new stacks in isolation before being nested into the root stack.

data/docs/getting-started.md

@@ -0,0 +1,734 @@
+---
+title: "Getting Started"
+weight: 1
+anchors:
+  - title: "Requirements"
+    url: "#requirements"
+  - title: "Installation"
+    url: "#installation"
+  - title: "Configuration"
+    url: "#configuration"
+  - title: "Setup"
+    url: "#setup"
+  - title: "Create a template"
+    url: "#create-a-template"
+  - title: "Create a new stack"
+    url: "#create-a-new-stack"
+  - title: "Template refactor"
+    url: "#template-refactor"
+  - title: "Stack update"
+    url: "#stack-update"
+  - title: "Stack information"
+    url: "#stack-information"
+  - title: "Clean up"
+    url: "#clean-up"
+---
+
+## Requirements
+
+* Ruby (Version `>=` 2.0)
+* Bundler
+* Provider Credentials
+
+### Installing Ruby
+
+There are a variety of ways to install Ruby depending on platform and toolset. The
+Ruby website provides information about many of the installation options:
+
+* [Installing Ruby](https://www.ruby-lang.org/en/documentation/installation/)
+
+### Installing Bundler
+
+Once Ruby is installed, install Bundler using the `gem` command:
+
+~~~
+$ gem install bundler
+~~~
+
+### Provider credentials
+
+Required credentials differ based on the target provider in use. For more information
+about credentials specific to a certain provider, reference the miasma library for
+the provider:
+
+* [miasma-aws](https://github.com/miasma-rb/miasma-aws)
+* [miasma-azure](https://github.com/miasma-rb/miasma-azure)
+* [miasma-open-stack](https://github.com/miasma-rb/miasma-open-stack)
+* [miasma-rackspace](https://github.com/miasma-rb/miasma-rackspace)
+
+## Installation
+
+First, install the `sfn` gem:
+
+~~~
+$ gem install sfn
+~~~
+
+Now initialize a new project:
+
+~~~
+$ sfn init sparkle-guide
+~~~
+
+Finally change to the new project directory:
+
+~~~
+$ cd sparkle-guide
+~~~
+
+## Configuration
+
+The `init` command will have automatically generated a configuration file
+within the project directory. To view the current configuration status the
+`conf` command can be used:
+
+~~~
+$ bundle exec sfn conf
+~~~
+
+The configuration file for `sfn` is located within the `.sfn` file. Open this file
+and adjust the credentials section for your desired provider. The generated
+configuration file uses environment variables for provider configuration. This
+style of setup makes it easy to automatically set credential information using
+tools like direnv. Environment variable usage is not required, and credential
+values can be provided directly.
+
+_NOTE: It is important to **not** store provider credential secrets within the
+`.sfn` file if it will be checked into source control._
+
+### Test configuration
+
+Test the configuration by running a list command:
+
+~~~
+$ bundle exec sfn list
+~~~
+
+This should print a list of existing stacks on the configured provider. If no
+stacks exist, no entries will be shown. If an error message is received, check
+that the credentials information is properly set and try again.
+
+## Create a template
+
+Lets start by creating a full template. This template will create a compute resource
+on the desired provider and output the remote public address of the new compute instance.
+
+Create a new file: `./sparkleformation/compute.rb`:
+
+#### Template sparkles AWS
+
+~~~ruby
+SparkleFormation.new(:compute, :provider => :aws) do
+  AWSTemplateFormatVersion '2010-09-09'
+  description 'Sparkle Guide Compute Template'
+
+  parameters do
+    sparkle_image_id.type 'String'
+    sparkle_ssh_key_name.type 'String'
+    sparkle_flavor do
+      type 'String'
+      default 't2.micro'
+      allowed_values ['t2.micro', 't2.small']
+    end
+  end
+
+  dynamic!(:ec2_instance, :sparkle) do
+    properties do
+      image_id ref!(:sparkle_image_id)
+      instance_type ref!(:sparkle_flavor)
+      key_name ref!(:sparkle_ssh_key_name)
+    end
+  end
+
+  outputs.sparkle_public_address do
+    description 'Compute instance public address'
+    value attr!(:sparkle_ec2_instance, :public_ip)
+  end
+
+end
+~~~
+
+#### Template sparkles HEAT
+
+~~~ruby
+SparkleFormation.new(:compute, :provider => :heat) do
+  heat_template_version '2015-04-30'
+  description 'Sparkle Guide Compute Template'
+
+  parameters do
+    sparkle_image_id.type 'String'
+    sparkle_ssh_key_name.type 'String'
+    sparkle_flavor do
+      type 'String'
+      default 'm1.small'
+      allowed_values ['m1.small', 'm1.medium']
+    end
+  end
+
+  dynamic!(:nova_server, :sparkle) do
+    properties do
+      image ref!(:sparkle_image_id)
+      flavor ref!(:sparkle_flavor)
+      key_name ref!(:sparkle_ssh_key_name)
+    end
+  end
+
+  outputs.sparkle_public_address do
+    description 'Compute instance public address'
+    value attr!(:sparkle_nova_instance, 'accessIPv4')
+  end
+
+end
+~~~
+
+#### Template sparkles Azure
+
+~~~ruby
+SparkleFormation.new(:compute, :provider => :azure) do
+  set!('$schema', 'https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#')
+  content_version '1.0.0.0'
+  parameters do
+    sparkle_image_id do
+      type 'string'
+      default_value '14.04.2-LTS'
+    end
+    sparkle_flavor do
+      type 'string'
+      allowed_values [
+        'Standard_D1'
+      ]
+    end
+    storage_account_name.type 'string'
+    storage_container_name.type 'string'
+  end
+
+  dynamic!(:network_public_ip_addresses, :sparkle) do
+    properties do
+      set!('publicIPAllocationMethod', 'Dynamic')
+      dns_settings.domain_name_label 'sparkle'
+    end
+  end
+
+  dynamic!(:network_virtual_networks, :sparkle) do
+    properties do
+      address_space.address_prefixes ['10.0.0.0/16']
+      subnets array!(
+        ->{
+          name 'sparkle-subnet'
+          properties.address_prefix '10.0.0.0/24'
+        }
+      )
+    end
+  end
+
+  dynamic!(:network_interfaces, :sparkle) do
+    properties.ip_configurations array!(
+      ->{
+        name 'ipconfig1'
+        properties do
+          set!('privateIPAllocationMethod', 'Dynamic')
+          set!('publicIPAddress').id resource_id!(:sparkle_network_public_ip_addresses)
+          subnet.id concat!(resource_id!(:sparkle_network_virtual_networks), '/subnets/sparkle-subnet')
+        end
+      }
+    )
+  end
+
+  dynamic!(:compute_virtual_machines, :sparkle) do
+    properties do
+      hardware_profile.vm_size parameters!(:sparkle_flavor)
+      os_profile do
+        computer_name 'sparkle'
+        admin_username 'sparkle'
+        admin_password 'SparkleFormation2016'
+      end
+      storage_profile do
+        image_reference do
+          publisher 'Canonical'
+          offer 'UbuntuServer'
+          sku parameters!(:sparkle_image_id)
+          version 'latest'
+        end
+        os_disk do
+          name 'osdisk'
+          vhd.uri concat!('http://', parameters!(:storage_account_name), '.blob.core.windows.net/', parameters!(:storage_container_name), '/sparkle.vhd')
+          caching 'ReadWrite'
+          create_option 'FromImage'
+        end
+        data_disks array!(
+          ->{
+            name 'datadisk1'
+            set!('diskSizeGB', 100)
+            lun 0
+            vhd.uri concat!('http://', parameters!(:storage_account_name), '.blob.core.windows.net/', parameters!(:storage_container_name), '/sparkle-data.vhd')
+            create_option 'Empty'
+          }
+        )
+      end
+      network_profile.network_interfaces array!(
+        ->{ id resource_id!(:sparkle_network_interfaces) }
+      )
+    end
+  end
+
+  outputs.sparkle_public_address do
+    type 'string'
+    value reference!(:sparkle_network_public_ip_addresses).ipAddress
+  end
+end
+~~~
+
+### View template
+
+View the processed JSON result:
+
+~~~
+$ bundle exec sfn print --file compute
+~~~
+
+This will output the serialized JSON template generated by SparkleFormation. The JSON is the template
+content which will be sent to the remote provider API with the stack create request.
+
+## Create a new stack
+
+After seeing the result of the compiled and serialized template, lets use that template to
+create a new stack. To start the stack creation process run the following command:
+
+~~~
+$ bundle exec sfn create sparkle-guide-compute --file compute
+~~~
+
+Before creating this new stack, `sfn` will prompt for the parameters defined within the template.
+The `sparkle_image_id` and `sparkle_ssh_key_name` parameters are not defined with default values within the template,
+so values _must_ be provided when prompted. The prompt for the `sparkle_flavor` parameter will show the
+default value defined within the template, and can be used or overridden with a different value.
+
+After `sfn` has completed prompting for stack parameters, it will initiate the stack creation
+request with the remote provider. The creation request to the API is only for initiation. A successful
+response does not indicate that the stack was created successfully, rather it indicates that the request
+to create the stack was successful.
+
+Once the create request is complete, `sfn` will automatically transition to event polling. Resource
+events related to the new stack will be displayed until the stack reaches a "complete" state: success
+or failure. The automatic transition to event polling ensures that the `sfn create` command will return
+a proper exit code once the stack has reached a completion state.
+
+At successful completion of the stack creation, the outputs defined within the template will be displayed
+showing the public address of the newly created compute instance.
+
+## Template refactor
+
+A key feature of SparkleFormation is the ability to break down templates into reusable parts which can
+then be re-used in multiple templates. Lets break down our existing template into re-usable parts and
+re-build the template using those parts.
+
+### Registry
+
+The registry is a place to store values that may be used in multiple places. With the value defined in
+a single location, updates to the value only require one modification to apply globally. In our `compute`
+example, the allowed instance flavor values would an ideal candidate for a registry entry.
+
+Create a new file at `./sparkleformation/registry/instance_flavor.rb`
+
+#### Registry sparkles AWS
+
+~~~ruby
+SfnRegistry.register(:instance_flavor) do
+  ['m1.small', 'm1.medium']
+end
+~~~
+
+#### Registry sparkles HEAT
+
+~~~ruby
+SfnRegistry.register(:instance_flavor) do
+  ['m1.small', 'm1.medium']
+end
+~~~
+
+#### Registry sparkles Azure
+~~~ruby
+SfnRegistry.register(:instance_flavor) do
+  ['Standard_D1']
+end
+~~~
+
+_NOTE: For more information see: [Registry building blocks](../sparkle_formation/building-blocks.html#registry)_
+
+### Component
+
+Components are items which are used a single time within a template. The version information and description
+are both items in our `compute` template that are only used a single time, but should be defined in all templates.
+Lets move those items into a component.
+
+Create a new file at `./sparkleformation/components/base.rb`
+
+#### Component sparkles AWS
+
+~~~ruby
+SparkleFormation.component(:base) do
+  AWSTemplateFormatVersion '2010-09-09'
+  description 'Sparkle Guide Compute Template'
+end
+~~~
+
+#### Component sparkles HEAT
+
+~~~ruby
+SparkleFormation.component(:base) do
+  heat_template_version '2015-04-30'
+  description 'Sparkle Guide Compute Template'
+end
+~~~
+
+#### Component sparkles Azure
+
+~~~ruby
+SparkleFormation.component(:base) do
+  set!('$schema', 'https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#')
+  content_version '1.0.0.0'
+end
+~~~
+
+_NOTE: For more information see: [Component building blocks](../sparkle_formation/building-blocks.html#components)_
+
+### Dynamic
+
+Dynamics are items which can be used multiple times within a template. A dynamic requires a custom name be provided
+and allows for an optional Hash of values. Dynamics are useful for injecting a common structure into a template
+multiple times. In the `compute` template above, we can now extract the remainder of the template and convert it
+into a dynamic.
+
+Create a new file at `./sparkleformation/dynamics/node.rb`
+
+#### Dynamic sparkles AWS
+
+~~~ruby
+SparkleFormation.dynamic(:node) do |name, opts={}|
+
+  parameters do
+    set!("#{name}_image_id".to_sym).type 'String'
+    set!("#{name}_ssh_key_name".to_sym).type 'String'
+    set!("#{name}_flavor".to_sym) do
+      type 'String'
+      default 'm1.small'
+      allowed_values registry!(:instance_flavor)
+    end
+  end
+
+  outputs.set!("#{name}_public_address".to_sym) do
+    description "Compute instance public address - #{name}"
+    value attr!("#{name}_ec2_instance".to_sym, :public_ip)
+  end
+
+  dynamic!(:ec2_instance, name) do
+    properties do
+      image_id ref!("#{name}_image_id".to_sym)
+      instance_type ref!("#{name}_flavor".to_sym)
+      key_name ref!("#{name}_ssh_key_name".to_sym)
+    end
+  end
+
+end
+~~~
+
+#### Dynamic sparkles HEAT
+
+~~~ruby
+SparkleFormation.dynamic(:node) do |name, opts={}|
+
+  parameters do
+    set!("#{name}_image_id".to_sym).type 'String'
+    set!("#{name}_ssh_key_name".to_sym).type 'String'
+    set!("#{name}_flavor".to_sym) do
+      type 'String'
+      default 'm1.small'
+      allowed_values registry!(:instance_flavor)
+    end
+  end
+
+  outputs.set!("#{name}_public_address".to_sym) do
+    description "Compute instance public address - #{name}"
+    value attr!("#{name}_nova_server".to_sym, 'accessIPv4')
+  end
+
+  dynamic!(:nova_server, name) do
+    properties do
+      image ref!("#{name}_image_id".to_sym)
+      flavor ref!("#{name}_flavor".to_sym)
+      key_name ref!("#{name}_ssh_key_name".to_sym)
+    end
+  end
+
+end
+~~~
+
+#### Dynamic sparkles Azure
+
+~~~~ruby
+SparkleFormation.dynamic(:node) do |name, opts={}|
+  parameters do
+    set!("#{name}_image_id".to_sym) do
+      type 'string'
+      default_value '14.04.2-LTS'
+    end
+    set!("#{name}_flavor".to_sym) do
+      type 'string'
+      allowed_values registry!(:instance_flavor)
+    end
+  end
+
+  dynamic!(:network_public_ip_addresses, name) do
+    properties do
+      set!('publicIPAllocationMethod', 'Dynamic')
+      dns_settings.domain_name_label name
+    end
+  end
+
+  dynamic!(:network_interfaces, name) do
+    properties.ip_configurations array!(
+      ->{
+        name 'ipconfig1'
+        properties do
+          set!('privateIPAllocationMethod', 'Dynamic')
+          set!('publicIPAddress').id resource_id!("#{name}_network_public_ip_addresses".to_sym)
+          subnet.id concat!(resource_id!("#{name}_network_virtual_networks".to_sym), '/subnets/sparkle-subnet')
+        end
+      }
+    )
+  end
+
+  dynamic!(:compute_virtual_machines, name) do
+    properties do
+      hardware_profile.vm_size parameters!("#{name}_flavor".to_sym)
+      os_profile do
+        computer_name 'sparkle'
+        admin_username 'sparkle'
+        admin_password 'SparkleFormation2016'
+      end
+      storage_profile do
+        image_reference do
+          publisher 'Canonical'
+          offer 'UbuntuServer'
+          sku parameters!("#{name}_image_id".to_sym)
+          version 'latest'
+        end
+        os_disk do
+          name 'osdisk'
+          vhd.uri concat!('http://', parameters!(:storage_account_name), '.blob.core.windows.net/', parameters!(:storage_container_name), "/#{name}.vhd")
+          caching 'ReadWrite'
+          create_option 'FromImage'
+        end
+        data_disks array!(
+          ->{
+            name 'datadisk1'
+            set!('diskSizeGB', 100)
+            lun 0
+            vhd.uri concat!('http://', parameters!(:storage_account_name), '.blob.core.windows.net/', parameters!(:storage_container_name), "/#{name}-data.vhd")
+            create_option 'Empty'
+          }
+        )
+      end
+      network_profile.network_interfaces array!(
+        ->{ id resource_id!("#{name}_network_interfaces".to_sym) }
+      )
+    end
+  end
+
+  outputs.set!("#{name}_public_address".to_sym) do
+    type 'string'
+    value reference!("#{name}_network_public_ip_addresses".to_sym).ipAddress
+  end
+end
+~~~~
+
+The first thing to note about this dynamic file is the `name` argument at the top.
+
+`SparkleFormation.dynamic(:node) do |name, opts={}|`
+
+This variable is used throughout the dynamic to provide uniquely named parameters, resources, and outputs. Also
+note the use of they registry to define the allowed values for the flavor parameter.
+
+`allowed_values registry!(:instance_flavor)`
+
+_NOTE: For more information see: [Dynamic building blocks](../sparkle_formation/building-blocks.html#dynamics)_
+
+### Template
+
+Now that the original template has been refactored into re-usable parts, lets update our `./sparkleformation/compute.rb`
+template:
+
+#### Template sparkles AWS
+
+~~~ruby
+SparkleFormation.new(:compute, :provider => :aws).load(:base).overrides do
+  dynamic!(:node, :sparkle)
+end
+~~~
+
+#### Template sparkles HEAT
+
+~~~ruby
+SparkleFormation.new(:compute, :provider => :heat).load(:base).overrides do
+  dynamic!(:node, :sparkle)
+end
+~~~
+
+#### Template sparkles Azure
+
+~~~ruby
+SparkleFormation.new(:compute, :provider => :azure).load(:base).overrides do
+  parameters do
+    storage_account_name.type 'string'
+    storage_container_name.type 'string'
+  end
+
+  dynamic!(:network_virtual_networks, :sparkle) do
+    properties do
+      address_space.address_prefixes ['10.0.0.0/16']
+      subnets array!(
+        ->{
+          name 'sparkle-subnet'
+          properties.address_prefix '10.0.0.0/24'
+        }
+      )
+    end
+  end
+
+  dynamic!(:node, :sparkle)
+end
+~~~
+
+The template is now greatly compacted, and composed entirely of re-usable parts. The `.load(:base)` is inserting
+the base component we defined above. The `dynamic!(:node, :sparkle)` is inserting the node dynamic we defined
+above and using the custom name `sparkle`. We can print this template, and see the result is the same as the original
+template.
+
+~~~
+$ sfn print --file compute
+~~~
+
+## Stack update
+
+### The NO-OP update
+
+We can verify that our new template is the same as our original template by updating the running stack and applying
+our new template:
+
+~~~
+$ sfn update sparkle-guide-compute --file compute --defaults
+~~~
+
+The `--defaults` flag will suppress prompts for stack parameters and use the existing values defined for the running
+stack. The result of this command will either explicitly state that no updates were performed, or the event stream
+will show that no resources were modified depending on the provider.
+
+### The real update (parameters)
+
+Now lets update the stack by modifying the paramters of the running stack. We will change the flavor of the instance
+which will result in the resource being replaced within the stack. Run the update command but do not provide any
+flags:
+
+~~~
+$ sfn update sparkle-guide-compute
+~~~
+
+Now `sfn` will prompt for parameter values. Notice that the default values are the values used when creating the
+stack. When the `sparkle_flavor` parameter is prompted, choose a different value from the allowed list. After the
+update has completed, the outputs displayed of the stack will have changed showing a new public address for the
+compute instance.
+
+### The real update (template)
+
+Since our template has been refactored and is now composed of re-usable parts, it's easy to quickly expand our stack.
+Lets add an additional compute resource to our `./sparkleformation/compute.rb` template:
+
+#### Template sparkles AWS
+
+~~~ruby
+SparkleFormation.new(:compute, :provider => :aws).load(:base).overrides do
+  dynamic!(:node, :sparkle)
+  dynamic!(:node, :unicorn)
+end
+~~~
+
+#### Template sparkles HEAT
+
+~~~ruby
+SparkleFormation.new(:compute, :provider => :heat).load(:base).overrides do
+  dynamic!(:node, :sparkle)
+  dynamic!(:node, :unicorn)
+end
+~~~
+
+#### Template sparkles Azure
+
+~~~ruby
+SparkleFormation.new(:compute, :provider => :azure).load(:base).overrides do
+  parameters do
+    storage_account_name.type 'string'
+    storage_container_name.type 'string'
+  end
+
+  dynamic!(:network_virtual_networks, :sparkle) do
+    properties do
+      address_space.address_prefixes ['10.0.0.0/16']
+      subnets array!(
+        ->{
+          name 'sparkle-subnet'
+          properties.address_prefix '10.0.0.0/24'
+        }
+      )
+    end
+  end
+
+  dynamic!(:node, :sparkle)
+  dynamic!(:node, :unicorn)
+end
+~~~
+
+
+Printing the template we can see that by adding a single line we have added not only a new resource to our template,
+but a new output as well.
+
+~~~
+$ sfn print --file compute
+~~~
+
+Now we can apply this updated template to our existing stack. On this update command, we _must_ provide the `--file`
+flag so our modified template will be sent in our request:
+
+~~~
+$ sfn update sparkle-guide-compute --file compute
+~~~
+
+When `sfn` prompts for parameters, the previously seen `sparkle` parameters will be requested, but we will also
+see new `unicorn` parameters requested for the new compute resource we added. After the update has completed the
+stack outputs will be displayed and will now include two public addresses: one for `sparkle` and one for `unicorn`.
+
+## Stack information
+
+With stacks currently existing on the remote provider, we can now use the inspection commands:
+
+~~~
+$ sfn list
+~~~
+
+Will provide a list of current stacks. This may include only the `sparkle-guide-compute` stack or it may include
+other stacks that were created by other users or the provider itself.
+
+We can also describe a specific stack. The describe command will list all the resources composing the requested
+stack, as well as any stack outputs defined for the stack:
+
+~~~
+$ sfn describe sparkle-guide-compute
+~~~
+
+## Clean up
+
+To conclude this guide, we want to be sure to remove the example stack we created. This is done using the
+destroy command:
+
+~~~
+$ sfn destroy sparkle-guide-compute
+~~~

data/sparkle-guides.gemspec

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sparkle-guides
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - Chris Roberts
@@ -18,6 +18,8 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - README.md
+- docs/apply-and-nested.md
+- docs/getting-started.md
 - sparkle-guides.gemspec
 homepage: http://github.com/sparkleformation/sparkle-guides
 licenses: