Skip to content

Commit

Permalink
docs: Add v0 import example to v0-compatibility
Browse files Browse the repository at this point in the history
This shows another way to use two versions of rego in the same app.

Signed-off-by: Charlie Egan <charlie@styra.com>
  • Loading branch information
charlieegan3 committed Dec 17, 2024
1 parent e26a7ad commit 297cf7a
Showing 1 changed file with 59 additions and 6 deletions.
65 changes: 59 additions & 6 deletions docs/content/v0-compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,17 +61,19 @@ as part of an upgrade to OPA v1.0.

### v0.x compatibility mode in Rego package

There are three ways to enable v0.x compatibility mode in the [Rego package](https://pkg.go.dev/github.com/open-policy-agent/opa/rego):
There are various ways to use v0.x compatible functionality in the
[Rego package](https://pkg.go.dev/github.com/open-policy-agent/opa/v1/rego):

1. Set the Rego version on modules
2. Set the Rego version on bundle manifests
3. Use the SetRegoVersion Rego argument
4. Import the [v0 package](https://pkg.go.dev/github.com/open-policy-agent/opa/rego)

1 & 2 are preferred as they are more granular and make it easier to run a
mix of v0.x and v1.0 compatible Rego in the same OPA instance and thus better
support a gradual upgrade path.

The `SetRegoVersion` method on [Module](https://pkg.go.dev/github.com/open-policy-agent/opa/ast#Module.SetRegoVersion?)
The `SetRegoVersion` method on [Module](https://pkg.go.dev/github.com/open-policy-agent/opa/v1/ast#Module.SetRegoVersion?)
can be used like this:

```go
Expand All @@ -82,7 +84,7 @@ m := ast.Module{
m.SetRegoVersion(ast.RegoV0)
```

Similarly, the [Bundle Manifest](https://pkg.go.dev/github.com/open-policy-agent/opa/bundle#Manifest.SetRegoVersion) Rego version
Similarly, the [Bundle Manifest](https://pkg.go.dev/github.com/open-policy-agent/opa/v1/bundle#Manifest.SetRegoVersion) Rego version
can be set like this:

```go
Expand All @@ -92,9 +94,10 @@ b := Bundle{
b.SetRegoVersion(ast.RegoV0)
```

If you cannot set the Rego version on modules or bundle manifests, you
can use the [`SetRegoVersion`](https://pkg.go.dev/github.com/open-policy-agent/opa/rego#SetRegoVersion) Rego argument to control the Rego version used when
evaluating policies.
If you cannot set the Rego version on modules or bundle manifests, you can use
the
[`SetRegoVersion`](https://pkg.go.dev/github.com/open-policy-agent/opa/v1/rego#SetRegoVersion)
Rego argument to control the Rego version used when evaluating policies.

Users are encouraged to use the more granular options where possible to better
allow them to upgrade Rego used in their system to Rego v1 gradually.
Expand All @@ -111,6 +114,56 @@ r := rego.New(
)
```

Finally, another option is to import the `v0` package instead. This can even be
used alongside the `v1` package in the same program if required. The program
below will evaluate the same Rego using both the v0 and v1 Rego packages, v1 is
running in v0 compatibility mode with `SetRegoVersion`:

```go
package main

import (
"context"
"encoding/json"
"fmt"

v0rego "github.com/open-policy-agent/opa/rego"
v1ast "github.com/open-policy-agent/opa/v1/ast"
v1rego "github.com/open-policy-agent/opa/v1/rego"
)

func main() {
// we have a v0 Rego module, we want to evaluate it using the v1 rego
// package and the v0 rego package in the same program.
module := `package example
messages[msg] {
msg := "foo"
}
`

rv1 := v1rego.New(
v1rego.Query("data.example.messages"),
v1rego.SetRegoVersion(v1ast.RegoV0),
v1rego.Module("example.rego", module),
)

rs, _ := rv1.Eval(context.TODO())
bs, _ := json.Marshal(rs)
fmt.Println(string(bs))

rv0 := v0rego.New(
v0rego.Query("data.example.messages"),
v0rego.Module("example.rego", module),
)

rs, _ = rv0.Eval(context.TODO())
bs, _ = json.Marshal(rs)

fmt.Println(string(bs))
}
```

### v0.x compatibility mode in the OPA Go SDK

{{< info >}}
Expand Down

0 comments on commit 297cf7a

Please sign in to comment.