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 HelmChartnoteNot 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 |
|
---|---|
Description | This syntax is wrapped in quotes because This syntax renders string values. Do not use this syntax if the Kubernetes API field requires an integer value. |
Example |
The template function above renders as a string. For example:
|
repl{{ ... }}
Syntax |
|
---|---|
Description | This syntax uses the delimiter after |
Example |
The template function above renders as an integer. For example:
|
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.