Validate Resources

Validation rules are probably the most common and practical types of rules you will be working with, and the main use case for admission controllers such as Kyverno. In a typical validation rule, one defines the mandatory properties with which a given resource should be created. When a new resource is created by a user or process, the properties of that resource are checked by Kyverno against the validate rule. If those properties are validated, meaning there is agreement, the resource is allowed to be created. If those properties are different, the creation is blocked. The behavior of how Kyverno responds to a failed validation check is determined by the validationFailureAction field. It can either be blocked (enforce) or noted in a policy report (audit). Validation rules in audit mode can also be used to get a report on matching resources which violate the rule(s), both upon initial creation and when Kyverno initiates periodic scans of Kubernetes resources. Resources in violation of an existing rule placed in audit mode will also surface in an event on the resource in question.

To validate resource data, define a pattern in the validation rule. To deny certain API requests define a deny element in the validation rule along with a set of conditions that control when to allow or deny the request.

Basic Validations

As a basic example, consider the below ClusterPolicy which validates that any new Namespace that is created has the label purpose with the value of production.

 1apiVersion: kyverno.io/v1
 2# The `ClusterPolicy` kind applies to the entire cluster.
 3kind: ClusterPolicy
 4metadata:
 5  name: require-ns-purpose-label
 6# The `spec` defines properties of the policy.
 7spec:
 8  # The `validationFailureAction` tells Kyverno if the resource being validated should be allowed but reported (`audit`) or blocked (`enforce`).
 9  validationFailureAction: enforce
10  # The `rules` is one or more rules which must be true.
11  rules:
12  - name: require-ns-purpose-label
13    # The `match` statement sets the scope of what will be checked. In this case, it is any `Namespace` resource.
14    match:
15      resources:
16        kinds:
17        - Namespace
18    # The `validate` statement tries to positively check what is defined. If the statement, when compared with the requested resource, is true, it is allowed. If false, it is blocked.
19    validate:
20      # The `message` is what gets displayed to a user if this rule fails validation and is therefore blocked.
21      message: "You must have label `purpose` with value `production` set on all new namespaces."
22      # The `pattern` object defines what pattern will be checked in the resource. In this case, it is looking for `metadata.labels` with `purpose=production`.
23      pattern:
24        metadata:
25          labels:
26            purpose: production

If a new Namespace with the following definition is submitted to Kyverno, given the ClusterPolicy above, it will be allowed (validated). This is because it contains the label of purpose=production, which is the only pattern being validated in the rule.

1apiVersion: v1
2kind: Namespace
3metadata:
4  name: prod-bus-app1
5  labels:
6    purpose: production

By contrast, if a new Namespace with the below definition is submitted, given the ClusterPolicy above, it will be blocked (invalidated). As you can see, its value of the purpose label differs from that required in the policy. But this isn’t the only way a validation can fail. If, for example, the same Namespace is requested which has no labels defined whatsoever, it too will be blocked for the same reason.

1apiVersion: v1
2kind: Namespace
3metadata:
4  name: prod-bus-app1
5  labels:
6    purpose: development

Save the above manifest as ns.yaml and try to create it with your sample ClusterPolicy in place.

1$ kubectl create -f ns.yaml
2Error from server: error when creating "ns.yaml": admission webhook "validate.kyverno.svc" denied the request: 
3
4resource Namespace//prod-bus-app1 was blocked due to the following policies
5
6require-ns-purpose-label:
7  require-ns-purpose-label: 'Validation error: You must have label `purpose` with value `production` set on all new namespaces.; Validation rule require-ns-purpose-label failed at path /metadata/labels/purpose/'

Change the development value to production and try again. Kyverno permits creation of your new Namespace resource.

Validation Failure Action

The validationFailureAction attribute controls admission control behaviors for resources that are not compliant with a policy. If the value is set to enforce, resource creation or updates are blocked when the resource does not comply. When the value is set to audit, a policy violation is logged in a PolicyReport or ClusterPolicyReport but the resource creation or update is allowed.

Patterns

