OPA Migration Strategy Discussion

[KevFan]

OPA Migration Strategy Discussion

Background

We need your input on a critical decision about migrating from OPA v0.x to OPA v1.x in Authorino. This affects anyone using OPA policies in their AuthConfig resources.

Current Situation

What We've Done So Far

• Merged build(deps): bump github.com/open-policy-agent/opa from 0.68.0 to 1.4.0 #531: Updated to OPA v1 Go dependencies internally
• Kept v0 behavior: Still using v0 syntax and package in the code
• Tested v1 migration: Attempted full migration in PR #545 but discovered compatibility issues

v0 Compatibility Paradox

During our migration testing in PR #545, we discovered something unexpected: OPA v1's v0 compatibility mode is actually MORE restrictive than pure OPA v1 in some cases.

What We Found:

# This might work in pure OPA v1:
method = object.get(input.context.request.http, "method", "")
allow if { method == "GET" }

# But FAILS in OPA v1 with v0 compatibility mode:
# Error: "var cannot be used for rule name"

# Only this works in v0 compatibility mode:
allow {
  method := object.get(input.context.request.http, "method", "")
  method == "GET"
}

Why This Happens:

• v1 Parser: v0 compatibility mode still uses the strict OPA v1 parser
• v0 Emulation: Tries to emulate v0 behavior but with v1 parser limitations
• Stricter Rules: Some patterns that work in pure v1 fail in v0 compatibility mode

This means any AuthConfig using OPA policies would likely need syntax updates regardless of which approach we choose.

OPA Documentation References

For more details on OPA's migration approach, see:

• OPA v0 Compatibility Mode - How OPA v1 handles v0 syntax
• Upgrading to OPA v1 - Official migration guide

The Decision We Need to Make

Option A: Stay on v0 Behavior (Current State)

• ✅ Zero breaking changes for users
• ✅ All existing AuthConfig resources continue working unchanged
• ✅ No user migration required
• ❌ Using deprecated OPA patterns (linter warnings)
• ❌ Missing OPA v1 performance improvements
• ❌ Technical debt - will eventually be forced to migrate

Option B: Migrate to v1 with "v0 Compatibility"

