3. OPA 本地环境搭建：安装 OPA CLI、运行 OPA 服务器、使用 curl 测试策略

在将 OPA 集成到 Helm 发布流水线之前，首先需要在本地搭建一个可用的 OPA 环境。本章将指导你完成 OPA CLI 的安装、OPA 服务器的启动，并通过 curl 验证策略是否生效。这是后续所有多集群合规校验的基础设施。

3.1 安装 OPA CLI

OPA 提供了跨平台的二进制分发，支持 Linux、macOS 和 Windows。推荐使用最新稳定版本（当前为 v0.60.0+）。

curl -sL -o opa https://openpolicyagent.org/downloads/v0.60.0/opa_linux_amd64
chmod +x opa
sudo mv opa /usr/local/bin/

opa version

curl -sL -o opa https://openpolicyagent.org/downloads/v0.60.0/opa_darwin_amd64
chmod +x opa
sudo mv opa /usr/local/bin/

opa version

Invoke-WebRequest -Uri https://openpolicyagent.org/downloads/v0.60.0/opa_windows_amd64.exe -OutFile opa.exe
# 将 opa.exe 添加到 PATH

opa version

3.2 运行 OPA 服务器

OPA 可以以独立服务器模式运行，通过 REST API 对外提供策略评估服务。这是与 Helm 发布流水线集成的标准方式。

启动 OPA 服务器需要指定监听地址和端口，同时加载策略文件（.rego）。以下命令启动一个开发模式下的 OPA 服务器：

# 启动 OPA 服务器，监听 8181 端口，加载当前目录下的所有 .rego 文件
opa run --server --addr=0.0.0.0:8181 ./policies/

启动成功后，终端会输出类似以下信息：

{"level":"info","msg":"Initializing server.","time":"2025-01-15T10:00:00Z"}
{"level":"info","msg":"Server started.","time":"2025-01-15T10:00:00Z","addr":":8181"}

OPA 服务器默认提供以下核心 API 端点：

3.3 使用 curl 测试策略

OPA 服务器启动后，我们可以通过 curl 命令上传策略、提交输入数据并获取评估结果。以下是一个完整的测试流程。

3.3.1 准备示例策略

创建一个简单的 Rego 策略文件 check_namespace.rego，用于校验 Kubernetes 命名空间是否包含必需的标签：

package kubernetes.admission

# 默认拒绝
default allow := false

# 允许：命名空间必须包含 "env" 标签，且值在允许列表中
allow {
    input.kind == "Namespace"
    input.metadata.labels.env
    input.metadata.labels.env in ["prod", "staging", "dev"]
}

# 允许：非 Namespace 资源默认放行（仅用于演示）
allow {
    input.kind != "Namespace"
}

3.3.2 上传策略到 OPA

# 将策略文件上传到 OPA
curl -X PUT --data-binary @check_namespace.rego \
  http://localhost:8181/v1/policies/check_namespace

成功响应：

{"result":{"id":"check_namespace"}}

3.3.3 执行策略查询

构造一个合规的 Namespace 输入：

# 测试合规的 Namespace（env=prod）
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "kind": "Namespace",
      "metadata": {
        "name": "production",
        "labels": {
          "env": "prod"
        }
      }
    }
  }' \
  http://localhost:8181/v1/data/kubernetes/admission/allow

预期响应（允许）：

{"result":true}

构造一个不合规的 Namespace 输入（缺少 env 标签）：

# 测试不合规的 Namespace（缺少 env 标签）
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "kind": "Namespace",
      "metadata": {
        "name": "default",
        "labels": {}
      }
    }
  }' \
  http://localhost:8181/v1/data/kubernetes/admission/allow

预期响应（拒绝）：

{"result":false}

3.4 本地环境架构图

下图展示了 OPA 本地开发环境的组件关系与数据流：

3.5 常见问题与排查

• 端口冲突：如果 8181 端口被占用，使用 --addr=0.0.0.0:8182 指定其他端口。
• 策略未加载：检查 OPA 启动时指定的策略目录路径是否正确，或通过 curl http://localhost:8181/v1/policies 列出已加载的策略。
• JSON 格式错误：curl 的 -d 参数必须使用双引号包裹键名，且不能有多余的逗号。
• 跨域问题：如果从浏览器调用 OPA API，需要添加 --cors 标志启动 OPA。

3.6 环境验证清单

完成上述步骤后，使用以下清单确认环境就绪：