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 inkey
are not expanded, only those invalue
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 }}
inhelp
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).