JMESPath

The add() filter very simply adds two values and produces a sum. The official JMESPath library does not include most basic arithmetic operators such as add, subtract, multiply, and divide, the exception being sum() as documented here. While sum() is useful in that it accepts an array of integers as an input, add() is useful as a simplified filter when only two individual values need to be summed. Note that add() here is different from the length() filter which is used to obtain a count of a certain number of items. Use add() instead when you have values of two fields you wish to add together.

add() is also value-aware (based on the formatting used for the inputs) and is capable of adding numbers, quantities, and durations without any form of unit conversion.

Arithmetic filters like add() currently accept inputs in the following formats.

• Number (ex., `10`)
• Quantity (ex., ‘10Mi’)
• Duration (ex., ‘10h’)

Note that how the inputs are enclosed determines how Kyverno interprets their type. Numbers enclosed in back ticks are scalar values while quantities and durations are enclosed in single quotes thus treating them as strings. Using the correct enclosing character is important because, in Kubernetes “regular” numbers are treated implicitly as units of measure. The number written `10` is interpreted as an integer or “the number ten” whereas ‘10’ is interpreted as a string or “ten bytes”. See the Formatting section above for more details.

Some specific behaviors to note:

• If a duration (‘1h’) and a number (`5`) are the inputs, the number will be interpreted as seconds resulting in a sum of 1h0m5s.
• Because of durations being a string just like resource quantities, and the minutes unit of “m” also present in quantities interpreted as the “milli” prefix, there is no support for minutes.

Example: This policy denies a Pod if any of its containers specify memory requests and limits in excess of 200Mi.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: add-demo
 5spec:
 6  validationFailureAction: Enforce
 7  background: false
 8  rules:
 9  - name: add-demo
10    match:
11      any:
12      - resources:
13          kinds:
14          - Pod
15          operations:
16          - CREATE
17          - UPDATE
18    validate:
19      message: "The total memory defined in requests and limits must not exceed 200Mi."
20      foreach:
21      - list: "request.object.spec.containers"
22        deny:
23          conditions:
24            any:
25            - key: "{{ add('{{ element.resources.requests.memory || `0` }}', '{{ element.resources.limits.memory || `0` }}') }}"
26              operator: GreaterThan
27              value: 200Mi

The base64_decode() filter takes in a base64-encoded string and produces the decoded output similar to the tool and command base64 --decode. This can be useful when working with Kubernetes Secrets and deciphering their values in order to take action on them in a policy.

Some specific behaviors to note:

• Base64-encoded strings with newline characters will be printed back with them inline.

Example: This policy checks every container, initContainer, and ephemeralContainer in a Pod and decodes a Secret having the path data.license to ensure it does not refer to a prohibited license key.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: base64-decode-demo
 5spec:
 6  background: false
 7  validationFailureAction: Enforce
 8  rules:
 9  - name: base64-decode-demo
10    match:
11      any:
12      - resources:
13          kinds:
14          - Pod
15    preconditions:
16      all:
17      - key: "{{ request.object.spec.[containers, initContainers, ephemeralContainers][].env[].valueFrom.secretKeyRef || '' | length(@) }}"
18        operator: GreaterThanOrEquals
19        value: 1
20      - key: "{{request.operation}}"
21        operator: NotEquals
22        value: DELETE
23    validate:
24      message: This license key may not be consumed by a Secret.
25      foreach:
26      - list: "request.object.spec.[containers, initContainers, ephemeralContainers][].env[].valueFrom.secretKeyRef"
27        context:
28        - name: status
29          apiCall:
30            jmesPath: "data.license"
31            urlPath: "/api/v1/namespaces/{{request.namespace}}/secrets/{{element.name}}"
32        deny:
33          conditions:
34            any:
35            - key: "{{ status | base64_decode(@) }}"
36              operator: Equals
37              value: W0247-4RXD3-6TW0F-0FD63-64EFD-38180

The base64_encode() filter is the inverse of the base64_decode() filter and takes in a regular, plaintext and unencoded string and produces a base64-encoded output similar to the tool and command base64. This can be useful when working with Kubernetes Secrets by encoding data into the base64 format which is the only acceptable format for Kubernetes Secrets.

Example: This policy generates a Secret when a new Namespace is created the contents of which is the value of an annotation named corpkey.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: base64-encode-demo
 5spec:
 6  rules:
 7  - name: gen-supkey
 8    match:
 9      any:
10      - resources:
11          kinds:
12          - Namespace
13    generate:
14      apiVersion: v1
15      kind: Secret
16      name: sup-key
17      namespace: "{{request.object.metadata.name}}"
18      synchronize: false
19      data:
20        data:
21          token: "{{ base64_encode('{{ request.object.metadata.annotations.corpkey }}') }}"

