Skip to main content

Static Context

This topic provides a list of the KOTS template functions in the 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.

Certificate Functions​

PrivateCACert​

Introduced in KOTS v1.117.0

func PrivateCACert() string

PrivateCACert returns the name of a ConfigMap containing one or more private CA certificates:

  • For Embedded Cluster installations, the ConfigMap returned by PrivateCACert contains the CA trust store from the host. Embedded Cluster determines the CA trust store by first checking the SSL_CERT_FILE environment variable. If SSL_CERT_FILE is not set, Embedded Cluster then searches common certificate paths and uses the first valid certificate file found.

  • For KOTS installations in existing clusters, the end user can optionally create and pass the ConfigMap to the install command using the --private-ca-configmap flag. For more information, see install.

note

PrivateCACert returns the name of the ConfigMap even if the ConfigMap has no entries. If no ConfigMap exists, PrivateCACert returns the empty string.

KOTS mounts the ConfigMap returned by the PrivateCACert template function as a volume in the kotsadm container at /certs. Each key in the ConfigMap is created as a file, with its value as the file's contents. KOTS then sets the SSL_CERT_DIR environment variable in the kotsadm container to /certs. SSL_CERT_DIR is a common environment variable that is supported by most tools and languages to override the trust store.

The primary use case for the PrivateCACert template function is to make sure that KOTS trusts the private CA certificates issued by TLS man-in-the-middle (MITM) proxies in the end user's environment and can make outbound internet connects without TLS errors.

Can the ConfigMap returned by PrivateCACert also be mounted in application containers?

You can use the PrivateCACert template function to mount the ConfigMap in your application container. To do so, you can use the same method that is used by KOTS described above. However, note that the SSL_CERT_DIR environment variable overrides the trust store in the container. This means that only the CAs included in the ConfigMap will be trusted.

If you do not want to override the trust store, you should mount the ConfigMap to an alternate directory in the container and append the certificates to the default trust store. For example, for Debian/Ubuntu environments, you could mount the ConfigMap from the PrivateCACert template function in a subpath of the /usr/local/share/ca-certificates directory in the container, and run the update-ca-certificates command in an init container or the container's entrypoint to update the trust store in the container to include the additional certificates.

Replicated recommends that you consider the container OS and the language(s) used by your application to determine the method that you want to use to append certificates to the trust store.

Cluster Information Functions​

Distribution​

func Distribution() string

Distribution returns the Kubernetes distribution detected. The possible return values are:

  • aks
  • digitalOcean
  • dockerDesktop
  • eks
  • embedded-cluster
  • gke
  • ibm
  • k0s
  • k3s
  • kind
  • kurl
  • microk8s
  • minikube
  • oke
  • openShift
  • rke2
note

IsKurl can also be used to detect kURL instances.

Detect the Distribution​

repl{{ Distribution }}

Equal To Comparison​

repl{{ eq Distribution "gke" }}

Not Equal To Comparison​

repl{{ ne Distribution "embedded-cluster" }}

See Functions in the Go documentation.

IsKurl​

func IsKurl() bool

IsKurl returns true if running within a kurl-based installation.

Detect kURL Installations​

repl{{ IsKurl }}

Detect Non-kURL Installations​

repl{{ not IsKurl }}

See Functions in the Go documentation.

KotsVersion​

func KotsVersion() string

KotsVersion returns the current version of KOTS.

repl{{ KotsVersion }}

You can compare the KOTS version as follows:

repl{{KotsVersion | semverCompare ">= 1.19"}}

This returns true if the KOTS version is greater than or equal to 1.19.

For more complex comparisons, see Semantic Version Functions in the sprig documentation.

KubernetesMajorVersion​

Introduced in KOTS v1.92.0

func KubernetesMajorVersion() string

KubernetesMajorVersion returns the Kubernetes server major version.

repl{{ KubernetesMajorVersion }}

You can compare the Kubernetes major version as follows:

