Background Scans

Manage applying policies to existing resources in a cluster.

Kyverno can validate existing resources in the cluster that may have been created before a policy was created. This can be useful when evaluating the potential effects new validate policies will have on a cluster prior to changing them to enforce mode. The application of policies to existing resources is referred to as background scanning and is enabled by default unless background is set to false in a policy like shown below in the snippet.

1spec:
2  background: false
3  rules:
4  - name: default-deny-ingress

Background scanning, enabled by default in a Policy or ClusterPolicy object with the spec.background field, allows Kyverno to scan existing resources and find if they match any validate rules. If existing resources are found which would violate an existing policy, the background scan notes them in a ClusterPolicyReport or a PolicyReport object, depending on if the resource is namespaced or not. It does not block any existing resources that match a validate rule, even in enforce mode. Background scanning is an optional field and defaults to true, only taking effect on validate rules. It has no effect on either generate or mutate rules.

By default, background scanning occurs every hour and can be configured via the background-scan flag.

When background scanning is enabled, regardless of whether the policy’s validationFailureAction is set to enforce or audit, the violation will be recorded in a report. To see the specifics of how reporting works with background scans, refer to the tables below.

Reporting behavior when background: true

New ResourceExisting Resource
validationFailureAction: enforceNoneReport
validationFailureAction: auditReportReport

Reporting behavior when background: false

New ResourceExisting Resource
validationFailureAction: enforceNoneNone
validationFailureAction: auditReportNone

Also, policy rules that are written using certain variables from AdmissionReview request information (e.g. request.userInfo) cannot be applied to existing resources in the background scanning mode since that information must come from an AdmissionReview request and is not available if the resource exists. Hence, these rules must set background to false to disable background scanning. The exceptions to this are request.object and request.namespace variables.

Last modified February 19, 2022 at 10:24 AM PST: [main] 1.6 updates (#477) (bc4c364)