The compare() filter is provided as an analog to the inbuilt function to Golang of the same name. It compares two strings lexicographically where the first string is compared against the second. If both strings are equal, the result is 0 (ex., “a” compared to “a”). If the first is in lower lexical order than the second, the result is -1 (ex., “a” compared to “b”). And if the first is in higher order than the second, the result is 1 (ex., “b” compared to “a”). Kyverno also has built-in operators for string comparison where Equals is usually the most common, and in most use cases it is more practical to use the Equals operator in expressions such as preconditions and deny.conditions blocks.

Example: This policy will write a new label called dictionary into a Service putting into order the values of two annotations if the order of the first comes before the second.

 1apiVersion : kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: compare-demo
 5spec:
 6  background: false
 7  rules:
 8  - name: write-dictionary
 9    match:
10      any:
11      - resources:
12          kinds:
13          - Service
14    preconditions:
15      any:
16      - key: "{{ compare('{{request.object.metadata.annotations.foo}}', '{{request.object.metadata.annotations.bar}}') }}"
17        operator: LessThan
18        value: 0
19    mutate:
20      patchStrategicMerge:
21        metadata:
22          labels:
23            dictionary: "{{request.object.metadata.annotations.foo}}-{{request.object.metadata.annotations.bar}}"

The divide() filter performs arithmetic divide capabilities between two input fields and produces an output quotient. Like other arithmetic custom filters, it is input aware based on the type passed and, for quantities, allows auto conversion between units of measure. For example, dividing 10Mi (ten mebibytes) by 5Ki (five kibibytes) results in the value 5120 as units are first normalized and then canceled through division. The divide() filter is currently under development to better account for all permutations of input types, however the below table captures the most common and practical use cases.

Arithmetic filters like divide() currently accept inputs in the following formats.

• Number (ex., `10`)
• Quantity (ex., ‘10Mi’)
• Duration (ex., ‘10h’)

Note that how the inputs are enclosed determines how Kyverno interprets their type. Numbers enclosed in back ticks are scalar values while quantities and durations are enclosed in single quotes thus treating them as strings. Using the correct enclosing character is important because, in Kubernetes “regular” numbers are treated implicitly as units of measure. The number written `10` is interpreted as an integer or “the number ten” whereas ‘10’ is interpreted as a string or “ten bytes”. See the Formatting section above for more details.

Example: This policy will check every container in a Pod and ensure that memory limits are no more than 2.5x its requests.

 1apiVersion : kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: enforce-resources-as-ratio
 5spec:
 6  validationFailureAction: Audit
 7  rules:
 8  - name: check-memory-requests-limits
 9    match:
10      any:
11      - resources:
12          kinds:
13          - Pod
14          operations:
15          - CREATE
16          - UPDATE
17    validate:
18      message: Limits may not exceed 2.5x the requests.
19      foreach:
20      - list: "request.object.spec.containers"
21        deny:
22          conditions:
23            any:
24              # Set resources.limits.memory equal to zero if not present and resources.requests.memory equal to 1m rather than zero
25              # to avoid undefined division error. No memory request in this case is basically the same as 1m. Kubernetes API server
26              # will automatically set requests=limits if only limits is defined.
27            - key: "{{ divide('{{ element.resources.limits.memory || '0' }}', '{{ element.resources.requests.memory || '1m' }}') }}"
28              operator: GreaterThan
29              value: 2.5

The equal_fold() filter is designed to provide text case folding for two sets of strings as inputs. Case folding allows comparing two strings for equivalency where the only differences are letter cases. The return is a boolean (either true or false). For example, comparing “pizza” to “Pizza” results in true because other than title case on “Pizza” the strings are equivalent. Likewise with “pizza” and “pIzZa”. Comparing “pizza” to “APPLE” results in false because even once normalized to the same case, the strings are different.

Related filters to equal_fold() are to_upper() and to_lower() which can also be used to normalize text for comparison.

Example: This policy will validate that a ConfigMap with a label named dept and the value of a key under data by the same name have the same case-insensitive value.

 1apiVersion : kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: equal-fold-demo
 5spec:
 6  validationFailureAction: Enforce
 7  background: false
 8  rules:
 9  - name: validate-dept-label-data
10    match:
11      any:
12      - resources:
13          kinds:
14          - ConfigMap
15    validate:
16      message: The dept label must equal the data.dept value aside from case.
17      deny:
18        conditions:
19          any:
20          - key: "{{ equal_fold('{{request.object.metadata.labels.dept}}', '{{request.object.data.dept}}') }}"
21            operator: NotEquals
22            value: true

The image_normalize() filter is used to output the canonical image string as it is known internally to Kyverno. This filter will render the internal values for the default image registry and tag (latest) if they apply to a given image. It is useful particularly in mutate rules where the full image value is needed to decide whether to mutate it. This filter cannot be tested with the Kyverno CLI because the runtime context is only available in webhook mode.