repl{{lt (KubernetesMajorVersion | ParseInt) 2 }}

This returns true if the Kubernetes major version is less than 2.

KubernetesMinorVersion​

Introduced in KOTS v1.92.0

func KubernetesMinorVersion() string

KubernetesMinorVersion returns the Kubernetes server minor version.

repl{{ KubernetesMinorVersion }}

You can compare the Kubernetes minor version as follows:

repl{{gt (KubernetesMinorVersion | ParseInt) 19 }}

This returns true if the Kubernetes minor version is greater than 19.

KubernetesVersion​

Introduced in KOTS v1.92.0

func KubernetesVersion() string

KubernetesVersion returns the Kubernetes server version.

repl{{ KubernetesVersion }}

You can compare the Kubernetes version as follows:

repl{{KubernetesVersion | semverCompare ">= 1.19"}}

This returns true if the Kubernetes version is greater than or equal to 1.19.

For more complex comparisons, see Semantic Version Functions in the sprig documentation.

Namespace​

func Namespace() string

Namespace returns the Kubernetes namespace that the application belongs to.

'{{repl Namespace}}'

NodeCount​

func NodeCount() int

NodeCount returns the number of nodes detected within the Kubernetes cluster.

repl{{ NodeCount }}

Lookup​

Introduced in KOTS v1.103.0

func Lookup(apiversion string, resource string, namespace string, name string) map[string]interface{}

Lookup searches resources in a running cluster and returns a resource or resource list.

Lookup uses the Helm lookup function to search resources and has the same functionality as the Helm lookup function. For more information, see lookup in the Helm documentation.

repl{{ Lookup "API_VERSION" "KIND" "NAMESPACE" "NAME" }}

Both NAME and NAMESPACE are optional and can be passed as an empty string ("").

The following combination of parameters are possible:

BehaviorLookup function
kubectl get pod mypod -n mynamespacerepl{{ Lookup "v1" "Pod" "mynamespace" "mypod" }}
kubectl get pods -n mynamespacerepl{{ Lookup "v1" "Pod" "mynamespace" "" }}
kubectl get pods --all-namespacesrepl{{ Lookup "v1" "Pod" "" "" }}
kubectl get namespace mynamespacerepl{{ Lookup "v1" "Namespace" "" "mynamespace" }}
kubectl get namespacesrepl{{ Lookup "v1" "Namespace" "" "" }}

The following describes working with values returned by the Lookup function:

  • When Lookup finds an object, it returns a dictionary with the key value pairs from the object. This dictionary can be navigated to extract specific values. For example, the following returns the annotations for the mynamespace object:

    repl{{ (Lookup "v1" "Namespace" "" "mynamespace").metadata.annotations }}

  • When Lookup returns a list of objects, it is possible to access the object list through the items field. For example:

    services: |
      repl{{- range $index, $service := (Lookup "v1" "Service" "mynamespace" "").items }}
      - repl{{ $service.metadata.name }}
      repl{{- end }}

    For an array value type, omit the |. For example:

    services:
      repl{{- range $index, $service := (Lookup "v1" "Service" "mynamespace" "").items }}
      - repl{{ $service.metadata.name }}
      repl{{- end }}

  • When no object is found, Lookup returns an empty value. This can be used to check for the existence of an object.

Date Functions​

Now​

func Now() string

Returns the current timestamp as an RFC3339 formatted string.

'{{repl Now }}'

NowFmt​

func NowFmt(format string) string

Returns the current timestamp as a formatted string. For information about Go time formatting guidelines, see Constants in the Go documentation.

'{{repl NowFmt "20060102" }}'

Encoding Functions​

Base64Decode​

func Base64Decode(stringToDecode string) string

Returns decoded string from a Base64 stored value.

'{{repl ConfigOption "base_64_encoded_name" | Base64Decode }}'

Base64Encode​

func Base64Encode(stringToEncode string) string

