Skip to main content
In the introduction, Alex faced a common visibility gap: resources created before policies existed were difficult to identify as non-compliant. Kyverno’s reporting system fills that gap by producing PolicyReport and ClusterPolicyReport resources that summarize policy evaluations across your cluster. Before we look at how to inspect reports in a live cluster, first understand what a report is and how it’s generated. Who creates reports? The reports controller is the Kyverno component responsible for generating and updating PolicyReport and ClusterPolicyReport resources. It acts as the central record keeper and receives evaluation results from two primary sources: real-time admission reviews and periodic background scans. Admission reviews (real-time) This trigger runs whenever a resource is created or updated. Kyverno evaluates applicable policies during the admission request and the reports controller records an entry for any policy with spec.admission set to true (the default).
The image describes the "Reports Controller" focusing on "Trigger 1: Admission Reviews," detailing the evaluation process of a resource during a CREATE or UPDATE request, and the capture of results from policies with specific admission settings.
By default, Kyverno policies evaluate both at admission (spec.admission: true) and in background scans (spec.background: true) unless you explicitly change those fields. Use admission evaluation for immediate enforcement and background scans for periodic compliance checks.
Background scans (periodic) The second trigger is the background scan, which evaluates policies against resources that already exist in the cluster. Kyverno periodically re-evaluates resources for any policy with spec.background set to true and forwards those results to the reports controller.
The image outlines two triggers for "The Reports Controller": "Admission Reviews" (real-time evaluations) and "Background Scans" (periodic scans of existing resources), including their purposes and methods.
Consolidation by the reports controller The reports controller merges results from both admission reviews and background scans into PolicyReport (namespaced) and ClusterPolicyReport (cluster-scoped) resources. This consolidation provides a single source of truth for policy compliance across your cluster.
The image is a diagram explaining how the Reports Controller consolidates results from "Admission Reviews" and "Background Scans" into "PolicyReport & ClusterPolicyReport" resources. It includes a description of the process.
Report types Which report type is used depends on the evaluated resource’s scope:
The image is a table comparing PolicyReport (Namespaced) and ClusterPolicyReport (Cluster-Scoped) types, detailing their kind, scope, applicable resources, and examples.
What does a PolicyReport look like? A PolicyReport is essentially a report card for a single Kubernetes resource. It has three primary sections:
  • Scope: identifies the resource (kind, name, namespace).
  • Results: an array with one entry per policy rule evaluated against that resource.
  • Summary: aggregated counts for pass, fail, warn, error, and skip.
Example (truncated) PolicyReport:
The results array is the most important section for troubleshooting: each element corresponds to a single rule evaluation and indicates the outcome. Breaking down a single result entry Each result entry contains the fields you’ll use to identify and prioritize violations:
  • policy, rule: which policy and rule were evaluated.
  • result: the evaluation outcome (pass, fail, skip, warn, error).
  • message: human-readable description of the validation or error (critical for debugging).
  • Additional optional fields: category, severity, scored, source, etc., which help with filtering and prioritization.
Example result entry:
Understanding result values The possible outcomes provide context beyond binary pass/fail and support auditability:
The image is a table explaining the core outcomes of rule evaluations, including results like "pass," "fail," "skip," "warn," and "error," with brief descriptions for each.
Recap In this lesson you learned:
  1. The reports controller consolidates evaluations from admission reviews (real-time) and background scans (periodic).
  2. There are two report types that correspond to resource scope: namespaced PolicyReport and cluster-scoped ClusterPolicyReport.
  3. A PolicyReport contains a summary and a results array; the results array is where you’ll analyze compliance issues.
  4. The result values (pass, fail, skip, warn, error) provide an audit trail that indicates compliance, intentional skips, or policy processing errors.
The image is a summary list detailing four aspects of reporting: the reporter, report types, content, and the audit trail, each with a brief explanation. It features a gradient background and bullet points numbered from 01 to 04.
Next steps You now have the foundation to read and interpret PolicyReport resources. In the next lesson we will demonstrate how reports are generated in a cluster and how to query and filter PolicyReports and ClusterPolicyReports to prioritize remediation. References

Watch Video