中间表示（IR）

Nantian Gateway 的控制面监听 Kubernetes 资源并将其转换为数据面可直接消费的形式。这个形式就是中间表示，简称 IR。

IR 是整个网关配置的一个规范化、带版本号的快照：每个监听器、每条路由规则、每个后端、每个端点、每个 Wasm 插件和每个 AI 服务定义，全部展开为数据面可以直接理解的格式。每当 Kubernetes 资源发生变化时，控制面构建一个新的 IR 快照，然后通过 gRPC 推送到所有已连接的数据面。

为什么需要 IR？

Kubernetes Gateway API 的资源表达能力很强，结构也很层次化。一个 HTTPRoute 可以匹配路径、过滤请求头、重写 URL，并按独立权重将流量分发到五个后端。数据面不需要所有这些结构：它需要一个扁平的、已解析的配置，能够高效地加载到运行时的路由表中。

IR 充当解耦层：

翻译器（在控制面中）将 Gateway API 资源转换为 IR 格式，解析引用、折叠继承关系、应用默认值。
数据面接收 IR 并直接加载到其路由引擎中，完全不需要感知 Kubernetes。

这种拆分意味着控制面可以独立演进其翻译逻辑（新的 Gateway API 特性、新的 CRD、策略变更），而不影响数据面。数据面也因此保持小巧和专注。

IR 是如何构建的

┌──────────────────────────────────────────────────────────┐
│                    Kubernetes API                        │
│                                                          │
│  Gateways  Routes  Services  EndpointSlices  AIServices  │
└──────────────────────┬───────────────────────────────────┘
                       │  Watch & reconcile（监听与调和）
                       ▼
┌──────────────────────────────────────────────────────────┐
│                 翻译器（Translator）                     │
│                                                          │
│  Resolve references（解析引用）・Collapse hierarchies（折叠层级）│
│  Apply defaults（应用默认值）・Normalize configurations（规范化配置）│
│  Validate rules（校验规则）・Reject invalid combinations（拒绝无效组合）│
└──────────────────────┬───────────────────────────────────┘
                       │  IR Snapshot（IR 快照）
                       ▼
┌──────────────────────────────────────────────────────────┐
│                IR（带版本号）                             │
│                                                          │
│  listeners  routes  backends  endpoints  AI services     │
└──────────────────────┬───────────────────────────────────┘
                       │  xDS（gRPC 双向流）
                       ▼
┌──────────────────────────────────────────────────────────┐
│                 数据面（Data Planes）                    │
│                                                          │
│  Receive snapshot（接收快照）· Apply to runtime（应用到运行时）│
│  Ack to control（向控制面确认）                            │
└──────────────────────────────────────────────────────────┘

翻译器在每次监听的 Kubernetes 资源发生变化时运行。它收集所有相关资源，解析交叉引用，应用策略，并生成一个 IR 快照。如果校验通过，快照会获得一个版本号，并通过 xDS 发布到数据面。

快照是原子的：要么完整且有效，要么翻译器拒绝它，数据面继续使用上一个有效版本运行。

IR 快照中包含什么

一个 IR 快照包含以下规范化资源类型：

组件	内容
Listeners（监听器）	网关监听器定义，包括协议、端口、TLS 配置和附加的过滤器链。
Routes（路由）	展开后的路由规则，包含匹配条件（路径、请求头、查询参数）、动作和后端引用。
Backends（后端）	解析后的后端服务，包含负载均衡策略、超时、重试配置和熔断器设置。
Endpoints（端点）	每个后端的具体 IP 地址和端口，从 EndpointSlice 资源中获取。
AI Services（AI 服务）	AI 提供方连接信息：模型名称、认证令牌、端点 URL 和限流策略。
Wasm Plugins（Wasm 插件）	插件引用和附加到监听器或路由的配置负载。

IR 快照带有版本号，且不可变。每个新快照递增版本计数器，数据面知道它们正在运行哪个版本。如果它们从控制面请求的版本已过期或未知，控制面会发送最新版本。

通过 Admin API 查看 IR

控制面的 Admin API 暴露了一个快照端点，用于查看当前的 IR：

GET /v1/snapshot

返回内容包括：

当前快照版本号
IR 中各资源类型的数量
快照构建的时间戳
完整 IR 的压缩表示（用于调试）

示例：

kubectl port-forward -n nantian-gw svc/nantian-gw-controlplane-admin 18081:18081
curl -s http://localhost:18081/v1/snapshot | jq .

{
  "version": 42,
  "builtAt": "2026-06-19T10:15:30Z",
  "resourceCounts": {
    "listeners": 3,
    "routes": 12,
    "backends": 8,
    "endpoints": 24,
    "aiServices": 2,
    "wasmPlugins": 1
  }
}

使用这个端点来验证你的 Kubernetes 配置是否生成了预期的 IR，以及控制面当前认为哪个版本是有效的。

与 xDS 的关系

IR 是通过 gRPC xDS 通道传输的内容。每个数据面打开一条到控制面的双向流，请求最新的快照，控制面以类型化 protobuf 消息的形式发送 IR。然后数据面对新的 IR 与其当前运行时状态做 diff，只应用变更部分：添加新的监听器、更新路由表、或摘除已移除的后端。

这就是 IR 存在的原因：给数据面一个可以高效 diff 和应用的东西，而不需要它理解 Kubernetes 本身。