OPA

如何优雅的使用opa进行开发

文章目录

  1. 1. opa
    1. 1.1. run
    2. 1.2. eval
    3. 1.3. deps
    4. 1.4. test
    5. 1.5. check & fmt
  2. 2. vscode-opa
    1. 2.1. 功能
    2. 2.2. 快捷键配置

上文OPA-重新定义规则引擎-入门篇一个简单的例子介绍了OPA如何使用。也提供了在线运行版代码供大家尝试。

本文趁热打铁，介绍如何优雅的使用opa进行开发。

opa

opa（命令行工具）现在迭代比较快，为了性能和一些丰富的内置函数，推荐使用最新版

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

查看命令帮助

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

看介绍能知道每个命令是干啥的，用到时具体看help就行

这里边挑常用的命令讲下：

run

opa run是OPA实现的交互式运行（REPL）命令，本地学习或者调试会很方便

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  #获取上下文

你会得到json格式的data下的所有节点内容

主要有两类，所有quick-start目录下的

  • 配置文件（.json|.yaml|.yml）

对应的父节点是data

  • Rego文件(包括test文件)

对应的父节点是data.<package name>

Tips: 这样配置文件都挂在data这个根节点下了，如果想加载配置文件时增加父节点（如data.example.file）该怎么办？
可以文件的路径映射前缀 opa run example.file:quick-start
注意只会改变配置文件的父节点
这一点很有用，以后讲bundle也会提到

当然也可以指定输入文件input。这个比较特殊，命令行保留了包前缀repl.input给input

也就是说，可以用repl.input:<path to input.json>的方式传递输入，而避免挂载到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"
  ]
}

Tips: -w支持交互式窗口内实时文件变更reload
-s支持服务常驻式启动，启动后可以REST-Api查询；

eval

opa eval是用来查询策略结果

-d 指定上下文，-i 指定输入

-f 指定返回格式，默认json，还支持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"
    ]
  }
]

--explain=notes 配合 trace(msg) 可以调试执行过程

如下边规则增加trace(role_name)调用

1
2
3
4
5
allow {
  trace(role_name)
  user_has_role[role_name]
  role_has_permission[role_name]
}

--explain=notes时可以看到所有调用点note

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

除此，默认--explain支持full和fails的trace打印

Tips: 还支持性能分析 --metrics, --instrument, --profile

deps

opa deps 用来分析查询依赖

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

opa test 用来跑测试，-c支持输出覆盖率，--threshold 可指定通过覆盖率

check & fmt

opa check 是语法检查;opa fmt是格式化

vscode-opa

命令虽少可还是要记啊，有没有不用敲命令这么费劲的

有！官方强大的交互式编辑器扩展vscode-opa，了解下~~

安装后只要在vscode的配置里指定OPA执行文件路径就可以用了

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

功能

它基本支持上述大部分命令功能：

  • 在保存时检查语法（Check Syntax on Save）
  • 计算包结果（Evaluate Packages）
  • 计算选择部分结果（Evaluate Selections）
  • 部分评估选择（Partially Evaluate Selections）
  • 对选择部分代码运行追踪（Trace Selections）
  • 对选择部分性能分析（Profile Selections）
  • 在工作区中运行测试（Run Tests in Workspace）
  • 切换工作区的测试覆盖（Toggle Coverage in Workspace）
  • 切换选择部分的测试覆盖（Toggle Coverage of Selections）

其中评估（Evaluate)和测试覆盖显示（Coverage）在日常开发中很实用

具体如下图：

插件效果

快捷键配置

这里可以配置用户快捷键方便直接调起命令：

（官方推荐的前两个Evaluate的，后边Test相关的也可以加上）

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"
    },
]

Tip: 插件默认只取项目根目录的input.json作为输入
配置opa.bundleMode默认为true，则会只获取目录里的所有data.{json|yaml}
如果设置为false，则会获取目录中所有.{json|yaml}

好了，现在可以优雅的使用opa开发了。

下一篇我们来讲讲OPA的函数和虚拟文档，了解下他们各自适用的场景。

本文代码详见:NewbMiao/opa-koans

如有疑问，请文末留言交流或邮件：newbvirgil@gmail.com 本文链接 : https://newbmiao.github.io/2020/03/14/how-to-use-opa-cli-elegantly.html