Templates

Use Templates to transform Parameter and Secret values into any format.

Templates allow parameters and secrets to be transformed into semi-structured or unstructured data formats.

Templates are scoped to projects only and do not require a particular environment.

For added value, the Liquid Template Language can be used to dynamically generate template bodies.

Templates are useful for pulling in semi-structured data into an application via our CloudTruth CLI, the Kubernetes Kubetruth operator, or one of our many Integration options


Creating a Template

Here are some sample templates for JSON, YAML, ConfigMaps, TFVars and dotenv.

Since templates are scoped to projects, be sure to select the target project where the template will be used via the global project selector

  1. Select Create Template from the global Project and Environment action menu at the top of the page to open the CREATE NEW TEMPLATE dialog:

  • TEMPLATE NAME - The reference name of the template used for retrieval

  • DESCRIPTION - Further describe the template's purpose (optional)

  1. Fill out the form with the appropriate information:

  1. Submit the form to create the json template within the targeted project:

  1. This will expose the template editor, from here we can edit, preview, and submit the template:

  1. In this example, we are using a Liquid script to structure the parameters and their values into the JSON format (note the Draft status on the left next to the template's name)

Along with Liquid, CloudTruth provides several helper methods to retrieve various CloudTruth Application values to enhance the templating experience. See the Automatic Parameters section below for the available parameters and descriptions.

  1. At this point, clicking Preview will generate the template's output for the selected environment, which is default:

On Preview, if any of the referenced parameters where created as a secret parameter, the entire template body will be masked as a protective measure. Clicking Show Secrets will reveal the entire template body.

  1. Provided there were no errors in the template during preview, clicking Submit will save the template.

Editing a Template

Once a template has been submitted and saved, editing a template is as easy as clicking the Edit Template button and using the same process to edit, preview, and submit the changes as we did in the Create process above.

Deleting a Template

  1. To delete a template, click the action menu in the template detail view and select Delete:

  1. Simply confirm and the template will deleted.


Automatic Parameters

In addition to your parameters, CloudTruth adds several automatic parameters that can be referenced in templates:

cloudtruth.self

The name of the current template.

cloudtruth.project

The name of the current project.

cloudtruth.environment

The name of the current environment.

cloudtruth.environment.children

returns a list of the current environment's children

cloudtruth.templates.<name>

evaluates template <name> against the current environment and includes its contents in this template.

cloudtruth.parameters.<name>

Another way to reference the parameter <name>.

cloudtruth.projects.<name>

A reference to another project. See below for more on referencing parameters and templates in other projects.

Parameter Attributes

All parameters automatically include attributes to allow retrieving attributes of that parameter. For example, to see the ID of your current project, use cloudtruth.project.id. These attributes are derived from the API and match the meaning in the API. The full list of available attributes is:

AttributeApplies ToDescription

id

All objects

The ID of the object.

name

All objects

The name of the object.

description

All objects

The description of the object.

parent

Environments

The parent Environment of the current Environment.

depends_on

Projects

Project that the specified project depends on.

value

Parameters and Templates

The value of the object.

secret

Parameters and Templates

If True, the object is a secret.

type

Parameters and Templates (including cloudtruth.self)

The type of the object.

CloudTruth Filters

In addition to the usual filters Liquid provides, CloudTruth adds a few new ones for you:

Custom FilterDescription

dns_safe

Ensures the value is safe for use as a DNS name or Kubernetes resources name.

env_safe

Ensures the value is safe for setting as shell environment variable.

key_safe

Ensures the value is safe for use as a key inside the Kubernetes ConfigMap/Secret data hash.

indent: count

Indents each line in the value by count spaces.

nindent: count

Adds a leading newline, then indents each line in the value by count spaces.

parse_yaml

Parses a YAML string into a structured representation.

to_yaml

Converts an object to a YAML representation.

parse_json

Parses a JSON string into a structured representation.

to_json

Converts an object to a JSON representation.

encode64

Base64 encodes a value.

decode64

Base64 decodes a value.

sha256

Takes the sha256 digest of a value.

merge: other

Merges the other hash value into this one.

re_replace: pat, repl, flags

Regular expression replaces pattern pat in the value with replacement repl, with optional flags "i" for ignore case, "m" for multiline and "x" for extended.

re_contains: pat, flags

Returns a boolean indicating whether the pattern pat is found in the value, with optional flags as re_replace.

names

Given a dictionary of parameters (e.g. cloudtruth.parameters), return a list of parameter names.

values

Given a dictionary of parameters, return a list of parameter values. Note that parameter attributes are still available to objects in this list.

Guidelines

Circular references

CloudTruth will prevent creating a circular reference between templates, for example:

  • Template A references template B

  • Template B references templates C

  • Template C references template A

Should a template result in a circular reference, CloudTruth will display an error and display the erroring circular reference.

Parameters with non-conventional names

CloudTruth does not restrict parameter names, but Liquid follows the traditional identifier naming conventions: alphanumerics and underscores only. If the need to reference a parameter with non-conventional characters arises, use the following guidelines:

e.g. Referencing a parameter with special characters:

{{ My.Non Traditional Parameter Name! }}

Needs to be:

{{ cloudtruth.parameters["My.Non Traditional Parameter Name!"] }}

This notation can be used for any reference, conventional or non-conventional, for example:

cloudtruth.parameters["conventional_template_name"]

Parameters and Templates from Other Projects

By default, all parameters and templates are referenced from the current project.

However, referencing a parameter or template from another project requires referencing the targeted project the parameter or template is associated first:

Parameter:

{{ cloudtruth.projects.<other_proj_name>.parameters.<param_name> }}

Template:

{{ cloudtruth.projects.<other_proj_name>.templates.<template_name> }}

Template History

You can view the history of raw project templates in the history page. Selecting Templates will bring up a template list for your specified project.

Template History by Tag

You can select an environment tag to compare the project's current templates to and click Apply.

The table now displays a dropdown to show any differences in the templates for the current time compared to the templates content at the selected tag. Selecting the dropdown will bring up a side-by-side view of the template with highlighted differences.

History by date

You can select a date and approximate time to compare the project's current templates to and click Apply.

The table now displays a dropdown to show any differences in the templates for the current time compared to the templates content at the selected time. Selecting the dropdown will bring up a side by side view of the template with highlighted differences.

Last updated

CopyrightΒ© 2023 CloudTruth