6.13. Template

Template documents can contain one or more placeholder entries which are replaced when Clara Deploy SDK loads the document during pipeline job creation.

When a template is loaded by Clara Deploy SDK, it is merged with a provided set of key-value pairs (arguments), and resolved. Once resolved, template placeholders will be replaced by provided arguments values. Any remaining placeholders are replaced with the default value provided by sub-properties of the document’s parameters property.

Any arguments passed to Clara Deploy SDK which have names which do not match names of the document’s parameters property are illegal, and will be rejected by Clara Deploy SDK.

The template type is derived from the document type, and therefore has all of the properties of document.

6.13.1. Properties

6.13.1.1. parameters

type: object

Set of name-value pairs, represented as YAML properties. Where the name of the property is the name of the pair; and the value of the property is the value of the pair.

Notice: parameter properties are expected to be string values. Use of non-string values is undefined.

6.13.1.2. Example:

parameters:
  ## Declares ${{ template-parameter-1 }} placeholders can be used in the document.
  ## When the document is loaded, an no argument for template-parameter-1 is passed in
  ## the default value of "Some value" will be used.
  template-parameter-1: Some value
  ## Declares ${{ another-template-param }} placeholders can be used in the document.
  ## When the document is loaded, an no argument for another-template-param is passed in
  ## the default value of "Another value" will be used.
  another-template-param: Another value

6.13.2. Placeholders

Template placeholders take the form of ${{ followed by a name (remember, names have restrictions on the values they can have), followed by }}.

Let’s take a look at an example:

parameters:
  ## Declares ${{ input-from }} placeholders can be used in the document.
  ## When the document is loaded, an no argument for input-from is passed in
  ## the default value of "" will be used.
  input-from:
  ## Declares ${{ input-name }} placeholders can be used in the document.
  ## When the document is loaded, an no argument for input-name is passed in
  ## the default value of "" will be used.
  input-name:

name: templated-example
container:
  image: clara/examples/centos
input:
  - from: ${{ input-from }}
    name: ${{ input-name }}
    path: /in

Above is an example of an operator definition using templates. You can see that the template accepts arguments for two parameters: input-from and input-name. If values are not passed to the template when the definition is loaded, the default values will be used. Regardless of the presence or absence of arguments being passed to the template loader, the template is always resolved by Clara Deploy SDK when loaded.

In this example, the operator’s input property takes template arguments for its from and name properties. This is a powerful way to make operator definitions reusable by multiple pipelines.