Chapter 4. Template processing in policies

Reference Kubernetes resources such as resource-specific and generic template functions on your hub cluster by using the {{hub …​ hub}} delimiters, or on your managed cluster by using the {{ …​ }} delimiters. You can use resource-specific functions for convenience and to make the content of your resources more accessible.

If you use the generic function, lookup, which is more advanced, familiarize yourself with the YAML structure of the resource that is being looked up. In addition to these functions, utility functions such as base64enc, base64dec, indent, autoindent, toInt, toBool, and more are available.

Policy templates are expressed as strings in the YAML manifest, using quotes or a block scalar (| or >). After processing, the resolved value is also a string. The toInt and toBool functions convert template output to integer or boolean types when the enforced resource expects those data types.

The fromSecret function returns the value of the given data key in the secret.

View the following syntax for the function:

func fromSecret (ns string, secretName string, datakey string) (dataValue string, err error)

When you use this function, enter the namespace, name, and data key of a Kubernetes Secret resource. You must use the same namespace that is used for the policy when using the function in a hub cluster template. See Template processing for more details.

View the following configuration policy that enforces a Secret resource on the target cluster:

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-fromsecret
spec:
  object-templates:
  - objectDefinition:
      apiVersion: v1
      kind: Secret
      metadata:
        name: demosecret
        namespace: test
      type: Opaque
      data:
        USER_NAME: YWRtaW4=
        PASSWORD: '{{ fromSecret "default" "localsecret" "PASSWORD" }}'

+ * You receive a policy violation if the Kubernetes Secret resource does not exist on the target cluster. If the data key does not exist on the target cluster, the value becomes an empty string. * When you use the fromSecret function with hub cluster templates, the output is automatically encrypted using the protect function to protect the value in flight to the managed cluster. * The value for the PASSWORD data key is a template that references the secret on the target cluster.

Important: When you add multiline string values such as, certificates, always add | toRawJson | toLiteral syntax at the end of the template pipeline to handle line breaks. For example, if you are copying a certificate from a Secret resource and including it in a ConfigMap resource, your template pipeline might be similar to the following syntax:

ca.crt: '{{ fromSecret "openshift-config" "ca-config-map-secret" "ca.crt"  | base64dec | toRawJson | toLiteral }}'

The fromConfigMap function returns the value of the given data key in the config map. When you use this function, enter the namespace, name, and data key of a Kubernetes ConfigMap resource. You must use the same namespace that is used for the policy using the function in a hub cluster template. See Template processing for more details.

View the following syntax for the function:

func fromConfigMap (ns string, configmapName string, datakey string) (dataValue string, err Error)

View the following configuration policy that enforces a Kubernetes resource on the target managed cluster:

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-fromcm-lookup
spec:
  object-templates:
  - objectDefinition:
      ...
      data:
        app-name: sampleApp
        app-description: "this is a sample app"
        log-file: '{{ fromConfigMap "default" "logs-config" "log-file" }}'
        log-level: '{{ fromConfigMap "default" "logs-config" "log-level" }}'

+ * If the data key does not exist on the target cluster, the value becomes an empty string. * The log-file template value retrieves the value of the log-file data key from the logs-config ConfigMap in the default namespace. * The log-level template value retrieves the value of the log-level data key from the logs-config ConfigMap in the default namespace.

The fromClusterClaim function returns the value of the Spec.Value in the ClusterClaim resource.

View the following syntax for the function:

func fromClusterClaim (clusterclaimName string) (dataValue string, err Error)

View the following example of the configuration policy that enforces a Kubernetes resource on the target managed cluster:

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-clusterclaims
spec:
  object-templates:
  - objectDefinition:
      ...
      data:
        platform: '{{ fromClusterClaim "platform.open-cluster-management.io" }}'
        product: '{{ fromClusterClaim "product.open-cluster-management.io" }}'
        version: '{{ fromClusterClaim "version.openshift.io" }}'

+ * When you use this function, enter the name of a Kubernetes ClusterClaim resource. You receive a policy violation if the ClusterClaim resource does not exist. * Configuration values can be set as key-value properties. * The value for the platform data key is a template that retrieves the value of the platform.open-cluster-management.io cluster claim. Similarly, it retrieves values for product and version from the ClusterClaim resource.

The lookupClusterClaim function is similar to the fromClusterClaim function. The only difference is that when the lookupClusterClaim function cannot find the ClusterClaim resource, lookupClusterClaim gives you an empty string. You can use your preferred templating function to detect when the response is an empty string, and then adjust the output. For example, when the ClusterClaim does not exist, you can define a default value or skip the object.

View the following example of the configuration policy that enforces a Kubernetes resource on the target managed cluster:

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-clusterclaims
spec:
  object-templates:
  - objectDefinition:
      ...
      kind: ConfigMap
      data:
        something: '{{ default "empty" (lookupClusterClaim "possibly.nonexistent") }}'

+ * When the possibly.nonexistent ClusterClaim is found, its value gets used in the ConfigMap. If the ClusterClaim does not exist, empty gets used instead through the default function that is provided by Sprig.

