Tracking: cluster-connected policy evaluation for gator

[JaydipGabani]

Summary

gator is offline-only today: gator test and gator verify evaluate resources against policies the caller supplies from local files (-f) or OCI images (-i). Two separate requests both need gator to talk to a live cluster, and they need most of the same plumbing.

This issue tracks them together so the flag surface, policy-loading path, and result contract stay consistent instead of being invented twice.

Sub-issues

• Add gator audit command to scan live cluster resources for policy violations #4484 — gator audit: evaluate resources already in the cluster
• Add gator support for evaluating resources against in-cluster policies #4714 — evaluate candidate resources not yet in the cluster against in-cluster policies

The two differ only in where the resources under evaluation come from. Everything between "connect to a cluster" and "print results" is shared.

Shared building blocks

These need one implementation, not two:

1. Cluster connection. kubeconfig loading with --kubeconfig and --context overrides. pkg/gator/policy/client (added by Add gator policy command for managing Gatekeeper library policies #4330) already has a dynamic client that lists ConstraintTemplates, but it uses clientcmd.NewDefaultClientConfigLoadingRules() with empty ConfigOverrides — no context selection. Extending it is preferable to adding a second client.

2. Loading policies from the API server. ConstraintTemplates plus the generated constraint CRs. Needed by Add gator support for evaluating resources against in-cluster policies #4714 always, and by Add gator audit command to scan live cluster resources for policy violations #4484 under its proposed --from-cluster.

3. Client-side spec.match evaluation. Namespaces, kinds, label selectors, namespaceSelector, excludedNamespaces. Requires resolving the target Namespace object.

4. data.inventory construction for referential constraints, including deciding what to do when the needed GVKs are not available and how to report that the result is an approximation.

5. Enforcement-action reporting. deny / warn / dryrun, plus scopedEnforcementActions and its webhook vs audit scope. gator audit cares about the audit scope; candidate-resource evaluation cares about the webhook scope. Same data, different default.

6. Output and exit codes. Table / JSON / YAML, and CI-gating behavior. These should be identical across both commands.

Design questions to settle once

Answering these per-issue will produce an inconsistent CLI. Worth deciding up front:

• Flag naming and shape. Is cluster mode a flag on the existing gator test (--from-cluster), a new subcommand, or both? Add gator audit command to scan live cluster resources for policy violations #4484 proposes gator audit as a subcommand and also proposes --from-cluster as a flag on it, which suggests the two axes — where resources come from and where policies come from — should be independent.
• RBAC. State the minimum permissions explicitly. Reading ConstraintTemplates and constraints needs get/list on those types only. Populating data.inventory needs read on the synced GVKs, which is a much broader ask, and should be opt-in and documented as such.
• Engine parity. Rego and CEL / K8sNativeValidation, and the VAP-generated path.
• External data providers. Cannot be reached client-side in general. Both commands must fail loudly or mark those constraints unevaluated — never silently pass.
• Expansion. ExpansionTemplate should be applied so workloads are evaluated as their generated Pods, matching admission and audit.
• Mutation. Admission mutates before validating. Either apply Assign / AssignMetadata / ModifySet from the cluster, or document clearly that mutation is not simulated. This matters more for Add gator support for evaluating resources against in-cluster policies #4714 than for Add gator audit command to scan live cluster resources for policy violations #4484.
• Version skew. gator's embedded frameworks/constraint version will not always match the cluster's Gatekeeper version. Results are an approximation; decide how to surface that.

Out of scope

• Replacing the in-cluster audit loop (pkg/audit) or the admission webhook. These are client-side diagnostic tools, not enforcement.
• Any guarantee of byte-identical results with server-side evaluation. Skew, external data, and mutation all make that unachievable; the goal is a useful and honestly-labelled approximation.

Related

• Add gator policy command for managing Gatekeeper library policies #4330 — gator policy, which introduced the existing cluster client
• pkg/gator/ — evaluation harness
• pkg/audit/manager.go — in-cluster audit loop