容器与云原生 / 系统课时
Gateway API 核心资源
Gateway API 核心资源
Gateway API 把“谁提供网关能力、网关在哪里监听、哪些请求允许进入、最终转发到谁”拆成独立资源。本篇聚焦 GatewayClass、Gateway、HTTPRoute 与后端引用的职责边界,并建立一条可用于阅读配置和排查路由问题的关联链路。
学习目标
- 区分 GatewayClass、Gateway、HTTPRoute 与
backendRefs的职责。 - 说清请求从监听器到 Service 的资源关联顺序。
- 能用
kubectl确认集群是否已经提供 Gateway API 核心资源。
四类对象如何分工
GatewayClass 是集群级资源,描述“由哪一种控制器实现 Gateway”。它类似一份网关实现模板,本身不承载某个业务域名,也不直接接收流量。不同控制器会声明不同的 controllerName。
Gateway 是命名空间级资源,选择一个 GatewayClass,并定义实际监听器,例如 HTTP 80 端口、HTTPS 443 端口、允许的主机名和路由挂载范围。它回答的是“入口在哪里、以什么协议接收请求”。
HTTPRoute 也是命名空间级资源。它通过 parentRefs 绑定 Gateway,再用 hostnames、matches、filters 和 backendRefs 描述 HTTP 请求如何匹配和转发。业务团队通常主要维护这一层。
backendRefs 不是独立 Kind,而是 Route 规则中的后端引用。最常见的后端是同一命名空间中的 Service;跨命名空间引用时通常还需要目标命名空间中的 ReferenceGrant 授权。

从声明到转发的关联链路
可以把四者理解为一条声明链:控制器先识别 GatewayClass,再调谐引用该 Class 的 Gateway;Route 只有在被 Gateway 接受后,规则才会继续解析其后端引用;后端引用解析成功后,数据面才能把匹配请求送往 Service。
下面是结构片段,用来观察字段之间的引用关系。它包含占位符,因此不是可直接应用的完整清单。
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: <GATEWAY_CLASS>
spec:
controllerName: <CONTROLLER_NAME>
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: app-gateway
namespace: default
spec:
gatewayClassName: <GATEWAY_CLASS>
listeners:
- name: http
protocol: HTTP
port: 80
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: app-route
namespace: default
spec:
parentRefs:
- name: app-gateway
rules:
- backendRefs:
- name: app-service
port: 80这段片段的关键不是字段数量,而是三个引用:gatewayClassName 把 Gateway 连接到 GatewayClass,parentRefs 把 HTTPRoute 连接到 Gateway,backendRefs 把匹配规则连接到 Service。实际配置还要根据控制器补充域名、TLS、允许的 Route 范围等内容。
检查集群是否具备这些资源
Gateway API 通常由网关控制器连同 CRD 一起安装。先查看 API 资源,再查看可用的 GatewayClass。
kubectl api-resources --api-group=gateway.networking.k8s.io -o name
kubectl get gatewayclass预期输出
gatewayclasses.gateway.networking.k8s.io
gateways.gateway.networking.k8s.io
httproutes.gateway.networking.k8s.io
<OTHER_GATEWAY_API_RESOURCES>
NAME CONTROLLER ACCEPTED AGE
<GATEWAY_CLASS> <CONTROLLER_NAME> True <VALUE>实际资源列表会随安装的 Gateway API 版本增加其他 Route 类型;<GATEWAY_CLASS>、<CONTROLLER_NAME> 和 <VALUE> 也会因控制器与集群而不同。如果前三个核心资源不存在,说明 CRD 尚未安装;如果 GatewayClass 存在但 ACCEPTED 不是 True,应先修复控制器或 Class 配置,再创建业务 Gateway。
判断问题应该查哪一层
看到“Gateway 一直没有地址”时,优先检查 GatewayClass 是否被控制器接受,以及 Gateway 的监听器状态。看到“Route 不生效”时,先看 parentRefs 是否被接受,再看主机名、路径等匹配条件。看到“Route 已接受但返回 503”时,应继续检查 backendRefs 是否解析成功以及 Service 是否存在可用端点。
这种职责拆分让平台团队可以控制 GatewayClass 与共享 Gateway,应用团队只维护 HTTPRoute;排障时也能沿着 Class → Gateway → Route → Service 的链路逐层缩小范围。