For example, assuming the value of the default registry is left at its defaults of docker.io and a Pod is sent to Kyverno which has a single container the value of its image field being only nginx, when run through the image_normalize() filter will come out docker.io/nginx:latest.

Example: This policy will mutate the value of the image field in a Pod’s containers[] array if, after normalization, it begins with docker.io. The registry will be replaced with harbor.corp.org.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: image-normalize-demo
 5spec:
 6  rules:
 7    - name: replace-image-registry-pod-containers
 8      match:
 9        any:
10        - resources:
11            kinds:
12            - Pod
13      mutate:
14        foreach:
15        - list: "request.object.spec.containers"
16          patchStrategicMerge:
17            spec:
18              containers:
19              - name: "{{ element.name }}"
20                image: "{{ regex_replace_all('^docker.io/(.*)$', image_normalize('{{element.image}}'), 'harbor.corp.org/$1' )}}"

The is_external_url() filter takes a URL string and returns a boolean indicating whether the URL is external. It’s especially useful for handling edge cases in Kubernetes related to internal domain names, ExternalName services pointing to external domain names, and invalid URLs. By utilizing this filter, the policy can more accurately decide whether to block or allow the creation or modification of resources based on the URL’s external status. Additionally, the filter employs local server DNS resolution; if this fails, an error is returned, helping to prevent SSRF attacks.

Example: This policy looks for a field named test within the data section of ConfigMaps and runs is_external_url() to determine if the value associated with test is an external URL.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: check-external-url-in-configmap
 5spec:
 6  validationFailureAction: Enforce
 7  background: false
 8  rules:
 9    - name: validate-external-url
10      match:
11        any:
12        - resources:
13            kinds:
14              - ConfigMap
15      validate:
16        message: "ConfigMap contains an external URL."
17        deny:
18          conditions:
19            all:
20             - key: "{{ request.object.data.test | is_external_url(@) }}"
21              operator: Equals
22              value: true

The items() filter iterates on map keys (ex., annotations or labels) or arrays and converts them to an array of objects with key/value attributes with custom names.

For example, given the following map below

1{
2  "team": "apple",
3  "organization": "banana"
4}

the items() filter can transform this into an array of objects which assigns a key and value of arbitrary name to each of the entries in the map.

 1$ echo '{"team" : "apple" , "organization" : "banana" }' | kyverno jp query "items(@, 'key', 'value')"
 2[
 3  {
 4    "key": "organization",
 5    "value": "banana"
 6  },
 7  {
 8    "key": "team",
 9    "value": "apple"
10  }
11]

It can also work on an input source given as an array of objects.

 1$ echo '[{"team" : "apple"} , {"organization" : "banana"}]' |  kyverno jp query "items(@, 'key', 'value')"
 2Reading from terminal input.
 3Enter input object and hit Ctrl+D.
 4# items(@, 'key', 'value')
 5[
 6  {
 7    "key": 0,
 8    "value": {
 9      "team": "apple"
10    }
11  },
12  {
13    "key": 1,
14    "value": {
15      "organization": "banana"
16    }
17  }
18]

Related filter to items() is its inverse, object_from_lists().

Example: This policy will take the labels on a Namespace foobar where a Bucket is deployed and add them as key/value elements to the spec.forProvider.tagging.tagSet[] array.

 1apiVersion : kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: test-policy
 5spec:
 6  background: false
 7  rules:
 8  - name: test-rule
 9    match:
10      any:
11      - resources:
12          kinds:
13          - Bucket
14    context:
15    - name: nslabels
16      apiCall:
17        urlPath: /api/v1/namespaces/foobar
18        jmesPath: items(metadata.labels,'key','value')
19    mutate:
20      foreach:
21      - list: "nslabels"
22        patchesJson6902: |-
23          - path: "/spec/forProvider/tagging/tagSet/-1"
24            op: add
25            value:
26              key: "{{element.key}}"
27              value": "{{element.value}}"          

Given a Namespace which looks like the following

1apiVersion: v1
2kind: Namespace
3metadata:
4  name: foobar
5  labels:
6    team: apple
7    organization: banana

and a Bucket which looks like the below

 1apiVersion: s3.aws.crossplane.io/v1beta1
 2kind: Bucket
 3metadata:
 4  name: lambda-bucket
 5spec:
 6  forProvider:
 7    acl: private
 8    locationConstraint: eu-central-1
 9    accelerateConfiguration:
10      status: Enabled
11    versioningConfiguration:
12      status: Enabled
13    notificationConfiguration:
14      lambdaFunctionConfigurations:
15        - events: ["s3:ObjectCreated:*"]
16          lambdaFunctionArn: arn:aws:lambda:eu-central-1:255932642927:function:lambda
17    paymentConfiguration:
18      payer: BucketOwner
19    tagging:
20      tagSet:
21        - key: s3-bucket
22          value: lambda-bucket
23    objectLockEnabledForBucket: false
24  providerConfigRef:
25    name: default

