Exceptions

Although Kyverno policies contain multiple methods to provide fine-grained control as to which resources they act upon in the form of match/exclude blocks, preconditions at multiple hierarchies, anchors, and more, all these mechanisms have in common that the resources which they are intended to exclude must occur in the same rule definition. This may be limiting in situations where policies may not be directly editable, or doing so imposes an operational burden.

For example, in organizations where multiple teams must interact with the same cluster, a team responsible for policy authoring and administration may not be the same team responsible for submission of resources. In these cases, it can be advantageous to decouple the policy definition from certain exclusions. Additionally, there are often times where an organization or team must allow certain exceptions which would violate otherwise valid rules but on a one-time basis if the risks are known and acceptable. Imagine a validate policy exists in the cluster and in Enforce mode which mandates all Pods must not mount host namespaces. A separate team has a legitimate need to run a specific tool in this cluster for a limited time which violates this policy. Normally, the policy would block such a “bad” Pod if the policy was not previously altered in such a way to allow said Pod to run. Rather than making adjustments to the policy, an exception may be granted. Both of these examples are use cases for a PolicyException resource described below.

A PolicyException is a Namespaced Custom Resource which allows a resource(s) to be allowed past a given policy and rule combination. It can be used to exempt any resource from any Kyverno rule type although it is primarily intended for use with validate rules. A PolicyException encapsulates the familiar match/exclude statements used in Policy and ClusterPolicy resources but adds an exceptions{} object to select the policy and rule name(s) used to form the exception. The logical flow of how a PolicyException works in tandem with a validate policy is depicted below.

An example set of resources is shown below.

A ClusterPolicy exists containing a single validate rule in Enforce mode which requires all Pods must not use any host namespaces via the fields hostPID, hostIPC, or hostNetwork. If any of these fields are defined, they must be set to a value of false.

 1apiVersion: kyverno.io/v2beta1
 2kind: ClusterPolicy
 3metadata:
 4  name: disallow-host-namespaces
 5spec:
 6  validationFailureAction: Enforce
 7  background: false
 8  rules:
 9    - name: host-namespaces
10      match:
11        any:
12        - resources:
13            kinds:
14              - Pod
15      validate:
16        message: >-
17          Sharing the host namespaces is disallowed. The fields spec.hostNetwork,
18          spec.hostIPC, and spec.hostPID must be unset or set to `false`.          
19        pattern:
20          spec:
21            =(hostPID): "false"
22            =(hostIPC): "false"
23            =(hostNetwork): "false"

A cluster administrator wishes to grant an exception to a Pod or Deployment named important-tool which will be created in the delta Namespace. A PolicyException resource is created which specifies the policy name and rule name which should be bypassed as well as the resource kind, Namespace, and name which may bypass it.

 1apiVersion: kyverno.io/v2alpha1
 2kind: PolicyException
 3metadata:
 4  name: delta-exception
 5  namespace: delta
 6spec:
 7  exceptions:
 8  - policyName: disallow-host-namespaces
 9    ruleNames:
10    - host-namespaces
11    - autogen-host-namespaces
12  match:
13    any:
14    - resources:
15        kinds:
16        - Pod
17        - Deployment
18        namespaces:
19        - delta
20        names:
21        - important-tool*

A Deployment matching the characteristics defined in the PolicyException, shown below, will be allowed creation even though it technically violates the rule’s definition.

 1apiVersion: apps/v1
 2kind: Deployment
 3metadata:
 4  name: important-tool
 5  namespace: delta
 6  labels:
 7    app: busybox
 8spec:
 9  replicas: 1
10  selector:
11    matchLabels:
12      app: busybox
13  template:
14    metadata:
15      labels:
16        app: busybox
17    spec:
18      hostIPC: true
19      containers:
20      - image: busybox:1.35
21        name: busybox
22        command: ["sleep", "1d"]

PolicyExceptions are always Namespaced yet may provide an exception for a cluster-scoped resource as well. There is no correlation between the Namespace in which the PolicyException exists and the Namespace where resources may be excepted.

Exceptions against a ClusterPolicy and those against a (Namespaced) Policy can be disambiguated by specifying the value of the exceptions[].policyName field in the format <namespace>/<policy-name>.

1exceptions:
2- policyName: team-a/disallow-host-namespaces
3  ruleNames:
4  - host-namespaces

Since PolicyExceptions are just another Custom Resource, their use can and should be controlled by a number of different mechanisms to ensure their creation in a cluster is authorized including:

• Kubernetes RBAC
• Specific Namespace for PolicyExceptions (see Container Flags)
• Existing GitOps governance processes
• Kyverno validate rules
• YAML manifest validation

PolicyExceptions may be subjected to Kyverno validate policies which can be used to provide additional guardrails around how they may be crafted. For example, it is considered a best practice to only allow very narrow exceptions to a much broader rule. Given the case shown earlier, only a Pod or Deployment with the name important-tool would be allowed by the exception, not any Pod or Deployment. Kyverno policy can help ensure, both in the cluster and in a CI/CD process via the CLI, that PolicyExceptions conform to your design standards. Below is an example of a sample policy to illustrate how a Kyverno validate rule ensure that a specific name must be used when creating an exception. For other samples, see the policy library.

 1apiVersion: kyverno.io/v2beta1
 2kind: ClusterPolicy
 3metadata:
 4  name: policy-for-exceptions
 5spec:
 6  validationFailureAction: Enforce
 7  background: false
 8  rules:
 9  - name: require-match-name
10    match:
11      any:
12      - resources:
13          kinds:
14          - PolicyException
15    validate:
16      message: >-
17                An exception must explicitly specify a name for a resource match.
18      pattern:
19        spec:
20          match:
21            =(any):
22            - resources:
23                names: "?*"
24            =(all):
25            - resources:
26                names: "?*"