Skip to main content

Templates

Sandboxes, RouteGroups, and ResourcePlugins support yaml and json templating which allows substituting values provided in the spec files with values specified on the command line or in other files.

Templating helps with CI automation where some values come from the environment and it also helps with spec organisation, such as allowing a script to be edited in a file with extension .sh while having it automatically embedded into the spec.

A template file is a yaml file with template directives in strings. A template directive takes the form @{<value-spec>}.

A value spec specifies something to put in place of the template directive, which may be a variable reference or an embedding:

<value-spec> ::= <variable-ref> | <embedding>

Variables​

A variable in a template directive takes the form @{<variable>} and can occur in any string literal. For example

name: "@{dev}-@{team}-feature"
city: "@{city}"

A variable must match the regular expression ^[a-zA-Z][a-zA-Z0-9._-]*$.

Variable values are then supplied on the command line in the form --set <variable>=<value>. For example

signadot sandbox apply -f SANDBOX_FILE --set dev=jane --set team=plumbers

If a variable reference occurs in a sandbox file and no value for that variable is provided, then an error is flagged and the operation is aborted.

Embeddings​

An embedding takes the form @{embed: <file>}. <file> is a path to another file. Relative paths are interpreted relative to the directory in which the template file lives, or relative to the current working directory if the template file is stdin.

The contents of <file> are then placed in the string in the resulting document. For example, with template

name: "@{embed: name.txt}"

and if name.txt contains

Jane
Plumb

Then the expanded file would be

name: "Jane\nPlumb"

Perhaps rendered to yaml as

name: |
  Jane
  Plumb

Expansion Encodings​

Both variable references and embeddings can be expanded in a few different ways.

By default, the value of a variable or the contents of a file are simply placed in the string in which the directive occurs. This replacement occurs by means of operations on the yaml/json string in which the directive occurs, rather than by means of operations on the containing document, so there is no problem with quoting or indentation. This expansion encoding is called a raw expansion encoding and it is the default.

Alternative expansion encodings can be specified for variables or embeddings by appending [<encoding>] to the variable name or the operation. raw, yaml, and binary expansion encodings are supported.

Expansion encodings other than raw cannot occur properly within a string, nor can one have multiple template directives in one string when one of them is a non-raw expansion encoding.

Below are examples of the input and output of raw, yaml, and binary expansion encodings.

For example:

# illegal template
name: " @{embed[yaml]: file.yaml}"
#      ^ (contains a space outside the directive)
---
# ok embedding, nothing outside the directive
name: "@{embed[yaml]: file.yaml}"

raw expansion encoding​

# both dev and team are expanded with the raw expansion encoding,
# which is just string interpolation.
name: "@{dev[raw]}-@{team}"
---
# output
name: "jane-plumbers"

yaml expansion encoding​

# the value of the field 'podTemplate' will be the full yaml (not a string)
# defined by the contents of pod-template.yaml 
podTemplate: "@{embed[yaml]: pod-template.yaml}"
---
# output
podTemplate:
  spec:
    containers:

raw expansion encoding of yaml​

# the value of the field 'podTemplateString' will be a string containing
# yaml defined by the contents of pod-template.yaml
podTemplateString: "@{embed[raw]: pod-template.yaml}"
---
# output
podTemplateString: |
  spec:
    containers:

yaml expansion encoding of a port number​

# with --set port=123, port will be a yaml number
port: "@{port[yaml]}"
---
# output
port: 123

binary expansion encoding​

# with --set data="$(dd if=/dev/urandom count=1)"
data: "@{data[binary]}"
--- 
# output
data: "mj3cLyX8B5yiL0S9jOm2WKapDD8a56WyJW0nyg7ufiL8w8KZ4mEM0z7eCnBAlqBuDpJPjIwy7Am3X5yQSv7MHZK0Ui+QRCL0D53blHAcFS8WV9bZSRkTBtBAyaeF0tH0HLRKPyXuJPDoZC1NmQIPdsW/el5gmf9nXjtYegjd8oNiN4bayDULXEOjeYkKNyVGGCvCn6TAQ3UeCmfckIcad7Ek1Vvm4EETDF4OFAL6hsYBujeZXdjn/vIquWtMWCq8iVPlLJQ0sMyzCCsNJvx170RSNF6/xh7zeI+RsfFBD/b71Kg0GdFz8zSOSSxsRZqAZBZGdUmYmJvQOyhYOq5Z9sumwSnqgBHjP3gnUaVS4jyaQuhcJJoLlTwHTd6X0WLPknctDGZWCLMd10XVLvKJoPEL99GDhWKyDpXwB2PNNWtZBa8UGrr6YYRsrttlgFkKd/tcSc/zYc8rjsdWARBPSvntSAzKPy459niet+OtpW8SpBuykmT60OZdRUYkntdEvmn7YP88e4aQxT3hZJx+qQGaJUT00w/MdtPL9JUZ63LVKvyDzCf3FGEtDipZZemveNQmyzTg/3mAIBHljS7QZdzeZtZ4ITh+Nxjm30I/Hedkd1qrPBZtoTqMgyVtXYCU+HVLMbiDLUj/9Jc0XL8VHwQoaCJ9M/V+ORZYSOdlDYY="