Select Resources
match and exclude to filter and select resources.The match and exclude filters control which resources policies are applied to.
The match and exclude clauses have the same structure and can each contain only one of the two elements:
any: specify resource filters on which Kyverno will perform the logical OR operation while choosing resourcesall: specify resource filters on which Kyverno will perform the logical AND operation while choosing resources
Resource Filters
The following resource filters can be specified under an any or all clause.
resources: select resources by names, namespaces, kinds, label selectors, annotations, and namespace selectors.subjects: select users, user groups, and service accountsroles: select namespaced rolesclusterRoles: select cluster wide roles
Note
Specifying resource filters directly undermatch and exclude has been marked for deprecation and will be removed in a future release. It is highly recommended you specify them under any or all blocks.
At least one element must be specified in a match.(any/all).resources.kinds or exclude block. The kind attribute is mandatory when working with the resources element. Wildcards (*) are currently not supported in the match.(any/all).resources.kinds field.
In addition, a user may specify the group and apiVersion with a kind in the match / exclude declarations for a policy rule.
Supported formats:
Group/Version/KindVersion/KindKind
To resolve kind naming conflicts, specify the API group and version. For example, the Kubernetes API, Calico, and Antrea all register a Kind with the name NetworkPolicy.
These can be distinguished as:
networking.k8s.io/v1/NetworkPolicycrd.antrea.io/v1alpha1/NetworkPolicy
When Kyverno receives an admission controller request (i.e., a validation or mutation webhook), it first checks to see if the resource and user information matches or should be excluded from processing. If both checks pass, then the rule logic to mutate, validate, or generate resources is applied.
Match statements
In any rule statement, there must be a single match statement to function as the filter to which the rule will apply. Although the match statement can be complex having many different elements, there must be at least one. The most common type of element in a match statement is one which filters on categories of Kubernetes resources, for example Pods, Deployments, Services, Namespaces, etc. Variable substitution is not currently supported in match or exclude statements.
In this snippet, the match statement matches on all resources that EITHER have the kind Service with name “staging” OR have the kind Service and are being created in the “prod” Namespace.
1spec:
2 rules:
3 - name: no-LoadBalancer
4 match:
5 any:
6 - resources:
7 kinds:
8 - Service
9 names:
10 - "staging"
11 - resources:
12 kinds:
13 - Service
14 namespaces:
15 - "prod"
By combining multiple elements in the match statement, you can be more selective as to which resources you wish to process. Additionally, wildcards are supported for even greater control. For example, by adding the resources.names field, the previous match statement can further filter out Services that begin with the text “prod-” OR have the name “staging”. resources.names takes in a list of names and would match all resources which have either of those names.
1spec:
2 rules:
3 - name: no-LoadBalancer
4 match:
5 any:
6 - resources:
7 names:
8 - "prod-*"
9 - "staging"
10 kinds:
11 - Service
12 - resources:
13 kinds:
14 - Service
15 subjects:
16 - kind: User
17 name: dave
match.any[0] will now match on only Services that begin with the name “prod-” OR have the name “staging” and not those which begin with “dev-” or any other prefix. match.any[1] will match all Services being created by the dave user regardless of the name of the Service. And since these two are specified under the any key, the entire rule will act on all Services with names prod-* or staging OR on all services being created by the dave user. In both match and exclude statements, wildcards are supported to make selection more flexible.
Note
Kyverno also supportsresources.name which allows you to pass in only a single name rather than a list, but resources.name is being deprecated in favor of resources.names and will be removed in a future release.
In this snippet, the match statement matches only resources that have the group networking.k8s.io, version v1 and kind NetworkPolicy. By adding Group,Version,Kind in the match statement, you can be more selective as to which resources you wish to process.
1spec:
2 rules:
3 - name: no-LoadBalancer
4 match:
5 resources:
6 kinds:
7 - networking.k8s.io/v1/NetworkPolicy
By specifying the kind in version/kind format, only specific versions of the resource kind will be matched.
1spec:
2 rules:
3 - name: no-LoadBalancer
4 match:
5 resources:
6 kinds:
7 - v1/NetworkPolicy
As of Kyverno 1.5.0, wildcards are supported in the kinds field allowing you to match on every resource type in the cluster.
Selector labels support wildcards (* or ?) for keys as well as values in the following paths.
match.resources.selector.matchLabelsexclude.resources.selector.matchLabelsmatch.any.resources.selector.matchLabelsmatch.all.resources.selector.matchLabelsexclude.any.resources.selector.matchLabelsexclude.all.resources.selector.matchLabels
Supported formats:
**pattern**patternpattern?patte?rn
In the below policy, all resource kinds are checked for the existence of a label having key app.kubernetes.io/name.
1apiVersion: kyverno.io/v1
2kind: ClusterPolicy
3metadata:
4 name: require-labels
5spec:
6 validationFailureAction: audit
7 background: false
8 rules:
9 - name: check-for-labels
10 match:
11 resources:
12 kinds:
13 - "*"
14 preconditions:
15 - key: "{{ request.operation }}"
16 operator: Equals
17 value: CREATE
18 validate:
19 message: "The label `app.kubernetes.io/name` is required."
20 pattern:
21 metadata:
22 labels:
23 app.kubernetes.io/name: "?*"
Note
Keep in mind that when matching on all kinds (*) the policy you write must be applicable across all of them. Typical uses for this type of wildcard matching are elements within the metadata object.
Here are some other examples of match statements.
Match a Deployment or StatefulSet with a specific label
This is an example that selects a Deployment OR a StatefulSet with a label app=critical.
Condition checks inside the resources block follow the logic “AND across types but an OR within list types”. For example, if a rule match contains a list of kinds and a list of namespaces, the rule will be evaluated if the request contains any one (OR) of the kinds AND any one (OR) of the namespaces. Conditions inside clusterRoles, roles, and subjects are always evaluated using a logical OR operation, as each request can only have a single instance of these values.
In the below snippet, kinds and selector are peer/sibling elements, and so they are ANDed together.
1spec:
2 rules:
3 - name: match-critical-app
4 match:
5 # AND across kinds and namespaceSelector
6 resources:
7 # OR inside list of kinds
8 kinds:
9 - Deployment
10 - StatefulSet
11 selector:
12 matchLabels:
13 app: critical
This pattern can be leveraged to produce very fine-grained control over the selection of resources, for example the snippet as shown below which combines match elements that include resources, subjects, roles, and clusterRoles.
Advanced match statement
1spec:
2 # validationFailureAction controls admission control behaviors,
3 # when a policy rule fails:
4 # - use 'enforce' to block resource creation or modification
5 # - use 'audit' to allow resource updates and report policy violations
6 validationFailureAction: enforce
7 # Each policy has a list of rules applied in declaration order
8 rules:
9 # Rules must have a unique name
10 - name: "check-pod-controller-labels"
11 # Each rule matches specific resource described by "match" field.
12 match:
13 resources:
14 kinds: # Required, list of kinds
15 - Deployment
16 - StatefulSet
17 # Optional resource names. Supports wildcards (* and ?)
18 names:
19 - "mongo*"
20 - "postgres*"
21 # Optional list of namespaces. Supports wildcards (* and ?)
22 namespaces:
23 - "dev*"
24 - test
25 # Optional label selectors. Values support wildcards (* and ?)
26 selector:
27 matchLabels:
28 app: mongodb
29 matchExpressions:
30 - {key: tier, operator: In, values: [database]}
31 # Optional users or service accounts to be matched
32 subjects:
33 - kind: User
34 name: mary@somecorp.com
35 # Optional roles to be matched
36 roles:
37 # Optional clusterroles to be matched
38 clusterRoles:
39 - cluster-admin
Note
Although the above snippet is useful for showing the types of matching that you can use, most policies either use one or just a couple different elements within theirmatch statements.
Match Deployments in Namespaces using labels
This example selects Deployments in Namespaces that have a label type=connector or type=compute using a namespaceSelector.
Here, kinds and namespaceSelector are peer elements under match.resources and are evaluated using a logical AND operation.
1spec:
2 rules:
3 - name: check-min-replicas
4 match:
5 # AND across resources and selector
6 resources:
7 # OR inside list of kinds
8 kinds:
9 - Deployment
10 namespaceSelector:
11 matchExpressions:
12 - key: type
13 operator: In
14 values:
15 - connector
16 - compute
Combining match and exclude
All match and exclude conditions must be satisfied for a resource to be selected for the policy rule. In other words, the match and exclude conditions are evaluated using a logical AND operation. Elements in the exclude block follow the same specifications as those in the match block.
Exclude cluster-admin ClusterRole
Here is an example of a rule that matches all Pods excluding those created by using the cluster-admin ClusterRole.
1spec:
2 rules:
3 name: match-pods-except-cluster-admin
4 match:
5 resources:
6 kinds:
7 - Pod
8 exclude:
9 clusterRoles:
10 - cluster-admin
Exclude kube-system namespace
This rule matches all Pods except those in the kube-system Namespace.
Note
Exclusion of selected Namespaces by name is supported beginning in Kyverno 1.3.0. 1spec:
2 rules:
3 name: match-pods-except-admin
4 match:
5 resources:
6 kinds:
7 - Pod
8 exclude:
9 resources:
10 namespaces:
11 - kube-system
Match a label and exclude users and roles
The following example matches all resources with label app=critical excluding the resources created by ClusterRole cluster-admin OR by the user John.
Note
Sinceroles and clusterRoles are built internally by Kyverno from AdmissionReview contents, rules which contain either of these must define background: false since the AdmissionReview payload is not available in background mode.
1spec:
2 rules:
3 - name: match-criticals-except-given-rbac
4 match:
5 resources:
6 kind:
7 - Pod
8 selector:
9 matchLabels:
10 app: critical
11 exclude:
12 clusterRoles:
13 - cluster-admin
14 subjects:
15 - kind: User
16 name: John
Match a label and exclude users
A variation on the above sample, this snippet uses any and all statements to exclude multiple users.
1spec:
2 validationFailureAction: enforce
3 background: false
4 rules:
5 - name: match-criticals-except-given-users
6 match:
7 all:
8 - resources:
9 kinds:
10 - Pod
11 selector:
12 matchLabels:
13 app: critical
14 exclude:
15 any:
16 - subjects:
17 - kind: User
18 name: susan
19 - kind: User
20 name: dave
Match all Pods using annotations
Here is an example of a rule that matches all Pods having imageregistry: "https://hub.docker.com/" annotations.
1spec:
2 rules:
3 - name: match-pod-annotations
4 match:
5 resources:
6 annotations:
7 imageregistry: "https://hub.docker.com/"
8 kinds:
9 - Pod