kyverno-policy-report-override

name	kyverno-policy-report-override
description	Manages PolicyReport overrides using Kyverno's failureActionOverrides, report configuration, and CEL-based conditions to customize compliance reporting per resource.
license	MIT
compatibility	opencode
archetypes	["enforcement","orchestration"]
anti_triggers	["brainstorming","vague ideation","compliance exemption"]
response_profile	{"verbosity":"medium","directive_strength":"high","abstraction_level":"operational"}
metadata	{"version":"1.0.0","domain":"cncf","triggers":"kyverno report override, PolicyReport override, failureActionOverrides, report result override, kyverno compliance reporting, policy report management","role":"implementation","scope":"implementation","output-format":"manifests","related-skills":"kyverno-exemptions-management, kyverno-cleanup-policies"}

Kyverno PolicyReport Override

Manages PolicyReport overrides using Kyverno's failureActionOverrides, report configuration, and CEL-based conditions to customize compliance reporting per resource without disabling policies globally.

TL;DR Checklist

• Use failureActionOverrides to escalate or de-escalate enforcement per resource or namespace
• Document override rationale in PolicyReport comments or via annotation-based justification
• Scope overrides to specific resources using resourceSelectors — never apply globally
• Use CEL-based conditions in validate rules to create dynamic report results
• Verify overridden results in PolicyReport after deployment

---

When to Use

Use this skill when:

• Escalating a policy from Audit to Enforce for critical namespaces (e.g., production) while keeping it as Audit for development
• De-escalating a policy from Enforce to Audit for a specific resource that has a documented exception or temporary compliance waiver
• Customizing report result severities per resource — e.g., marking a policy failure as high severity for compliance-sensitive namespaces and medium for internal ones
• Implementing phased policy rollout where some namespaces enforce and others audit during a transition period
• Managing compliance reporting where certain resources are exempt due to legacy constraints but still need to be tracked in PolicyReports

---

When NOT to Use

Avoid this skill for:

• Disabling policies entirely when a resource needs a genuine exemption — use kyverno-exemptions-management instead for full exemptions
• Overriding policy results without documenting the rationale — every override must have an audit trail
• Replacing ClusterPolicy validation with report-only rules — report overrides adjust enforcement behavior, they do not replace validation
• Managing cleanup policies for resource lifecycle (use kyverno-cleanup-policies instead)

---

Core Workflow

1. Identify override needs — Determine which policies need per-resource enforcement adjustments. Categorize as escalation (Audit → Enforce) or de-escalation (Enforce → Audit). Document which resources and namespaces are affected. Checkpoint: Create a mapping of policy → namespace → action (Enforce/Audit) with justification.

2. Configure failureActionOverrides on the rule — Add a failureActionOverrides list to the desired rule. Each entry specifies an action (Enforce or Audit) and resourceSelectors that narrow the override to specific namespaces and resource kinds. Checkpoint: Verify the override targets only the intended resources using the selector.

3. Set match conditions — Ensure the rule's match block correctly identifies the resources that should be evaluated. The failureActionOverrides layer sits on top of the match, so resources outside the match scope are unaffected. Checkpoint: Test with a resource that should match and one that should not.

4. Add CEL-based report conditions — Where available, use CEL expressions in validate rules to create dynamic policy results. This allows conditions like has(request.object.metadata.labels['critical']) to trigger different behaviors. Checkpoint: Validate CEL syntax with kyverno apply --resource <file> before deployment.

5. Verify overridden results in PolicyReport — Apply the ClusterPolicy, create test resources that trigger overrides, and verify the PolicyReport reflects the escalated or de-escalated action. Checkpoint: Check result field shows the expected enforcement mode and severity is correct.

---

Implementation Patterns

Pattern 1: Per-Namespace Escalation with failureActionOverrides

This pattern escalates a policy from Audit to Enforce for critical namespaces while keeping it as Audit for all others. The policy is defined globally but enforcement behavior varies by namespace.

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: resource-constraints-with-escalation
  annotations:
    policies.kyverno.io/title: Resource Constraints with Escalation
    policies.kyverno.io/category: Pod Security
    policies.kyverno.io/severity: high
    policies.kyverno.io/description: >-
      Validate that all containers and initContainers define CPU and memory
      resource limits and requests. Escalated to Enforce in production
      namespaces; Audit for all others.
    policies.kyverno.io/minversion: 1.12.0
