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 opa | macOS 安装 | |
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=basic | API 访问控制,生产必须开启 | |
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: 10 | bundle 拉取配置,实现策略集中分发 | |
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.method | input 是每次请求传入的上下文,不落盘 | |
data.inventory.servers | data 是加载进来的策略与静态数据 | |
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 与 revision | roots 限制 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=token | API 需 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 看原因opa fmt --check → opa check --strict → opa test --coverage --threshold 80 → opa build -b . -o bundle.tar.gzCI 签名 bundle → 上传对象存储 → OPA 配置 bundles 轮询 → /v1/status 校验 → 决策日志观察部署 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,三件套缺一不可
相关工具
Linux命令速查
文件、文本、权限、进程、网络、磁盘、systemd与防火墙等 Linux 常用命令速查手册
Docker命令速查
镜像、容器、网络、数据卷、Compose、Swarm、清理与排障等 Docker 常用命令速查手册
Nginx命令速查
服务管理、配置指令、反向代理、HTTPS、限流缓存、日志排查等 Nginx 常用命令速查手册
K8S命令速查
集群上下文、Pod调试、工作负载、Service与Ingress、存储、权限、排障等 kubectl 常用命令速查手册
Windows CMD命令速查
文件目录、网络诊断、进程服务、系统信息、用户权限、注册表、批处理等 Windows CMD 常用命令速查手册
systemctl服务管理速查
服务启停、开机自启、unit文件编写、日志查看、定时器、依赖分析与排障等 systemctl 命令速查手册
关于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 策略门禁与审计日志,以及安全与平台工程面试复习。