Skip to content

template-functions-about.mdx

Latest commit

 

History

History
170 lines (111 loc) · 7.34 KB

template-functions-about.mdx

File metadata and controls

170 lines (111 loc) · 7.34 KB

import UseCases from "../partials/template-functions/_use-cases.mdx" import StaticContext from "../partials/template-functions/_static-context.mdx" import ConfigContext from "../partials/template-functions/_config-context.mdx" import LicenseContext from "../partials/template-functions/_license-context.mdx" import KurlContext from "../partials/template-functions/_kurl-context.mdx" import IdentityContext from "../partials/template-functions/_identity-context.mdx" import KurlAvailability from "../partials/kurl/_kurl-availability.mdx"

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. You can use the Replicated template functions in Kubernetes manifest files for applications deployed by a Replicated installer (Embedded Cluster, KOTS, kURL).

All functionality of the Go templating language, including if statements, loops, and variables, is supported with Replicated template functions. 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 for applications deployed by a Replicated installer, 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

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

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.

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

  • Embedded Cluster v3 does not support the following template functions:

    • 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, ReplicatedImageName, and ReplicatedImageName template functions instead. For more information, see Template Functions for Embedded Cluster (Beta).

Syntax {#syntax}

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

Syntax requirements

Replicated 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 Replicated template functions are used must be valid YAML. This is because the YAML manifests are linted before Replicated template functions are rendered.

repl{{ ... }} {#syntax-integer}

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 ... }} {#syntax-string}

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 {#contexts}

Replicated 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

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

Config context

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

License context

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

kURL context

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

Identity context

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