Spec Expansion

Note: This feature has been experimental since version 0.16 (and called “Recursive Rendering”). It has been changed in 0.20 and declared stable since that version.

Spec expansion is a concept similar to macros, perhaps aimed at obsoleting it altogether one day. For now, both of these live side by side.

The idea behind spec expansion is simple:

• Spec values can contain references to other spec or config values.

• A mechanism that runs right before template is rendered traverses the spec and expands and re-expands these values.

• The spec is expanded in a loop that ends when either:

  • No value has changed in last iteration.

  • Maximum allowed amount of iterations has been reached. This can be changed by passing --max-passes X on commandline. See Commandline Usage for more information.

• Note that for yaml mappings (e.g. key: value) references in key are not expanded, only those in value are.

Example

Let’s consider the following spec:

name: "myname"
help: "This is a help for {{ config.os.id }}/{{ spec.myname }} image."

Let’s try rendering a very simple template that looks like this:

{{ spec.help }}

• In the first expansion pass of spec, {{ config.os.id }} and {{ spec.myname }} in help value will get substitued.

• The second expansion pass will find out that there are no changes and will end spec expansion (so 2 passes are necessary).