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: Adding example for rego.metadata.role() usage #4640

Merged
merged 1 commit into from
Apr 28, 2022
Merged

docs: Adding example for rego.metadata.role() usage #4640

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
22 changes: 11 additions & 11 deletions docs/content/annotations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ weight: 18

The package and individual rules in a module can be annotated with a rich set of metadata.

```live:rego/metadata:query:read_only
```live:rego/metadata:module:read_only
# METADATA
# title: My rule
# description: A rule that determines if x is allowed.
Expand Down Expand Up @@ -64,7 +64,7 @@ The `document` scope annotation can be applied to any rule in the set (i.e., ord

#### Example

```live:rego/metadata/scope:query:read_only
```live:rego/metadata/scope:module:read_only
# METADATA
# scope: document
# description: A set of rules that determines if x is allowed.
Expand All @@ -88,7 +88,7 @@ The `title` annotation is a string value giving a human-readable name to the ann

#### Example

```live:rego/metadata/title:query:read_only
```live:rego/metadata/title:module:read_only
# METADATA
# title: Allow Ones
allow {
Expand All @@ -108,7 +108,7 @@ The `description` annotation is a string value describing the annotation target,

#### Example

```live:rego/metadata/description:query:read_only
```live:rego/metadata/description:module:read_only
# METADATA
# description: |
# The 'allow' rule...
Expand All @@ -135,7 +135,7 @@ When a *related-resource* entry is presented as a string, it needs to be a valid

#### Examples

```live:rego/metadata/related_resources1:query:read_only
```live:rego/metadata/related_resources1:module:read_only
# METADATA
# related_resources:
# - ref: https://example.com
Expand All @@ -147,7 +147,7 @@ allow {
}
```

```live:rego/metadata/related_resources2:query:read_only
```live:rego/metadata/related_resources2:module:read_only
# METADATA
# organizations:
# - https://example.com/foo
Expand Down Expand Up @@ -178,7 +178,7 @@ Optionally, the last word may represent an email, if enclosed with `<>`.

#### Examples

```live:rego/metadata/authors1:query:read_only
```live:rego/metadata/authors1:module:read_only
# METADATA
# authors:
# - name: John Doe
Expand All @@ -190,7 +190,7 @@ allow {
}
```

```live:rego/metadata/authors2:query:read_only
```live:rego/metadata/authors2:module:read_only
# METADATA
# authors:
# - John Doe
Expand All @@ -207,7 +207,7 @@ The `organizations` annotation is a list of string values representing the organ

#### Example

```live:rego/metadata/organizations:query:read_only
```live:rego/metadata/organizations:module:read_only
# METADATA
# organizations:
# - Acme Corp.
Expand All @@ -225,7 +225,7 @@ In-depth information on this topic can be found [here](../schemas#schema-annotat

#### Example

```live:rego/metadata/schemas:query:read_only
```live:rego/metadata/schemas:module:read_only
# METADATA
# schemas:
# - input: schema.input
Expand All @@ -242,7 +242,7 @@ The `custom` annotation is a mapping of user-defined data, mapping string keys t

#### Example

```live:rego/metadata/custom:query:read_only
```live:rego/metadata/custom:module:read_only
# METADATA
# custom:
# my_int: 42
Expand Down
50 changes: 49 additions & 1 deletion docs/content/policy-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1099,12 +1099,60 @@ net.cidr_contains_matches({["1.1.0.0/16", "foo"], "1.1.2.0/24"}, {"x": "1.1.1.12
| <span class="opa-keep-it-together">``output := rego.metadata.chain()``</span> | Each entry in the ``output`` array represents a node in the path ancestry (chain) of the active rule that also has declared [annotations](../annotations).``output`` is ordered starting at the active rule, going outward to the most distant node in its package ancestry. A chain entry is a JSON document with two members: ``path``, an array representing the path of the node; and ``annotations``, a JSON document containing the annotations declared for the node. The first entry in the chain always points to the active rule, even if it has no declared annotations (in which case the ``annotations`` member is not present). | ✅ |
| <span class="opa-keep-it-together">``output := rego.metadata.rule()``</span> | Returns a JSON object ``output`` containing the set of [annotations](../annotations) declared for the active rule and using the `rule` [scope](../annotations#scope). If no annotations are declared, an empty object is returned. | ✅ |

#### Example

Given the input document

```live:example/metadata/1:input
{
"number": 11,
"subject": {
"name": "John doe",
"role": "customer"
}
}
```

the following policy

```live:example/metadata/1:module
package example

# METADATA
# title: Deny invalid numbers
# description: Numbers may not be higer than 5
# custom:
# severity: MEDIUM
deny[format(rego.metadata.rule())] {
input.number > 5
}

# METADATA
# title: Deny non-admin subjects
# description: Subject must have the 'admin' role
# custom:
# severity: HIGH
deny[format(rego.metadata.rule())] {
input.subject.role != "admin"
}

format(meta) := {"severity": meta.custom.severity, "reason": meta.description}
```

will output

```live:example/metadata/1:query:merge_down
deny
```
```live:example/metadata/1:output
```

#### Metadata Merge strategies

When multiple [annotations](../annotations) are declared along the path ancestry (chain) for a rule, how any given annotation should be selected, inherited or merged depends on the semantics of the annotation, the context of the rule, and the preferences of the developer.
OPA doesn't presume what merge strategy is appropriate; instead, this lies in the hands of the developer. The following example demonstrates how some string and list type annotations in a metadata chain can be merged into a single metadata object.

```live:rego/metadata:query:read_only
```live:rego/metadata:module:read_only
# METADATA
# title: My Example Package
# description: A set of rules illustrating how metadata annotations can be merged.
Expand Down