Update docs and server binding addr per OPA v1.0 specs #7140

ashutosh-narkar · 2024-10-29T23:36:03Z

This changes updates the docs and all the policy examples in them to
be OPA v1.0-compliant. It also binds the OPA server to localhost
interface by default per OPA v1.0 specs.

Co-authored-by: Charlie Egan [email protected]
Signed-off-by: Ashutosh Narkar [email protected]

netlify · 2024-11-07T22:38:27Z

✅ Deploy Preview for openpolicyagent ready!

Name	Link
🔨 Latest commit	`cb7ba62`
🔍 Latest deploy log	https://app.netlify.com/sites/openpolicyagent/deploys/6763f29c80cf4c0008e8b70b
😎 Deploy Preview	https://deploy-preview-7140--openpolicyagent.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

anderseknert

Great work! Is the plan to add docs on how to "downgrade" OPA 1.0 for legacy compatibility here or in a later PR?

ashutosh-narkar · 2024-11-12T00:26:45Z

Great work! Is the plan to add docs on how to "downgrade" OPA 1.0 for legacy compatibility here or in a later PR?

Yes @anderseknert. We'll add a section for 0.x compatibility later in this PR.

anderseknert · 2024-11-12T08:37:32Z

@ashutosh-narkar neat! If you can remember to, ping me when that's in and I'd be happy to review 😃

johanfylling

Just a few comments/questions

docs/content/cli.md

johanfylling · 2024-11-28T10:01:28Z

cmd/run.go