Returns a Base64 encoded string.

'{{repl ConfigOption "name" | Base64Encode }}'

UrlEncode​

func UrlEncode(stringToEncode string) string

Returns the string, url encoded. Equivalent to the QueryEscape function within the golang net/url library. For more information, see func QueryEscape in the Go documentation.

'{{repl ConfigOption "smtp_email" | UrlEncode }}:{{repl ConfigOption "smtp_password" | UrlEncode }}@smtp.example.com:587'

UrlPathEscape​

func UrlPathEscape(stringToEncode string) string

Returns the string, url path encoded. Equivalent to the PathEscape function within the golang net/url library. For more information, see func PathEscape in the Go documentation.

'{{repl ConfigOption "smtp_email" | UrlPathEscape }}:{{repl ConfigOption "smtp_password" | UrlPathEscape }}@smtp.example.com:587'

Encryption Functions​

KubeSeal​

func KubeSeal(certData string, namespace string, name string, value string) string

Integer and Float Functions​

HumanSize​

func HumanSize(size interface{}) string

HumanSize returns a human-readable approximation of a size in bytes capped at 4 valid numbers (eg. "2.746 MB", "796 KB"). The size must be a integer or floating point number.

'{{repl ConfigOption "min_size_bytes" | HumanSize }}'

Proxy Functions​

HTTPProxy​

func HTTPProxy() string

HTTPProxy returns the address of the proxy that the Admin Console is configured to use.

repl{{ HTTPProxy }}

HTTPSProxy​

func HTTPSProxy() string

HTTPSProxy returns the address of the proxy that the Admin Console is configured to use.

repl{{ HTTPSProxy }}

NoProxy​

func NoProxy() string

NoProxy returns the comma-separated list of no-proxy addresses that the Admin Console is configured to use.

repl{{ NoProxy }}

Math Functions​

Add​

func Add(x interface{}, y interface{}) interface{}

Adds x and y.

If at least one of the operands is a floating point number, the result will be a floating point number.

If both operands are integers, the result will be an integer.

'{{repl Add (ConfigOption "maximum_users") 1}}'

Div​

func Div(x interface{}, y interface{}) interface{}

Divides x by y.

If at least one of the operands is a floating point number, the result will be a floating point number.

If both operands are integers, the result will be an integer and will be rounded down.

'{{repl Div (ConfigOption "maximum_users") 2.0}}'

Mult​

func Mult(x interface{}, y interface{}) interface{}

Multiplies x and y.

Both operands must be either an integer or a floating point number.

If at least one of the operands is a floating point number, the result will be a floating point number.

If both operands are integers, the result will be an integer.

'{{repl Mult (NodePrivateIPAddressAll "DB" "redis" | len) 2}}'

If a template function returns a string, the value must be converted to an integer or a floating point number first:

'{{repl Mult (ConfigOption "session_cookie_age" | ParseInt) 86400}}'

Sub​

func Sub(x interface{}, y interface{}) interface{}

Subtracts y from x.

If at least one of the operands is a floating point number, the result will be a floating point number.

If both operands are integers, the result will be an integer.

'{{repl Sub (ConfigOption "maximum_users") 1}}'

String Functions​

ParseBool​

func ParseBool(str string) bool

ParseBool returns the boolean value represented by the string.

'{{repl ConfigOption "str_value" | ParseBool }}'

ParseFloat​

func ParseFloat(str string) float64

ParseFloat returns the float value represented by the string.

'{{repl ConfigOption "str_value" | ParseFloat }}'

ParseInt​

func ParseInt(str string, args ...int) int64

ParseInt returns the integer value represented by the string with optional base (default 10).

'{{repl ConfigOption "str_value" | ParseInt }}'

ParseUint​

func ParseUint(str string, args ...int) uint64

ParseUint returns the unsigned integer value represented by the string with optional base (default 10).

'{{repl ConfigOption "str_value" | ParseUint }}'

