2. OPA 规则基础：Rego 语言入门、规则与查询、数据与输入文档

在深入排查 OPA 准入控制延迟之前，必须牢固掌握 Rego 语言的核心概念。本章将系统讲解 Rego 的基本语法、规则与查询的结构，以及 data 和 input 两个关键文档的作用。这些基础是理解后续规则复杂度分析和性能优化的前提。

2.1 Rego 语言入门

Rego 是一种专为策略定义和策略决策而设计的声明式查询语言。它并非通用编程语言，而是专注于“策略即代码”（Policy as Code）场景。Rego 的核心思想是：策略是数据查询。你定义一组规则（Rule），然后通过查询（Query）来获取策略决策结果。

2.1.1 基本语法元素

2.1.2 表达式与逻辑

Rego 中的表达式是逻辑条件，多个表达式之间用 ; 或换行分隔，表示逻辑“与”（AND）。同一规则内不同子句之间是“或”（OR）关系。

# 逻辑与：所有条件必须同时满足
allow {
    input.user == "admin"
    input.action == "delete"
}

# 逻辑或：使用不同规则体实现
allow {
    input.user == "admin"
}
allow {
    input.user == "superuser"
}

2.2 规则（Rule）与查询（Query）的基本结构

2.2.1 规则结构

规则是 Rego 策略的基本单元。每条规则由一个头部和一个或多个体组成。

# 规则头部：规则名(参数) [= 值]
# 规则体：条件表达式序列

# 布尔规则（默认返回 true/false）
allowed_namespace {
    input.namespace == "production"
}

# 完整规则（返回具体值）
allowed_ports[port] {
    port := input.ports[_]
    port > 1024
    port < 65535
}

# 带默认值的规则
default allow = false
allow {
    input.user == "admin"
}

2.2.2 查询结构

查询是向 OPA 引擎发起的策略评估请求。在 Kubernetes 准入控制场景中，查询通常由 API Server 自动构造。

# 简单查询：检查某个规则是否为真
data.kubernetes.admission.allow

# 带变量的查询：获取具体值
x := data.kubernetes.admission.allowed_namespaces[x]

# 复杂查询：组合多个规则
allow := data.kubernetes.admission.allow
violations := data.kubernetes.admission.violations

2.3 数据文档（data）与输入文档（input）的概念

OPA 的评估模型基于两个核心文档：data 和 input。理解它们的区别和用途是编写高效策略的基础。

2.3.1 数据文档（data）

data 是 OPA 的全局持久化数据，包含所有加载的策略规则和外部数据。它由以下部分组成：

• 策略规则： 所有通过 package 声明的规则自动挂载到 data 下。例如 package kubernetes.admission 中的规则可通过 data.kubernetes.admission 访问。
• 外部数据： 通过 Bundle、API 推送或文件加载的 JSON/YAML 数据，如 RBAC 配置、命名空间白名单、资源配额等。
• 内置数据： OPA 内置的元数据，如 data.opametadata。

# 假设加载了以下外部数据（JSON）
{
  "allowed_registries": ["docker.io", "gcr.io"],
  "admin_users": ["alice", "bob"]
}

# 在 Rego 中访问
allowed_registry {
    input.image.startswith(data.allowed_registries[_])
}

is_admin {
    input.user == data.admin_users[_]
}

2.3.2 输入文档（input）

input 是每次策略评估时传入的临时请求数据。在 Kubernetes 准入控制中，input 包含 AdmissionReview 请求的全部内容。

# 典型的 Kubernetes 准入控制 input 结构（简化）
{
  "kind": "AdmissionReview",
  "request": {
    "uid": "12345",
    "operation": "CREATE",
    "object": {
      "kind": "Pod",
      "metadata": {
        "name": "nginx-pod",
        "namespace": "default"
      },
      "spec": {
        "containers": [
          {"name": "nginx", "image": "nginx:latest"}
        ]
      }
    },
    "userInfo": {
      "username": "kubernetes-admin",
      "groups": ["system:masters"]
    }
  }
}

# 在 Rego 中访问 input
deny[msg] {
    input.request.operation == "CREATE"
    input.request.object.kind == "Pod"
    not startswith(input.request.object.spec.containers[_].image, "allowed-registry.com/")
    msg := sprintf("容器镜像 %v 不在允许的仓库中", [input.request.object.spec.containers[_].image])
}

2.3.3 data 与 input 的对比

2.4 规则评估流程与文档关系

下面的 SVG 图展示了 OPA 在 Kubernetes 准入控制场景中的规则评估流程，以及 data 和 input 如何协同工作。

2.5 实战示例：一个完整的准入控制规则

下面是一个完整的 Rego 规则示例，展示了 data 和 input 的协同使用。该规则用于检查 Pod 是否使用了允许的镜像仓库。

package kubernetes.admission

# 默认拒绝
default deny = false

# 从 data 中读取允许的镜像仓库列表
allowed_registries := data.config.allowed_registries

# 拒绝规则：如果镜像不在允许列表中，则拒绝
deny[msg] {
    input.request.operation == "CREATE"
    input.request.object.kind == "Pod"
    container := input.request.object.spec.containers[_]
    not startswith(container.image, allowed_registries[_])
    msg := sprintf("容器 %v 的镜像 %v 不在允许的仓库列表中", [container.name, container.image])
}

# 审计规则：记录所有创建 Pod 的操作
audit_log[entry] {
    input.request.operation == "CREATE"
    input.request.object.kind == "Pod"
    entry := {
        "pod_name": input.request.object.metadata.name,
        "namespace": input.request.object.metadata.namespace,
        "user": input.request.userInfo.username,
        "time": time.now_ns()
    }
}

2.6 常见误区与最佳实践