Gateway API v1.6 补齐四层路由：TCPRoute、UDPRoute 正式进入 v1

2026-08-04 44 预计阅读时间: 1 分钟
来源: kubernetes.io AI 摘要 Original link

Disclaimer: This article is an AI-assisted summary. Read it together with the original source when precision matters. The summary may omit context, version differences, or edge cases and is not official documentation.

预计阅读时间：8 分钟

Gateway API v1.6.0 把 Kubernetes 服务网络向前推进了一层：TCPRoute 和 UDPRoute 从实验通道毕业，进入 gateway.networking.k8s.io/v1 标准 API。数据库、DNS、VoIP、游戏服务器和 IoT 遥测等原始 TCP/UDP 工作负载，现在可以使用可移植、面向角色的 Gateway API 模型，不必只依赖 Service 或某个控制器的私有 CRD。

与此同时，实验资源开始迁入独立的 gateway.networking.x-k8s.io API 组。这个变化让生产级能力和可能随时调整的实验设计在对象定义上直接分开。

L4 路由终于成为标准能力

此前，Gateway API 已经为 HTTP 和 TLS 流量建立了稳定模型，但原始四层协议缺少同等级的标准路由对象。v1.6.0 中，TCPRoute 和 UDPRoute 达到 GA 稳定性，并升级到 v1。

它们不解析 HTTP 路径、请求头或其他七层内容，只依据监听协议和端口接收连接或数据报，然后把流量交给后端。职责划分很清楚：

  • 平台团队通过 GatewayClass 和 Gateway 管理网关实现、地址及监听端口。
  • 应用团队通过 TCPRoute 或 UDPRoute 声明后端服务。
  • allowedRoutes 限制监听器可以接收哪些路由类型。
  • parentRefs.sectionName 把路由精确绑定到指定监听器。

旧的 v1alpha2 TCPRoute 和 UDPRoute 已在 v1.6 中弃用，并将在未来版本移除。升级时不能只更新 CRD，还应同步迁移仓库中的清单和生成模板。

一套可以改造的 TCPRoute 清单

下面假设集群已经安装 Gateway API v1.6 CRD，并部署了支持该版本的 Gateway Controller。运行前必须把 gatewayClassName: example-gateway-class 改成集群实际存在的类名；可先执行 kubectl get gatewayclass 查看。

示例后端使用 socat 在 6000 端口启动 TCP 回显服务，外部流量从 Gateway 的 12345 端口进入：

apiVersion: v1
kind: Namespace
metadata:
  name: l4-demo
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: tcp-echo
  namespace: l4-demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app: tcp-echo
  template:
    metadata:
      labels:
        app: tcp-echo
    spec:
      containers:
        - name: socat
          image: alpine/socat:1.8.0.0
          args:
            - TCP-LISTEN:6000,fork,reuseaddr
            - EXEC:/bin/cat
          ports:
            - name: tcp
              containerPort: 6000
---
apiVersion: v1
kind: Service
metadata:
  name: tcp-echo
  namespace: l4-demo
spec:
  selector:
    app: tcp-echo
  ports:
    - name: tcp
      port: 6000
      targetPort: 6000
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: l4-gateway
  namespace: l4-demo
spec:
  gatewayClassName: example-gateway-class
  listeners:
    - name: tcp-12345
      protocol: TCP
      port: 12345
      allowedRoutes:
        kinds:
          - kind: TCPRoute
---
apiVersion: gateway.networking.k8s.io/v1
kind: TCPRoute
metadata:
  name: tcp-echo
  namespace: l4-demo
spec:
  parentRefs:
    - name: l4-gateway
      sectionName: tcp-12345
  rules:
    - backendRefs:
        - name: tcp-echo
          port: 6000

保存为 tcp-route.yaml 后，可以这样实践：

kubectl apply -f tcp-route.yaml
kubectl -n l4-demo wait --for=condition=Available deployment/tcp-echo --timeout=120s
kubectl -n l4-demo get gateway,tcproute
kubectl -n l4-demo describe gateway l4-gateway
kubectl -n l4-demo describe tcproute tcp-echo

从 Gateway 状态中取得控制器分配的地址，再用 Netcat 测试：

GATEWAY_HOST=$(kubectl -n l4-demo get gateway l4-gateway \
  -o jsonpath='{.status.addresses[0].value}')
printf 'hello gateway-api\n' | nc -w 3 "$GATEWAY_HOST" 12345

正常情况下会收到相同文本。若 Gateway 没有地址或 Route 未被接纳，应检查状态条件中的 Accepted、Programmed 和 ResolvedRefs，而不是只查看 Pod 是否运行。

UDPRoute 的模型相同：将监听器协议改为 UDP，把 allowedRoutes.kinds 和资源类型改为 UDPRoute。如果 parentRefs 同时省略 sectionName 和端口，路由会尝试附加到该 Gateway 上所有兼容的 TCP 或 UDP 监听器；生产清单通常更适合显式指定 sectionName，避免新增监听器后扩大绑定范围。

实验 API 有了醒目的边界

过去，标准资源和实验资源都位于 gateway.networking.k8s.io，主要依靠 v1alpha2 之类的版本号区分成熟度。v1.6 开始，新实验资源进入 gateway.networking.x-k8s.io，类型名称也带有 X 前缀，例如 XBackend 和 XMesh。

XBackend 是面向 Gateway API 后端的通用装饰资源。其首个版本支持 ExternalHostname 目标，可用于需要把流量导向集群外主机名的场景，例如访问云端 AI API。不过它仍是实验 API，字段和行为可能变化，不应直接视为生产稳定接口。

这种外部目标还涉及 confused deputy 等安全风险。实现方可以把它作为 Extended/Optional 能力，由集群管理员在理解 DNS、出口控制、身份与 TLS 边界后选择启用。引用实验后端时，路由必须明确填写完整组名：

backendRefs:
  - name: ai-provider-api
    kind: XBackend
    group: gateway.networking.x-k8s.io

未来实验对象毕业时，会迁回 gateway.networking.k8s.io 并去掉 X 前缀。这个过程意味着资源名称和 API 组都可能变化，GitOps 仓库应把实验清单与稳定清单分目录管理，并为升级保留迁移窗口。

上线前检查四件事

采用 v1.6 时，应先确认 Gateway Controller 明确支持该版本及所需功能。Gateway API 的一致性依赖 conformance 测试，但某个实现支持 HTTPRoute，并不自动意味着它已经实现标准 TCPRoute、UDPRoute 或可选的 XBackend。

上线前建议完成以下检查：

  1. 确认 CRD、控制器和 GatewayClass 的版本兼容，不要只更新客户端清单。
  2. 将所有 v1alpha2 TCPRoute、UDPRoute 迁移到 gateway.networking.k8s.io/v1。
  3. 检查 Gateway 与 Route 的状态条件，并验证真实 TCP 连接或 UDP 数据报路径。
  4. 对实验 API 设置单独的准入策略、权限和升级流程，尤其谨慎处理外部主机名与出口流量。

TCPRoute 和 UDPRoute 进入标准通道，意味着 Gateway API 已不再局限于 Web 流量。它开始为四层和七层协议提供一套统一的角色、绑定和状态模型，但可移植性仍取决于控制器实现与 conformance 能力；在生产迁移中，这一点比 YAML 能否成功提交更重要。

# AI # Go # Kubernetes # LLM # 云原生 # 可观测性 # 后端 # 安全 # 数据库

相关推荐