A validation rule which checks resource data is defined as an overlay pattern that provides the desired configuration. Resource configurations must match fields and expressions defined in the pattern to pass the validation rule. The following rules are followed when processing the overlay pattern:

1. Validation will fail if a field is defined in the pattern and if the field does not exist in the configuration.
2. Undefined fields are treated as wildcards.
3. A validation pattern field with the wildcard value ‘*’ will match zero or more alphanumeric characters. Empty values are matched. Missing fields are not matched.
4. A validation pattern field with the wildcard value ‘?’ will match any single alphanumeric character. Empty or missing fields are not matched.
5. A validation pattern field with the wildcard value ‘?*’ will match any alphanumeric characters and requires the field to be present with non-empty values.
6. A validation pattern field with the value null or "" (empty string) requires that the field not be defined or has no value.
7. The validation of siblings is performed only when one of the field values matches the value defined in the pattern. You can use the conditional anchor to explicitly specify a field value that must be matched. This allows writing rules like ‘if fieldA equals X, then fieldB must equal Y’.
8. Validation of child values is only performed if the parent matches the pattern.

Wildcards

1. * - matches zero or more alphanumeric characters
2. ? - matches a single alphanumeric character

For a couple of examples on how wildcards work in rules, see the following.

This policy requires that all containers in all Pods have CPU and memory resource requests and limits defined:

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: all-containers-need-requests-and-limits
 5spec:
 6  validationFailureAction: enforce
 7  rules:
 8  - name: check-container-resources
 9    match:
10      resources:
11        kinds:
12        - Pod
13    validate:
14      message: "All containers must have CPU and memory resource requests and limits defined."
15      pattern:
16        spec:
17          containers:
18          # Select all containers in the pod. The `name` field here is not specifically required but serves
19          # as a visual aid for instructional purposes.
20          - name: "*"
21            resources:
22              limits:
23                # '?' requires 1 alphanumeric character and '*' means that
24                # there can be 0 or more characters. Using them together
25                # e.g. '?*' requires at least one character.
26                memory: "?*"
27                cpu: "?*"
28              requests:
29                memory: "?*"
30                cpu: "?*"

The following validation rule checks for a label in Deployment, StatefulSet, and DaemonSet resources:

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: check-label-app
 5spec:
 6  validationFailureAction: enforce
 7  rules:
 8    - name: check-label-app
 9      match:
10        resources:
11          kinds:
12          - Deployment
13          - StatefulSet
14          - DaemonSet
15      validate:
16        message: "The label `app` is required."
17        pattern:
18          spec:
19            template:
20              metadata:
21                labels:
22                  app: "?*"

Operators

Operators in the following support list values as of Kyverno 1.3.6 in addition to scalar values.

Anchors

Anchors allow conditional processing (i.e. “if-then-else”) and other logical checks in validation patterns. The following types of anchors are supported:

Anchors and child elements: Conditional and Equality

Child elements are handled differently for conditional and equality anchors.

For conditional anchors, the child element is considered to be part of the “if” clause, and all peer elements are considered to be part of the “then” clause. For example, consider the following ClusterPolicy pattern statement:

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: conditional-anchor-dockersock
 5spec:
 6  validationFailureAction: enforce
 7  background: false
 8  rules:
 9  - name: conditional-anchor-dockersock
10    match:
11      resources:
12        kinds:
13        - Pod
14    validate:
15      message: "If a hostPath volume exists and is set to `/var/run/docker.sock`, the label `allow-docker` must equal `true`."
16      pattern:
17        metadata:
18          labels:
19            allow-docker: "true"
20        (spec):
21          (volumes):
22          - (hostPath):
23              path: "/var/run/docker.sock"

This reads as “If a hostPath volume exists and the path equals /var/run/docker.sock, then a label “allow-docker” must be specified with a value of true.” In this case, the conditional checks the spec.volumes and spec.volumes.hostPath map. The child element of spec.volumes.hostPath is the path key and so the check ends the “If” evaluation at path. The entire metadata object is a peer element to the spec object because these reside at the same hierarchy within a Pod definition. Therefore, conditional anchors can not only compare peers when they are simple key/value, but also when peers are objects or YAML maps.

