OPA local development — CLI (run, eval, test) and vscode-opa

Contents

  1. 1. The opa binary
    1. 1.1. run — REPL
    2. 1.2. eval — one-shot queries
    3. 1.3. deps
    4. 1.4. test, check, fmt
  2. 2. vscode-opa
    1. 2.1. What you get
    2. 2.2. Keybindings (macOS)

After the RBAC intro, you’ll want opa on your PATH, a handful of CLI commands (run, eval, test, …), and the VS Code extension so you’re not retyping flags.

The opa binary

The CLI moves fast — new builtins and perf fixes land often. Grab a current build:

1
2
3
4
# mac
curl -L -o opa https://openpolicyagent.org/downloads/latest/opa_darwin_amd64
chmod +x opa
mv opa /usr/local/bin/opa

Help output:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
$ opa -h
An open source project to policy-enable your service.

Usage:
opa [command]

Available Commands:
build Compile Rego policy queries
check Check Rego source files
deps Analyze Rego query dependencies
eval Evaluate a Rego query
fmt Format Rego source files
help Help about any command
parse Parse Rego source file
run Start OPA in interactive or server mode
test Execute Rego test cases
version Print the version of OPA

You don’t need every subcommand on day one. These four cover most daily work.

run — REPL

opa run starts an interactive session — handy for learning and printf-debugging Rego.

1
2
3
4
5
$ opa run quick-start
OPA 0.17.3 (commit 28ca58f3, built at 2020-03-03T18:07:55Z)
Run 'help' to see a list of commands.

> data

You get JSON for everything under data. Two sources:

  • Config files (.json, .yaml, .yml) → data
  • .rego modules (including tests) → data.<package>

Want config under data.example.file instead of the root? Prefix the path: opa run example.file:quick-start — only JSON/YAML paths move; Rego packages stay as declared. Same trick shows up again with bundles.

Feed input via repl.input:<path> so it doesn’t land under data:

1
2
3
4
5
6
7
8
9
10
11
$ opa run  quick-start  repl.input:quick-start/input.json
> data.example_rbac
{
"allow": true,
"role_has_permission": [
"widget-reader"
],
"user_has_role": [
"widget-reader"
]
}

-w reloads changed files in the REPL. -s runs a persistent server (REST API).

eval — one-shot queries

opa eval answers a query against a bundle of modules + data.

-d loads policy/data paths, -i sets input, -f picks output format (values, bindings, pretty, source, …).

1
2
3
4
5
6
7
8
9
10
11
12
opa eval -f values -d quick-start -i quick-start/input.json "data.example_rbac"
[
{
"allow": true,
"role_has_permission": [
"widget-reader"
],
"user_has_role": [
"widget-reader"
]
}
]

Add trace(msg) in the policy and run with --explain=notes:

1
2
3
4
5
allow {
trace(role_name)
user_has_role[role_name]
role_has_permission[role_name]
}
1
2
3
4
5
6
opa eval -f pretty -d quick-start -i quick-start/input.json "data.example_rbac.allow" --explain=notes

query:1 Enter data.example_rbac.allow = _
quick-start/exa:6 | Enter data.example_rbac.allow
note | | Note "widget-reader"
true

Default --explain also supports full and fails. For timing: --metrics, --instrument, --profile.

deps

See what a query touches — base docs vs virtual docs:

1
2
3
4
5
6
7
8
9
10
$ opa deps -d quick-start "data.example_rbac"
+------------------------+---------------------------------------+
| BASE DOCUMENTS | VIRTUAL DOCUMENTS |
+------------------------+---------------------------------------+
| data.bindings | data.example_rbac.allow |
| data.roles | data.example_rbac.role_has_permission |
| input.action.operation | data.example_rbac.user_has_role |
| input.action.resource | |
| input.subject.user | |
+------------------------+---------------------------------------+

test, check, fmt

  • opa test — runs test_* rules; -c for coverage, --threshold to fail CI under a floor
  • opa check — parse/compile sanity
  • opa fmt — format Rego

vscode-opa

Tired of retyping commands? vscode-opa wraps most of the above.

Point it at your binary:

1
"opa.path": "/usr/local/bin/opa"

What you get

  • Check syntax on save
  • Evaluate package / selection
  • Partial evaluate selection
  • Trace / profile selection
  • Run tests and toggle coverage (workspace or selection)

Evaluate + coverage overlays are the ones I live in.

vscode-opa — eval, test, and coverage in the editor

Keybindings (macOS)

Official docs suggest evaluate first; I added test shortcuts too:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

[
{
"key": "cmd+e",
"command": "opa.eval.selection",
"when": "editorLangId == rego"
},
{
"key": "shift+cmd+a",
"command": "opa.eval.package",
"when": "editorLangId == rego"
},
{
"key": "shift+cmd+c",
"command": "opa.test.coverage.workspace",
"when": "editorLangId == rego"
},
{
"key": "shift+cmd+t",
"command": "opa.test.workspace",
"when": "editorLangId == rego"
},
]

By default the extension reads input.json at the workspace root. opa.bundleMode (default true) loads only data.{json|yaml} inside a directory; set false to pick up any .json/.yaml.

That’s enough to stay in the editor most days.

Next: functions vs virtual documents — when to use which.

Code: NewbMiao/opa-koans/quick-start

Questions? Leave a comment below or email: newbvirgil@gmail.com