OPA 1.0 docs #6455
OPA 1.0 docs #6455
Conversation
Signed-off-by: Johan Fylling <johan.dev@fylling.se>
Signed-off-by: Johan Fylling <johan.dev@fylling.se>
✅ Deploy Preview for openpolicyagent ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Signed-off-by: Johan Fylling <johan.dev@fylling.se>
docs/content/opa-1.md
Outdated
| @@ -0,0 +1,201 @@ | |||
| --- | |||
| title: OPA 1.0 | |||
| kind: misc | |||
There was a problem hiding this comment.
I'd be inclined to file this under a more prominent section, even the core docs for the next few releases. We're going to promote this, but it'd be nice to have it be eye catching in the sidebar too.
docs/content/opa-1.md
Outdated
| weight: 4 | ||
| --- | ||
|
|
||
| OPA v1.0 will introduce breaking changes to the Rego language. |
There was a problem hiding this comment.
There are also server changes such as Binding the OPA server to the localhost interface by default.
I know of at least one issue to the OPA server labelled as v1: #2137 - there might be others too. Does it make sense to talk more generally about breaking changes with this in mind?
| OPA’s Go SDK and Go API will be equipped with similar functionality, as well. | ||
| In addition to this, the bundle manifest will also be updated to include a bit that indicates whether pre-OPA v1.0 behavior is desired. | ||
| OPA tooling such as the `opa build` command will be equipped with a new flag that will allow users to control the relevant bit in the manifest. | ||
| This should be useful for cases when pre-OPA v1.0 functionality is desired but the users themselves have no control over the OPA deployment and hence cannot set the CLI flag. |
There was a problem hiding this comment.
I think this applies to
In addition to this, the bundle manifest will also be updated to include a bit that indicates whether pre-OPA v1.0 behavior is desired.
rather than
OPA tooling such as the
opa buildcommand will be equipped with a new flag that will allow users to control the relevant bit in the manifest.
| | p if { true } | {"p": true} | {"p": true} | | ||
| | p.a if { true } | {"p":{"a": true}} | {"p":{"a": true}} | | ||
| | p.a.b if { true } | {"p": {"a": {"b": true}} | {"p": {"a": {"b": true}} | | ||
| | p contains “a” | {"p": {"a"}} | {"p": {"a"}} | |
There was a problem hiding this comment.
Would it be helpful to provide a column for the best practice form from v1?
There was a problem hiding this comment.
Best practice would be anything in the output in v1.0 column that isn't a compile error.
Should we add a table to the end where we highlight what's the 1.0-compatible version of deprecated forms?
There was a problem hiding this comment.
Actually, on review, I think this table is great as it is.
docs/content/opa-1.md
Outdated
| If the Rego language was changed so that all rules were single-value by default, unless the `contains` keyword was used to make them multi-value, then the outcome of a rule like `p.a { true }` would change between today and v1.0 without generating an error. | ||
| Generating errors in this case is preferable to changing the semantics of existing rules. Whereby, use of the `if` keyword will be a requirement in OPA v1.0, as this is also backwards compatible with older versions of OPA. | ||
|
|
||
| In OPA v1.0, the `if` keyword is only required for rules with a declared body. Constants, rules that only consist of a value assignment, do not require `if`. |
There was a problem hiding this comment.
I think we can make this clearer by saying, "so all of the following forms are unchanged" or similar.
Other option is to remove the output in v1.0 col since it's the same?
docs/content/opa-1.md
Outdated
|
|
||
| import rego.v1 # Implies future.keywords.if and future.keywords.contains | ||
|
|
||
| a contains b if { b := 1} |
There was a problem hiding this comment.
| a contains b if { b := 1} | |
| a contains b if { b := 1 } |
|
|
||
| 1. A new `rego.v1` import has been introduced that, when used, makes OPA apply all restrictions that will eventually be enforced by default in OPA v1.0. | ||
| If a Rego module imports `rego.v1`, it means applicable `future.keywords` imports are implied. It is illegal to import both `rego.v1` and `future.keywords` in the same module. | ||
| 2. The `--rego-v1` flag on the `opa fmt` command will rewrite existing modules to use the `rego.v1` import instead of `future.keywords` imports. |
There was a problem hiding this comment.
Should we mention somewhere when these flags were introduced? I.e. v0.59.0 (or at least when this became stable)
| The Rego compiler supports [strict mode](../policy-language/#strict-mode), which enforces additional constraints and safety checks during compilation. | ||
| One of these checks is to ensure that `input` and `data` are reserved keywords and may not be used as names for rules and variable assignments. | ||
|
|
||
| The `input` document holds the user-provided input, while the data pushed into OPA and rule evaluation results are nested under the `data` document. |
There was a problem hiding this comment.
In some of the repos where I've helped teams enforce strict mode, they have not understood that with input as { .. } doesn't constitute shadowing. Perhaps it would be good to say something to that end here.
Signed-off-by: Johan Fylling <johan.dev@fylling.se>
Signed-off-by: Johan Fylling <johan.dev@fylling.se>
Fixes: open-policy-agent#6453 Signed-off-by: Johan Fylling <johan.dev@fylling.se>
requested by @anderseknert Signed-off-by: Johan Fylling <johan.dev@fylling.se>
Signed-off-by: Johan Fylling <johan.dev@fylling.se>
docs/content/policy-language.md
Outdated
| default allow := false | ||
|
|
||
| # 'if' is part of default v1.0 syntax, and doesn't need import. | ||
| # 'if' is required before role body. |
Signed-off-by: Johan Fylling <johan.dev@fylling.se>
No description provided.