GeekIt

Open Policy Agent命令速查

安装与子命令、服务配置、eval 求值、Rego 语法与内置函数、测试覆盖率、打包签名、集成部署与报错排查等 158 条命令

共 158 条命令 · 12 类场景 · 点击右侧图标可复制

命令 / 片段说明复制
opa version查看 OPA 版本,1.0 起 Rego 默认使用 v1 语法
opa -h查看全部子命令
opa run进入交互式 REPL,边写边验证策略
opa run --server以服务模式启动,暴露 REST API(默认 8181)
opa eval一次性求值,最常用的调试入口
opa test执行以 test_ 开头的测试规则
opa fmt格式化 Rego 代码
opa check语法与类型检查
opa build把策略与数据打包成 bundle
opa inspect查看 bundle 内容与 manifest
opa deps输出包与规则依赖关系
opa capabilities查看当前版本支持的内置函数
opa sign为 bundle 签名,防止策略被篡改
brew install opamacOS 安装
curl -L -o opa https://openpolicyagent.org/downloads/latest/opa_linux_amd64_static下载静态二进制,适合容器与 CI
命令 / 片段说明复制
opa run --server --addr :8181启动服务,指定监听地址
opa run --server --addr :8181 ./policies启动时加载本地策略目录
opa run --server -b bundle.tar.gz以 bundle 方式加载策略
opa run --server -c config.yaml使用配置文件启用 bundle 拉取与日志上报
opa run --server --log-level debug开启调试日志,排查决策异常
opa run --server --diagnostic-addr :8282健康检查与指标端口,与业务端口分离
opa run --server --watch监听策略文件变化并热加载(开发环境用)
opa run --server --authentication=token --authorization=basicAPI 访问控制,生产必须开启
opa run --server --tls-cert-file cert.pem --tls-private-key-file key.pem启用 HTTPS
services: acmecorp: url: https://api.example.com配置远端服务凭据,供 bundle/日志使用
bundles: authz: service: acmecorp resource: bundles/authz.tar.gz polling: min_delay_seconds: 10bundle 拉取配置,实现策略集中分发
decision_logs: service: acmecorp reporting: min_delay_seconds: 30决策日志上报,做审计与回溯
status: service: acmecorp状态上报,便于平台监控 agent 健康度
命令 / 片段说明复制
opa eval -d policy.rego "data.example.allow"加载策略并求值某个决策
opa eval -d policy.rego -i input.json "data.example.allow"带输入文件求值
opa eval -d policy.rego -I "data.example.allow"从标准输入读取 input,管道场景用
opa eval -f pretty -d policy.rego "data.example"美化输出(默认)
opa eval -f raw -d policy.rego "data.example.allow"只输出值,便于脚本判断
opa eval -f json -d policy.rego "data.example.allow"JSON 输出,便于程序解析
opa eval -f bindings -d policy.rego "data.example"只输出变量绑定结果
opa eval --fail-defined -f raw -d policy.rego "data.example.deny[_]"有结果即返回非零,CI 门禁常用
opa eval --explain=full -d policy.rego -i input.json "data.example.allow"输出完整求值过程,定位为何不通过
opa eval --explain=fails "data.example.allow"只显示失败分支,输出更精简
opa eval -b bundle.tar.gz "data.example.allow"基于 bundle 求值
opa eval -d policy.rego --input-file input.json -v "data"查看整个 data 命名空间,确认加载是否正确
命令 / 片段说明复制
package example声明包名,决定 data.example 路径
import future.keywords.if老版本需显式导入关键字(1.0+ 默认启用)
default allow := false默认拒绝:策略未命中时返回 false
allow if { input.method == "GET" input.path == "/public" }v1 语法:条件块用 if 引导
allow if input.user == "admin"单行条件可省略大括号
deny contains msg if { not input.authed msg := "unauthenticated" }集合规则,可累积多条拒绝原因
allow := true { input.user == "admin" }老式写法(0.x),迁移时需改为 if
some role in input.roles role == "admin"遍历集合,v1 推荐 in 写法
every role in input.roles { role != "banned" }全称判断,全部满足才为真
admins := [u | some u in input.users; u.role == "admin"]数组推导,做数据加工
count_by_role := {r: n | some r in {"admin", "dev"} n := count([u | u := input.users[_]; u.role == r]) }对象推导,生成聚合结果
allow if { some i input.roles[i] == "admin" }索引遍历写法,兼容老版本
not p 表示取反取反前变量必须已绑定,否则报 unsafe var
策略里不要用 = 做比较比较用 ==,= 是统一(unification)
命令 / 片段说明复制
count(input.roles) > 0计数,判断集合非空
concat(",", input.groups)拼接字符串数组
split(input.path, "/")按分隔符拆分
contains(input.path, "/admin")字符串包含判断
startswith(input.path, "/api/")前缀匹配
endswith(input.path, ".json")后缀匹配
regex.match("^/admin/.*$", input.path)正则匹配,复杂规则用
glob.match("/admin/*", ["/"], input.path)通配符匹配,注意分隔符参数
net.cidr_contains("10.0.0.0/8", input.ip)IP 段判断,网络策略常用
json.marshal(input)序列化为 JSON 字符串
json.unmarshal(input.body)解析 JSON 请求体
yaml.unmarshal(input.config)解析 YAML(K8s 场景常用)
time.now_ns() < time.parse_rfc3339_ns(input.expire_at)时间比较,做有效期控制
object.get(input, "user", "anonymous")安全取字段并给默认值
array.concat(input.a, input.b)合并数组
sort(input.roles)排序,便于做稳定输出
sum([1, 2, 3])求和
sprintf("%s-%d", [input.name, input.id])格式化字符串
walk(input, [path, value])递归遍历所有节点
http.send({"method": "get", "url": "https://api/check", "timeout": "3s"})外部调用(慎用,会阻塞求值)
opa capabilities | grep cidr确认内置函数是否支持
命令 / 片段说明复制
input.request.methodinput 是每次请求传入的上下文,不落盘
data.inventory.serversdata 是加载进来的策略与静态数据
opa eval -d data.json -d policy.rego "data.example.allow"同时加载数据文件与策略
opa eval -d policies/ "data"加载整个目录,确认包路径正确
json 数据文件内容即 data 根节点例如 data.json 里 {"inventory": {...}} 对应 data.inventory
data.example.allow 是完整决策路径与 package 声明一一对应
input 为空时不要直接取嵌套字段用 object.get 或 default 避免 undefined
opa eval -I "data.example.allow" < input.json重定向方式注入 input
策略内不要缓存外部状态OPA 求值应尽量纯函数化,便于测试与缓存
大对象走 data 而非 input静态清单放 data 可复用,避免每次请求传输
命令 / 片段说明复制
opa test .执行当前目录全部测试
opa test -v .输出每个用例的执行明细
opa test -r .显示通过的用例(默认只显示失败)
opa test --coverage .输出行覆盖率报告
opa test --coverage --threshold 80 .覆盖率低于 80% 时返回非零
opa test -f json .JSON 结果,接入流水线解析
test_admin_allowed if { allow with input as {"user": "admin"} }用 with 覆盖 input 做用例
test_deny_unknown_user if { not allow with input as {"user": "guest"} }验证拒绝路径
test_rule if { allow with data.inventory as {"servers": []} }用 with 模拟 data,隔离外部依赖
test_http if { http.send(...) with http.send as {"status_code": 200} }mock 内置函数,避免真实网络调用
print("value:", input.user)调试打印(需 --explain 或直接运行测试查看)
test_ 前缀且无参数才是测试命名不符合约定不会被收集执行
命令 / 片段说明复制
opa fmt -w .就地格式化所有 Rego 文件
opa fmt -d policy.rego只显示格式差异
opa fmt --check .检查格式,CI 中不合规返回非零
opa check .语法检查,不执行策略
opa check --strict .严格模式,检查未使用变量等问题
opa check --v0-compatible .检查是否兼容旧版语法
opa deps .输出依赖树,排查循环引用
opa inspect bundle.tar.gz查看 bundle 中的包与 manifest
opa inspect -a bundle.tar.gz查看 bundle 中的注解(annotations)
conftest test deployment.yaml配合 conftest 对 YAML/JSON 做策略校验
conftest test --policy ./policies deployment.yaml指定策略目录做 CI 门禁
fmt + check + test 是策略仓库的必备门禁保证风格统一且行为可回归
命令 / 片段说明复制
opa build -b . -o bundle.tar.gz把策略与数据打包成 bundle
opa build -b . --optimize=1 -o bundle.tar.gz优化 bundle,减少求值开销
opa build -b . -e example/allow -o bundle.tar.gz指定入口,生成可执行查询包
opa build -b . --target wasm -e example/allow -o bundle.tar.gz编译为 Wasm,供 Envoy 等场景使用
opa build -b . --signing-key private.pem -o bundle.tar.gz签名 bundle,防止中间人篡改
opa run -s -b bundle.tar.gz以 bundle 启动服务
opa eval -b bundle.tar.gz "data.example.allow"校验 bundle 内策略是否可用
bundle 目录结构对应包路径policies/example.rego 对应 data.example
.manifest 决定 roots 与 revisionroots 限制 bundle 能写哪些 data 路径
manifest 中 roots 配置错会导致策略不生效常见于多团队共用一个 OPA 的场景
命令 / 片段说明复制
opa sign --signing-key private.pem -b . -o bundle.tar.gz对 bundle 签名
opa run -s -b bundle.tar.gz --verification-key public.pem加载时校验签名,失败则拒绝加载
opa eval -b bundle.tar.gz --verification-key public.pem "data.example.allow"求值前校验 bundle 来源
openssl genrsa -out private.pem 2048生成签名私钥
openssl rsa -in private.pem -pubout -out public.pem导出公钥分发给 agent
--authentication=tokenAPI 需 Bearer Token,避免裸奔
--authorization=basic按路径限制读写权限
--tls-cert-file / --tls-private-key-file服务端启用 HTTPS
--tls-ca-cert-file校验客户端证书(mTLS)
策略仓库要开分支保护与评审OPA 策略等同于生产权限配置,改动需审计
私钥不要放在 OPA 节点上签名在 CI 完成,节点只持有公钥
命令 / 片段说明复制
curl -X POST localhost:8181/v1/data/example/allow -d '{"input": {"user": "admin"}}'调用 REST 决策接口
curl localhost:8181/v1/data/example/allow不传 input 的默认求值
curl localhost:8181/v1/policies查看已加载的策略
curl -X PUT localhost:8181/v1/policies/example --data-binary @policy.rego通过 API 下发策略
curl localhost:8181/health健康检查(诊断端口默认 8282)
curl localhost:8181/v1/status查看 bundle 与插件状态
kubectl apply -f gatekeeper.yaml在 K8s 部署 Gatekeeper(OPA 的 K8s 集成)
kubectl get constrainttemplates查看约束模板
kubectl get constraints查看约束实例与违规情况
kubectl get configmap -n opa查看 kube-mgmt 同步的策略与数据
kubectl logs -n gatekeeper-system deploy/gatekeeper-controller-manager查看准入拒绝原因
Envoy ext_authz 指向 OPA 的 9191 gRPC 端口服务网格外部授权标准接法
OPA 无状态,可水平扩展策略与数据通过 bundle 分发,注意拉取间隔
命令 / 片段说明复制
rego_parse_error: unexpected ... token语法错误:多为缺少 if、括号或逗号
var x is unsafe变量在取反或比较前未绑定,调整语句顺序或改用 in
complete rules must not produce multiple outputs同一规则多条路径产出不同值,改集合规则或用 else
rego_type_error: match error类型不匹配,如对字符串做数值运算
undefined ref: data.example.allow包名或规则名写错,用 opa eval "data" 确认路径
allow is undefined没有 default 且条件未命中,加 default allow := false
input 为 undefined未传 input 或字段层级写错,用 object.get 兜底
bundle not found / failed to load bundle路径或远端地址错误,检查配置与网络
signature verification failed签名与公钥不匹配,确认签名密钥与 bundle 版本
eval: context deadline exceeded / canceled求值超时,检查 http.send 与死循环推导
http.send 报网络错误出网受限或 URL 不可达,优先改为数据驱动而非实时调用
策略更新后不生效未开 --watch 或 bundle 轮询未到,查看 /v1/status
Gatekeeper 拒绝但看不到原因看 constraint 的 status 与 controller 日志中的 violation
manifest roots 冲突多个 bundle 写了同一 data 路径,拆分 roots
opa test 不收集用例函数名未以 test_ 开头或带了参数