For equality anchors, a child element is considered to be part of the “then” clause. Now, consider the same ClusterPolicy as above but using equality anchors:

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: equality-anchor-no-dockersock
 5spec:
 6  validationFailureAction: enforce
 7  background: false
 8  rules:
 9  - name: equality-anchor-no-dockersock
10    match:
11      resources:
12        kinds:
13        - Pod
14    validate:
15      message: "If a hostPath volume exists, it must not be set to `/var/run/docker.sock`."
16      pattern:
17        =(spec):
18          =(volumes):
19          - =(hostPath):
20              path: "!/var/run/docker.sock"

This is read as “If a hostPath volume exists, then the path must not be equal to /var/run/docker.sock”. In this sample, the object spec.volumes.hostPath is being checked, which is where the “If” evaluation ends. Similar to the conditional example above, the path key is a child to hostPath and therefore is the one being evaluated under the “then” check.

Existence anchor: At Least One

The existence anchor is used to check that, in a list of elements, at least one element exists that matches the pattern. This is done by using the ^() notation for the field. The existence anchor only works on array/list type data.

For example, this pattern will check that at least one container is using an image named nginx:latest:

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: existence-anchor-at-least-one-nginx
 5spec:
 6  validationFailureAction: enforce
 7  rules:
 8  - name: existence-anchor-at-least-one-nginx
 9    match:
10      resources:
11        kinds:
12        - Pod
13    validate:
14      message: "At least one container must use the image `nginx:latest`."
15      pattern:
16        spec:
17          ^(containers):
18            - image: nginx:latest

Contrast this existence anchor, which checks for at least one instance, with a wildcard which checks for every instance.

1      pattern:
2        spec:
3          containers:
4          - name: "*"
5            image: nginx:latest

This snippet above instead states that every entry in the array of containers, regardless of name, must have the image set to nginx:latest.

anyPattern

In some cases, content can be defined at different levels. For example, a security context can be defined at the Pod or Container level. The validation rule should pass if either one of the conditions is met.

The anyPattern tag is a logical OR across multiple validation patterns and can be used to check if any one of the patterns in the list match.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: check-root-user
 5spec:
 6  validationFailureAction: enforce
 7  background: false
 8  rules:
 9  - name: check-root-user
10    exclude:
11      resources:
12        namespaces:
13        - kube-system
14    match:
15      resources:
16        kinds:
17        - Pod
18    validate:
19      message: "Root user is not allowed. Set runAsNonRoot to true."
20      anyPattern:
21      # Checks for `runAsNonRoot` on the Pod.
22      - spec:
23          securityContext:
24            runAsNonRoot: true
25      # Checks for `runAsNonRoot` on every container.
26      - spec:
27          containers:
28          # The `name` field here is not specifically required but rather used
29          # as a visual aid for instructional purposes.
30          - name: "*"
31            securityContext:
32              runAsNonRoot: true

The anyPattern method is best suited for validation cases which do not use a negated condition. In the above example, only one of the spec contents must be valid. The same is true of negated conditions, however in the below example, this is slightly more difficult to reason about in that when negated, the anyPattern option allows any resource to pass so long as it doesn’t have at least one of the patterns.