the final spec.forProvider.tagging.tagSet[] will appear as below. Note that as of Kubernetes 1.21, the immutable label with key kubernetes.io/metadata.name and value equal to that of the Namespace name is automatically added to all Namespaces, hence the discrepancy when comparing Namespace with Bucket resource manifests above.

 1$ kubectl get bucket lambda-bucket -o json | kyverno jp query "spec.forProvider.tagging.tagSet[]"
 2[
 3  {
 4    "key": "s3-bucket",
 5    "value": "lambda-bucket"
 6  },
 7  {
 8    "key": "kubernetes.io/metadata.name",
 9    "value": "foobar"
10  },
11  {
12    "key": "organization",
13    "value": "banana"
14  },
15  {
16    "key": "team",
17    "value": "apple"
18  }
19]

The label_match() filter compares two sets of Kubernetes labels (both key and value) and outputs a boolean response if they are equivalent. This custom filter is useful in that it functions similarly to how the Kubernetes API server associates one resource with another through label selectors. There may be one or multiple labels in each set. Labels may occur in any order. A response of true indicates all the labels (key and value) in the first input are accounted for in the second input. The second input, to which the first is compared, may have additional labels but it must have at minimum all those listed in the first input.

For example, the first collection compared to the second below results in true despite the ordering.

1{
2  "dog": "lab",
3  "color": "tan"
4}

1{
2  "color": "tan",
3  "dog": "lab"
4}

Likewise, these two below collections also result in true when compared because the entirety of the first is found within the second.

1{
2  "dog": "lab",
3  "color": "tan"
4}

1{
2  "color": "tan",
3  "weight":"chonky",
4  "dog": "lab"
5}

These last two collections when compared are false because one of the values of one of the labels does not match what is in the first input.

1{
2  "dog": "lab",
3  "color": "tan"
4}

1{
2  "color": "black",
3  "dog": "lab"
4}

Example: This policy checks all incoming Deployments to ensure they have a matching, preexisting PodDisruptionBudget in the same Namespace. The label_match() filter is used in a query to count how many PDBs have a label set matching that of the incoming Deployment.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: require-pdb
 5spec:
 6  validationFailureAction: Audit
 7  background: false
 8  rules:
 9  - name: require-pdb
10    match:
11      any:
12      - resources:
13          kinds:
14          - Deployment
15          operations:
16          - CREATE
17    context:
18    - name: pdb_count
19      apiCall:
20        urlPath: "/apis/policy/v1beta1/namespaces/{{request.namespace}}/poddisruptionbudgets"
21        jmesPath: "items[?label_match(spec.selector.matchLabels, `{{request.object.spec.template.metadata.labels}}`)] | length(@)"
22    validate:
23      message: "There is no corresponding PodDisruptionBudget found for this Deployment."
24      deny:
25        conditions:
26          any:
27          - key: "{{pdb_count}}"
28            operator: LessThan
29            value: 1

The lookup() function returns the value for the given key/index in an object/array. While the JMESPath language allows lookups with constant keys/indexes only, the lookup() function supports arbitrary JMESPath expressions, thus enabling dynamic lookups.

Parameters:

• Input 1: The object or array to look into.
• Input 2: The key of type String to look up in the object or the index of type Number to look up in the array. Array indexes must be integer numbers.
• Output: The value corresponding to the key or index, or null if the key or index does not exist.

Examples:

Example object lookup

A policy denies a pod if at least one container has an AppArmor profile other than runtime/default configured via annotation container.apparmor.security.beta.kubernetes.io/<container_name>:

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: lookup-demo
 5spec:
 6  rules:
 7  - name: demo
 8    match:
 9      all:
10      - resources:
11          kinds:
12          - v1/Pod
13        namespaces:
14        - lookup-demo
15    validate:
16      message: Using AppArmor profiles other than 'runtime/default' is forbidden
17      deny:
18        conditions:
19          all:
20          - key: |-
21              request.object.spec.[initContainers,containers] || `[]`
22              |
23              []
24              |
25              [?
26                (
27                  lookup(
28                    `{{ request.object.metadata.annotations || `{}` }}`
29                    ,
30                    join('', ['container.apparmor.security.beta.kubernetes.io/', name])
31                  )
32                  || 'runtime/default'
33                ) != 'runtime/default'
34              ]              
35            operator: NotEquals
36            value: []

Example array lookup

Randomly select an entry from an array:

1$ cat <<EOF | kubectl kyverno jp query "lookup(@, modulo(random('[0-9]{1,6}') | parse_json(@), length(@)))"
2- item1
3- item2
4- item3
5EOF

