Go Templates

template expressions use the Go Text Template library with some additional functions provided by the gomplate library.

In this example we print out the exchange rates returned by an HTTP API Call

display-with-gotemplate.yaml
---
apiVersion: canaries.flanksource.com/v1
kind: Canary
metadata:
  name: currency-converter-display-gotemplate
spec:
  http:
    - name: USD
      url: https://api.frankfurter.app/latest?from=USD&to=GBP,EUR,ILS,ZAR
      display:
        template: "$1 = €{{.json.rates.EUR}}, £{{.json.rates.GBP}}, ₪{{.json.rates.ILS}}"

Switching scripting language

Use a shebang (#!) line to choose a different shell (python, bash and pwsh are included in the base image)

exec:
  script: |
    #! pwsh
    Get-Items | ConvertTo-JSON

Escaping templates in Helm Charts

If you need to pass a template through a Helm Chart and prevent Helm from templating you need to escape it:

{{`{{ .secret }}`}}

Alternatively change the templating delimiters

Multiline handling with YAML

If you are using a YAML multiline string use | and not > which will strip newlines

Instead of:

exec:
  script: >
    #! pwsh
    Get-Items | ConvertTo-JSON

Do this:

exec:
  script: |
    #! pwsh
    Get-Items | ConvertTo-JSON

Changing templating delimiters

The template delimiters can be changed from the defaults of $() and {{}} with gotemplate comments

exec:
  script: |
    #! pwsh
    # gotemplate: left-delim=$[[ right-delim=]]
    $message = "$[[.config.name]]"
    Write-Host "{{  $message }}"
    Write-Host  @{ Number = 1; Shape = "Square"; Color = "Blue"} | ConvertTo-JSON

base64

Encode

Encode data as a Base64 string. Specifically, this uses the standard Base64 encoding as defined in RFC4648 §4 (and not the URL-safe encoding).

{{ base64.Encode "hello world" }} // aGVsbG8gd29ybGQ=
{{ "hello world" | base64.Encode }} // aGVsbG8gd29ybGQ=

Decode

Decode a Base64 string. This supports both standard (RFC4648 §4) and URL-safe (RFC4648 §5) encodings.

{{ base64.Decode "aGVsbG8gd29ybGQ=" }} // hello world
{{ "aGVsbG8gd29ybGQ=" | base64.Decode }} // hello world

note

For the functions that return an array, a Go []interface{} is returned, regardless of whether the input was a different type.

Collection

dict

Dict is a convenience function that creates a map with string keys. Provide arguments as key/value pairs. If an odd number of arguments is provided, the last is used as the key, and an empty string is set as the value.

All keys are converted to strings.

This function is equivalent to Sprig's dict function, as used in Helm templates.

For creating more complex maps, see data.JSON or data.YAML.

For creating arrays, see coll.Slice.

{{ coll.Dict "name" "Frank" "age" 42 | data.ToYAML }}

// age: 42
// name: Frank

{{ dict 1 2 3 | toJSON }} // {"1":2,"3":""}

{{ define "T1" }}Hello {{ .thing }}!{{ end -}}
{{ template "T1" (dict "thing" "world")}}
{{ template "T1" (dict "thing" "everybody")}}

// Hello world!
// Hello everybody!

slice

Creates a slice (like an array or list). Useful when needing to range over a bunch of variables.

{{ range slice "Bart" "Lisa" "Maggie" }}Hello, {{ . }}{{ end }}

// Hello, Bart
// Hello, Lisa
// Hello, Maggie

has

Reports whether a given object has a property with the given key, or whether a given array/slice contains the given value. Can be used with if to prevent the template from trying to access a non-existent property in an object.

{{ $l := slice "foo" "bar" "baz" }}there is {{ if has $l "bar" }}a{{else}}no{{end}} bar // there is a bar

{{ $o := dict "foo" "bar" "baz" "qux" }}
{{ if has $o "foo" }}{{ $o.foo }}{{ else }}THERE IS NO FOO{{ end }} // bar

jsonpath

Extracts portions of an input object or list using a JSONPath expression.

Any object or list may be used as input. The output depends somewhat on the expression; if multiple items are matched, an array is returned.

{{ .books | jsonpath `$..works[?( @.edition_count > 400 )].title` }} // [Alice's Adventures in Wonderland Gulliver's Travels]

jq

Filters an input object or list using the jq language, as implemented by gojq.

Any JSON datatype may be used as input (NOTE: strings are not JSON-parsed but passed in as is). If the expression results in multiple items (no matter if streamed or as an array) they are wrapped in an array. Otherwise a single item is returned (even if resulting in an array with a single contained element).

JQ filter expressions can be tested at jqplay

Keys

Return a list of keys in one or more maps.

The keys will be ordered first by map position (if multiple maps are given), then alphabetically.

Values

Return a list of values in one or more maps.

The values will be ordered first by map position (if multiple maps are given), then alphabetically by key.