1validate:
2  message: Cannot use Flux v1 annotation.
3  anyPattern:
4  - metadata:
5      =(annotations):
6        X(fluxcd.io/*): "*?"
7  - metadata:
8      =(annotations):
9        X(flux.weave.works/*): "*?"

If the desire is to state, “neither annotation named fluxcd.io/ nor flux.weave.works/ may be present”, then this would need two separate rules to express as including either one would mean the other is valid and therefore the resource is allowed.

Deny rules

In addition to applying patterns to check resources, a validation rule can deny a request based on a set of conditions. A deny condition is useful for applying fine-grained access controls that cannot otherwise be performed using native Kubernetes RBAC, or when wanting to explicitly deny requests based upon operations performed against existing objects.

You can use match and exclude to select when the rule should be applied and then use additional conditions in the deny declaration to apply fine-grained controls.

Also see using Preconditions for matching rules based on variables. deny statements can similarly use any and all blocks like those available to preconditions.

In addition to admission review request data, user information, and built-in variables, deny rules and preconditions can also operate on ConfigMap data, and in the future data from API server lookups, etc.

Deny DELETE requests based on labels

This policy denies delete requests for objects with the label app.kubernetes.io/managed-by: kyverno and for all users who do not have the cluster-admin role.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: deny-deletes
 5spec:
 6  validationFailureAction: enforce
 7  background: false
 8  rules:
 9  - name: block-deletes-for-kyverno-resources
10    match:
11      resources:
12        selector:
13          matchLabels:
14            app.kubernetes.io/managed-by: kyverno
15    exclude:
16      clusterRoles:
17      - cluster-admin
18    validate:
19      message: "Deleting {{request.oldObject.kind}}/{{request.oldObject.metadata.name}} is not allowed"
20      deny:
21        conditions:
22        - key: "{{request.operation}}"
23          operator: In
24          value:
25          - DELETE

Block changes to a custom resource

This policy denies admission review requests for updates or deletes to a custom resource, unless the request is from a specific service account or matches specified roles.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: block-updates-to-custom-resource
 5spec:
 6  validationFailureAction: enforce
 7  background: false
 8  rules:
 9  - name: block-updates-to-custom-resource
10    match:
11      resources:
12        kinds:
13        - SomeCustomResource
14    exclude:
15      subjects:
16      - kind: ServiceAccount
17        name: custom-controller
18      clusterRoles:
19      - custom-controller:*
20      - cluster-admin
21    validate:
22      message: "Modifying or deleting this custom resource is forbidden."
23      deny: {}

Prevent changing NetworkPolicy resources

This policy prevents users from changing NetworkPolicy resources with names that end with -default.

 1apiVersion: kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: deny-netpol-changes
 5spec:
 6  validationFailureAction: enforce
 7  background: false
 8  rules:
 9  - name: deny-netpol-changes
10    match:
11      resources:
12        kinds:
13        - NetworkPolicy
14        name: "*-default"
15    exclude:
16      clusterRoles:
17      - cluster-admin
18    validate:
19      message: "Changing default network policies is not allowed."
20      deny: {}

foreach

The foreach declaration simplifies validation of sub-elements in resource declarations, for example Containers in a Pod.

A foreach declaration can contain multiple entries to process different sub-elements e.g. one to process a list of containers and another to process the list of initContainers in a Pod.

Each foreach entry must contain a list attribute that defines the sub-elements it processes. For example, iterating over the list of containers in a Pod is performed using this list declaration:

1list: request.object.spec.containers

When a foreach is processed, the Kyverno engine will evaluate list as a JMESPath expression to retrieve zero or more sub-elements for further processing.

A variable element is added to the processing context on each iteration. This allows referencing data in the element using element.<name> where name is the attribute name. For example, using the list request.object.spec.containers when the request.object is a Pod allows referencing the container image as element.image within a foreach.

The following child declarations are permitted in a foreach:

• Patterns
• AnyPatterns
• Deny

In addition, each foreach declaration can contain the following declarations:

• Context: to add additional external data only available per loop iteration.
• Preconditions: to control when a loop iteration is skipped

Here is a complete example to enforce that all container images are from a trusted registry:

 1apiVersion : kyverno.io/v1
 2kind: ClusterPolicy
 3metadata:
 4  name: check-images
 5spec:
 6  validationFailureAction: enforce
 7  background: false
 8  rules:
 9  - name: check-registry
10    match:
11      resources:
12        kinds:
13        - Pod
14    preconditions:
15      - key: "{{request.type}}"
16        operator: NotEquals
17        value: "DELETE"
18    validate:
19      message: "unknown registry"  
20      foreach:
21      - list: "request.object.spec.initContainers"
22        pattern:
23          image: "trusted-registry.io/*"      
24      - list: "request.object.spec.containers"
25        pattern:
26          image: "trusted-registry.io/*"

Note that the pattern is applied to the element and hence does not need to specify spec.containers and can directly reference the attributes of the element, which is a container in the example above.