The lookup function returns the Kubernetes resource as a JSON compatible map. When you use this function, enter the API version, kind, namespace, name, and optional label selectors of the Kubernetes resource. You must use the same namespace that is used for the policy within the hub cluster template. See Template processing for more details.

If the requested resource does not exist, an empty map is returned. If the resource does not exist and the value is provided to another template function, you might get the following error: invalid value; expected string.

Note: Use the default template function, so the correct type is provided to later template functions. See Sprig open source for supported functions.

View the following syntax for the function:

func lookup (apiversion string, kind string, namespace string, name string, labelselector ...string) (value string, err Error)

For label selector examples, see Kubernetes labels and selectors. View the following example of the configuration policy that enforces a Kubernetes resource on the target managed cluster:

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-lookup
spec:
  object-templates:
  - objectDefinition:
      ...
      data:
        app-name: sampleApp
        app-description: "this is a sample app"
        metrics-url: >-
          http://{{ (lookup "v1" "Service" "default" "metrics").spec.clusterIP }}:8080

+ * Configuration values can be set as key-value properties. * The value for the metrics-url data key is a template that retrieves the v1/Service Kubernetes resource metrics from the default namespace, and is set to the value of the spec.clusterIP in the queried resource.

The base64enc function returns a base64 encoded value of the input data string. When you use this function, enter a string value.

View the following syntax for the function:

func base64enc (data string) (enc-data string)

View the following example of the configuration policy that uses the base64enc function:

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-fromsecret
spec:
  object-templates:
  - objectDefinition:
      ...
      data:
        USER_NAME: >-
          {{ fromConfigMap "default" "myconfigmap" "admin-user" | base64enc }}

The base64dec function returns a base64 decoded value of the input enc-data string. When you use this function, enter a string value.

View the following syntax for the function:

func base64dec (enc-data string) (data string)

View the following example of the configuration policy that uses the base64dec function:

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-fromsecret
spec:
  object-templates:
  - objectDefinition:
      ...
      data:
        app-name: >-
          {{ ( lookup "v1"  "Secret" "testns" "mytestsecret") .data.appname ) | base64dec }}

The indent function returns the padded data string. When you use this function, enter a data string with the specific number of spaces.

View the following syntax for the function:

func indent (spaces  int,  data string) (padded-data string)

View the following example of the configuration policy that uses the indent function:

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
spec:
  object-templates:
  - objectDefinition:
      ...
      data:
        Ca-cert: >-
          {{ ( index ( lookup "v1" "Secret" "default" "mycert-tls"  ).data  "ca.pem"  ) |  base64dec | indent 4  }}

The autoindent function acts like the indent function that automatically determines the number of leading spaces based on the number of spaces before the template.

View the following example of the configuration policy that uses the autoindent function:

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-fromsecret
spec:
  object-templates:
  - objectDefinition:
      ...
      data:
        Ca-cert: >-
          {{ ( index ( lookup "v1" "Secret" "default" "mycert-tls"  ).data  "ca.pem"  ) |  base64dec | autoindent }}

The toInt function casts and returns the integer value of the input value. When this is the last function in the template, there is further processing of the source content. This is to ensure that the value is interpreted as an integer by the YAML. When you use this function, enter the data that needs to be cast as an integer.

View the following syntax for the function:

func toInt (input interface{}) (output int)

View the following example of the configuration policy that uses the toInt function:

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-template-function
spec:
  object-templates:
  - objectDefinition:
      ...
      spec:
        vlanid: >-
          {{ (fromConfigMap "site-config" "site1" "vlan")  | toInt }}

The toBool function converts the input string into a boolean, and returns the boolean. When this is the last function in the template, there is further processing of the source content. This is to ensure that the value is interpreted as a boolean by the YAML. When you use this function, enter the string data that needs to be converted to a boolean.

View the following syntax for the function:

func toBool (input string) (output bool)

View the following example of the configuration policy that uses the toBool function:

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-template-function
spec:
  object-templates:
  - objectDefinition:
      ...
      spec:
        enabled: >-
          {{ (fromConfigMap "site-config" "site1" "enabled")  | toBool }}

The fromYaml, or fromYAML, function parses a YAML string into a Golang object. You can use this function with a ConfigMap resource that has a YAML string value.

View the following example of the configuration policy that uses the fromYaml function:

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-template-function
spec:
  object-templates:
  - objectDefinition:
      ...
      spec:
        replicas: >-
          {{ (fromConfigMap "default" "app-config" "config.yaml") | fromYaml | index "replicas" }}

The toYaml, or toYAML, function parses a Golang object into a YAML string. For a multiline result to be properly indented, you must pass the output to either the autoindent or indent function.

View the following example of the configuration policy that uses the toYaml function:

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-template-function
spec:
  object-templates:
  - objectDefinition:
      ...
      data:
        config.yaml: |
          {{ dict "key1" "value1" "key2" "value2" | toYaml | autoindent }}

The protect function enables you to encrypt a string in a hub cluster policy template. It is automatically decrypted on the managed cluster when the policy is evaluated. Use this function to encrypt sensitive hub cluster template values in transit to managed clusters.