The modulo() filter returns the modulo or remainder between a division of two numbers. For example, the modulo of a division between 10 and 3 would be 1 since 3 can be divided into 10 only 3 times (equaling 9) while producing 1 as a remainder.

Arithmetic filters like modulo() currently accept inputs in the following formats.

• Number (ex., `10`)
• Quantity (ex., ‘10Mi’)
• Duration (ex., ‘10h’)

Note that how the inputs are enclosed determines how Kyverno interprets their type. Numbers enclosed in back ticks are scalar values while quantities and durations are enclosed in single quotes thus treating them as strings. Using the correct enclosing character is important because, in Kubernetes “regular” numbers are treated implicitly as units of measure. The number written `10` is interpreted as an integer or “the number ten” whereas ‘10’ is interpreted as a string or “ten bytes”. See the Formatting section above for more details.

Example: This policy checks every container and ensures that memory limits are evenly divisible by its requests.

 1apiVersion : kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: modulo-demo
 5spec:
 6  validationFailureAction: Audit
 7  rules:
 8  - name: check-memory-requests-limits
 9    match:
10      any:
11      - resources:
12          kinds:
13          - Pod
14          operations:
15          - CREATE
16          - UPDATE
17    validate:
18      message: Limits must be evenly divisible by the requests.
19      foreach:
20      - list: "request.object.spec.containers"
21        deny:
22          conditions:
23            any:
24              # Set resources.limits.memory equal to zero if not present and resources.requests.memory equal to 1m rather than zero
25              # to avoid undefined division error. No memory request in this case is basically the same as 1m. Kubernetes API server
26              # will automatically set requests=limits if only limits is defined.
27            - key: "{{ modulo('{{ element.resources.limits.memory || '0' }}', '{{ element.resources.requests.memory || '1m' }}') }}"
28              operator: GreaterThan
29              value: 0

The multiply() filter performs standard multiplication on two inputs producing an output product. Like other arithmetic filters, it is input aware and will produce output with appropriate units attached.

Arithmetic filters like multiply() currently accept inputs in the following formats.

• Number (ex., `10`)
• Quantity (ex., ‘10Mi’)
• Duration (ex., ‘10h’)

Note that how the inputs are enclosed determines how Kyverno interprets their type. Numbers enclosed in back ticks are scalar values while quantities and durations are enclosed in single quotes thus treating them as strings. Using the correct enclosing character is important because, in Kubernetes “regular” numbers are treated implicitly as units of measure. The number written `10` is interpreted as an integer or “the number ten” whereas ‘10’ is interpreted as a string or “ten bytes”. See the Formatting section above for more details.

Due to the commutative property of multiplication, the ordering of inputs (unlike with divide()) is irrelevant.

Example: This policy sets the replica count for a Deployment to a value of two times the current number of Nodes in a cluster.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: multiply-demo
 5spec:
 6  background: false
 7  rules:
 8    - name: multiply-replicas
 9      match:
10        any:
11        - resources:
12            kinds:
13            - Deployment
14      context:
15        - name: nodecount
16          apiCall:
17            urlPath: "/api/v1/nodes"
18            jmesPath: "items[] | length(@)"
19      mutate:
20        patchStrategicMerge:
21          spec:
22            replicas: "{{ multiply( `{{nodecount}}`,`2`) }}"

The object_from_lists() filter takes an array of objects and, based on the selected keys, produces a map. This is essentially the inverse of the items() filter.

For example, given a Pod definition that looks like the following

 1apiVersion: v1
 2kind: Pod
 3metadata:
 4  name: object-from-list-demo
 5  labels:
 6    foo: bar
 7spec:
 8  containers:
 9  - name: containername01
10    image: containerimage:01
11    env:
12    - name: KEY
13      value: "123-456-789"
14    - name: endpoint
15      value: "licensing.corp.org"

you may want to convert the spec.containers[].env[] array of objects into a map where each entry in the map sets the key to the name and the value to the value fields. Running this through the object_from_lists() filter will produce a map containing those entries.

1$ kyverno jp query -i pod.yaml "object_from_lists(spec.containers[].env[].name,spec.containers[].env[].value)"
2{
3  "KEY": "123-456-789",
4  "endpoint": "licensing.corp.org"
5}

Related filter to object_from_lists() is its inverse, items().

Example: This policy converts all the environment variables across all containers in a Pod to labels and adds them to that same Pod. Any existing labels will not be replaced but rather augmented with the converted list.

 1apiVersion : kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: object-from-list-demo
 5  annotations:
 6    pod-policies.kyverno.io/autogen-controllers: none
 7spec:
 8  background: false
 9  rules:
