Compile Time Parameters

Compile time parameters are parameters utilized during the compilation of a template. These parameters can only be used via the SparkleFormation library. It is for this reason that compile time parameters are generally discouraged from use. In most situations the structure of the template can be refactored to remove any requirement of compile time parameters. To handle the cases that fall outside of “most situations”, SparkleFormation provides support for compile time parameters.

Usage

Compile time parameters are defined during the instantiation of a template:

SparkleFormation.new(:test,
  :compile_time_parameters => {
    :number_of_nodes => {
      :type => :number,
      :default => 1
    }
  }
) do

  state!(:number_of_nodes).times do |i|
    dynamic!(:ec2_instance, "node_#{i}")
  end

end

Parameter Declaration

Declaring compile time parameters is done via the :compile_time_parameters option when instantiating a new template. This option expects a Hash value in which the keys are parameter names, and their respective values are a Hash defining options for the parameter. The available items within the option Hash for compile time parameters:

Multiple value support

The :multiple option for compile time parameters will automatically convert a received comma-delimited list into an Array of items. Each item in the list must be the expected type for the parameter. For example, a compile time parameter defined as:

SparkleFormation.new(:test,
  :compile_time_parameters => {
    :network_ids => {
      :type => :string,
      :multiple => true
    }
  }
)

If the value provided for this parameter is:

network-a2413, network-cs214, network-as113

The resulting value when accessed will be:

[
  "network-a2413",
  "network-cs214",
  "network-as113"
]

Complex type support

Complex types are supported but should rarely be used. Defining these types of compile time parameters impose restrictions on templates and make them much less flexible. However, there may be cases where providing a complex type to a template is ideal. It is important to note these restrictions:

• No :multiple support
• No user defined input via sfn CLI
• No template serialization

The last restriction is extremely important. Compile time parameters are stored in a template’s outputs. This is done to support template reprocessing and change detection. Complex types are not stored within the template output due to the fragility introduced by the dependency on the complex type to properly serialize itself. The size of the serialization is also a concern which can easily invalidate a template due to size restrictions given a sufficiently complex type.

In general complex types should never be used. Given a situation where complex types may seem like the correct solution, re-evaluate the usage and determine no other solution can be implemented to solve the problem. Compile time parameters already make templates less flexible and complex types increases this rigidity.

Prompting when nested

The :prompt_when_nested is used by implementations to suppress parameter prompts when the template is encountered in a nested context. This allows for parent templates to handle compile time parameters for a nested template, but the nested template still retains its ability to be built in a standalone context.

Accessing Parameter Values

Compile time parameter values can be accessed via the state! method. If a compile time parameter has been defined for a template, and no value has been provided when that template is compiled, state! will raise an ArgumentError. This exception will only be raised on defined compile time parameters, and not other values that may be persisted within the state.

Example usage:

SparkleFormation.new(:test,
  :compile_time_parameters => {
    :number_of_nodes => {
      :type => :number,
      :default => 1
    }
  }
) do

  state!(:number_of_nodes).times do |i|
    dynamic!(:ec2_instance, "node_#{i}")
  end

end

Template Modification

When compile time parameters are present SparkleFormation will automatically adjust the outputs of the template to include a CompileState output. The output will contain a JSON dump of the compile time parameter values used to generate the template. This allows update requests to fetch the previous state and seed the compilation of the updated template. This approach provides consistency and removes any requirement of prior knowledge about how a template was used to build a stack.

Template Nesting

Compile time parameters are local to a given template instance. A parent template can provide compile time parameters when nesting a template. This is done using the :parameters option when nesting:

SparkleFormation.new(:node_generator,
  :parameters => {
    :number_of_nodes => {
      :type => :number,
      :prompt_when_nested => false
    }
  }
) do
  state!(:number_of_nodes).times do |i|
    dynamic!(:ec2_instance, "node_#{i}")
  end

end

SparkleFormation.new(:root) do
  nest!(:nested_template,
    :parameters => {
      :number_of_nodes => 5
    }
  )
end

In this example the :root template is providing the compile time parameter :number_of_nodes explicitly to the :node_generator template. Due to the compile time parameter option :prompt_when_nested being set to false, when the :root template is compiled, no prompt will be received for the :number_of_nodes compile time parameter. However, if the :node_generator template is compiled directly, the prompt will be received.