PolicyReport from Background Scan

Kyverno generates real-time reports for new and updated resources at admission time. That provides immediate feedback, but it leaves a blind spot: resources that already existed in the cluster before your policies were applied. This section explains how to use Kyverno’s background scanning to evaluate existing resources and generate PolicyReports and ClusterPolicyReports for them. Alex already has real-time reporting enabled and can see compliance for every new Pod. However, his cluster contains hundreds of pre-existing resources that were never evaluated by Kyverno — the security team needs a complete inventory of the cluster’s compliance. Background scanning is the mechanism that fills that gap.

The image presents "Alex's Final Reporting Challenge," detailing three problems related to cluster deployments and compliance status in a Kyverno policies context.

What is background scanning?

Background scanning is the periodic evaluation of stored cluster resources against your policies to generate reports for resources that were created before your policies existed.
It runs independently of admission requests and produces the same type of reporting output used for admission-time evaluations.

The image contains text explaining that background scanning is the periodic application of policies to existing resources for generating reports, along with a simple graphic design.

Controlling background evaluation with spec.background

Each policy has a spec.background field. When set to true, the policy participates in background scans.
The default is true, so policies you create will be evaluated during background scans unless you explicitly opt out.

Example policy snippet:

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: example-policy
spec:
  background: false   # set to false to disable background scanning for this policy
  rules:
    - name: validate-example
      validate:
        message: "example validation"
        pattern:
          metadata:
            labels:
              app: "?*"

If a policy should only run at admission time (for example, it relies on request-scoped identity), set spec.background: false to prevent it from being evaluated by the Reports Controller.

The image describes background scanning control settings, mentioning that the spec.background field is used in every policy and is set to true by default.

Primary use cases

Audit pre-existing resources to find violations that occurred before policy rollout.
Test new policies in audit mode: leave the policy in audit mode and let the background scan evaluate the cluster. The resulting reports show what would be blocked if the policy were enforced — without disrupting running workloads.

Kyverno components and responsibilities

Understanding which component does what helps you configure and interpret background scanning and reports correctly.

Component	Primary Responsibility	Notes
Admission Controller	Applies `validate`, `mutate`, and `verifyImages` rules to admission requests	Synchronous, request-scoped validation and mutation
Background Controller	Processes `generate` and `mutateExisting` rules on stored resources	Asynchronous; does not generate PolicyReports
Reports Controller	Generates reports for admission requests and runs background scans to create `PolicyReport` / `ClusterPolicyReport`	Aggregates ephemeral scan results into durable reports

Use backticks for rule names and fields when referencing them in text (e.g., validate, mutateExisting, spec.background).

The image is a table explaining the responsibilities of different Kyverno components: the Admission Controller, Background Controller, and Reports Controller. Each component has specific tasks such as applying rules and handling background scanning.

How background scanning works (high level)

The Reports Controller wakes on a configurable schedule (default: once per hour).
It scans resources across the cluster against policies that have spec.background: true.
For each evaluated resource, the Reports Controller produces an internal ephemeral report — EphemeralReport or ClusterEphemeralReport.
The controller immediately processes and aggregates these ephemeral results into durable PolicyReport or ClusterPolicyReport objects.

Ephemeral reports are the same resource type used during admission reporting; the difference is that their content is populated from background evaluations rather than live admission requests.

The image is a flowchart titled "The Background Scanning Flow," detailing the process of a Reports Controller that scans resources and creates Ephemeral and Policy Reports, with configurable intervals.

Migration note

Prior to Kyverno v1.12 the temporary reports were named BackgroundReport / ClusterBackgroundReport. These were unified into EphemeralReport and ClusterEphemeralReport to simplify reporting semantics.

Limitations and important considerations

Background scans evaluate stored resources (data from etcd). Because they are not tied to an admission request, request-scoped context is unavailable.
Do not rely on user identity or request-specific variables in policies that you want to run in the background.

Unsupported during background scans:

Matching on user/subject information such as Roles/ClusterRoles or subjects.
Request-specific variables like request.userInfo.

Supported during background scans:

Fields that reflect the stored resource state, e.g., request.object and request.namespace, effectively map to the current stored resource when evaluated in background.

The image outlines limitations of background scanning, highlighting that matching on roles, cluster roles, or subjects, and using most request variables are not supported when the background is set to true.

If your policy uses request.userInfo or matches on subjects, set spec.background: false to prevent background-evaluation errors.

Configuring the background scan interval

The Reports Controller background scan interval is configurable with the controller flag --background-scan-interval.
Example (operator or deployment arguments): set the scan interval to 30 minutes:

# Example snippet to pass as controller args (varies by deployment method)
args:
  - --background-scan-interval=30m

Summary

Background scanning audits resources that predate your policies and fills the visibility gap left by admission-only reporting.
spec.background controls whether a policy participates in background scans (default: true).
The Reports Controller periodically wakes, evaluates resources, produces ephemeral reports, and aggregates them into durable PolicyReport / ClusterPolicyReport objects.
Avoid using admission-time data (e.g., request.userInfo) in policies you expect to run during background scans.

Links and references

Kyverno documentation: https://kyverno.io/
Kubernetes API concepts: https://kubernetes.io/docs/concepts/overview/what-is-kubernetes/
Kyverno GitHub: https://github.com/kyverno/kyverno

That’s it for this section.

PolicyReport from Background Scan

Watch Video

Practice Lab