go-template-utils

README

What is go-template-utils?

A library for processing Go templates in policy templates or other Open Cluster Management objects.

Go to the Contributing guide to learn how to get involved.

• The go-template-utils repository is part of the open-cluster-management community. For more information, visit: open-cluster-management.io.

How do templates work?

To get started, use the templates.NewResolver function along with a templates.Config instance.

See the ResolveTemplate example for an example of how to use this library.

Under the hood, go-template-utils wraps the text/template package. This means that as long as the input to templates.ResolveTemplate can be marshaled to YAML, any of the text/template package features can be used.

A subset of Sprig functions is imported into the resolver, listed in pkg/templates/sprig_wrapper.go.

Additionally, the following custom functions are supported:

Function	Description	Example
atoi	Parses an input string and returns an integer like the Atoi function.	{{ "6" | atoi }}
autoindent	Automatically indents the input string based on the leading spaces.	{{ "Templating\nrocks!" | autoindent }}
base64enc	Decodes the input Base64 string to its decoded form.	{{ "VGVtcGxhdGVzIHJvY2shCg==" | base64dec }}
base64enc	Encodes an input string in the Base64 format.	{{ "Templating rocks!" | base64enc }}
indent	Indents the input string by the specified amount.	{{ "Templating\nrocks!" | indent 4 }}
fromClusterClaim	Returns the value of a specific ClusterClaim.	{{ fromClusterClaim "name" }}
fromConfigMap	Returns the value of a key inside a ConfigMap.	{{ fromConfigMap "namespace" "config-map-name" "key" }}
copyConfigMapData	Returns the data contents of the specified ConfigMap	{{ copyConfigMapData "namespace" "config-map-name" }}
fromSecret	Returns the value of a key inside a Secret. If the EncryptionMode is set to EncryptionEnabled, this will return an encrypted value.	{{ fromSecret "namespace" "secret-name" "key" }}
copySecretData	Returns the data contents of the specified Secret. If the EncryptionMode is set to EncryptionEnabled, this will return an encrypted value.	{{ copySecretData "namespace" "secret-name" }}
lookup	Generic lookup function for any Kubernetes object.	{{ (lookup "v1" "Secret" "namespace" "name").data.key }}
protect	Encrypts any string using AES-CBC.	{{ "super-secret" | protect }}
toBool	Parses an input boolean string converts it to a boolean but also removes any quotes around the map value.	key: "{{ "true" | toBool }}" => key: true
toInt	Parses an input string and returns an integer but also removes anyquotes around the map value.	key: "{{ "6" | toInt }}" => key: 6
toLiteral	Removes any quotes around the template string after it is processed.	key: "{{ "[10.10.10.10, 1.1.1.1]" | toLiteral }} => key: [10.10.10.10, 1.1.1.1]

template-resolver CLI (Beta)

The template-resolver CLI tool is used to help during policy development involving templates. Note that the generated output is only partially validated for syntax.

Installing the binary

go install github.com/stolostron/go-template-utils/v4/cmd/template-resolver@latest

Managed Cluster Templates Example

kubectl -n default create configmap cool-car --from-literal=model=Shelby\ Mustang
kubectl -n default create configmap not-cool-car --from-literal=model=Pinto

cat <<EOF > policy-example.yaml
apiVersion: policy.open-cluster-management.io/v1
kind: Policy
metadata:
  name: label-configmaps
spec:
  disabled: false
  policy-templates:
    - objectDefinition:
        apiVersion: policy.open-cluster-management.io/v1
        kind: ConfigurationPolicy
        metadata:
          name: label-configmaps
        spec:
          remediationAction: enforce
          severity: low
          object-templates-raw: |
            {{- range (lookup "v1" "ConfigMap" "default" "").items }}
            {{- if and .data.model (contains "Mustang" .data.model) }}
            - complianceType: musthave
              objectDefinition:
                kind: ConfigMap
                apiVersion: v1
                metadata:
                  name: {{ .metadata.name }}
                  namespace: {{ .metadata.namespace }}
                  labels:
                    ford.com/model: Mustang
            {{- end }}
            {{- end }}
EOF

template-resolver policy-example.yaml

The output should be:

apiVersion: policy.open-cluster-management.io/v1
kind: Policy
metadata:
  name: label-configmaps
spec:
  disabled: false
  policy-templates:
    - objectDefinition:
        apiVersion: policy.open-cluster-management.io/v1
        kind: ConfigurationPolicy
        metadata:
          name: label-configmaps
        spec:
          object-templates:
            - complianceType: musthave
              objectDefinition:
                apiVersion: v1
                kind: ConfigMap
                metadata:
                  labels:
                    ford.com/model: Mustang
                  name: cool-car
                  namespace: default
          remediationAction: enforce
          severity: low

Hub and Managed Cluster Templates Example

kubectl -n default create configmap cool-car --from-literal=model=Shelby\ Mustang
kubectl -n default create configmap not-cool-car --from-literal=model=Pinto

cat <<EOF > policy-example.yaml
apiVersion: policy.open-cluster-management.io/v1
kind: Policy
metadata:
  name: label-configmaps
  namespace: policies
spec:
  disabled: false
  policy-templates:
    - objectDefinition:
        apiVersion: policy.open-cluster-management.io/v1
        kind: ConfigurationPolicy
        metadata:
          name: label-configmaps
        spec:
          remediationAction: enforce
          severity: low
          object-templates-raw: |
            {{- range (lookup "v1" "ConfigMap" "default" "").items }}
            {{- if and .data.model (contains "Mustang" .data.model) }}
            - complianceType: musthave
              objectDefinition:
                kind: ConfigMap
                apiVersion: v1
                metadata:
                  name: {{ .metadata.name }}
                  namespace: {{ .metadata.namespace }}
                  labels:
                    cluster-name: {{hub .ManagedClusterName hub}}
                    ford.com/model: Mustang
            {{- end }}
            {{- end }}
EOF

template-resolver -hub-kubeconfig ~/.kube/config -cluster-name local-cluster policy-example.yaml

The output should be:

apiVersion: policy.open-cluster-management.io/v1
kind: Policy
metadata:
  name: label-configmaps
  namespace: policies
spec:
  disabled: false
  policy-templates:
    - objectDefinition:
        apiVersion: policy.open-cluster-management.io/v1
        kind: ConfigurationPolicy
        metadata:
          name: label-configmaps
        spec:
          object-templates:
            - complianceType: musthave
              objectDefinition:
                apiVersion: v1
                kind: ConfigMap
                metadata:
                  labels:
                    cluster-name: local-cluster
                    ford.com/model: Mustang
                  name: cool-car
                  namespace: default
          remediationAction: enforce
          severity: low