// Module included in the following assemblies:

// *scalability_and_performance/cluster-compare/creating-a-reference-configuration.adoc

:_mod-docs-content-type: REFERENCE

[id="cluster-compare-templating-reference_{context}"]
= Reference template functions

[role="_abstract"]
The `cluster-compare` plugin supports all `sprig` library functions, except for the `env` and `expandenv` functions. For the full list of `sprig` library functions, see "Sprig Function Documentation".

The following table describes the additional template functions for the `cluster-compare` plugin:

.Additional cluster-compare template functions
[cols=".^2,.^4,.^6a",options="header"]
|====

|Function |Description |Example

|`fromJson`
|Parses the incoming string as a structured JSON object.
|`value: {{ obj := spec.jsontext \| fromJson }}{{ obj.field }}`

|`fromJsonArray`
|Parses the incoming string as a structured JSON array.
| `value: {{ obj := spec.jsontext \| fromJson}}{{ index $obj 0 }}`

|`fromYaml`
|Parses the incoming string as a structured YAML object.
|`value: {{ obj := spec.yamltext \| fromYaml }}{{ obj.field }}`

|`fromYamlArray`
|Parses the incoming string as a structured YAML array.
|`value: {{ obj := spec.yamltext \| fromYaml}}{{ index $obj 0 }`

|`toJson`
|Renders incoming data as JSON while preserving object types.
|`jsonstring: {{ $variable \| toJson }}`

|`toToml`
|Renders the incoming string as structured TOML data.
|`tomlstring: {{ $variable \| toToml }}`

|`toYaml`
|Renders incoming data as YAML while preserving object types.
|For simple scalar values: `value: {{ $data \| toYaml }}`

For lists or dictionaries: `value: {{ $dict \| toYaml \| nindent 2 }}`

|`doNotMatch`
|Prevents a template from matching a cluster resource, even if it would normally match. You can use this function inside a template to conditionally exclude certain resources from correlation. The specified reason is logged when running with the `--verbose` flag. Templates excluded due to `doNotMatch` are not considered comparison failures.

This function is especially useful when your template does not specify a fixed name or namespace. In these cases, you can use the `doNotMatch` function to exclude specific resources based on other fields, such as `labels` or `annotations`.
|`{{ if $condition }}{{ doNotMatch $reason }}{{ end }}`

|`lookupCRs`
|Returns an array of objects that match the specified parameters. For example: `lookupCRs $apiVersion $kind $namespace $name`.

If the `$namespace` parameter is an empty string (`""`) or `\*`, the function matches all namespaces. For cluster-scoped objects, the function matches objects with no namespace.

If the `$name` is an empty string or `*`, the function matches any named object.
|-

|`lookupCR`
|Returns a single object that matches the parameters. If multiple objects match, the function returns nothing. This function takes the same arguments as the `lookupCRs` function.
|-

|====

The following example shows how to use the `lookupCRs` function to retrieve and render values from multiple matching resources:

.Config map example using `lookupCRs`
[source,yaml]
----
kind: ConfigMap
apiVersion: v1
metadata:
  labels:
    k8s-app: kubernetes-dashboard
  name: kubernetes-dashboard-settings
  namespace: kubernetes-dashboard
data:
  dashboard: {{ index (lookupCR "apps/v1" "Deployment" "kubernetes-dashboard" "kubernetes-dashboard") "metadata" "name" \| toYaml }}
  metrics: {{ (lookupCR "apps/v1" "Deployment" "kubernetes-dashboard" "dashboard-metrics-scraper").metadata.name \| toYaml }}
----

The following example shows how to use the `lookupCR` function to retrieve and use specific values from a single matching resource:

.Config map example using `lookupCR`
[source,yaml]
----
kind: ConfigMap
apiVersion: v1
metadata:
  labels:
    k8s-app: kubernetes-dashboard
  name: kubernetes-dashboard-settings
  namespace: kubernetes-dashboard
data:
  {{- $objlist := lookupCRs "apps/v1" "Deployment" "kubernetes-dashboard" "*" }}
  {{- $dashboardName := "unknown" }}
  {{- $metricsName := "unknown" }}
  {{- range $obj := $objlist }}
    {{- $appname := index $obj "metadata" "labels" "k8s-app" }}
    {{- if contains "metrics" $appname }}
      {{- $metricsName = $obj.metadata.name }}
    {{- end }}
    {{- if eq "kubernetes-dashboard" $appname }}
      {{- $dashboardName = $obj.metadata.name }}
    {{- end }}
  {{- end }}
  dashboard: {{ $dashboardName }}
  metrics: {{ $metricsName }}
----

