OPA Policy Engine and Workbench

Current Product Scope

This module documents the OPA implementation that is currently shipped in GitOpsHQ Values Governance. Approval and break-glass flows are handled by IAM approval policy modules, not by this OPA workspace. All OPA endpoints are gated behind the FeatureValuesGovernance feature flag.

What Exists Today

Embedded OPA engine with Rego v1 parsing.
Policy sets with enable/disable control.
22 built-in policies in 5 categories.
Custom Rego policy authoring in UI.
Assignment model across 6 scope types.
Violation tracking with resolve workflow.
Rego Playground with YAML input and rule-level output.

Workspace Map

List of policy sets with active/disabled state.
Category and policy-count visibility per set.
Create new policy set with name and description.

Two core tabs: Policies and Assignments.
Add built-in policy from catalog or add custom Rego policy.
Delete set, policy, or assignment from this view.

Built-ins grouped by category with severity and target badges.
Preview drawer shows full Rego content.
Test in Playground shortcut is available from catalog and preview.

Filter by unresolved/resolved/all.
Shows enforcement (deny, warn, audit) and severity.
Unresolved items can be marked as resolved.

Monaco Rego editor + YAML input editor.
Run evaluation and inspect rule-by-rule output.
Supports loading Rego directly from built-in catalog.

Policy Data Model

Policy Type: builtin or rego.
Target: values, manifest, both.
Enforcement: deny (block), warn (allow + warning), audit (allow + audit record).
Severity: error, warning, info.
Category: security, reliability, cost, compliance, custom, access-control.
Enabled: policy-level and policy-set-level activation state exists in model.

Assignment Model (Where a Set Applies)

Policy sets are assignable to:

organization
chart
team
tenant
project
environment

Environment assignment supports environment name, with optional project scoping.

Team Scope Limitation

The model and SQL support team-scoped assignments, but EvalContext in the automated evaluation paths (tenant.go, hq_variables.go, promotion.go) never sets TeamID. Team-scoped assignments are therefore not effectively applied in current automated evaluation flows.

Built-in Catalog (22 Policies)

No privileged containers
No hostNetwork / hostPID
Non-root and read-only rootfs warnings
No latest image tag

Require resource limits
Require liveness/readiness probes
Minimum replicas in production
Warn on missing PDB in production

Warn on oversized CPU/memory limits
Warn on excessive replica count

Require deployment labels
Require namespace in namespaced resources
Require approved image registries

Viewer read-only restrictions
Production admin/owner-only restrictions
Sensitive field / bulk-change / critical-empty protections
Audit-style value change trace rules

Important Current Behavior

When adding a built-in from the catalog UI, enforcement is currently created as deny by default. Review this decision during rollout.

Rego Evaluation Behavior

Rule naming that the engine evaluates

Custom and playground flows evaluate rules that start with deny or warn.
If no such rule names exist, fallback queries target deny and warn.

Severity mapping in playground output

Rule name starts with deny -> error
Rule name starts with warn -> warning
Other matched rule -> info

Input shape used by policies

input.values
input.manifests (when manifest input exists)
input.context (organizationId, projectId, tenantId, environment, chartId, teamId, servicePath)
input.user (interactive flows)
input.diff (changedFields, previousValues)

Where OPA Is Evaluated In Real Product Flows

Tenant values update flow evaluates policies before write and blocks on deny violations.

HQ variable resolution/reapply flow evaluates policies and records violation history.

Promotion request flow evaluates the source environment's values YAML content, with context.environment set to the target environment, before request creation.

Release creation (CreateRelease) does not re-run OPA server-side. The policySnapshotJson included in the release payload is client-supplied from a prior evaluation.

Ad-hoc evaluate and playground flows support policy testing and debugging in UI.

Practical Notes For Operators

Access-control built-ins rely on user and diff context; these signals are strongest in interactive value edit flows.
Manifest-target policies (PolicyTargetManifest and PolicyTargetBoth) are defined in the engine and data model, but no automated evaluation handler currently wires manifest input. EvaluatePolicies only calls EvaluateValues. Manifest-target policies are therefore not exercised in current automated flows (tenant updates, HQ resolution, promotion).
Custom policy category selection in current UI is focused on resource-governance categories (security, reliability, cost, compliance, custom).

Common Failure Modes

Rule names do not follow deny* or warn*, causing empty results.
Assignment target mismatch (wrong scope or missing environment name).
Built-in added as deny unexpectedly and blocks rollout.
Playground input is not a YAML map (key-value object).
Policy set exists but remains disabled.