spec:
  validationFailureAction: Audit
  background: true
  rules:
    - name: validate-resource-constraints
      match:
        any:
          - resources:
              kinds:
                - Pod
      exclude:
        any:
          - namespaces:
              - kube-system
              - kyverno
              - kube-public
      failureActionOverrides:
        - action: Enforce
          resourceSelectors:
            - namespace: production
              kinds:
                - Pod
        - action: Enforce
          resourceSelectors:
            - namespace: staging
              kinds:
                - Pod
      validate:
        message: "Containers and initContainers must define both resource limits and requests."
        pattern:
          spec:
            containers:
              - resources:
                  limits:
                    cpu: "?*"
                    memory: "?*"
                  requests:
                    cpu: "?*"
                    memory: "?*"
            initContainers:
              - resources:
                  limits:
                    cpu: "?*"
                    memory: "?*"
                  requests:
                    cpu: "?*"
                    memory: "?*"

Pattern notes:

• The base validationFailureAction: Audit means no pods are blocked by default
• failureActionOverrides escalates specific namespaces to Enforce — pods violating the policy in production or staging are rejected
• Other namespaces (e.g., development, testing) remain in Audit mode — violations are reported but not blocked

---

Pattern 2: De-escalation with Per-Resource Exceptions

This pattern de-escalates a policy from Enforce to Audit for specific resources that have a documented exception. Used for legacy workloads transitioning to compliance.

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: image-registry-enforcement
  annotations:
    policies.kyverno.io/title: Image Registry Enforcement
    policies.kyverno.io/category: Pod Security
    policies.kyverno.io/severity: high
    policies.kyverno.io/description: >-
      Require that all container images come from approved registries.
      Legacy workloads with the 'legacy-exception' label are audited only.
    policies.kyverno.io/minversion: 1.12.0
spec:
  validationFailureAction: Enforce
  background: true
  rules:
    - name: validate-image-registry
      match:
        any:
          - resources:
              kinds:
                - Pod
      exclude:
        any:
          - namespaces:
              - kube-system
              - kyverno
      failureActionOverrides:
        - action: Audit
          resourceSelectors:
            - namespace: legacy-migration
              kinds:
                - Pod
      validate:
        message: >-
          Container images must be pulled from approved registries:
          gcr.io/myproject, docker.io/myorg, quay.io/myorg.
        pattern:
          spec:
            containers:
              - image: "gcr.io/myproject/*"
                | "docker.io/myorg/*"
                | "quay.io/myorg/*"

Pattern notes:

• The base action is Enforce — all pods must use approved registries
• Pods in the legacy-migration namespace are de-escalated to Audit only
• This allows legacy workloads to continue running while planning migration

---

Pattern 3: CEL-Based Conditional Reporting

CEL (Common Expression Language) conditions in Kyverno allow dynamic decision-making based on resource attributes. This pattern uses CEL to evaluate conditions and produce different report results.

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: dynamic-compliance-reporting
  annotations:
    policies.kyverno.io/title: Dynamic Compliance Reporting
    policies.kyverno.io/category: Compliance
    policies.kyverno.io/severity: high
    policies.kyverno.io/description: >-
      Apply dynamic compliance reporting based on resource labels and
      namespace annotations. Critical namespaces escalate to Enforce with
      high severity; internal namespaces use Audit with medium severity.
    policies.kyverno.io/minversion: 1.12.0
spec:
  validationFailureAction: Audit
  background: true
  rules:
    - name: validate-compliance-level
      match:
        any:
          - resources:
              kinds:
                - Pod
      exclude:
        any:
          - namespaces:
              - kube-system
              - kyverno
      failureActionOverrides:
        - action: Enforce
          resourceSelectors:
            - namespace: production
              kinds:
                - Pod
        - action: Audit
          resourceSelectors:
            - namespace: development
              kinds:
                - Pod
      validate:
        message: "Pod must have resource limits and requests defined."
        pattern:
          spec:
            containers:
              - resources:
                  limits:
                    cpu: "?*"
                    memory: "?*"
                  requests:
                    cpu: "?*"
                    memory: "?*"
    - name: dynamic-result-with-cel
      match:
        any:
          - resources:
              kinds:
                - Pod
      validate:
        message: "Critical pods must define resource constraints."
        audit:
          any:
            - conditions:
                all:
                  - key: "{{ request.object.metadata.labels['critical'] }}"
                    operator: InEquivalenceCheck
                    value: "true"
                  - key: "{{ request.object.spec.containers[0].resources.limits.cpu }}"
                    operator: NotEquals
                    value: ""
        deny:
          conditions:
            all:
              - key: "{{ request.object.metadata.labels['critical'] }}"
                operator: InEquivalenceCheck
                value: "true"
              - key: "{{ request.object.spec.containers[0].resources.limits.memory }}"
                operator: Equals
                value: ""