-	if !addrSetByUser && !rt.Params.V0Compatible && rt.Params.V1Compatible {
-		rt.Params.Addrs = &[]string{defaultLocalAddr}
+	if !addrSetByUser && rt.Params.V0Compatible {
+		rt.Params.Addrs = &[]string{defaultAddr}


I wonder, should we really default to 0.0.0.0 if the --v0-compatible flag is set? This has security implications. If you can add --v0-compatible to your command, you can also add --addr ':8181'.

This is existing behavior which the flag is supposed to maintain. We already have a section on the security implications of this in the docs and we also log a warning on the command line. So I don't see a reason to change this.

johanfylling · 2024-11-28T10:15:11Z

docs/content/policy-language.md

-```
+Name | Description                                                                                                                                                                                                                                                    
+--- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+Duplicate imports | Duplicate [imports](../policy-language/#imports), where one import shadows another, are prohibited.                                                                                                                                                            


We should drop this table entry, as this is part of the default v1 constraints.

We could keep it, with a comment, to let users know it's still relevant with --v0-compatible --strict. But maybe it's more clear if that's a separate table. And then it should probably also be put in the v0 migration guide, with just a link here.

I've reworded this section to align with 1.0

johanfylling · 2024-11-28T10:15:31Z

docs/content/policy-language.md

+Duplicate imports | Duplicate [imports](../policy-language/#imports), where one import shadows another, are prohibited.                                                                                                                                                            
+Unused local assignments | Unused arguments or [assignments](../policy-reference/#assignment-and-equality) local to a rule, function or comprehension are prohibited                                                                                                                                   
+Unused imports | Unused [imports](../policy-language/#imports) are prohibited.                                                                                                                                                                                                  
+`input` and `data` reserved keywords | `input` and `data` are reserved keywords, and may not be used as names for rules and variable assignment.                                                                                                                                                     


johanfylling · 2024-11-28T10:15:40Z

docs/content/policy-language.md

+Unused local assignments | Unused arguments or [assignments](../policy-reference/#assignment-and-equality) local to a rule, function or comprehension are prohibited                                                                                                                                   
+Unused imports | Unused [imports](../policy-language/#imports) are prohibited.                                                                                                                                                                                                  
+`input` and `data` reserved keywords | `input` and `data` are reserved keywords, and may not be used as names for rules and variable assignment.                                                                                                                                                     
+Use of deprecated built-ins | Use of deprecated functions is prohibited, and these will be removed in OPA 1.0. Deprecated built-in functions: `any`, `all`, `re_match`,  `net.cidr_overlap`, `set_diff`, `cast_array`, `cast_set`, `cast_string`, `cast_boolean`, `cast_null`, `cast_object`


johanfylling

Lookin' good :). Some comments.

docs/content/opa-1.md

docs/content/v0-compatibility.md

johanfylling · 2024-12-03T15:20:48Z

docs/content/v0-compatibility.md

+  `--rego-v1` flag below.
+- `inspect`: supports Rego v0 syntax modules, use of `import rego.v1` is optional.
+- `parse`: supports Rego v0 syntax modules, use of `import rego.v1` is optional.
+- `run`: supports modules (including discovery bundle) using Rego v0 syntax, use of `import rego.v1` is optional. Binds server listeners to all interfaces by default, rather than localhost.


Not sure if we should really bind to all interfaces with the --v0-compatible flag ..
If you can add --v0-compatible to your command, then surely you can add the flag to set an external listener too.

docs/content/v0-compatibility.md

docs/content/v0-upgrade.md

johanfylling

Some more comments

docs/content/policy-language.md

docs/content/v0-upgrade.md

johanfylling

Looks good 👍
Just a couple of notes.

docs/content/policy-language.md

johanfylling · 2024-12-06T14:22:23Z

docs/content/v0-compatibility.md

+
+### 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):


I wonder if we need this section at all. The old OPA API will retain the v0 behaviour, and you need to update your code to import the v1 packages to get the new v1 behaviour.

The techniques described here are however a good primer on how to manually control the applied rego-version regardless of whether you're using the v0 or v1 parts of the API. Is there a place where they would fit in?

johanfylling · 2024-12-06T14:30:27Z

docs/content/v0-compatibility.md

+
+### 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):


OK maybe we shouldn't drop the section completely; it's probably worthwhile mentioning that the old parts of the API forks as before, to soothe some nerves.

We're gonna need to find a good place for describing the v1 API, though.

docs/content/v0-upgrade.md

ashutosh-narkar · 2024-12-06T22:16:03Z

We're gonna need to find a good place for describing the v1 API, though.

Maybe Integrating OPA section?

ashutosh-narkar · 2024-12-18T18:43:17Z

docs/content/cli.md

Will this get regenerated? cc @johanfylling @charlieegan3

I have rebased and regenerated it now. I have pushed directly to the branch.

This changes updates the docs and all the policy examples in them to be OPA v1.0-compliant. It also binds the OPA server to `localhost` interface by default per OPA v1.0 specs. Co-authored-by: Charlie Egan <[email protected]> Signed-off-by: Ashutosh Narkar <[email protected]>

Signed-off-by: Charlie Egan <[email protected]>

ashutosh-narkar force-pushed the 1.0-docs branch from 685eef0 to f660edd Compare November 7, 2024 23:49

anderseknert reviewed Nov 11, 2024

View reviewed changes

ashutosh-narkar force-pushed the 1.0-docs branch 2 times, most recently from 73c0bb2 to 7215e50 Compare November 23, 2024 01:25

johanfylling reviewed Nov 28, 2024

View reviewed changes

johanfylling reviewed Dec 3, 2024

View reviewed changes

ashutosh-narkar force-pushed the 1.0-docs branch from c72434b to 6f8aa58 Compare December 4, 2024 02:07

johanfylling reviewed Dec 5, 2024

View reviewed changes

ashutosh-narkar force-pushed the 1.0-docs branch from 8d41fd1 to aaacc6c Compare December 5, 2024 20:32

ashutosh-narkar marked this pull request as ready for review December 5, 2024 22:44

ashutosh-narkar requested review from anderseknert and johanfylling December 5, 2024 22:47

ashutosh-narkar force-pushed the 1.0-docs branch from 77a3db8 to e31b7d3 Compare December 6, 2024 00:00

ashutosh-narkar changed the title ~~1.0 docs~~ Update docs and server binding addr per OPA v1.0 specs Dec 6, 2024

johanfylling previously approved these changes Dec 6, 2024

View reviewed changes

ashutosh-narkar dismissed johanfylling’s stale review via 1e835ab December 6, 2024 22:15

ashutosh-narkar force-pushed the 1.0-docs branch from e31b7d3 to 1e835ab Compare December 6, 2024 22:15

ashutosh-narkar force-pushed the 1.0-docs branch from 1e835ab to 427330f Compare December 6, 2024 22:22

ashutosh-narkar force-pushed the 1.0-docs branch from cfb3749 to 6d9847d Compare December 18, 2024 00:44

charlieegan3 force-pushed the 1.0-docs branch from d8ea86c to adba53c Compare December 18, 2024 14:56

ashutosh-narkar force-pushed the 1.0-docs branch from ef9d8b7 to 09d5a2f Compare December 18, 2024 18:42

ashutosh-narkar commented Dec 18, 2024

View reviewed changes

charlieegan3 force-pushed the 1.0-docs branch from 09d5a2f to 07d416e Compare December 19, 2024 09:43

docs: Regenerate CLI docs

cb7ba62

Signed-off-by: Charlie Egan <[email protected]>

johanfylling approved these changes Dec 19, 2024

View reviewed changes

johanfylling merged commit 9a7d920 into open-policy-agent:main Dec 19, 2024
28 checks passed

BrewTestBot mentioned this pull request Dec 20, 2024

opa 1.0.0 Homebrew/homebrew-core#201984

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update docs and server binding addr per OPA v1.0 specs #7140

Update docs and server binding addr per OPA v1.0 specs #7140

ashutosh-narkar commented Oct 29, 2024 •

edited

Loading

netlify bot commented Nov 7, 2024 •

edited

Loading

anderseknert left a comment

ashutosh-narkar commented Nov 12, 2024

anderseknert commented Nov 12, 2024

johanfylling left a comment

johanfylling Nov 28, 2024

ashutosh-narkar Dec 4, 2024

johanfylling Nov 28, 2024

ashutosh-narkar Dec 4, 2024

johanfylling Nov 28, 2024

johanfylling Nov 28, 2024

johanfylling left a comment

johanfylling Dec 3, 2024

johanfylling left a comment

johanfylling left a comment

johanfylling Dec 6, 2024

johanfylling Dec 6, 2024

ashutosh-narkar commented Dec 6, 2024

ashutosh-narkar Dec 18, 2024

charlieegan3 Dec 19, 2024


		### 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):

Update docs and server binding addr per OPA v1.0 specs #7140

Update docs and server binding addr per OPA v1.0 specs #7140

Conversation

ashutosh-narkar commented Oct 29, 2024 • edited Loading

netlify bot commented Nov 7, 2024 • edited Loading

✅ Deploy Preview for openpolicyagent ready!

anderseknert left a comment

Choose a reason for hiding this comment

ashutosh-narkar commented Nov 12, 2024

anderseknert commented Nov 12, 2024

johanfylling left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johanfylling left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johanfylling left a comment

Choose a reason for hiding this comment

johanfylling left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ashutosh-narkar commented Dec 6, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ashutosh-narkar commented Oct 29, 2024 •

edited

Loading

netlify bot commented Nov 7, 2024 •

edited

Loading