10  - name: object-from-list-rule
11    match:
12      any:
13      - resources:
14          kinds:
15          - Pod
16    context:
17    - name: envs
18      variable:
19        jmesPath: request.object.spec.containers[].env[]
20    - name: envs_to_labels
21      variable:
22        jmesPath: object_from_lists(envs[].name, envs[].value)
23    mutate:
24      patchStrategicMerge:
25        metadata:
26          labels:
27            "{{envs_to_labels}}"

Given an incoming Pod that looks like the following

 1apiVersion: v1
 2kind: Pod
 3metadata:
 4  name: object-from-list-demo
 5  labels:
 6    foo: bar
 7spec:
 8  containers:
 9  - name: containername01
10    image: containerimage:01
11    env:
12    - name: KEY
13      value: "123-456-789"
14    - name: ENDPOINT
15      value: "licensing.corp.org"
16  - name: containername02
17    image: containerimage:02
18    env:
19    - name: ZONE
20      value: "fl-west-03"

after applying the policy the resulting label set on the Pod appears as shown below.

1$ kubectl get pod/object-from-list-demo -o json | kyverno jp query "metadata.labels"
2{
3  "ENDPOINT": "licensing.corp.org",
4  "KEY": "123-456-789",
5  "ZONE": "fl-west-03",
6  "foo": "bar"
7}

The parse_json() filter takes in a string of any valid encoded JSON and parses it into a fully-formed JSON object. This is useful because it allows Kyverno to access and work with string data that is stored anywhere which accepts strings as if it were “native” JSON data. Primary use cases for this filter include adding anything from snippets to whole documents as the values of labels, annotations, or ConfigMaps which should then be consumed by policy.

Example: This policy uses the parse_json() filter to read a ConfigMap where a specified key contains JSON-encoded data (an array of strings in this case) and sets the supplementalGroups field of a Pod, if not already supplied, to that list.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: parse-json-demo
 5spec:
 6  rules:
 7  - name: parse-supplementalgroups-from-json
 8    match:
 9      any:
10      - resources:
11          kinds:
12          - Pod
13    context:
14    - name: gidsMap
15      configMap:
16        name: user-gids-map
17        namespace: default
18    mutate:
19      patchStrategicMerge:
20        spec:
21          securityContext:
22            +(supplementalGroups): "{{ gidsMap.data.\"{{ request.object.metadata.labels.\"corp.com/service-account\" }}\" | parse_json(@)[*].to_number(@) }}"

The referenced ConfigMap may look similar to the below.

1apiVersion: v1
2kind: ConfigMap
3metadata:
4  name: user-gids-map
5  namespace: default
6data:
7  finance: '["1001","1002"]'

The parse_yaml() filter is the YAML equivalent of the parse_json() filter and takes in a string of any valid YAML document, serializes it into JSON, and parses it so it may be processed by JMESPath. Like parse_json(), this is useful because it allows Kyverno to access and work with string data that is stored anywhere which accepts strings as if it were “native” YAML data. Primary use cases for this filter include adding anything from snippets to whole documents as the values of labels, annotations, or ConfigMaps which should then be consumed by policy.

Example: This policy parses a YAML document as the value of an annotation and uses the filtered value from a JMESPath expression in a variable substitution.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: parse-yaml-demo
 5spec:
 6  validationFailureAction: Enforce
 7  background: false
 8  rules:
 9  - name: check-goodbois
10    match:
11      any:
12      - resources:
13          kinds:
14          - Pod
15    validate:
16      message: "Only good bois allowed."
17      deny:
18        conditions:
19        - key: "{{request.object.metadata.annotations.pets | parse_yaml(@).species.isGoodBoi }}"
20          operator: NotEquals
21          value: true

The referenced Pod may look similar to the below.

 1apiVersion: v1
 2kind: Pod
 3metadata:
 4  name: mypod
 5  labels:
 6    app: busybox
 7  annotations:
 8    pets: |-
 9      species:
10        dog: lab
11        name: dory
12        color: black
13        height: 15
14        isGoodBoi: false
15        snacks:
16        - chimken
17        - fries
18        - pizza      
19spec:
20  containers:
21  - name: busybox
22    image: busybox:1.28

The path_canonicalize() filter is used to normalize or canonicalize a given path by removing excess slashes. For example, a path supplied to the filter may be /var//lib///kubelet which will be canonicalized into /var/lib/kubelet which is how an operating system would interpret the former. This filter is primarily used as a circumvention protection for what would otherwise be strict string matches for paths.

Example: This policy uses the path_canonicalize() filter to check the value of each hostPath.path field in a volume block in a Pod to ensure it does not attempt to mount the Containerd host socket.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: path-canonicalize-demo
 5spec:
 6  validationFailureAction: Enforce
 7  background: false
 8  rules:
 9  - name: disallow-mount-containerd-sock
