随着 Ingress NGINX 逐步进入退役周期，Kubernetes 入口治理能力也正在加快从 Ingress 向 Gateway API 演进。
面向这一变化，KubeSphere 正式推出 Gateway API 网关扩展。这意味着，KubeSphere 基于 Gateway API 的网关能力已正式落地，并进入可用阶段。
此前，我们已在《关于 Ingress NGINX 退役的说明》中说明了三点：
- Kubernetes Ingress API 本身并未被弃用；
- 进入退役流程的是 Ingress NGINX 这一实现；
- KubeSphere 将提供基于 Gateway API 的网关能力，并支持可视化管理。
这次发布，正是这一承诺的正式兑现。
接下来，我们从实际场景出发，看看 KubeSphere Gateway API 网关扩展解决了什么问题、适合哪些场景，以及现有 Ingress 业务如何平滑迁移。
为什么需要 Gateway API
Ingress 是 Kubernetes 早期用于管理外部访问入口的标准抽象，在很长一段时间里发挥了重要作用。但在更复杂的生产场景中，它也逐渐暴露出一些长期存在的问题。
协议覆盖有限。Ingress API 主要面向 HTTP/HTTPS。gRPC、TLS passthrough、原始 TCP 等场景通常依赖具体 Controller 的扩展能力或 annotation，不同实现之间的可迁移性有限。
多租户边界模糊。在一个集群中，多个团队共用 IngressClass 时，谁有权修改哪个 Ingress、不同团队的入口如何隔离，缺少标准化的边界。很多时候需要依赖 RBAC、命名空间规划和运维约定来共同维护。
角色职责压在一起。基础设施层（谁部署 Controller）、平台层（谁定义入口和监听端口）、业务层（谁配置路由规则）在 Ingress 这一种资源中被混在一起，平台团队和业务团队的职责边界不够清晰。
Gateway API 的价值，就在于它对这些问题做了更清晰的拆分。
在 Gateway API 中，GatewayClass、Gateway 和各类 Route 资源各司其职；HTTPRoute、GRPCRoute、TLSRoute、TCPRoute 等资源覆盖了从四层到七层的常见入口场景；而像 parentRefs、allowedRoutes 这样的字段，也把“谁能挂在哪个入口上”变成了标准 API 能力，而不再只是依赖约定。
不过，Gateway API 解决的首先是 API 标准层 的问题。对于一个真实的多租户平台来说，还需要继续回答几个更落地的问题：
- 谁来部署和维护 GatewayClass 背后的数据面工作负载？
- 不同团队的 Gateway 如何按企业空间、项目等组织结构隔离？
- 网关资源能否在控制台中直接管理，而不是只能通过命令行维护？
KubeSphere Gateway API 网关扩展，解决的正是这一层平台化能力。
三个核心概念，对应 Gateway API 标准
为了让 Gateway API 能够真正适用于企业级、多租户场景，KubeSphere 在标准模型之上引入了三个核心概念，并与 Gateway API 的角色保持一致。
1. 网关实现（Gateway Implementation）
网关实现对应 Gateway API 背后的实现组
件，包含网关实现工作负载以及一个 GatewayClass 实例。流量真正被接收和转发的位置，就在这一层。
网关实现通过 Service 对外暴露，当前支持 NodePort 和 LoadBalancer 两种方式，用户可以根据集群环境和基础设施条件进行选择。
2. 网关（Gateway）
网关对应 Gateway API 中的 Gateway 资源。它通过 listeners 引用同层级网关实现中的 entrypoints，用于定义监听端口、协议以及 TLS 证书等配置。
这一层通常更接近平台团队的职责边界，用来统一定义入口能力。
3. 应用路由（Route）
应用路由对应 Gateway API 中的各类路由资源，用于定义流量进入 Gateway 之后应如何转发到后端服务。
当前，KubeSphere 已支持以下四种 Route 类型：
这覆盖了从七层到四层的常见入口场景，也使不同协议下的路由规则能够以更标准化的方式进行配置。
整体来看，这三类资源分别对应实现层、入口层和路由层，职责划分比传统 Ingress 模型更清晰，也更适合平台团队和业务团队分工协作。
三层级治理：把 API 字段对齐到组织结构
支持 Gateway API 只是第一步。对于企业级平台来说，更关键的是如何把这套能力真正纳入组织结构和权限体系中。KubeSphere Gateway API 网关扩展将网关实现和网关划分为三个层级：集群、企业空间、项目。
在这一模型下，网关层级与网关实现层级一一对应。Gateway 只能引用同层级的网关实现，而 Route 的可绑定范围也会随着 Gateway 的层级受到限制。
这种隔离并不是界面上的“软约束”，而是通过 Gateway 的路由允许范围在控制面进行约束。跨层级的 Route 即便配置了
parentRefs，也不会被对应 Gateway 接受或生效。
这套机制对应着三类典型使用场景：
- 集群层级网关：由平台管理员维护，作为集群统一的南北向入口，允许集群范围内的 Route 挂载。
- 企业空间层级网关：由企业空间管理员维护，作为某个业务线或部门边界内的入口。
- 项目层级网关：由项目级用户维护，生命周期和项目对齐。
对于此前使用 Ingress 构建多租户入口体系的用户来说，这类问题并不陌生。过去很多隔离能力依赖 RBAC 和运维约定来维持，而现在，这些边界可以直接落到资源层级和标准 API 字段中。
监控和日志：依赖 WizTelemetry 扩展
网关实现的可观测性通过独立扩展接入：
- WizTelemetry 监控：提供网关实现的指标采集与监控面板，覆盖连接数、QPS、延迟、错误率等指标。
- WizTelemetry 日志：提供网关日志的搜索与排查能力。
网关扩展本身聚焦数据面和控制面能力，观测层则可按需启用。如果生产环境对请求级排查、访问日志检索和故障定位有要求，建议同时启用 WizTelemetry 监控和 WizTelemetry 日志扩展。
迁移建议：Ingress 资源不必立即重写，但替代方案应尽快规划
这里仍需再次强调一个关键点：
Ingress API（networking.k8s.io/v1）仍然是 Kubernetes 稳定 API，并没有被弃用。进入退役流程的是 Ingress NGINX 这一实现，而不是 Ingress 资源本身。
基于这一点，我们建议：
第一，存量 Ingress 资源不需要立即重写。已有业务可以继续运行，迁移工作可以结合业务节奏逐步推进，而不是一次性切换。
第二，仍依赖 Ingress NGINX 的环境应尽早规划替代方案。可以结合自身场景评估 Gateway API，或选择其他仍在持续维护的 Ingress Controller，优先梳理现有规则、证书和扩展依赖，再分批迁移。
第三，新业务更建议直接基于 Gateway API 进行设计。无论是协议覆盖、职责划分，还是多租户治理能力，Gateway API 都更适合作为下一阶段的入口标准。
同时，我们也将逐步推出辅助迁移工具，帮助用户将业务从 Ingress NGINX 稳定过渡到 Gateway API。
如何启用
进入 KubeSphere 控制台后，按以下路径操作即可：
扩展中心 → 搜索 “Gateway API 网关” → 安装并启用
❝版本说明 Gateway API 网关已支持 KubeSphere v4.2.1 及以上版本。 如在扩展中心未搜索到该扩展，请先将扩展仓库升级至 v11.2.0 及以上版本。
完整文档请参考：
https://docs.kubesphere.com.cn/v4.2.1/11-use-extensions/31-gatewayapi/
如果你正在规划新的入口方案，建议从测试环境或新业务开始体验 Gateway API 网关扩展。
我们也非常欢迎你在实际使用中的反馈，这将直接影响后续默认网关方案的选择。如有问题或建议，欢迎通过 GitHub Issue 或开发者论坛与我们交流。
