template_functions.md

Template Functions

• Template Functions
  • lower, lowercase
  • upper, uppercase
  • title
  • sprintf, printf
  • trim
  • trimPrefix, trimSuffix
  • default
  • required
  • env
  • sha1sum, sha256sum
  • str
  • replace
  • alphanumify, alphanumdash
  • dottodash, dottounder
  • index

The following template functions are available, with some functions having aliases for convenience:

lower, lowercase

Converts the value to string as stated in String conversion, then lowercases it.

{{ "Namespace" | lower }}
namespace

upper, uppercase

Converts the value to string as stated in String conversion, then uppercases it.

{{ "Namespace" | upper }}
NAMESPACE

title

Converts the value to string as stated in String conversion, then capitalize the first character of each word.

{{ "hello world" | title }}
Hello World

While available, it's use is discouraged for file names.

sprintf, printf

Alias of Go's fmt.Sprintf.

{{ printf "number-%d" 20 }}
number-20

trim

Converts the value to string as stated in String conversion, then removes any whitespace at the beginning or end of the string.

{{ "   hello world    " | trim }}
hello world

trimPrefix, trimSuffix

Converts the value to string as stated in String conversion, then removes either the prefix or the suffix.

Do note that the parameters are flipped from Go's strings.TrimPrefix and strings.TrimSuffix: here, the first parameter is the prefix, rather than being the last parameter. This is to allow piping one output to another:

{{ "   foo" | trimPrefix " " }}
foo

default

If the value is set, return it, otherwise, a default value is used.

{{ "" | default "bar" }}
bar

required

If the argument renders to an empty string, the application fails and exits with non-zero status code.

{{ "" | required }}
<!-- argument is marked as required, but it was not found in the YAML data -->

env

Fetch an environment variable to be printed. If the environment variable is mandatory, consider using required. If the environment variable might be empty, consider using default.

env allows the key to be case-insensitive: it will be uppercased internally.

{{ env "user" }}
patrick

sha1sum, sha256sum

Renders a sha1sum or sha256sum of a given value. The value is converted first to their YAML representation, with comments removed, then the sum is performed. This is to ensure that the "behavior" can stay the same, even when the file might have multiple comments that might change.

Primitives such as string, bool and float64 are converted as-is.

While not recommended, you can use this to always generate a new name if the YAML declaration drifts. The following snippet uses ., which represents the entire YAML file -- on a multi-YAML file, each . represents a single file:

{{ . | sha1sum }}
f502bbf15d0988a9b28b73f8450de47f75179f5c

str

Converts any primitive as stated in String conversion, to string:

{{ false | str }}
false

replace

Converts the value to a string as stated in String conversion, then replaces all ocurrences of a string with another:

{{ "hello.dev" | replace "." "_" }}
hello_dev

alphanumify, alphanumdash

Converts the value to a string as stated in String conversion, and keeps from the original string only alphanumeric characters -- for alphanumify -- or alphanumeric plus dashes and underscores -- like URLs, for alphanumdash:

{{ "secret-foo.dev" | alphanumify }}
secretsfoodev

{{ "secret-foo.dev" | alphanumdash }}
secrets-foodev

dottodash, dottounder

Converts the value to a string as stated in String conversion, and replaces all dots to either dashes or underscores:

{{ "secret-foo.dev" | dottodash }}
secrets-foo-dev

{{ "secret-foo.dev" | dottounder }}
secrets-foo_dev

Particularly useful for Kubernetes FQDNs needed to be used as filenames.

index

For certain resources where YAML indexes are not alphanumeric, but contain special characters such as labels or annotations, index allows you to retrieve those resources. Consider the following YAML:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
  labels:
    app.kubernetes.io/name: patrickdap-deployment

It's not possible to access the value patrickdap-deployment using dot notation like this: {{ .metadata.labels.app.kubernetes.io/name }}: the Go Template engine will throw an error. Instead, you can use index:

{{ index "app.kubernetes.io/name" .metadata.labels }}
patrickdap-deployment

The reason the parameters are flipped is to allow piping one output to another:

{{ .metadata.labels | index "app.kubernetes.io/name" }}
patrickdap-deployment