运维常用组合

本地开发opa run → 写 policy.rego → opa eval -d . -i input.json "data.example.allow" → --explain=full 看原因
策略仓库 CIopa fmt --check → opa check --strict → opa test --coverage --threshold 80 → opa build -b . -o bundle.tar.gz
下发到生产CI 签名 bundle → 上传对象存储 → OPA 配置 bundles 轮询 → /v1/status 校验 → 决策日志观察
K8s 准入控制部署 Gatekeeper → 写 ConstraintTemplate → 创建 Constraint → kubectl get constraints → 观察违规事件
服务鉴权服务把请求上下文 POST /v1/data/authz/allow → OPA 返回 boolean → 服务据此放行或拒绝
排障路径opa eval --explain=full → opa eval "data" 确认加载 → /v1/status 看 bundle → 日志 debug

常见问题排查

1. 默认拒绝

每个决策规则都配 default,未命中时明确返回 false,避免 undefined 引发意外放行

2. 拒绝原因用集合规则

deny contains msg 可累积多条原因,便于调用方展示与审计

3. 求值保持纯函数

尽量用 data 驱动,少用 http.send,OPA 才能稳定缓存与横向扩展

4. v1 语法已成默认

OPA 1.0 起 if/contains/in 为必需关键字,老策略迁移要跑 opa check --v0-compatible