• ✅ Modern OPA v1 packages internally
• ✅ Some v0 syntax continues working (see v0 compatibility docs)
• ❌ Still breaking - many v0 patterns fail due to parser strictness (as seen in PR #545)
• ❌ Paradoxically more restrictive than pure v1 in some cases
• ❌ Confusing - users don't know which v0 syntax works
• ❌ Semi-compatible - worst of both worlds

Option C: Full (Pure) v1 Migration (Clean Break)

• ✅ Future-proof - uses canonical OPA v1 syntax
• ✅ Consistent - all policies use same modern syntax
• ✅ Better performance - access to all v1 improvements
• ✅ Clear migration - users know exactly what to update (follow upgrade guide)
• ✅ Less restrictive than v0 compatibility mode for some patterns
• ❌ Breaking change - all OPA policies must be updated
• ❌ User effort - requires updating AuthConfig resources

Real-World Examples

v0 Compatibility Mode Restrictions

# This FAILS in v0 compatibility mode:
authorization:
  my-policy:
    opa:
      rego: |
        method = object.get(input.context.request.http, "method", "")
        allow { method == "GET" }

# This works in v0 compatibility mode:
authorization:
  my-policy:
    opa:
      rego: |
        allow {
          method := object.get(input.context.request.http, "method", "")
          method == "GET"
        }

Pure v1 Syntax

# This works in pure v1 mode:
authorization:
  my-policy:
    opa:
      rego: |
        method = object.get(input.context.request.http, "method", "")
        allow if { method == "GET" }

External Policy Implications

Important: External OPA policies (referenced by URL) must be compatible with whichever mode we choose:

• v0 Compatibility: External policies need very specific v0-compatible syntax
• Pure v1: External policies can use modern v1 syntax

Example external policy issue we encountered:

allowed-methods:
  opa:
    externalPolicy:
      url: https://raw.githubusercontent.com/example/policy.rego
      # ↑ This policy must match our chosen syntax mode

We Need Your Input! 🗣️

1. Your Current OPA Usage

• Do you use OPA policies in your AuthConfig resources?
• Do you use external OPA policy URLs?
• What patterns do you typically use? (simple rules, complex logic, variable assignments?)
• How many AuthConfig resources with OPA policies do you have?

2. Breaking Change Tolerance (Updated)

Given that all options except A require some policy updates:

• How acceptable would it be to update your OPA policies?
• Would you prefer cleaner v1 syntax or limited v0 compatibility?
• What timeline would work for your organization to make such updates?

3. External Dependencies

• Do you reference external OPA policy URLs in your configs?
• Are those external policies using v0 or v1 syntax?
• Do you maintain custom OPA policies that would need updating?

4. Migration Support

What would help you migrate?

• Migration guide with examples?
• Automated migration tools?
• Extended deprecation period?
• Side-by-side syntax documentation?
• Policy validation tools?

Suggested Timeline

• Discussion Period: Next 4 weeks (gather your feedback)
• Decision: End of month 1
• Implementation: Months 2-4 (if migration chosen)
• Release: Target next major version

Additional Resources

• Testing PR: #545 - OPA v1 Migration Attempt
• OPA v0 Compatibility: https://www.openpolicyagent.org/docs/v0-compatibility
• OPA v1 Upgrade Guide: https://www.openpolicyagent.org/docs/v0-upgrade

Key Questions for Discussion

1. Given the v0 compatibility limitations, which option do you prefer and why?
2. Do you use external OPA policy URLs? What syntax do they use?
3. Would you prefer clean v1 syntax or limited v0 compatibility?
4. How many OPA policies would you need to update?
5. What migration support would be most helpful?

Context: Why This Matters

• OPA v0.x is deprecated - will eventually lose support
• v0 compatibility is more limited than initially expected
• We want to avoid forced migration with no transition time
• Your input will directly influence our decision
• Breaking changes should be rare and well-justified

---

Please share your thoughts, use cases, and preferences below! Your feedback will directly shape how we handle this migration.

[guicassolato]

+1 to Pure v1 here.

This change will eventually be released with a new version of Authorino. Users who want to migrate to such version should prepare for the breaking change.

We want to avoid forced migration with no transition time

If this is absolutely imperative, well-known attributes could be introduced exposing internals of the binary such as the version of Authorino and/or some of its modules. Users could rely on those attributes to write dynamic external policy URLs that would always fetch the appropriate version of their OPA policies.

[KevFan]

We want to avoid forced migration with no transition time

If this is absolutely imperative, well-known attributes could be introduced exposing internals of the binary such as the version of Authorino and/or some of its modules. Users could rely on those attributes to write dynamic external policy URLs that would always fetch the appropriate version of their OPA policies.

Yeah, not absolutely imperative, but likely better posed as a question to on how to handle this breaking change for users. Definitely at least should give a notice period of the breaking change before we make the change 🤔 Not sure would it be even a good idea to have a transition period (support both versions for a period of time?) as the docs states:

Note: Using v0 packages and v1 packages in the same program is considered an anti-pattern and is not recommended or supported. Any interoperability between the two packages is not guaranteed and should be considered unsupported.

Possibly the ideal is to provide a script/tool to also help migrate existing AuthConfigs if using the new Authorino version with this change 🤔

[maleck13]

What if we introduced v1 as an option and allowed users to use it instead of v0, we could then depreciate v0 and have logs or perhaps a validating webhook that reports a warning? It may be a bad idea to use v0 and v1 in the same program, but in this case I wonder could we consider each AuthConfig "its own program"?

Just a thought but allowing a user to add an annotation to the authconfig to indicate using v1 but documenting that this annotation is going to become the default behaviour in version x.y of authorino. Or having some form of prefix (basically looking for a way to indicate use of v1 perhaps it can be inferred?) and when not v1 we issue the warning. This gives time for users to learn new syntax and migrate

[KevFan]

Yeah, originally I was thinking a warning in the status block if we were to support a transition period. To infer, I was just thinking to see does the OPA rego compile using v1 or v0 (unless people think this would be too heavy of an operation 🤔 ), and update the status block with the warning if v0 is successful. This way v1 immediately becomes the default behaviour without users needing to add an annotation and provide docs or tool to migrate

[maleck13]

Yeah this seems reasonable. Most of the Rego is small and so i would expect the overhead of compile relatively small. So I think we should log a warning and add a status warning. Then also adding documentation to call out the depreciation.