Skip to main content

About Template Functions

This topic describes Replicated KOTS template functions, including information about use cases, template function contexts, syntax.

Overview

For standard Kubernetes manifests deployed with Replicated KOTS, Replicated provides a set of custom template functions based on the Go text/template library.

Common use cases for KOTS template functions include rendering values that are specific to the customer environment during installation or upgrade, such as:

  • Customer license field values
  • User-provided configuration values
  • Information about the customer environment, such the number of nodes or the Kubernetes version in the cluster where the application is installed

KOTS template functions are also useful for rendering values that are not specific to the customer environment, such as:

  • Generating random strings
  • Performing mathematical operations
  • Converting a string to lowercase or uppercase

All functionality of the Go templating language, including if statements, loops, and variables, is supported with KOTS template functions. For more information about the Go library, see text/template in the Go documentation.

Supported File Types

You can use KOTS template functions in any Kubernetes manifest files for applications deployed by KOTS, such as:

  • Custom resources in the kots.io API group like Application, Config, or HelmChart
    note

    Not all fields in the Config custom resource support templating. For more information, see Item Properties in Config.

  • Custom resources in other API groups like Preflight, SupportBundle, or Backup
  • Kubernetes objects like Deployments, Services, Secrets, or ConfigMaps
  • Kubernetes Operators

Helm Charts

KOTS template functions are not directly supported in Helm charts. However, the HelmChart custom resource provides a way to map values rendered by KOTS template functions to Helm chart values. This allows you to use KOTS template functions with Helm charts without making changes to those Helm charts.

For information about how to map values from the HelmChart custom resource to Helm chart values.yaml files, see Manipulating Helm Chart Values with KOTS.

Template Function Rendering

During application installation and upgrade, KOTS templates all Kubernetes manifest files in a release (except for the Config custom resource) at the same time during a single process. For the Config custom resource, KOTS templates each array of items separately. For information about the syntax of items in the Config custom resource, see items in Config.

Within valid YAML that is templated at the same time, you can use Go to assign a template function to a variable for the purpose of accessing the rendered value from another template function. For an example of using Go variables with KOTS template functions to generate and then access values, see Example: Using Variables to Generate TLS Certificates and Keys.

Syntax

You can include KOTS template functions in manifest files as strings, using the syntax described in this section.

The KOTS template function syntax supports the following functionally equivalent delimiters:

  • '{{repl ... }}': This syntax includes quotation marks to be valid YAML and renders a string value.
  • repl{{ ... }}: This syntax renders an integer value.

'{{repl ... }}'

Syntax
'{{repl ... }}'
Description

This syntax is wrapped in quotes because {{ is not a valid beginning for a string in YAML. To use a template function with this syntax as a value in a YAML file, you must wrap it in quotation marks.

This syntax renders string values. Do not use this syntax if the Kubernetes API field requires an integer value.

Example
env:
- name: MAX_CONCURRENT_USERS
value: '{{repl LicenseFieldValue "max_concurrent_users"}}'

The template function above renders as a string. For example:

env:
- name: MAX_CONCURRENT_USERS
value: '100'

repl{{ ... }}

Syntax
repl{{ ... }}
Description

This syntax uses the delimiter after repl, and does not require quotation marks. Use this syntax to render integer values.

Example
replicas: repl{{ ConfigOption "replicas" }}

The template function above renders as an integer. For example:

replicas: 5

Contexts

KOTS template functions are grouped into different contexts, depending on the phase of the application lifecycle when the function is available and the context of the data that is provided.

Static Context

You can use template functions in the static context in any manifest file at any time.

The static context also includes the Masterminds Sprig function library. For more information, see Sprig Function Documentation on the sprig website.

For a list of all KOTS template functions available in the static context, see Static context.

Config Context

Template functions in the config context are available when rendering an application that includes a Config custom resource. At execution time, template functions in the config context also can use the static context functions.

For a list of all KOTS template functions available in the config context, see Config context.

License Context

Template functions in the license context have access to customer license and version data.

For a list of all KOTS template functions available in the license context, see License context.

kURL Context

Template functions in the kURL context have access to information about applications installed in embedded clusters created by Replicated kURL.

For a list of all KOTS template functions available in the kURL context, see kURL context.

Identity Context

Template functions in the Identity context have access to Replicated identity service information.

For a list of all KOTS template functions available in the identity context, see Identity context.