容器与云原生 / 系统课时
理解 GatewayClass 与 Gateway
理解 GatewayClass 与 Gateway
本课解决 Gateway API 中“谁提供入口能力”和“实际入口实例是谁”容易混淆的问题。学完后,你能从 GatewayClass 到 Gateway 再到入口地址建立完整关系,理解基础设施提供者、具体 Gateway 实例与可用地址之间的职责边界。
学习目标
- 理解 GatewayClass、Gateway 与底层基础设施提供者之间的关系。
- 区分“定义由谁实现”和“创建哪个入口实例”两个层次。
- 能根据 Gateway 的状态判断入口地址和配置是否已经被控制器接受。
Gateway API 为什么拆成两层
传统 Ingress 往往把路由对象和入口实现的选择放在相对紧凑的模型里。Gateway API 更强调职责分离:GatewayClass 描述一类由基础设施提供者实现的网关能力,Gateway 则表示一个实际请求的网关实例。
因此可以把它们理解成“类”和“实例”的关系。GatewayClass 解决的是“这个 Gateway 由哪种实现负责”,Gateway 解决的是“我要创建哪个具体入口、监听哪些端口和协议”。

GatewayClass 表达谁来实现
GatewayClass 的核心价值是把 API 与具体实现绑定起来。它包含用于识别控制器的 spec.controllerName,通常由基础设施提供者或平台团队负责创建和维护。应用团队通常不需要为每个业务 Gateway 修改这个标识。
一个集群可以存在多个 GatewayClass,分别代表不同的入口实现或不同的基础设施能力。选择哪一个 GatewayClass,实际上是在声明“这个 Gateway 希望由哪类网关控制器接管”。
Gateway 表达哪个具体入口
Gateway 引用一个 GatewayClass,并通过 listeners 描述希望开放的监听能力,例如监听地址、端口、协议以及相关的 TLS 配置。它是一个具体的入口资源,因此可以被不同团队、不同环境按实际需求创建多个实例。
Gateway 的状态还会反馈控制器是否已经接受配置,以及最终是否产生可访问地址。这里的关键思维是:spec 表达期望状态,status 反映控制器观察到的实际状态。只看到 Gateway YAML 创建成功,并不等于入口已经可以接收流量。
从 GatewayClass 追到入口地址
判断一条 Gateway 链路是否建立,可以沿着四层关系检查:Gateway 是否引用了预期的 GatewayClass;GatewayClass 是否存在对应控制器实现;Gateway 的 listener 是否被控制器接受;Gateway status 中是否出现可用地址。
这样定位问题时,就能把“类选择错误”“控制器未接管”“监听配置不被接受”和“入口地址尚未分配”区分开,而不是统称为 Gateway 不工作。
什么时候最容易混淆
最常见的混淆是把 GatewayClass 当成访问入口本身。实际上,客户端不会访问 GatewayClass;它是控制器选择和能力归类所需的资源。真正需要被关注的是具体 Gateway 的 listener、状态以及最终入口地址。
另一个误区是只检查 spec,忽略 status。Gateway API 的资源采用声明式模型,控制器需要经过观察、验证和配置基础设施的过程,最终状态可能与期望状态暂时不同。因此,治理入口时应同时关注“我声明了什么”和“控制器实际接受并分配了什么”。
理解这条分层关系后,后续再学习 HTTPRoute 等路由资源时,就可以自然地把“路由规则”和“入口基础设施”分开:Gateway 负责提供可接入的边界,路由资源再描述请求如何进入具体后端。