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 or verifyImages 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 rule, even in Enforce mode. Background scanning is an optional field and defaults to true, only taking effect on validate and verifyImages rules. It has no effect on either generate or mutate rules.

Background scanning occurs on a continual basis and offers some configuration options via container flags.

When background scanning is enabled, regardless of whether the policy’s validationFailureAction is set to Enforce or Audit, the results 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 either certain variables from AdmissionReview request information (e.g. request.userInfo), or fields like Roles, ClusterRoles, and Subjects in match and exclude statements, 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 as these will be translated from the current state of the resource.

Last modified January 17, 2023 at 11:46 AM PST: 1.9 documentation updates (#733) (702f6d2)