Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: Updating Rego examples in docs to be 1.0 compliant #6444

Merged
merged 7 commits into from
Dec 15, 2023
Merged

docs: Updating Rego examples in docs to be 1.0 compliant #6444

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
257cd85
Updating Rego examples in docs to be 1.0 compliant
johanfylling Nov 28, 2023
ab758ca
Updating more Rego examples
johanfylling Nov 29, 2023
7f254b8
Merge branch 'main' into rego-v1/docs
johanfylling Dec 12, 2023
5ce7e0f
Merge branch 'main' into rego-v1/docs
johanfylling Dec 12, 2023
051a04d
Merge branch 'main' into rego-v1/docs
johanfylling Dec 14, 2023
ebcc5c1
Merge branch 'main' into rego-v1/docs
johanfylling Dec 14, 2023
6e52462
Merge branch 'main' into rego-v1/docs
johanfylling Dec 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions cmd/deps.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,8 +53,7 @@ Given a policy like this:

package policy

import future.keywords.if
import future.keywords.in
import rego.v1

allow if is_admin

Expand Down
14 changes: 8 additions & 6 deletions cmd/test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -442,7 +442,7 @@ Example policy (example/authz.rego):

package authz

import future.keywords.if
import rego.v1

allow if {
input.path == ["users"]
Expand All @@ -458,25 +458,27 @@ Example test (example/authz_test.rego):

package authz_test

import rego.v1

import data.authz.allow

test_post_allowed {
test_post_allowed if {
allow with input as {"path": ["users"], "method": "POST"}
}

test_get_denied {
test_get_denied if {
not allow with input as {"path": ["users"], "method": "GET"}
}

test_get_user_allowed {
test_get_user_allowed if {
allow with input as {"path": ["users", "bob"], "method": "GET", "user_id": "bob"}
}

test_get_another_user_denied {
test_get_another_user_denied if {
not allow with input as {"path": ["users", "bob"], "method": "GET", "user_id": "alice"}
}

todo_test_user_allowed_http_client_data {
todo_test_user_allowed_http_client_data if {
false # Remember to test this later!
}

Expand Down
20 changes: 13 additions & 7 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,8 +173,10 @@ In this module:
```live:rule_body:module
package example

u {
"foo" == "foo"
import rego.v1

u if {
"foo" == "foo"
}
```

Expand All @@ -200,12 +202,14 @@ Here's what a more complex set of blocks could look like:
``````markdown
```live:eg:module:hidden
package example

import rego.v1
```

We can define a scalar rule:

```live:eg/string:module
string = "hello"
string := "hello"
```

Which generates the document you'd expect:
Expand All @@ -216,7 +220,7 @@ Which generates the document you'd expect:
We can then define a rule that uses the value of `string`:

```live:eg/string/rule:module
r { input.value == string }
r if { input.value == string }
```

And query it with some input:
Expand All @@ -241,17 +245,19 @@ In that example, the output for `eg/string` is evaluated with only the module:
```
package example

string = "hello"
string := "hello"
```

Whereas the `eg/string/rule` output is evaluated with the module:

```
package example

string = "hello"
import rego.v1

string := "hello"

r { input.value == string }
r if input.value == string
```

as well the given query and input.
Expand Down
67 changes: 37 additions & 30 deletions docs/content/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ at some point in time, but have been introduced gradually.

```live:example/refs:module:hidden
package example
import future.keywords
import rego.v1
```

When OPA evaluates policies it binds data provided in the query to a global
Expand Down Expand Up @@ -164,7 +164,7 @@ input.deadbeef

```live:example/exprs:module:hidden
package example
import future.keywords
import rego.v1
```

To produce policy decisions in Rego you write expressions against input and
Expand Down Expand Up @@ -223,7 +223,7 @@ input.servers[0].protocols[0] == "telnet"

```live:example/vars:module:hidden
package example
import future.keywords
import rego.v1
```

You can store values in intermediate variables using the `:=` (assignment)
Expand Down Expand Up @@ -275,7 +275,7 @@ x != y # y has not been assigned a value

```live:example/iter:module:hidden
package example
import future.keywords
import rego.v1
```

Like other declarative languages (e.g., SQL), iteration in Rego happens
Expand Down Expand Up @@ -378,7 +378,7 @@ to express _FOR SOME_ and _FOR ALL_ more explicitly.
{{< info >}}
To ensure backwards-compatibility, the keywords discussed below introduced slowly.
In the first stage, users can opt-in to using the new keywords via a special import:
`import future.keywords.every` introduces the `every` keyword described here.
`import rego.v1` or, alternatively, `import future.keywords.every` introduces the `every` keyword described here.
(Importing `every` means also importing `in` without an extra `import` statement.)

At some point in the future, the keyword will become _standard_, and the import will
Expand Down Expand Up @@ -482,7 +482,7 @@ logic statements. Rules can either be "complete" or "partial".

```live:example/complete:module:hidden
package example.rules
import future.keywords
import rego.v1
```

#### Complete Rules
Expand Down Expand Up @@ -573,7 +573,7 @@ any_public_networks

```live:example/partial_set:module:hidden
package example
import future.keywords
import rego.v1
```

Partial rules are if-then statements that generate a set of values and
Expand All @@ -586,8 +586,8 @@ public_network contains net.id if {
}
```

In the example above `public_network[net.id]` is the rule head and `net :=
input.networks[_]; net.public` is the rule body. You can query for the entire
In the example above `public_network contains net.id if` is the rule head and
`some net in input.networks; net.public` is the rule body. You can query for the entire
set of values just like any other value:

```live:example/partial_set/1/extent:query:merge_down
Expand Down Expand Up @@ -649,14 +649,16 @@ protocols:
```live:example/logical_or/complete:module:openable,merge_down
package example.logical_or

import rego.v1

default shell_accessible := false

shell_accessible := true {
input.servers[_].protocols[_] == "telnet"
shell_accessible if {
input.servers[_].protocols[_] == "telnet"
}

shell_accessible := true {
input.servers[_].protocols[_] == "ssh"
shell_accessible if {
input.servers[_].protocols[_] == "ssh"
}
```
```live:example/logical_or/complete:input:merge_down
Expand Down Expand Up @@ -690,14 +692,16 @@ could be modified to generate a set of servers that expose `"telnet"` or
```live:example/logical_or/partial_set:module:openable,merge_down
package example.logical_or

shell_accessible[server.id] {
server := input.servers[_]
server.protocols[_] == "telnet"
import rego.v1

shell_accessible contains server.id if {
server := input.servers[_]
server.protocols[_] == "telnet"
}

shell_accessible[server.id] {
server := input.servers[_]
server.protocols[_] == "ssh"
shell_accessible contains server.id if {
server := input.servers[_]
server.protocols[_] == "ssh"
}
```
```live:example/logical_or/partial_set:input:merge_down
Expand Down Expand Up @@ -748,23 +752,24 @@ For example:

```live:example/final:module:openable,merge_down
package example
import future.keywords.every # "every" implies "in"

allow := true { # allow is true if...
import rego.v1

allow if { # allow is true if...
count(violation) == 0 # there are zero violations.
}

violation[server.id] { # a server is in the violation set if...
violation contains server.id if { # a server is in the violation set if...
some server in public_servers # it exists in the 'public_servers' set and...
"http" in server.protocols # it contains the insecure "http" protocol.
}

violation[server.id] { # a server is in the violation set if...
violation contains server.id if { # a server is in the violation set if...
some server in input.servers # it exists in the input.servers collection and...
"telnet" in server.protocols # it contains the "telnet" protocol.
}

public_servers[server] { # a server exists in the public_servers set if...
public_servers contains server if { # a server exists in the public_servers set if...
some server in input.servers # it exists in the input.servers collection and...

some port in server.ports # it references a port in the input.ports collection and...
Expand Down Expand Up @@ -805,8 +810,8 @@ curl -L -o opa https://openpolicyagent.org/downloads/{{< current_version >}}/opa

{{< info >}}
Windows users can obtain the OPA executable from [here](https://openpolicyagent.org/downloads/{{< current_version >}}/opa_windows_amd64.exe).
The steps below are the same for Windows users except the executable name will be different.
Windows executable file name is opa_windows_amd64.exe, which inclues file extension name 'exe'. The checksums file name is opa_windows_amd64.exe.sha256.
The steps below are the same for Windows users except the executable name will be different.
Windows executable file name is opa_windows_amd64.exe, which inclues file extension name 'exe'. The checksums file name is opa_windows_amd64.exe.sha256.
Windows users can obtain the checksums from [here](https://openpolicyagent.org/downloads/{{< current_version >}}/opa_windows_amd64.exe.sha256).
{{< /info >}}

Expand Down Expand Up @@ -880,24 +885,26 @@ For example:
```live:example/using_opa:module:openable,read_only
package example

import rego.v1

default allow := false # unless otherwise defined, allow is false

allow := true { # allow is true if...
allow if { # allow is true if...
count(violation) == 0 # there are zero violations.
}

violation[server.id] { # a server is in the violation set if...
violation contains server.id if { # a server is in the violation set if...
some server
public_server[server] # it exists in the 'public_server' set and...
server.protocols[_] == "http" # it contains the insecure "http" protocol.
}

violation[server.id] { # a server is in the violation set if...
violation contains server.id if { # a server is in the violation set if...
server := input.servers[_] # it exists in the input.servers collection and...
server.protocols[_] == "telnet" # it contains the "telnet" protocol.
}

public_server[server] { # a server exists in the public_server set if...
public_server contains server if { # a server exists in the public_server set if...
some i, j
server := input.servers[_] # it exists in the input.servers collection and...
server.ports[_] == input.ports[i].id # it references a port in the input.ports collection and...
Expand Down
Loading