View the following example of the configuration policy that uses the protect function:

apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: demo-template-function
spec:
  object-templates:
  - objectDefinition:
    ...
    spec:
      enabled: >-
        {{hub (lookup "v1" "Secret" "default" "my-hub-secret").data.message | protect hub}}

+ * In this example, a lookup hub cluster template encrypts the secret value. On the replicated policy, the value resembles $ocm_encrypted:okrrBqt72oI+3WT/0vxeI3vGa+wpLD7Z0ZxFMLvL204=. * Encryption uses AES-CBC with 256-bit keys. * Each managed cluster has a unique key, rotated every 30 days. * The decrypted value is never stored in the policy on the managed cluster. * To force immediate key rotation, delete the policy.open-cluster-management.io/last-rotated annotation on the policy-encryption-key Secret in the managed cluster namespace on the hub cluster. Policies are then reprocessed to use the new encryption key.

The toLiteral function removes any quotation marks around the template string after it is processed. You can use this function to convert a JSON string from a config map field to a JSON value in the manifest.

Run the following function to remove quotation marks from the key parameter value:

key: '{{ "[\"10.10.10.10\", \"1.1.1.1\"]" | toLiteral }}'

After using the toLiteral function, the following update is displayed:

key: ["10.10.10.10", "1.1.1.1"]

The copySecretData function copies all of the data contents of the specified secret.

View the following sample of the function:

...
objectDefinition:
  apiVersion: v1
  kind: Secret
  metadata:
    name: my-secret-copy
  data: '{{ copySecretData "default" "my-secret" }}'

+ * When you use this function with hub cluster templates, the output is automatically encrypted using the protect function.

The copyConfigMapData function copies all of the data content of the specified config map.

View the following sample of the function:

...
objectDefinition:
  apiVersion: v1
  kind: ConfigMap
  metadata:
    name: my-secret-copy
  data: '{{ copyConfigMapData "default" "my-configmap" }}'

The getNodesWithExactRoles function returns a list of nodes with only the roles that you specify, and ignores nodes that have any additional roles except the node-role.kubernetes.io/worker role.

View the following sample function where you are selecting "infra" nodes and ignoring the storage nodes:

...
objectDefinition:
  apiVersion: v1
  kind: ConfigMap
  metadata:
    name: my-configmap
    data:
      infraNode: |
        {{- range $i,$nd := (getNodesWithExactRoles "infra").items }}
        node{{ $i }}: {{ $nd.metadata.name }}
        {{- end }}
      replicas: {{ len ((getNodesWithExactRoles "infra").items) | toInt }}

The hasNodesWithExactRoles function returns the true value if the cluster contains nodes with only the roles that you specify, and ignores nodes that have any additional roles except the node-role.kubernetes.io/worker role.

View the following sample of the function:

...
objectDefinition:
  apiVersion: v1
  kind: ConfigMap
  metadata:
    name: my-configmap
  data:
    key: '{{ hasNodesWithExactRoles "infra" }}'

The skipObject function is only available in managed cluster templates in a ConfigurationPolicy resource. Calling {{ skipObject }} at any time inside a Go template signals to skip that particular object for the policy. When you use the skipObject with the objectSelector, you can further filter objects selected by name. You can call skipObject by itself inside a conditional or with an optional boolean argument.

View the following example that selects objects that have the label foo: bar, but skips objects that have a name with the suffix -prod:

...
object-templates:
  - objectSelector:
      matchExpressions:
      - key: foo
        operator: In
        values:
        - bar
    objectDefinition:
      apiVersion: v1
      kind: ConfigMap
      data:
        key: '{{ skipObject (hasSuffix "-prod" .ObjectName) }}{{ hasNodesWithExactRoles "infra" }}'

Red Hat Advanced Cluster Management supports most of the template functions from the sprig open source project, except for env and expandenv.

View the following table:

Managed cluster and hub cluster templates reduce the need to create separate policies for each target cluster or hard code configuration values in policy definitions. For security, resource-specific and generic lookup functions in hub cluster templates are restricted to the policy namespace on the hub cluster.

Important: Using hub cluster templates to propagate secrets or other sensitive data exposes the data in the managed cluster namespace on the hub cluster, and on the managed clusters where that policy is distributed. Template content expands within the policy, and policies are not encrypted by the OpenShift Container Platform etcd encryption support. To address this, use fromSecret or copySecretData to automatically encrypt values from the secret, or use protect to encrypt other values.

Enable the governance-standalone-hub-templating add-on to resolve hub cluster templates on a managed cluster when you deploy configuration policies directly to managed clusters, for example, by using GitOps.

Required access: Cluster administrator

Grant permissions to the add-on group using roles and role bindings to allow the standalone hub cluster templating add-on to access resources through functions like lookup or fromConfigMap.

The add-on group uses the naming format system:open-cluster-management:cluster:<cluster_name>:addon:governance-standalone-hub-templating, where <cluster_name> represents your managed cluster name.

The add-on resolves hub cluster templates and saves the policy state in a secret on the managed clusters, preventing operational interruptions if the hub cluster becomes temporarily unavailable.