10    match:
11      any:
12      - resources:
13          kinds:
14          - Pod
15    validate:
16      foreach:
17      - list: "request.object.spec.volumes[]"
18        deny:
19          conditions:
20            any:
21            - key: "{{ path_canonicalize(element.hostPath.path) }}"
22              operator: Equals
23              value: "/var/run/containerd/containerd.sock"

The pattern_match() filter is used to perform a simple, non-regex match by specifying an input pattern and the string or number to which it should be compared. The output is always a boolean response. This filter can be useful when wishing to make simpler comparisons, typically with strings or numbers involved. It avoids many of the complexities of regex while still support wildcards such as * (zero or more characters) and ? (any one character). Note that since Kyverno supports overlay-style patterns and wildcards, use of pattern_match() is typically not needed in these scenarios. This filter is more valuable in dynamic lookup scenarios by using JMESPath variables for one or both inputs as exemplified below.

Example: This policy uses pattern_match() with dynamic inputs by fetching a pattern stored in a ConfigMap against an incoming Namespace label value.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: pattern-match-demo
 5spec:
 6  validationFailureAction: Enforce
 7  background: false
 8  rules:
 9  - match:
10      any:
11      - resources:
12          kinds:
13          - Namespace
14    name: dept-billing-check
15    context:
16    - name: deptbillingcodes
17      configMap:
18        name: deptbillingcodes
19        namespace: default
20    validate:
21      message: The department {{request.object.metadata.labels.dept}} must supply a matching billing code.
22      deny:
23        conditions:
24          any:
25            - key: "{{pattern_match('{{deptbillingcodes.data.{{request.object.metadata.labels.dept}}}}', '{{ request.object.metadata.labels.segbill}}') }}"
26              operator: Equals
27              value: false

The ConfigMap used as the source of the patterns may look like below.

1apiVersion: v1
2kind: ConfigMap
3metadata:
4  name: deptbillingcodes
5data:
6  eng_china: 158-6?-3*
7  eng_india: 158-7?-4*
8  busops: 145-0?-9*
9  finops: 145-1?-5*

And a Namespace upon which the above ClusterPolicy may act can look like below.

1apiVersion: v1
2kind: Namespace
3metadata:
4  name: ind-go
5  labels:
6    dept: eng_india
7    segbill: 158-73-417

The random() filter is used to generate a random sequence of string data based upon the input pattern, expressed as regex. The input it takes is a combination of the composition of the pattern and the length of each pattern. This filter is useful in a variety of ways including generating unique resource names. Some other use cases include creating Pod hashes, auth tokens, license keys, GUIDs, and more.

For example, random('[0-9a-z]{5}') will produce a string output of exactly 5 characters long composed of numbers in the collection 0-9 and lower-case letters in the collection a-z. The output might be "91t6f". More complex random output can be created by chaining multiple pattern and length combinations together. For example, to create a faux license key you could use the expression random('[A-Z0-9]{8}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{12}') which may generate the output "K284DW7Y-7LMT-XHR3-ZZ53-36366O8JVDG9".

Example: This policy uses random() to mutate a new Secret to add a label with key randomoutput and the value of which is random- followed by 6 random characters composed of lower-case letters a-z and numbers 0-9.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: ver-test
 5spec:
 6  rules:
 7  - name: test-ver-ver
 8    match:
 9      any:
10      - resources:
11          kinds:
12          - Secret
13          operations:
14          - CREATE
15    context:
16    - name: randomtest
17      variable:
18        jmesPath: random('[a-z0-9]{6}')
19    mutate:
20      patchStrategicMerge:
21        metadata:
22          labels:
23            randomoutput: random-{{randomtest}}

The regex_match() filter is similar to the pattern_match() filter except it accepts standard regular expressions as the comparison format. The first input is the pattern, specified in regex format, while the second is the string compared to the pattern which accepts either string or number. The output is always a boolean response. For example, the following two expressions, which check to ensure a number is in the range of one to seven, both evaluate to true.

regex_match('^[1-7]$',`1`)
regex_match('^[1-7]$','1')

Example: This policy checks that a PersistentVolumeClaim resource contains an annotation named backup-schedule and its value conforms to a standard Cron expression string. Note that the regular expression in the first input has had an additional backslash added to each backslash to be valid YAML. To use this sample regex in other applications, remove one of each double backslash pair.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: regex-match-demo
 5spec:
 6  background: true
 7  validationFailureAction: Enforce
 8  rules:
 9  - name: validate-backup-schedule-annotation-cron
