Namespaced Image Validating Policy#

NamespacedImageValidatingPolicy (nivpol) is the namespace-scoped counterpart of ImageValidatingPolicy. It lets teams define image verification rules (signature checking, digest pinning, etc.) within a single namespace rather than cluster-wide. The resource belongs to the policies.kyverno.io API group (v1beta1) and shares its spec structure with ImageValidatingPolicy through the ImageValidatingPolicyLike interface 1.

Full support for this type — across admission webhooks, background scanning, and policy reporting — was incrementally added via several PRs:

• PR #14242: foundational admission-controller and webhook wiring
• PR #16258: webhook reconciliation stability fix
• PR #16301: background scanner coverage fix

Related bugs were tracked in issue #15286 (webhook call failure) and issue #16300 (background reports not generated).

Webhook Registration and Routing#

The webhook controller (pkg/controllers/webhook/controller.go) handles NamespacedImageValidatingPolicy alongside its cluster-scoped sibling. Key details:

• Informer/lister registration: The controller holds a dedicated nivpolInformer and nivpolLister 2. Event handlers for create/update/delete are registered at startup 3.
• Validate webhook path: buildForPoliciesValidation calls getNamespacedImageValidatingPolicies() and appends webhook rules routed to /nivpol/validate under the ImageValidatingPolicyValidateWebhookName configuration 4.
• Mutate webhook path: A parallel path builds mutating webhook entries at /nivpol/mutate, but only for policies where mutation is actually needed (ivpolsNeedingMutation()) — policies with both mutateDigest: false and verifyDigest: false are excluded 5.
• Policy state recording: After building the configuration, all ivpol and nivpol policies are passed to recordPolicyState() so the policystatus controller can reflect webhook readiness 6.

Reconciliation Loop Fix (PR #16258)#

On platforms that normalize webhook configurations (e.g., GKE Autopilot), the webhook controller would enter an infinite reconciliation loop. Two bugs caused this 5:

1. Label selector normalization: mergeLabelSelectors() emitted non-nil empty maps/slices, which diverged from the Kubernetes API server's stored representation and caused perpetual DeepEqual failures on every reconcile cycle.
2. Unnecessary mutation webhook registration: Policies without mutation intent were still registering mutating webhooks, adding extra reconcile churn.

On GKE, this generated over 65 GB of audit logs per week from a single policy before the fix. The fix normalizes empty MatchLabels and MatchExpressions to nil after merging 5.

Background Scanning and Policy Report Generation#

Background Controller Integration#

The background report controller (pkg/controllers/report/background/controller.go) collects NamespacedImageValidatingPolicy resources during its reconcile loop 7. When nivpolLister is initialized, FetchNamespacedImageVerificationPolicies is called per namespace; each result is wrapped in engineapi.NewNamespacedImageValidatingPolicy() and included in the policies slice fed to the scanner. Non-background policies are filtered out via celpolicies.RemoveNoneBackgroundPolicies() before wrapping.

Scanner Type-Check Fix (PR #16301)#

The scanner (pkg/controllers/report/utils/scanner.go) classifies incoming GenericPolicy objects using interface assertions. Before PR #16301, this code used AsImageValidatingPolicy() — a type-narrowing call that only matched cluster-scoped policies — causing NamespacedImageValidatingPolicy resources to fall through silently with no report output 8.

The fix switches to AsImageValidatingPolicyLike(), which matches both ImageValidatingPolicy and NamespacedImageValidatingPolicy through their shared interface. The matched policy is then passed to the ivpolengine provider 9, which evaluates the image verification rules and feeds results into the background PolicyReport.

PR #16301 also added nil-check guards in the ivpolengine, mpolengine, and vpolengine metric wrappers to prevent nil-pointer panics during background scans 10.

Policy Status#

The policystatus controller tracks webhook readiness and RBAC health for all CEL-based policy types. For NamespacedImageValidatingPolicy, the dedicated handler lives in pkg/controllers/policystatus/nivpol.go 11. This file was added as part of PR #14242's status-handling work 1.

The status conditions mirror those of ImageValidatingPolicy:

• WebhookConfigured: set by StateRecorder.Ready(key) after the webhook controller installs the webhook entry 11
• RBACPermissionsGranted: verified by SubjectAccessReview against the reports service account for all matched resources 11

A known bug (issue #15286) manifested as "failed calling webhook 'ivpol.mutate.kyverno.svc-fail'" errors when creating NamespacedImageValidatingPolicy resources. The underlying cause was a resource-version conflict in the status controller ("the object has been modified; please apply your changes to the latest version"). This was resolved after the background scanner fix landed 12.

Key Source References#

Issues and PRs:

• PR #14242 — foundational admission + webhook support
• PR #16258 — webhook reconciliation loop fix
• PR #16301 — background scanner fix
• Issue #15286 — webhook call failure bug
• Issue #16300 — background reports not generated