5. 策略也要单测

用 with 覆盖 input 与 data,覆盖率门禁纳入 CI,避免策略回归

6. 签名与最小暴露

bundle 签名 + API 认证 + TLS,三件套缺一不可

共 158 条 OPA 命令 · 示例中的包名 example、路径与密钥文件名请替换为实际环境

关于Open Policy Agent命令速查

在线 Open Policy Agent(OPA)命令速查手册,按安装与常用子命令、服务与配置、评估 eval、Rego 语法基础、Rego 内置函数、输入与数据、测试与覆盖率、格式化与静态检查、打包 bundle、签名校验与安全、集成与部署、常见报错与排查等 12 类场景整理 150+ 条常用命令与片段,每条附中文说明与可直接复制的写法,支持关键词搜索、分类折叠和一键复制,打开网页即可查阅。涵盖 opa version/run/eval/test/fmt/check/build/inspect/deps/capabilities/sign 与 run --server/--addr/--log-level/--diagnostic-addr/--watch/--authentication/--authorization/--tls-cert-file 与配置文件 services/bundles/decision_logs/status 与 polling 与 $ref 与 bundle 下发、eval 的 -d/-i/-I/-f pretty|json|raw|bindings/--fail-defined/--explain=full|fails/-b bundle、Rego 的 package/import/default allow := false/if 关键字/contains/every/some in/数组与对象推导/not 取反与 unsafe var、内置函数 count/concat/split/contains/startswith/endswith/regex.match/glob.match/net.cidr_contains/json.marshal|unmarshal/yaml.unmarshal/time.now_ns|parse_rfc3339_ns/object.get/array.concat/sort/sum/sprintf/walk/http.send、input 与 data 路径与 data.json 加载、opa test 的 -v/-r/--coverage/--threshold/-f json 与 with input/data/内置函数 mock 与 print 调试、opa fmt -w|--check 与 opa check --strict|--v0-compatible 与 opa deps 与 conftest、opa build 的 -b/-o/--optimize/-e/--target wasm/--signing-key 与 manifest roots/revision 与 opa run -s -b、opa sign 与 --verification-key 与 openssl 生成密钥与 TLS/mTLS、REST API /v1/data/{path} 与 /v1/policies 与 /v1/status 与 /health 与 Gatekeeper 的 ConstraintTemplate/Constraint 与 kube-mgmt 与 Envoy ext_authz,以及 rego_parse_error、var is unsafe、complete rules must not produce multiple outputs、rego_type_error、undefined ref、allow is undefined、bundle not found、signature verification failed、context deadline exceeded 等报错排查。适用于 OPA 策略即代码落地、Rego 编写与单元测试、服务鉴权与细粒度授权、Kubernetes 准入控制与合规校验、bundle 集中分发与签名校验、CI 策略门禁与审计日志,以及安全与平台工程面试复习。

