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 Kubernetes manifest files for applications deployed by 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 during installation or upgrade, such as:

  • Customer-specific 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
  • Random strings

KOTS template functions can also be used to work with integer, boolean, float, and string values, such as doing mathematical operations, trimming leading and trailing spaces, or converting string values to integers or booleans.

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 Kubernetes manifest files for applications deployed by KOTS, such as:

  • Custom resources in the kots.io API group like Application, Config, or HelmChart
  • Custom resources in other API groups like Preflight, SupportBundle, or Backup
  • Kubernetes objects like Deployments, Services, Secrets, or ConfigMaps
  • Kubernetes Operators

Limitations​

  • Not all fields in the Config and Application custom resources support templating. For more information, see Application and Item Properties in Config.

  • Templating is not supported in the Embedded Cluster Config resource.

  • KOTS template functions are not directly supported in Helm charts. For more information, see Helm Charts below.

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 Setting 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 item separately so that config items can be used in templates for other items. For examples of this, see Using Conditional Statements in Configuration Fields and Template Function Examples.

Syntax​

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

Syntax Requirements​

KOTS template function syntax has the following requirements:

  • In both the repl{{ ... }} and {{repl ... }} syntaxes, there must be no whitespace between repl and the {{ delimiter.
  • The manifests where KOTS template functions are used must be valid YAML. This is because the YAML manifests are linted before KOTS template functions are rendered.

repl{{ ... }}​

This syntax is recommended for most use cases.

Any quotation marks wrapped around this syntax are stripped during rendering. If you need the rendered value to be quoted, you can pipe into quote (| quote) or use the {{repl ... }} syntax instead.

Integer Example​

http:
  port: repl{{ ConfigOption "load_balancer_port" }}
http:
  port: 8888

Example with | quote​

customTag: repl{{ ConfigOption "tag" | quote }}
customTag: 'key: value'

If-Else Example​

http:
  port: repl{{ if ConfigOptionEquals "ingress_type" "load_balancer" }}repl{{ ConfigOption "load_balancer_port" }}repl{{ else }}8081repl{{ end }}
http:
  port: 8081

For more examples, see Template Function Examples.

{{repl ... }}​

This syntax can be useful when having the delimiters outside the template function improves readability of the YAML, such as in multi-line statements or if-else statements.

To use this syntax at the beginning of a value in YAML, it must be wrapped in quotes because you cannot start a YAML value with the { character and manifests consumed by KOTS must be valid YAML. When this syntax is wrapped in quotes, the rendered value is also wrapped in quotes.

Example With Quotes​

The following example is wrapped in quotes because it is used at the beginning of a statement in YAML:

customTag: '{{repl ConfigOption "tag" }}'
customTag: 'key: value'

If-Else Example​

my-service:
  type: '{{repl if ConfigOptionEquals "ingress_type" "load_balancer" }}LoadBalancer{{repl else }}ClusterIP{{repl end }}'
my-service:
  type: 'LoadBalancer'

For more examples, see Template Function Examples.

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​

The context necessary to render the static template functions is always available.

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.