在 Higress 中集成 OPA 策略控制Wasm 插件配置与工作原理详解【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress本篇技术指南以 Higress 官方 OPA 插件plugins/wasm-go/extensions/opa为主线完整讲解如何通过该插件将 Open Policy AgentOPA策略引擎接入 Higress 网关实现基于 Rego 策略的请求级访问控制。读完本文你将掌握插件的全部配置字段、五种服务发现模式k8s/nacos/ip/route/dns的用法、插件与 OPA 服务之间的请求/响应协议input 结构、/v1/data/{policy}/allow决策接口、状态码映射以及如何在本地用 Docker Envoy 完成端到端验证。插件功能概述OPA 是一个开源的通用策略引擎使用 Rego 语言编写策略Policy将策略决策与业务逻辑解耦。Higress 的 OPA 插件将网关收到的 HTTP 请求构造成 OPA 标准的input数据结构发送给独立的 OPA 服务进行决策再根据决策结果放行或拒绝请求。插件注册于 main.go通过wrapper.SetCtx挂载了配置解析parseConfig、请求头处理onHttpRequestHeaders和请求体处理onHttpRequestBody三个回调表明该插件同时支持基于请求头和基于请求体的策略判定。插件当前版本为 2.0.2见 VERSION。运行属性属性值插件执行阶段认证阶段Authentication Phase插件执行优先级225执行阶段为认证阶段意味着 OPA 策略判定发生在网关认证/鉴权流程中早于路由转发与业务处理执行优先级 225 用于在同一阶段内对多个插件排序数值越小越先执行。将 OPA 判定放在认证阶段可以确保未通过策略校验的请求在进入上游业务服务之前即被拦截从源码实现看拒绝路径直接调用proxywasm.SendHttpResponseWithDetail返回响应不会继续转发见 main.go。配置字段详解插件的全部配置项如下表与官方文档一致并补充了源码级约束说明字段数据类型是否必填默认值描述policystring必填-OPA 策略Rego 包名/策略名用于拼接决策接口路径timeoutstring必填-访问 OPA 服务的超时时间如5s、3s支持 Go duration 格式serviceSourcestring必填-服务来源k8s、nacos、ip、route源码还支持dnshoststring非必填-服务主机serviceSource为ip时必填route模式同样使用该字段serviceNamestring非必填-服务名称serviceSource为k8s、nacos、ip时必填servicePortstring非必填-服务端口serviceSource为k8s、nacos、ip时必填namespacestring非必填-命名空间serviceSource为k8s、nacos时必填字段约束的源码依据policy 与 timeout 必填校验parseConfig中policy为空返回policy not allow emptytimeout为空返回timeout not allow empty两者缺失都会导致插件启动失败见 main.go。timeout 格式使用 Go 标准库time.ParseDuration解析如500ms、5s、10s随后转换为毫秒并存储为uint32格式非法会返回timeout parse fail见 main.go。host/serviceName/servicePort 校验若host为空且serviceName或servicePort为空返回invalid service config见 config.go。namespace 校验当serviceSource为k8s或nacos时namespace不允许为空否则返回namespace not allow empty见 config.go。serviceSource 合法性不支持的来源返回unknown service source: xxx见 config.go。服务发现模式与配置示例Client()函数config.go根据serviceSource构造不同的上游集群客户端。官方文档声明支持k8s、nacos、ip、route四种从源码结构看还额外支持dns模式通过domain字段指定域名以下逐一给出配置示例。1. k8s 模式服务发现于 KubernetesserviceSource: k8s serviceName: opa servicePort: 8181 namespace: higress-backend policy: example1 timeout: 5sk8s 模式使用K8sCluster按serviceName namespace port在集群内发现 OPA 服务见 config.go。这也是 main_test.go 中basicConfig采用的模式。2. nacos 模式服务发现于 NacosserviceSource: nacos serviceName: opa-service servicePort: 8181 namespace: public policy: example3 timeout: 10snacos 模式使用NacosCluster此时namespace字段实际对应Nacos 的 namespace ID见 config.go。该配置示例取自单元测试nacosConfig见 main_test.go。3. ip 模式静态 IP 直连serviceSource: ip host: 192.168.1.100 servicePort: 8181 policy: example2 timeout: 3sip 模式使用StaticIpClusterhost必填见 config.go适用于 OPA 服务部署在固定 IP 的场景例如独立虚机或外部主机。示例取自ipConfig测试见 main_test.go。4. route 模式跟随网关路由/虚拟主机serviceSource: route host: example.com policy: example4 timeout: 2sroute 模式使用RouteCluster只需提供host适用于 OPA 服务通过网关自身路由virtual host可达的场景见 config.go。envoy.yaml 的本地演示配置即采用此模式。5. dns 模式域名解析源码支持serviceSource: dns serviceName: opa servicePort: 8181 domain: opa.example.com policy: example1 timeout: 5sdns 模式使用DnsCluster通过domain字段指定域名、serviceNameservicePort指定集群名与端口见 config.go。官方文档表格未列出该模式此处依据源码补充说明。插件工作原理请求构造、决策接口与响应处理发送给 OPA 的 input 数据结构opaCall函数main.go在每次请求时构造如下input{ input: { request: { method: GET, scheme: http, path: /test?x1, headers: { :authority: example.com, :path: /test, :method: GET, content-type: application/json }, query: { x: [1] }, body: ... } } }要点method、scheme、path取自请求上下文headers为完整请求头从proxywasm.GetHttpRequestHeaders()获取query通过对path中的 query string 执行url.ParseQuery得到键对应值数组仅当存在请求体时才附加body字段即策略既可以只看请求头也可以校验请求体内容。请求体回调onHttpRequestBody的存在意味着对于 POST/PUT 等携带 body 的请求插件会进入 body 处理流程并将 body 纳入策略输入见 main.go。决策接口路径插件向 OPA 服务发起POST /v1/data/{policy}/allow请求{policy}即配置中的policy字段如example1并携带Content-Type: application/json见 main.go。因此策略中的allow规则就是决策入口。响应处理与状态码映射回调rspCallmain.go按如下规则处理 OPA 响应全部行为均有单元测试验证见 main_test.goOPA 响应情况网关行为响应状态码状态码详情StatusCodeDetailHTTP 200 且result: true放行ResumeHttpRequest恢复请求继续转发-HTTP 200 且result: false拒绝访问401 Unauthorizedopa.server_not_allowed非 200 状态码原样透出该状态码与 OPA 返回一致opa.status_ne_200响应体 JSON 解析失败网关内部错误500opa.bad_response_body缺少result字段或类型非布尔网关内部错误500opa.conversion_fail拒绝与错误路径均通过proxywasm.SendHttpResponseWithDetail直接向客户端返回响应不再调用上游。测试用例opa service denies accessmain_test.go验证了result: false时返回 401 及opa.server_not_allowedopa service returns non-200 statusmain_test.go验证了 500 透传opa service returns invalid response与opa service returns response without result field分别验证了解析失败与类型转换失败分支。OPA 服务安装参考启动 OPA 服务使用官方镜像以 server 模式启动 OPA暴露默认端口 8181docker run -d --name opa -p 8181:8181 openpolicyagent/opa:0.35.0 run -s创建 OPA 策略以下 Rego 策略要求请求的 HTTP 方法必须为GET否则allow为false默认拒绝curl -X PUT 127.0.0.1:8181/v1/policies/example1 \ -H Content-Type: text/plain \ -d package example1 import input.request default allow false allow { # HTTP method must GET request.method GET }注意策略中的import input.request与插件构造的input.request结构一一对应这是两者契约的关键插件发什么结构策略就 import 什么结构。查询策略验证决策结果curl -X POST 127.0.0.1:8181/v1/data/example1/allow \ -H Content-Type: application/json \ -d {input:{request:{method:GET}}}返回{result: true}表示允许将method改为POST再查询将返回{result: false}与插件在网关侧的行为一一对应。本地端到端验证Docker Envoy仓库为插件提供了免 Kubernetes 的本地验证环境包含 docker-compose.yaml 与 envoy.yamldocker-compose.yaml使用 Higress gateway 镜像higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/gateway:1.3.1以 Envoy 方式启动挂载本地envoy.yaml与编译产物plugin.wasm监听 10000 端口并开启 wasm 调试日志--component-log-level wasm:debugenvoy.yaml在http_filters中加载 wasm 插件其内嵌配置即 route 模式的插件配置serviceSource: route、host: OPA_SERVER:OPA_PORT、policy: example1、timeout: 5s并将默认路由指向opa-server集群STRICT_DNS 解析OPA_SERVER/OPA_PORT。按以下步骤即可本地验证编译插件得到plugin.wasm遵循 wasm-go 插件的构建方式将envoy.yaml中的OPA_SERVER与OPA_PORT替换为实际 OPA 服务地址执行docker compose up启动 Envoy用curl -X GET与curl -X POST分别访问localhost:10000验证 GET 放行、POST 被拒401。配置校验与单元测试插件配置的健壮性由 main_test.go 中的TestParseConfig覆盖合法配置k8s/ip/nacos/route 四种模式均能通过插件启动OnPluginStartStatusOK缺少policy、缺少timeout、timeout格式非法如invalid-timeout均导致插件启动失败OnPluginStartStatusFailed见 main_test.go。TestOnHttpRequestBodymain_test.go则验证了携带请求体的场景先处理请求头进入暂停态ActionPause读取 body 后再次发起 OPA 决策result: true时恢复请求继续转发。小结Higress OPA 插件将外部策略引擎的决策能力无缝接入网关认证阶段只需配置policy、timeout与serviceSource三种基础字段即可让每个请求在进入上游前经过 OPA 的 Rego 策略校验。理解插件构造的input.request结构与策略中import input.request的对应关系以及/v1/data/{policy}/allow决策接口的响应契约result布尔值、状态码映射是正确使用该插件的关键。如需深入源码建议从 config.go服务发现与客户端构造、main.go请求构造与决策处理以及 main_test.go行为契约测试入手。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 在 Higress 中集成 OPA 策略控制：Wasm 插件配置与工作原理详解
在 Higress 中集成 OPA 策略控制Wasm 插件配置与工作原理详解【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress本篇技术指南以 Higress 官方 OPA 插件plugins/wasm-go/extensions/opa为主线完整讲解如何通过该插件将 Open Policy AgentOPA策略引擎接入 Higress 网关实现基于 Rego 策略的请求级访问控制。读完本文你将掌握插件的全部配置字段、五种服务发现模式k8s/nacos/ip/route/dns的用法、插件与 OPA 服务之间的请求/响应协议input 结构、/v1/data/{policy}/allow决策接口、状态码映射以及如何在本地用 Docker Envoy 完成端到端验证。插件功能概述OPA 是一个开源的通用策略引擎使用 Rego 语言编写策略Policy将策略决策与业务逻辑解耦。Higress 的 OPA 插件将网关收到的 HTTP 请求构造成 OPA 标准的input数据结构发送给独立的 OPA 服务进行决策再根据决策结果放行或拒绝请求。插件注册于 main.go通过wrapper.SetCtx挂载了配置解析parseConfig、请求头处理onHttpRequestHeaders和请求体处理onHttpRequestBody三个回调表明该插件同时支持基于请求头和基于请求体的策略判定。插件当前版本为 2.0.2见 VERSION。运行属性属性值插件执行阶段认证阶段Authentication Phase插件执行优先级225执行阶段为认证阶段意味着 OPA 策略判定发生在网关认证/鉴权流程中早于路由转发与业务处理执行优先级 225 用于在同一阶段内对多个插件排序数值越小越先执行。将 OPA 判定放在认证阶段可以确保未通过策略校验的请求在进入上游业务服务之前即被拦截从源码实现看拒绝路径直接调用proxywasm.SendHttpResponseWithDetail返回响应不会继续转发见 main.go。配置字段详解插件的全部配置项如下表与官方文档一致并补充了源码级约束说明字段数据类型是否必填默认值描述policystring必填-OPA 策略Rego 包名/策略名用于拼接决策接口路径timeoutstring必填-访问 OPA 服务的超时时间如5s、3s支持 Go duration 格式serviceSourcestring必填-服务来源k8s、nacos、ip、route源码还支持dnshoststring非必填-服务主机serviceSource为ip时必填route模式同样使用该字段serviceNamestring非必填-服务名称serviceSource为k8s、nacos、ip时必填servicePortstring非必填-服务端口serviceSource为k8s、nacos、ip时必填namespacestring非必填-命名空间serviceSource为k8s、nacos时必填字段约束的源码依据policy 与 timeout 必填校验parseConfig中policy为空返回policy not allow emptytimeout为空返回timeout not allow empty两者缺失都会导致插件启动失败见 main.go。timeout 格式使用 Go 标准库time.ParseDuration解析如500ms、5s、10s随后转换为毫秒并存储为uint32格式非法会返回timeout parse fail见 main.go。host/serviceName/servicePort 校验若host为空且serviceName或servicePort为空返回invalid service config见 config.go。namespace 校验当serviceSource为k8s或nacos时namespace不允许为空否则返回namespace not allow empty见 config.go。serviceSource 合法性不支持的来源返回unknown service source: xxx见 config.go。服务发现模式与配置示例Client()函数config.go根据serviceSource构造不同的上游集群客户端。官方文档声明支持k8s、nacos、ip、route四种从源码结构看还额外支持dns模式通过domain字段指定域名以下逐一给出配置示例。1. k8s 模式服务发现于 KubernetesserviceSource: k8s serviceName: opa servicePort: 8181 namespace: higress-backend policy: example1 timeout: 5sk8s 模式使用K8sCluster按serviceName namespace port在集群内发现 OPA 服务见 config.go。这也是 main_test.go 中basicConfig采用的模式。2. nacos 模式服务发现于 NacosserviceSource: nacos serviceName: opa-service servicePort: 8181 namespace: public policy: example3 timeout: 10snacos 模式使用NacosCluster此时namespace字段实际对应Nacos 的 namespace ID见 config.go。该配置示例取自单元测试nacosConfig见 main_test.go。3. ip 模式静态 IP 直连serviceSource: ip host: 192.168.1.100 servicePort: 8181 policy: example2 timeout: 3sip 模式使用StaticIpClusterhost必填见 config.go适用于 OPA 服务部署在固定 IP 的场景例如独立虚机或外部主机。示例取自ipConfig测试见 main_test.go。4. route 模式跟随网关路由/虚拟主机serviceSource: route host: example.com policy: example4 timeout: 2sroute 模式使用RouteCluster只需提供host适用于 OPA 服务通过网关自身路由virtual host可达的场景见 config.go。envoy.yaml 的本地演示配置即采用此模式。5. dns 模式域名解析源码支持serviceSource: dns serviceName: opa servicePort: 8181 domain: opa.example.com policy: example1 timeout: 5sdns 模式使用DnsCluster通过domain字段指定域名、serviceNameservicePort指定集群名与端口见 config.go。官方文档表格未列出该模式此处依据源码补充说明。插件工作原理请求构造、决策接口与响应处理发送给 OPA 的 input 数据结构opaCall函数main.go在每次请求时构造如下input{ input: { request: { method: GET, scheme: http, path: /test?x1, headers: { :authority: example.com, :path: /test, :method: GET, content-type: application/json }, query: { x: [1] }, body: ... } } }要点method、scheme、path取自请求上下文headers为完整请求头从proxywasm.GetHttpRequestHeaders()获取query通过对path中的 query string 执行url.ParseQuery得到键对应值数组仅当存在请求体时才附加body字段即策略既可以只看请求头也可以校验请求体内容。请求体回调onHttpRequestBody的存在意味着对于 POST/PUT 等携带 body 的请求插件会进入 body 处理流程并将 body 纳入策略输入见 main.go。决策接口路径插件向 OPA 服务发起POST /v1/data/{policy}/allow请求{policy}即配置中的policy字段如example1并携带Content-Type: application/json见 main.go。因此策略中的allow规则就是决策入口。响应处理与状态码映射回调rspCallmain.go按如下规则处理 OPA 响应全部行为均有单元测试验证见 main_test.goOPA 响应情况网关行为响应状态码状态码详情StatusCodeDetailHTTP 200 且result: true放行ResumeHttpRequest恢复请求继续转发-HTTP 200 且result: false拒绝访问401 Unauthorizedopa.server_not_allowed非 200 状态码原样透出该状态码与 OPA 返回一致opa.status_ne_200响应体 JSON 解析失败网关内部错误500opa.bad_response_body缺少result字段或类型非布尔网关内部错误500opa.conversion_fail拒绝与错误路径均通过proxywasm.SendHttpResponseWithDetail直接向客户端返回响应不再调用上游。测试用例opa service denies accessmain_test.go验证了result: false时返回 401 及opa.server_not_allowedopa service returns non-200 statusmain_test.go验证了 500 透传opa service returns invalid response与opa service returns response without result field分别验证了解析失败与类型转换失败分支。OPA 服务安装参考启动 OPA 服务使用官方镜像以 server 模式启动 OPA暴露默认端口 8181docker run -d --name opa -p 8181:8181 openpolicyagent/opa:0.35.0 run -s创建 OPA 策略以下 Rego 策略要求请求的 HTTP 方法必须为GET否则allow为false默认拒绝curl -X PUT 127.0.0.1:8181/v1/policies/example1 \ -H Content-Type: text/plain \ -d package example1 import input.request default allow false allow { # HTTP method must GET request.method GET }注意策略中的import input.request与插件构造的input.request结构一一对应这是两者契约的关键插件发什么结构策略就 import 什么结构。查询策略验证决策结果curl -X POST 127.0.0.1:8181/v1/data/example1/allow \ -H Content-Type: application/json \ -d {input:{request:{method:GET}}}返回{result: true}表示允许将method改为POST再查询将返回{result: false}与插件在网关侧的行为一一对应。本地端到端验证Docker Envoy仓库为插件提供了免 Kubernetes 的本地验证环境包含 docker-compose.yaml 与 envoy.yamldocker-compose.yaml使用 Higress gateway 镜像higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/gateway:1.3.1以 Envoy 方式启动挂载本地envoy.yaml与编译产物plugin.wasm监听 10000 端口并开启 wasm 调试日志--component-log-level wasm:debugenvoy.yaml在http_filters中加载 wasm 插件其内嵌配置即 route 模式的插件配置serviceSource: route、host: OPA_SERVER:OPA_PORT、policy: example1、timeout: 5s并将默认路由指向opa-server集群STRICT_DNS 解析OPA_SERVER/OPA_PORT。按以下步骤即可本地验证编译插件得到plugin.wasm遵循 wasm-go 插件的构建方式将envoy.yaml中的OPA_SERVER与OPA_PORT替换为实际 OPA 服务地址执行docker compose up启动 Envoy用curl -X GET与curl -X POST分别访问localhost:10000验证 GET 放行、POST 被拒401。配置校验与单元测试插件配置的健壮性由 main_test.go 中的TestParseConfig覆盖合法配置k8s/ip/nacos/route 四种模式均能通过插件启动OnPluginStartStatusOK缺少policy、缺少timeout、timeout格式非法如invalid-timeout均导致插件启动失败OnPluginStartStatusFailed见 main_test.go。TestOnHttpRequestBodymain_test.go则验证了携带请求体的场景先处理请求头进入暂停态ActionPause读取 body 后再次发起 OPA 决策result: true时恢复请求继续转发。小结Higress OPA 插件将外部策略引擎的决策能力无缝接入网关认证阶段只需配置policy、timeout与serviceSource三种基础字段即可让每个请求在进入上游前经过 OPA 的 Rego 策略校验。理解插件构造的input.request结构与策略中import input.request的对应关系以及/v1/data/{policy}/allow决策接口的响应契约result布尔值、状态码映射是正确使用该插件的关键。如需深入源码建议从 config.go服务发现与客户端构造、main.go请求构造与决策处理以及 main_test.go行为契约测试入手。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考