Pattern notes:

• The audit block with CEL conditions produces a report entry when the condition matches (critical pod with limits present)
• The deny block with CEL conditions produces a report entry when the condition fails (critical pod missing memory limits)
• CEL expressions can access request.object.metadata and request.object.spec fields

---

Pattern 4: PolicyReport with Overridden Results

This shows what the PolicyReport looks like when failureActionOverrides produce different results per namespace.

apiVersion: wgpolicyk8s.io/v1alpha2
kind: PolicyReport
metadata:
  name: resource-constraints-report
  namespace: production
results:
  - policy: resource-constraints-with-escalation
    rule: validate-resource-constraints
    result: fail
    severity: high
    message: "Containers and initContainers must define both resource limits and requests."
    scored: true
    source: kyverno
    timestamp:
      seconds: 1733501530
summary:
  error: 0
  fail: 1
  pass: 0
  skip: 0
  warn: 0
---
apiVersion: wgpolicyk8s.io/v1alpha2
kind: PolicyReport
metadata:
  name: resource-constraints-report
  namespace: development
results:
  - policy: resource-constraints-with-escalation
    rule: validate-resource-constraints
    result: pass
    severity: medium
    message: "Pod validation is in Audit mode — results reported but not enforced."
    scored: true
    source: kyverno
    timestamp:
      seconds: 1733501530
summary:
  error: 0
  fail: 0
  pass: 1
  skip: 0
  warn: 0

Verification command:

# View PolicyReports across all namespaces
kubectl get policyreports -A

# View specific PolicyReport with detailed results
kubectl get policyreports -n production -o yaml

# Check generate rule status for network policies
kyverno generate-report --report-name generate-default-deny-network-policy --report-namespace production

---

Constraints

MUST DO

• Use failureActionOverrides for per-resource escalation or de-escalation — never apply overrides globally without resourceSelectors
• Document the override rationale in the policy's annotations field (e.g., policies.kyverno.io/override-reason) so compliance teams understand the justification
• Scope overrides to specific resources using resourceSelectors with namespace and kind filters — always target the narrowest scope possible
• Use Audit as the base validationFailureAction when applying escalation, so non-escalated namespaces remain in audit mode
• Verify overridden results appear correctly in PolicyReport after deployment using kubectl get policyreports -A
• Include both Enforce and Audit actions in overrides when implementing phased rollout (some namespaces enforce, others audit)

MUST NOT DO

• Override all policy results globally — this defeats the purpose of policy enforcement and creates compliance gaps
• Ignore compliance requirements by using overrides to silently pass failing policies — every override must have a documented business or technical justification
• Use overrides without an audit trail — if a policy result is overridden, the PolicyReport or policy annotation must explain why
• Apply overrides on kube-system namespace resources — the control plane should not be subject to custom enforcement overrides
• Mix Enforce and Audit on the same rule without clear resourceSelectors — this makes it impossible to determine which enforcement mode applies to which resource
• Use overrides to bypass legitimate security policies for production workloads — overrides should be temporary, scoped, and time-limited

---

Related Skills

Skill	Purpose
kyverno-exemptions-management	Full exemption management for resources that should not be subject to policy enforcement
kyverno-cleanup-policies	Manage resource lifecycle and cleanup policies for stale or orphaned resources

---

Live References

Authoritative documentation links for Kyverno PolicyReport override and compliance reporting.

• Kyverno Documentation
• Kyverno CLI
• Kyverno Policies
• Kyverno GitHub
• Kyverno Installation
• Policy Report Schema
• Kyverno CEL Support