容器与云原生 / 系统课时

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 授权。

Gateway API 核心资源职责关系

从声明到转发的关联链路

可以把四者理解为一条声明链:控制器先识别 GatewayClass,再调谐引用该 Class 的 Gateway;Route 只有在被 Gateway 接受后,规则才会继续解析其后端引用;后端引用解析成功后,数据面才能把匹配请求送往 Service。

下面是结构片段,用来观察字段之间的引用关系。它包含占位符,因此不是可直接应用的完整清单。

yaml
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。

bash
kubectl api-resources --api-group=gateway.networking.k8s.io -o name
kubectl get gatewayclass

预期输出

text
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 的链路逐层缩小范围。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

Gateway API 核心资源

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通