# Templates

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](https://shopify.github.io/liquid/) can be used to dynamically generate template bodies.

Templates are useful for pulling in semi-structured data into an application via our [CloudTruth CLI](https://docs.cloudtruth.com/configuration-management/cli-and-api/cloudtruth-cli), the [Kubernetes Kubetruth operator](https://docs.cloudtruth.com/configuration-management/integrations/kubernetes), or one of our many [Integration options](https://docs.cloudtruth.com/configuration-management/integrations)

***

## Creating a Template

{% hint style="info" %}
Here are some [sample templates](https://docs.cloudtruth.com/configuration-management/using-basic-templates/sample-templates) for JSON, YAML, ConfigMaps, TFVars and dotenv.
{% endhint %}

{% hint style="info" %}
Since templates are scoped to projects, be sure to select the target project where the template will be used via the global project selector
{% endhint %}

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:

<figure><img src="https://2952342643-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MGjN2Xg1mE8iTvg49dw%2Fuploads%2FJ1Ime0nIL7XAjdTqEHCi%2Fimage.png?alt=media&#x26;token=5ae54ed9-4276-48b6-b738-b0a9f522adf7" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2952342643-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MGjN2Xg1mE8iTvg49dw%2Fuploads%2F5PYhbDm0B8nROcViQr3l%2Fimage.png?alt=media&#x26;token=3c442f6f-7b57-414a-985f-f7988032eb26" alt="" width="484"><figcaption></figcaption></figure>

* **TEMPLATE NAME** - The reference name of the template used for retrieval
* **DESCRIPTION** - Further describe the template's purpose (optional)

2. Fill out the form with the appropriate information:

<figure><img src="https://2952342643-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MGjN2Xg1mE8iTvg49dw%2Fuploads%2FJ4DniPA5XWhaBpBrTqA1%2Fimage.png?alt=media&#x26;token=2d23d368-71fc-4e0c-bc6e-74ab6e36b530" alt="" width="485"><figcaption></figcaption></figure>

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

<figure><img src="https://2952342643-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MGjN2Xg1mE8iTvg49dw%2Fuploads%2FsARU4MysFw5B2BLQcfLo%2Fimage.png?alt=media&#x26;token=ac35873b-568f-46f7-8850-98aed6a847f7" alt="" width="563"><figcaption></figcaption></figure>

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

<figure><img src="https://2952342643-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MGjN2Xg1mE8iTvg49dw%2Fuploads%2Fflq44hLRsAKtYXF8G1Gx%2Fimage.png?alt=media&#x26;token=0861d134-3510-46f4-95c3-1bd2eca22ec2" alt="" width="375"><figcaption></figcaption></figure>

5. 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)

{% hint style="info" %}
&#x20;Along with Liquid, CloudTruth provides several helper methods to retrieve various CloudTruth Application values to enhance the templating experience. See the [Automatic Parameters](#automatic-parameters) section below for the available parameters and descriptions.
{% endhint %}

<figure><img src="https://2952342643-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MGjN2Xg1mE8iTvg49dw%2Fuploads%2F4xe8B0WIgtLdHNVXcCz9%2Fimage.png?alt=media&#x26;token=c37a5c45-573d-4248-b2c4-16ee2a188060" alt="" width="375"><figcaption></figcaption></figure>

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

<figure><img src="https://2952342643-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MGjN2Xg1mE8iTvg49dw%2Fuploads%2FYAgNbxTfPaLpIV5KHX97%2Fimage.png?alt=media&#x26;token=a45d46dd-b11d-44ab-8bea-92b0d049b94a" alt="" width="563"><figcaption></figcaption></figure>

{% hint style="info" %}
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.
{% endhint %}

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

<figure><img src="https://2952342643-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MGjN2Xg1mE8iTvg49dw%2Fuploads%2F0tteerCvlnaQpbjd6hp3%2Fimage.png?alt=media&#x26;token=ebcd803a-f2e3-40c1-a246-d209b1ec68eb" alt="" width="563"><figcaption></figcaption></figure>

## 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](#creating-a-template) process above.

## Deleting a Template

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

<figure><img src="https://2952342643-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MGjN2Xg1mE8iTvg49dw%2Fuploads%2FX45HLdbMKXjHMQbCzVzS%2Fimage.png?alt=media&#x26;token=80dd435c-ebc0-4da5-8f2e-5b7ee38951ab" alt="" width="563"><figcaption></figcaption></figure>

2. Simply confirm and the template will deleted.

<figure><img src="https://2952342643-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MGjN2Xg1mE8iTvg49dw%2Fuploads%2FhDB5qoLfpq0fHRJexicj%2Fimage.png?alt=media&#x26;token=5d39cff5-8737-449f-9004-b3d72764a5b5" alt="" width="512"><figcaption></figcaption></figure>

***

## Automatic Parameters

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

<table data-header-hidden data-full-width="false"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><code>cloudtruth.self</code></td><td>The name of the current template.</td></tr><tr><td><code>cloudtruth.project</code></td><td>The name of the current project.</td></tr><tr><td><code>cloudtruth.environment</code></td><td>The name of the current environment.</td></tr><tr><td><code>cloudtruth.environment.children</code></td><td>returns a list of the current environment's children</td></tr><tr><td><code>cloudtruth.templates.&#x3C;name></code></td><td>evaluates template <em>&#x3C;name></em> against the current environment and includes its contents in this template.</td></tr><tr><td><code>cloudtruth.parameters.&#x3C;name></code></td><td>Another way to reference the parameter <em>&#x3C;name></em>.</td></tr><tr><td><code>cloudtruth.projects.&#x3C;name></code></td><td>A reference to another project. See below for more on referencing parameters and templates in other projects.</td></tr></tbody></table>

## 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:

| Attribute   | Applies To                                             | Description                                        |
| ----------- | ------------------------------------------------------ | -------------------------------------------------- |
| 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 Filter                  | Description                                                                                                                                                        |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `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&#x20;

### 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!"] }}`

{% hint style="info" %}
This notation can be used for any reference, conventional or non-conventional, for example:

`cloudtruth.parameters["conventional_template_name"]`
{% endhint %}

### 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:&#x20;

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.

![](https://2952342643-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MGjN2Xg1mE8iTvg49dw%2Fuploads%2Fgit-blob-cc14f1fb749eefb23939a6654a6cf1f9132864c2%2Fimage%20\(220\).png?alt=media)

#### Template History by Tag

You can select an [environment tag](https://docs.cloudtruth.com/environments#tagging) to compare the project's current templates to and click Apply.

![](https://2952342643-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MGjN2Xg1mE8iTvg49dw%2Fuploads%2Fgit-blob-aee69cea298b918736ad280deacf0e9899d4465c%2Fimage%20\(222\).png?alt=media)

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.

![](https://2952342643-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MGjN2Xg1mE8iTvg49dw%2Fuploads%2Fgit-blob-35f60a0c45547dcd76072c9948b2234c655b4456%2Fimage%20\(224\).png?alt=media)

#### History by date

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

![](https://2952342643-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MGjN2Xg1mE8iTvg49dw%2Fuploads%2Fgit-blob-1dea0fb262daa778df85d7876bf8b9bfe591d206%2Fimage%20\(225\).png?alt=media)

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.

![](https://2952342643-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MGjN2Xg1mE8iTvg49dw%2Fuploads%2Fgit-blob-a357b402d8b37a6d557622096359d5b79d30c9d1%2Fimage%20\(226\).png?alt=media)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cloudtruth.com/configuration-management/using-basic-templates.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.