核心能力

  • 涵盖 opa version/run/eval/test/fmt/check/build/inspect/deps/capabilities/sign 与 run --server/--addr/--log-level/--diagnostic-addr/--watch/--authentication/--authorization/--tls-cert-file 与配置文件 services/bundles/decision_logs/status 与 polling 与 $ref 与 bundle 下发、eval 的 -d/-i/-I/-f pretty|json|raw|bindings/--fail-defined/--explain=full|fails/-b bundle、Rego 的 package/import/default allow := false/if 关键字/contains/every/some in/数组与对象推导/not 取反与 unsafe var、内置函数 count/concat/split/contains/startswith/endswith/regex.match/glob.match/net.cidr_contains/json.marshal|unmarshal/yaml.unmarshal/time.now_ns|parse_rfc3339_ns/object.get/array.concat/sort/sum/sprintf/walk/http.send、input 与 data 路径与 data.json 加载、opa test 的 -v/-r/--coverage/--threshold/-f json 与 with input/data/内置函数 mock 与 print 调试、opa fmt -w|--check 与 opa check --strict|--v0-compatible 与 opa deps 与 conftest、opa build 的 -b/-o/--optimize/-e/--target wasm/--signing-key 与 manifest roots/revision 与 opa run -s -b、opa sign 与 --verification-key 与 openssl 生成密钥与 TLS/mTLS、REST API /v1/data/{path} 与 /v1/policies 与 /v1/status 与 /health 与 Gatekeeper 的 ConstraintTemplate/Constraint 与 kube-mgmt 与 Envoy ext_authz,以及 rego_parse_error、var is unsafe、complete rules must not produce multiple outputs、rego_type_error、undefined ref、allow is undefined、bundle not found、signature verification failed、context deadline exceeded 等报错排查

