Skip to main content

About Replicated template functions

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

Overview​

Replicated provides a set of custom template functions based on the Go text/template library.

Common use cases for Replicated 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

Replicated 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.

Replicated template functions support all functionality of the Go templating language, including if statements, loops, and variables. For more information about the Go library, see text/template in the Go documentation.

Supported file types​

You can use Replicated template functions in Kubernetes manifest files, such as:

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

Replicated template functions are not directly supported in Helm charts. However, the HelmChart custom resource provides a way to map values rendered by Replicated template functions to Helm chart values. This allows you to use Replicated 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 values in HelmChart v2.

Template function rendering​

During application installation and upgrade, Replicated templates all Kubernetes manifest files in a release at the same time during a single process.

The Config custom resource is an exception. For the Config custom resource, Replicated templates each item separately. This allows you to use template functions in fields in the Config custom resource that render user-supplied values from other fields. For examples of this, see Template function examples.

Limitations​

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

  • The Embedded Cluster Config resource doesn't support Go templating in any fields.

  • Replicated template functions are not directly supported in Helm charts. For more information, see Supported file types on this page.

  • For installations with Embedded Cluster v3, the following template functions aren't supported:

    • HasLocalRegistry
    • LocalRegistryAddress
    • LocalRegistryHost
    • LocalRegistryNamespace
    • LocalImageName

    These template functions are typically used to conditionally rewrite image references in air gap installations to reference the local image registry. For Embedded Cluster v3 installations, use the ReplicatedImageName and ReplicatedImageRegistry template functions instead. For more information, see Template Functions for Embedded Cluster.

Syntax​

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

Syntax requirements​

Replicated template function syntax has the following requirements:

  • For both syntax options, repl{{ ... }} and {{repl ... }}, there must be no whitespace between repl and the {{ delimiter.
  • The manifests where you use Replicated template functions must be valid YAML, because Replicated lints the YAML manifests before rendering the template functions.

repl{{ ... }}​

Replicated recommends this syntax for most use cases.

Replicated strips any quotation marks wrapped around this syntax during rendering. If you need the rendered value in quotes, 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 ... }}​

Use this syntax when placing delimiters outside the template function improves YAML readability, such as in multi-line or if-else statements.

To use this syntax at the beginning of a YAML value, you must wrap it in quotes. YAML values cannot start with {, and KOTS requires valid YAML manifests. When you wrap this syntax in quotes, the rendered value is also wrapped in quotes.

Example with quotes​

The following example includes quotes because it appears at the beginning of a YAML value:

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​

Replicated groups template functions into different contexts based on the lifecycle phase when the function is available and the data 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 Replicated 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 the KOTS Config custom resource, which defines the KOTS Admin Console config screen. At execution time, template functions in the config context also can use the static context functions. For more information about configuring the Admin Console config screen, see About the Configuration Screen.

For a list of all Replicated 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 more information about managing customer licenses, see About Customers and Licensing.

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

kURL context​

note

Replicated kURL is available only for existing customers. If you are not an existing kURL user, use Replicated Embedded Cluster instead. For more information, see Use Embedded Cluster.

kURL is a Generally Available (GA) product for existing customers. For more information about the Replicated product lifecycle phases, see Support Lifecycle Policy.

Template functions in the kURL context have access to information about applications installed with Replicated kURL. For more information about kURL, see Introduction to kURL.

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

Identity context​

note

The KOTS identity service feature is deprecated and is not available to new users.

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

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

On this page