RandomString​

func RandomString(length uint64, providedCharset ...string) string

Returns a random string with the desired length and charset. Provided charsets must be Perl formatted and match individual characters. If no charset is provided, [_A-Za-z0-9] will be used.

Examples​

The following example generates a 64-character random string:

'{{repl RandomString 64}}'

The following example generates a 64-character random string that contains as and bs:

'{{repl RandomString 64 "[ab]" }}'

Generating Persistent and Ephemeral Strings​

When you assign the RandomString template function to a value key in the Config custom resource, you can use the hidden and readonly properties to control the behavior of the RandomString function each time it is called. The RandomString template function is called each time the user deploys a change to the configuration settings for the application.

Depending on if the hidden and readonly properties are true or false, the random string generated by a RandomString template function in a value key is either ephemeral or persistent between configuration changes:

  • Ephemeral: The value of the random string changes when the user deploys a change to the configuration settings for the application.
  • Persistent: The value of the random string does not change when the user deploys a change to the configuration settings for the application.

For more information about these properties, see hidden and readonly in Config.

note

If you assign the RandomString template function to a default key in the Config custom resource rather than a value key, then the hidden and readonly properties do not affect the behavior of the RandomString template function. For more information about the behavior of the default key in the Config custom resource, see default in Config.

The following table describes the behavior of the RandomString template function when it is assigned to a value key in the Config custom resource and the hidden and readonly properties are true or false:

readonlyhiddenOutcomeUse Case
falsetruePersistent

Set readonly to false and hidden to true if:

  • The random string must not change each time the user deploys a change to the application's configuration settings.
  • The user does not need to see or change, or must be prevented from seeing or changing, the value of the random string.
truefalseEphemeral

Set readonly to true and hidden to false if:

  • The random string must change each time the user deploys a change to the application's configuration settings.
  • The user does not need to change, or must be prevented from changing, the value of the random string.
  • The user must be able to see the value of the random string.
truetrueEphemeral

Set readonly to true and hidden to true if:

  • The random string must change each time the user deploys a change to the application's configuration settings.
  • The user does not need to see or change, or must be preventing from seeing or changing, the value of the random string.
falsefalsePersistent

Set readonly to false and hidden to false if:

  • The random string must not change each time the user deploys a change to the application's configuration settings.
  • The user must be able to see and change the value of the random string.

For example, set both readonly and hidden to false to generate a random password that users must be able to see and then change to a different value that they choose.

Split​

func Split(s string, sep string) []string

Split slices s into all substrings separated by sep and returns an array of the substrings between those separators.

'{{repl Split "A,B,C" "," }}'

Combining Split and index: Assuming the github_url param is set to https://github.mycorp.internal:3131, the following would set GITHUB_HOSTNAME to github.mycorp.internal.

'{{repl index (Split (index (Split (ConfigOption "github_url") "/") 2) ":") 0}}'

ToLower​

func ToLower(stringToAlter string) string

Returns the string, in lowercase.

'{{repl ConfigOption "company_name" | ToLower }}'

ToUpper​

func ToUpper(stringToAlter string) string

Returns the string, in uppercase.

'{{repl ConfigOption "company_name" | ToUpper }}'

Trim​

func Trim(s string, args ...string) string

Trim returns a string with all leading and trailing strings contained in the optional args removed (default space).

'{{repl Trim (ConfigOption "str_value") "." }}'

TrimSpace​

func TrimSpace(s string) string

Trim returns a string with all leading and trailing spaces removed.

'{{repl ConfigOption "str_value" | TrimSpace }}'

YamlEscape​

func YamlEscape(input string) string

YamlEscape returns an escaped and quoted version of the input string, suitable for use within a YAML document. This can be useful when dealing with user-uploaded files that may include null bytes and other nonprintable characters. For more information about printable characters, see Character Set in the YAML documentation.

repl{{ ConfigOptionData "my_file_upload" | YamlEscape }}