Kubernetes Gateway API v1.6 TCPRoute 标准化：从 TCP 暴露到回滚验收

如果一个集群要把原始 TCP 服务交给 Gateway 管理，过去常常要依赖控制器自定义资源。Gateway API v1.6 把 TCPRoute 和 UDPRoute 推进到 Standard，并统一使用 gateway.networking.k8s.io/v1，这意味着四层流量也有了更明确的便携式 API 边界。

这次更新最值得关注的不是多了一个资源名，而是 TCP/UDP 路由从实验能力进入稳定通道；真正上线前仍要核对 Gateway 控制器的 v1.6 支持和回滚路径。

Gateway API v1.6 到底改变了什么

Kubernetes SIG Network 在官方发布说明中把 Gateway API v1.6.0 定义为一次四层路由能力的稳定化更新。TCPRoute 和 UDPRoute 从 Experimental 进入 Standard，资源版本切换到 v1；此前的 v1alpha2 版本已被弃用，后续版本会移除。

同一版本还把新的实验资源放到了独立的 gateway.networking.x-k8s.io API 组，并用 X 前缀区分实验对象。这个边界很实用：看到 gateway.networking.k8s.io/v1 时，读者可以先按稳定 API 评估；看到 XBackend 时，则要把兼容变化列入风险清单。

一个 TCP 服务如何接入 Gateway

下面这个例子只做一件事：让 Gateway 的 TCP 端口 12345 把流量转给 my-foo-service:6000。图中的 Gateway、TCPRoute、Service 和端口数字都对应这条配置链，不代表某个特定控制器的界面。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
spec:
  gatewayClassName: example-gateway-class
  listeners:
    - name: foo
      protocol: TCP
      port: 12345
      allowedRoutes:
        kinds:
          - kind: TCPRoute
---
apiVersion: gateway.networking.k8s.io/v1
kind: TCPRoute
metadata:
  name: tcp-app
spec:
  parentRefs:
    - name: example-gateway
      sectionName: foo
  rules:
    - backendRefs:
        - name: my-foo-service
          port: 6000

这里有三个容易漏掉的连接点：监听器的 protocol 要写成 TCP，allowedRoutes.kinds 要允许 TCPRoute，而路由的 sectionName: foo 要与监听器名称一致。少一个连接点，资源可能创建成功，却不会形成可用的转发关系。

从实验版本迁移时先看 API 和控制器

不要把“资源版本变成 v1”理解成只改一行字符串。先确认当前集群安装的是哪一套 Gateway API CRD，再确认控制器的发布说明是否支持 v1.6 的 Standard TCPRoute。官方文章列出了当时已通过 v1.6 一致性测试的实现，但这不是所有控制器、所有发行版都自动具备的承诺。

迁移可以按下面的顺序做：

1. 保存当前 Gateway、TCPRoute 和后端 Service 清单，记录监听端口和 sectionName。
2. 安装或升级与控制器匹配的 Gateway API v1.6 Standard CRD，先检查资源发现结果。
3. 将测试环境的路由清单改为 gateway.networking.k8s.io/v1，查看 status.parents 与监听器状态。
4. 从 TCP 客户端连接 12345，确认后端 my-foo-service 的连接计数和应用日志都出现预期变化。

验收时重点看可见状态，而不是只看 YAML 已提交：Gateway 监听器应处于可接受状态，TCPRoute 的父引用应被接受，客户端连接应到达 Service 后端。若任一状态不成立，先回到控制器兼容性和 CRD 版本检查，不要直接扩大端口或修改业务服务。

TCPRoute 和普通 Service、旧式自定义资源怎么取舍

单纯在集群内部访问 TCP 服务时，Service 仍然是更短的路径；当平台团队需要统一入口、监听器和路由对象，或者希望在不同 Gateway 控制器之间保留较稳定的资源模型时，TCPRoute 才有明显价值。

相较于某个控制器专用的 CRD，Standard TCPRoute 的好处是 API 语义更容易迁移；代价是你必须接受 GatewayClass、监听器、路由父引用和控制器一致性实现这套额外对象。对只有一个内部端口的小服务，增加 Gateway 不一定划算。

上线和回滚时最容易忽略的边界

Standard 不等于每个控制器即时支持

Standard 描述的是 Gateway API 的稳定通道，不等于每个实现都在同一天完成全部能力。将“资源能被 API Server 接受”和“流量真的被代理”分成两个验收项。

不要把 XBackend 当成稳定后端对象

v1.6 的 XBackend 属于实验 API 组，官方明确提示其行为可能变化。它和 TCPRoute 的 Standard 化是同一版本里的两条不同消息，不能因为都出现在发布文章里就用同样的生产承诺。

回滚要恢复整组对象

如果升级后只恢复 TCPRoute 而保留了不匹配的 Gateway 监听器或 CRD，故障可能变成“资源存在但路由不接收”。回滚清单至少应包含 Gateway、TCPRoute、Service 关联配置，以及对应的 CRD 版本变更记录。

相关问题

TCPRoute 一定要指定 sectionName 吗？

不一定。指定 sectionName 可以把路由绑定到名为 foo 的单个 TCP 监听器；省略它时，按官方示例语义可以附着到 Gateway 上符合条件的 TCP 监听器，生产配置仍应明确核对控制器行为。

Gateway API v1.6 能直接替代所有 Ingress 配置吗？

不能直接等同。TCPRoute 解决的是 TCP 流量路由，Ingress 主要面向 HTTP/HTTPS；迁移时仍需按协议、TLS 终止位置和控制器能力逐项评估。

只升级 Kubernetes 就会得到 Gateway API v1.6 吗？

不会。Gateway API 以独立 CRD 和控制器生态发布，按官方文档安装或升级对应资源，并确认当前控制器支持的版本。

把这次新闻落成一张验收清单

• 版本：确认 CRD 和清单使用 gateway.networking.k8s.io/v1。
• 绑定：确认 Gateway 的 TCP 监听器允许 TCPRoute，路由父引用指向正确的 sectionName。
• 链路：确认端口 12345 的连接能到达 my-foo-service:6000。
• 回退：保留升级前整组对象和控制器版本，失败时恢复整组配置。

Gateway API v1.6 的价值在于把 TCP/UDP 路由的 API 形态稳定下来，但是否值得采用，最终取决于你的入口治理需求、控制器支持和回滚能力。先在测试集群把从 Gateway 到 Service 的链路验通，再谈迁移规模。