SparkleFormation: Template Anatomy

Template Anatomy

The anatomy of a template is dependent on the specific implementation that is targeted. Due to the freeform nature of the SparkleFormation DSL any orchestration API accepting a serialized document to describe resources is inherently supported. Due to that fact, this document will focus directly on the AWS CloudFormation style template as it is the most widely implemented.

Base Attributes

All templates must begin with the expected API version and may include a description and or metadata:

SparkleFormation.new(:template) do
  set!('AWSTemplateFormatVersion', '2010-09-09')
  description 'My New Stack'
  metadata.instances.description 'Awesome instances'
end

Parameters

Parameters are named variables available within the template that users may provide customized values when creating or updating a stack. This allows “runtime” modifications to occur when the template is evaluated by the API.

SparkleFormation.new(:template) do
  parameters do
    creator do
      type 'String'
      default ENV['USER']
    end
  end
end

Parameters

Mappings

Mappings are a nested key/value store. They provide an easy way to dynamically specify what value should be used based on context available when the template is evaluated by the API.

SparkleFormation.new(:template) do
  mappings.platforms.set!('us-west-2'._no_hump) do
    centos6 'ami-b6bdde86'
    centos7 'ami-c7d092f7'
  end
end

These can then be referenced using the map! helper method:

SparkleFormation.new(:template) do
  dynamic!(:ec2_instance, :foobar) do
    properties.image_id map!(:platforms, region!, :centos7)
  end
end

Conditions

Named conditions are defined in this section and then referenced elsewhere in the template. Conditions can be used to customize resource properties values or to allow/restrict the creation of resources and outputs.

SparkleFormation.new(:template) do
  parameters.creator do
    type 'String'
    default 'spox'
  end
  conditions do
    creator_is_spox equals!(ref!(:creator), 'spox')
  end
end

This condition can then be used to provide a custom value for a property:

SparkleFormation.new(:template) do
  parameters.creator do
    type 'String'
    default 'spox'
  end
  conditions do
    creator_is_spox equals!(ref!(:creator), 'spox')
  end
  dynamic!(:ec2_instance, :fubar).properties do
    key_name if!(:creator_is_spox, 'spox-key', 'default')
  end
end

The condition can also be used to restrict the creation of a resource:

SparkleFormation.new(:template) do
  parameters.creator do
    type 'String'
    default 'spox'
  end
  conditions do
    creator_is_spox equals!(ref!(:creator), 'spox')
  end
  dynamic!(:ec2_instance, :fubar) do
    on_condition! :creator_is_spox
  end
end

Resources

Resources are the infrastructure items and configurations to be provisioned by the orchestration API:

SparkleFormation.new(:template) do
  resources.my_instance do
    type 'AWS::EC2::Instance'
    properties do
      key_name 'default'
      ...
    end
  end
end

Resources

Outputs

Outputs are resultant values from the provisioned infrastructure stack. It generally contains information about specific resource attributes.

SparkleFormation.new(:template) do
  outputs do
    instance_address do
      description 'Public IP of my instance'
      value attr!(:my_instance, :public_ip)
    end
  end
end

Conditions can also be applied on outputs:

SparkleFormation.new(:template) do
  outputs do
    instance_address do
      description 'Public IP of my instance'
      value attr!(:my_instance, :public_ip)
      on_condition! :my_condition
    end
  end
end

Outputs