适用场景

适用于 OPA 策略即代码落地、Rego 编写与单元测试、服务鉴权与细粒度授权、Kubernetes 准入控制与合规校验、bundle 集中分发与签名校验、CI 策略门禁与审计日志,以及安全与平台工程面试复习。Open Policy Agent命令速查全程在浏览器中完成,无需安装插件,可放心用于日常办公与排障。

常见问题

Open Policy Agent命令速查是免费的吗?需要注册或安装吗?
Open Policy Agent命令速查完全免费,无需注册、无需下载安装任何软件,用浏览器打开网页即可直接使用,也不限制使用次数。
Open Policy Agent命令速查支持哪些功能?
涵盖 opa version/run/eval/test/fmt/check/build/inspect/deps/capabilities/sign 与 run --server/--addr/--log-level/--diagnostic-addr/--watch/--authentication/--authorization/--tls-cert-file 与配置文件 services/bundles/decision_logs/status 与 polling 与 $ref 与 bundle 下发、eval 的 -d/-i/-I/-f pretty|json|raw|bindings/--fail-defined/--explain=full|fails/-b bundle、Rego 的 package/import/default allow := false/if 关键字/contains/every/some in/数组与对象推导/not 取反与 unsafe var、内置函数 count/concat/split/contains/startswith/endswith/regex.match/glob.match/net.cidr_contains/json.marshal|unmarshal/yaml.unmarshal/time.now_ns|parse_rfc3339_ns/object.get/array.concat/sort/sum/sprintf/walk/http.send、input 与 data 路径与 data.json 加载、opa test 的 -v/-r/--coverage/--threshold/-f json 与 with input/data/内置函数 mock 与 print 调试、opa fmt -w|--check 与 opa check --strict|--v0-compatible 与 opa deps 与 conftest、opa build 的 -b/-o/--optimize/-e/--target wasm/--signing-key 与 manifest roots/revision 与 opa run -s -b、opa sign 与 --verification-key 与 openssl 生成密钥与 TLS/mTLS、REST API /v1/data/{path} 与 /v1/policies 与 /v1/status 与 /health 与 Gatekeeper 的 ConstraintTemplate/Constraint 与 kube-mgmt 与 Envoy ext_authz,以及 rego_parse_error、var is unsafe、complete rules must not produce multiple outputs、rego_type_error、undefined ref、allow is undefined、bundle not found、signature verification failed、context deadline exceeded 等报错排查。
Open Policy Agent命令速查适合哪些场景使用?
适用于 OPA 策略即代码落地、Rego 编写与单元测试、服务鉴权与细粒度授权、Kubernetes 准入控制与合规校验、bundle 集中分发与签名校验、CI 策略门禁与审计日志,以及安全与平台工程面试复习。