10    match:
11      any:
12      - resources:
13          kinds:
14          - PersistentVolumeClaim
15    validate:
16      message: The annotation `backup-schedule` must be present and in cron format.
17      deny:
18        conditions:
19          any:
20          - key: "{{ regex_match('^((?:\\*|[0-5]?[0-9](?:(?:-[0-5]?[0-9])|(?:,[0-5]?[0-9])+)?)(?:\\/[0-9]+)?)\\s+((?:\\*|(?:1?[0-9]|2[0-3])(?:(?:-(?:1?[0-9]|2[0-3]))|(?:,(?:1?[0-9]|2[0-3]))+)?)(?:\\/[0-9]+)?)\\s+((?:\\*|(?:[1-9]|[1-2][0-9]|3[0-1])(?:(?:-(?:[1-9]|[1-2][0-9]|3[0-1]))|(?:,(?:[1-9]|[1-2][0-9]|3[0-1]))+)?)(?:\\/[0-9]+)?)\\s+((?:\\*|(?:[1-9]|1[0-2])(?:(?:-(?:[1-9]|1[0-2]))|(?:,(?:[1-9]|1[0-2]))+)?)(?:\\/[0-9]+)?)\\s+((?:\\*|[0-7](?:-[0-7]|(?:,[0-7])+)?)(?:\\/[0-9]+)?)$', '{{request.object.metadata.annotations.\"backup-schedule\" || ''}}') }}"
21            operator: Equals
22            value: false

The regex_replace_all() filter is similar to the replace_all() filter only differing by the first and third inputs being a valid regular expression rather than a static string. For literal replacement, see regex_replace_all_literal(). If numbers are supplied for the second and third inputs, they will internally be converted to string. The output is always a string. For example, the expression regex_replace_all('([0-9])([0-9])', 'hello im 42 months old', '${1}1') results in the output hello im 41 months old. The first input provides the regex which should be used to match against the second input, and the third serves as the replacement which, in this case, replaces the first capture group from the end with the number 1.

Example: This policy mutates a Deployment having label named retention to set the last number to 0. For example, an incoming Deployment with the label value of days_37 would result in the value days_30 after mutation.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: regex-replace-all-demo
 5spec:
 6  background: false
 7  rules:
 8  - name: retention-adjust
 9    match:
10      any:
11      - resources:
12          kinds:
13          - Deployment
14    mutate:
15      patchStrategicMerge:
16        metadata:
17          labels:
18            retention: "{{ regex_replace_all('([0-9])([0-9])', '{{ @ }}', '${1}0') }}"

The regex_replace_all_literal() filter is similar to the regex_replace_all() filter with the third input being a static string used for literal replacement. If numbers are supplied for the second and third inputs, they will internally be converted to string. The output is always a string. For example, the expression regex_replace_all_literal('^(\d{3}-?\d{2}-?\d{4})$', '123-45-6789', 'redacted') would return redacted as the regex filter matches the faux social security number of 123-45-6789.

Example: This policy replaces the image registry for each image in every container so it comes from myregistry.corp.com. Note that, for images without an explicit registry such as nginx:latest, Kyverno will internally replace this to be docker.io/nginx:latest and thereby ensuring the regex pattern below matches.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: regex-replace-all-literal-demo
 5spec:
 6  background: false
 7  rules:
 8    - name: replace-image-registry
 9      match:
10        any:
11        - resources:
12            kinds:
13              - Pod
14      mutate:
15        foreach:
16        - list: "request.object.spec.containers"
17          patchStrategicMerge:
18            spec:
19              containers:
20              - name: "{{ element.name }}"
21                image: "{{ regex_replace_all_literal('^[^/]+', '{{element.image}}', 'myregistry.corp.com' )}}"

The replace() filter is similar to the replace_all() filter except it takes a fourth input (a number) to specify how many instances of the source string should be replaced with the replacement string in a parent. For example, the expression shown below results in the value Lorem muspi dolor sit amet foo muspi bar ipsum because only two instances of the string ipsum were requested to be replaced. String replacement begins at the left and proceeds to the right halting once the desired count has been reached. If -1 is specified for the four input, it results in all instances of the source string being replaced (effectively the same behavior as replace_all()).

replace('Lorem ipsum dolor sit amet foo ipsum bar ipsum', 'ipsum', 'muspi', `2`)

Example: This policy replaces the rule on an Ingress resource so that the path field will replace the first instance of /cart with /shoppingcart.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: replace-demo
 5spec:
 6  background: false
 7  rules:
 8    - name: replace-path
 9      match:
10        any:
11        - resources:
12            kinds:
13              - Ingress
14      mutate:
15        foreach:
16        - list: "request.object.spec.rules[].http.paths[]"
17          patchStrategicMerge:
18            spec:
19              rules:
20              - http:
21                  paths:
22                  - backend:
23                      service:
24                        name: kuard
25                        port:
26                          number: 8080
27                    path: "{{ replace('{{element.path}}', '/cart', '/shoppingcart', `1`) }}"
28                    pathType: ImplementationSpecific