4. OPA与API网关集成：Sidecar模式、External模式、插件机制

OPA（Open Policy Agent）与API网关的集成方式直接影响策略执行延迟、运维复杂度和故障隔离能力。本章从架构模式与插件机制两个维度，深入分析三种主流集成方案：Sidecar模式、External模式和插件机制（以Kong OPA插件为例），并给出延迟敏感场景下的选型建议。

4.1 集成模式总览

三种模式在部署拓扑、请求路径、策略缓存和故障处理上存在本质差异。下表从关键维度进行对比：

4.2 Sidecar模式：本地策略执行单元

Sidecar模式将OPA实例作为API网关的附属进程部署在同一Pod或同一主机内。网关通过localhost地址调用OPA的REST API或gRPC接口，请求不经过网络跳转，延迟极低。

4.2.1 架构与请求流程

下图展示了Sidecar模式下一次API请求的完整策略执行路径：

4.2.2 关键配置与代码示例

在Kubernetes环境中，Sidecar模式通常通过Pod内的多容器部署实现。以下是一个典型的Sidecar注入配置片段：

# Pod spec 片段：API网关 + OPA Sidecar
apiVersion: v1
kind: Pod
metadata:
  name: kong-gateway-with-opa
spec:
  containers:
  - name: kong
    image: kong:3.5
    env:
    - name: KONG_PROXY_LISTEN
      value: "0.0.0.0:8000"
    - name: KONG_ADMIN_LISTEN
      value: "0.0.0.0:8001"
    ports:
    - containerPort: 8000
    - containerPort: 8001
  - name: opa-sidecar
    image: openpolicyagent/opa:0.63.0
    args:
      - "run"
      - "--server"
      - "--addr=localhost:8181"
      - "--log-level=warn"
      - "/policies/bundle.tar.gz"
    volumeMounts:
    - name: opa-policies
      mountPath: /policies
    livenessProbe:
      httpGet:
        path: /health
        port: 8181
      initialDelaySeconds: 5
      periodSeconds: 10
  volumes:
  - name: opa-policies
    configMap:
      name: opa-policy-bundle

4.3 External模式：集中式策略服务

External模式将OPA部署为独立的服务集群，所有API网关实例通过网络调用同一个OPA服务。这种模式适合大规模微服务架构，策略统一管理，但引入了网络延迟和单点故障风险。

4.3.1 架构与请求流程

下图展示了External模式下多网关共享OPA集群的策略执行路径：

4.3.2 延迟优化策略

External模式下的延迟主要来自网络RTT和OPA服务端处理。以下优化手段可有效降低P99延迟：

• 网关侧缓存： 在网关内存中缓存OPA决策结果，设置合理的TTL（如5-30秒），对相同输入直接返回缓存结果，避免重复网络调用。
• 连接池与Keep-Alive： 使用HTTP/2或gRPC长连接，复用TCP连接，减少三次握手开销。建议连接池大小 ≥ 网关Worker数 × 2。
• OPA集群水平扩展： 根据QPS和策略复杂度，保持OPA节点CPU利用率在60%以下，避免排队延迟。
• 部分评估（Partial Evaluation）： 对于静态策略，使用OPA的部分评估功能预计算决策结果，减少运行时计算量。

# 网关侧缓存配置示例（基于Kong + OPA插件）
# 在Kong的OPA插件配置中启用缓存
{
  "opa_host": "opa-service.namespace.svc.cluster.local",
  "opa_port": 8181,
  "opa_path": "/v1/data/httpapi/authz",
  "cache_ttl": 10,
  "cache_max_size": 5000,
  "connection_timeout": 500,
  "read_timeout": 1000,
  "keepalive_pool_size": 64,
  "keepalive_max_requests": 1000
}

4.4 插件机制：Kong OPA插件深度解析

Kong OPA插件是插件机制的代表实现，它将OPA策略引擎直接嵌入Kong网关的请求处理管道中。插件以Lua代码形式运行在Kong的Worker进程内，策略评估通过内部函数调用完成，延迟最低。

4.4.1 插件工作原理

Kong OPA插件在access阶段拦截请求，构造OPA输入文档，调用OPA REST API（或本地OPA进程），根据决策结果决定放行或拒绝。其核心流程如下：

1. 请求拦截： 插件注册在access阶段，获取请求的method、path、headers、consumer等信息。
2. 输入构造： 将请求信息组装为OPA标准的input JSON对象，可包含自定义上下文（如JWT claims、元数据）。
3. 策略评估： 通过HTTP/gRPC调用OPA服务，或调用本地OPA进程的opa_eval函数，传入input和策略路径。
4. 决策处理： 解析OPA返回的result，若allow == true则继续请求，否则返回403并记录审计日志。

4.4.2 插件配置与代码示例

以下是一个完整的Kong OPA插件配置示例，展示如何将OPA策略集成到Kong路由中：

# 通过Kong Admin API启用OPA插件
curl -X POST http://localhost:8001/routes/{route_id}/plugins \
  -H "Content-Type: application/json" \
  -d '{
    "name": "opa",
    "config": {
      "opa_host": "opa-service.svc.cluster.local",
      "opa_port": 8181,
      "opa_path": "/v1/data/httpapi/authz",
      "include_consumer": true,
      "include_route": true,
      "input_preprocessor": "function(input) input.env = 'production'; return input end",
      "cache_ttl": 5,
      "cache_max_size": 2000,
      "timeout": 1000,
      "keepalive": true
    }
  }'

对应的OPA策略示例（Rego语言）：

# policy/authz.rego
package httpapi.authz

# 默认拒绝
default allow = false

# 允许：管理员或资源所有者
allow {
  input.consumer.role == "admin"
}

allow {
  input.consumer.id == input.route.service.owner_id
  input.method == "GET"
}

# 审计日志：记录所有拒绝请求
deny_reason = msg {
  not allow
  msg = sprintf("user %v not authorized for %v %v", [input.consumer.username, input.method, input.path])
}

4.4.3 延迟基准与优化

在Kong + OPA插件的基准测试中（策略为简单RBAC，输入大小约1KB），不同集成模式的P99延迟对比如下：

4.5 选型决策矩阵

根据实际业务场景，以下决策矩阵可帮助选择最合适的集成模式：