stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
702a27ac839f1de50f9c9f460000b8f7b2242efd
git.stella-ops.org/docs/operations/runbooks/policy-compilation-failed.md

4.1 KiB
Raw Blame History

Runbook: Policy Engine - Rego Compilation Errors

Sprint: SPRINT_20260117_029_DOCS_runbook_coverage Task: RUN-003 - Policy Engine Runbooks

Metadata

Field Value
Component Policy Engine
Severity High
On-call scope Platform team
Last updated 2026-01-17
Doctor check check.policy.compilation-health

Symptoms

  • Policy deployment failing with "compilation error"
  • Alert PolicyCompilationFailed firing
  • Error: "rego_parse_error" or "rego_type_error"
  • New policies not taking effect
  • OPA rejecting policy bundle

Impact

Impact Type Description
User-facing New policies cannot be deployed; using stale policies
Data integrity Existing policies continue to work; new rules not enforced
SLA impact Policy updates blocked; security posture may be outdated

Diagnosis

Quick checks

  1. Check Doctor diagnostics:

    stella doctor --check check.policy.compilation-health

  2. Check policy compilation status:

    stella policy status --compilation

  3. Validate specific policy:

    stella policy validate --file <policy-file>

Deep diagnosis

  1. Get detailed compilation errors:

    stella policy compile --verbose

    Look for: Line numbers, error types, undefined references

  2. Check for syntax errors:

    stella policy lint --file <policy-file>

  3. Check for type errors:

    stella policy typecheck --file <policy-file>

  4. Check OPA version compatibility:

    stella policy opa version
stella policy check-compat --file <policy-file>

Resolution

Immediate mitigation

  1. Rollback to last working policy:

    stella policy rollback --to-last-good

  2. Disable the failing policy:

    stella policy disable <policy-id>
stella policy reload

  3. Use previous bundle:

    stella policy bundle load --version <previous-version>

Root cause fix

If syntax error:

  1. Get exact error location:

    stella policy validate --file <policy-file> --show-line

  2. Common syntax issues:

    • Missing brackets or braces
    • Invalid rule head syntax
    • Incorrect import statements

  3. Fix and re-validate:

    stella policy validate --file <fixed-policy.rego>

If undefined reference:

  1. Check for missing imports:

    stella policy analyze --file <policy-file> --show-imports

  2. Verify data references exist:

    stella policy data show

  3. Add missing imports or data definitions

If type error:

  1. Check type mismatches:

    stella policy typecheck --file <policy-file> --verbose

  2. Common type issues:

    • Comparing incompatible types
    • Invalid function arguments
    • Missing type annotations

If OPA version incompatibility:

  1. Check Rego version features used:

    stella policy analyze --file <policy-file> --show-features

  2. Update policy to use compatible features or upgrade OPA

Verification

# Validate fixed policy
stella policy validate --file <fixed-policy.rego>

# Test policy compilation
stella policy compile --file <fixed-policy.rego>

# Deploy policy
stella policy deploy --file <fixed-policy.rego>

# Test policy evaluation
stella policy evaluate --test

Prevention

  • CI/CD: Add policy validation to CI pipeline before deployment
  • Linting: Run stella policy lint on all policy changes
  • Testing: Write unit tests for policies with stella policy test
  • Staging: Deploy to staging environment before production

Related Resources