5.2 Gateway API 资源模型
5.1 节的 Ingress 解决了一个问题:把七层路由声明化。但它把「入口」的所有职责——监听端口、TLS、路由、后端选择——压进一个扁平的 spec,而且所有字段只能写在同一个 namespace 里。Gateway API 在 2023 年作为正式 API 进入 K8s,回答的是同一个问题的进阶版:入口流量治理应该是什么资源模型。
本节先列 Ingress 的局限,再讲 Gateway API 的三层资源(GatewayClass/Gateway/HTTPRoute)与角色分离,最后落到匹配条件与后端权重分发。你会发现它不是「又一个控制器」,而是把控制器的能力边界重新定义了一遍。
Ingress 的局限:动机从哪里来
Ingress 的四个痛点,决定了 Gateway API 的设计方向:
| 维度 | Ingress | Gateway API |
|---|---|---|
| 结构 | 单一扁平资源,规则全塞一起 | 分层:Class/Gateway/Route |
| 角色 | 谁都能改,无边界 | 按角色划分归属 |
| 跨 namespace | 后端必须同 namespace | 通过 ReferenceGrant 显式授权 |
| 表达能力 | path/host 为主 | host+path+method+header+query |
| 流量分割 | 无原生支持 | 后端权重,开箱即用 |
其中「谁都能改」最致命:Ingress 只有一个对象,平台团队和应用团队都改它,导致入口配置互相踩踏。Gateway API 的解法是分对象:基础设施团队管 Gateway(监听什么端口、用什么证书),应用团队管 HTTPRoute(流量怎么路由)。分对象就是分职责。
三层资源模型与角色分离
Gateway API 的核心是三个资源,对应三个角色:
| 资源 | 作用域 | 谁创建 | 表达什么 |
|---|---|---|---|
| GatewayClass | 集群级 | 基础设施提供者 | 「这类 Gateway 由哪个控制器实现」 |
| Gateway | namespace 级 | 集群运维 | 「这个入口监听什么,用什么协议/证书」 |
| HTTPRoute | namespace 级 | 应用开发者 | 「这些请求怎么路由到我的后端」 |
三者是引用关系:Gateway 通过 spec.gatewayClassName 引用 GatewayClass,HTTPRoute 通过 spec.parentRefs 引用 Gateway。GatewayClass 是唯一绑定控制器的资源——它声明「由 Envoy Gateway/Contour/Traefik/ingress-nginx 实现」,控制器则 watch 所有引用它的 Gateway 与 Route。
这套模型把 5.1 节 Ingress 的「控制器实现什么」显式化了:GatewayClass 决定了数据面由谁跑,Gateway 决定了入口长什么样,HTTPRoute 决定了流量往哪走。三者分离,任何一方都不会被另一方拖垮。
parentRefs 与监听器:路由如何挂到入口
HTTPRoute 通过 spec.parentRefs 声明「我想挂到哪个 Gateway 的哪个 listener」:
spec:
parentRefs:
- name: shared-gw
namespace: infra
sectionName: https
sectionName: https 把这条 HTTPRoute 绑到名为 https 的 listener(Gateway 的端口协议单元)。控制器收到后,会把该 listener 下所有命中的 HTTPRoute 合并成一张路由表:请求先落到 listener,再在合并表里按规则匹配。合并语义是本节 lab 之外的实现细节,简化模型如下——同 listener 的规则按「匹配条件越具体越优先」排序,其余按控制器定义的稳定顺序兜底。
parentRefs 还带来一个 Ingress 没有的能力:一条 HTTPRoute 可以同时挂到多个 Gateway(比如 staging 与 prod 共用同一套路由声明)。Ingress 只能单实例路由,HTTPRoute 是「一份声明多处消费」——这正是声明式资源在复用上的优势。
匹配条件:比 Ingress 细一个数量级
HTTPRoute 的路由规则在 spec.rules[].matches[],每个 match 可以组合多个条件,全部满足才算命中:
| 条件 | 字段 | 语义 | 例子 |
|---|---|---|---|
| 域名 | hostnames | 精确或通配 | api.example.com |
| 路径 | path.type | Exact / PathPrefix / RegularExpression | PathPrefix: /v1 |
| 方法 | method | HTTP 方法 | GET |
| 头 | headers | 请求头精确/前缀/正则 | X-Canary: true |
| 查询参数 | queryParams | 精确/正则 | env=canary |
path.type 的三个取值比 Ingress 的 pathType 更直白:Exact 要求路径完全相等,PathPrefix 按 / 元素级前缀(沿用 5.1 节的边界规则),RegularExpression 用正则。Matches 是本节的 lab 落点——gateway.go 里 HTTPRoute.Matches 实现了 hostname 精确 + PathPrefix 前缀的判定,并规定「无匹配条件 = 匹配所有」。
匹配条件的组合与优先级
spec.rules[].matches[] 的语义要分清两层「或」与「且」:
| 层 | 关系 | 例子 |
|---|---|---|
| match 数组内部 | OR(任一 match 命中即可) | /v1 或 /v2 都算命中 |
| 单个 match 内部 | AND(host+path+method 全满足) | 既要有 host 又要路径对 |
两条 HTTPRoute 同时命中同一请求时,由优先级决定谁赢。完整规范(本卷 lab 的简化模型):匹配条件更具体的路由优先——如 host 精确 + path 都有的规则,高于只有 path 的规则;再按创建顺序等稳定规则兜底。优先级的意义在排障:两个 namespace 的路由指向同一 listener 时,「为什么这条规则不生效」往往就是「另一条更具体的规则先赢了」,而不是控制器故障。
后端权重分发:金丝雀开箱即用
路由规则的落点由 spec.rules[].backendRefs[] 描述,每个后端带一个 weight:
spec:
rules:
- backendRefs:
- name: stable
port: 80
weight: 3
- name: canary
port: 80
weight: 1
语义:命中该规则的流量按权重比例分配——stable:canary = 3:1,即约 75% 到 stable、25% 到 canary。这正是 Ingress 没有的能力:不需要部署第二个 Ingress 或写控制器特定的 annotation,就在 API 层面表达流量分割。金丝雀发布的典型流程就是先 1:3 试水,验证后再逐渐把权重翻转,最后删掉 canary 后端。
gateway.go 的 RouteBackend.Pick 用加权轮询实现这条语义:把每个后端按权重复制进池子再轮转,4 次 Pick 得到 canary 1 次、stable 3 次——与 weight 1:3 严格对应。
weight 的合法范围是 0–1000,默认 1。权重是相对语义不是绝对百分比:stable:canary = 1:1 与 2:2 的分发结果相同;weight: 0 表示暂时不发流量但保留配置。金丝雀发布的完整动作就是先加一条 weight: 1 的 canary 后端,观察指标后逐步加大权重,最后把 stable 权重降为 0 或删除 canary 后端——整套动作都在声明层完成,不碰数据面。
跨 namespace 引用:显式授权
Ingress 的后端必须与 Ingress 同 namespace,而 HTTPRoute 的后端可以引用别的 namespace——但需要显式授权。跨 namespace 引用的链路是:
HTTPRoute (namespace: apps) --backendRefs--> Service (namespace: shared)
↑ 被 ReferenceGrant 授权
ReferenceGrant 声明「shared namespace 里叫 svc-a 的 Service 允许被 apps namespace 的 HTTPRoute 引用」。没有这个授权,路由就是坏的。这套机制的价值不是加门槛,而是把跨 namespace 的依赖显式化:平台共享的 Service 由平台团队授权,应用团队无法越权引用。
为什么是「声明式基础设施层」而不是又一个控制器
看到 Gateway API 有 GatewayClass、有控制器绑定,很容易误以为它「又多了一个控制器」。准确的说法是:Gateway API 是一组 API 资源,不是控制器。
- GatewayClass 只是声明「由哪个控制器实现」,本身不跑任何数据面。
- 同一个 GatewayClass 可以指向 Envoy Gateway、Contour、Traefik 等不同实现——API 是稳定的,控制器是可替换的。
- HTTPRoute 描述「想要的流量行为」,与 5.1 节 Ingress 是同一层的抽象,只是更细分。
把它称作「声明式基础设施层」,强调的是:它定义的是接口契约,不是实现。应用团队只需表达路由意图;监听什么端口、TLS 怎么终止、数据面怎么跑,全部留给 GatewayClass 绑定的实现。这比 Ingress 更彻底地贯彻了「声明与执行解耦」——Ingress 至少把「执行」留给了一个隐式控制器,Gateway API 把「执行方式」也变成了可声明的选择。
从 Ingress 迁移:共存与取舍
Gateway API 不要求「一次性替换」:同一集群可以同时跑 Ingress 控制器与 Gateway 控制器,ingressClassName 与 gatewayClassName 各管各的资源。常见迁移路线是分两阶段:
| 阶段 | 动作 | 风险 |
|---|---|---|
| 共存期 | 新入口用 HTTPRoute,旧入口保持 Ingress | 两套数据面并存,注意规则别重叠 |
| 切换期 | 流量切到 Gateway 的 listener | 需验证等价性,靠权重渐进切换 |
| 下线期 | 删除旧 Ingress 与控制器 | 依赖 Ingress 的资源要一并迁移 |
取舍点在于团队能力与控制器成熟度:Gateway API 表达更强、支持跨 namespace 与权重,但要求控制器实现它(Envoy Gateway、Contour、Traefik 较成熟,ingress-nginx 对 Gateway API 的支持有限);Ingress 生态更老、选择更多。迁移的本质是把「隐式绑定控制器」改成「显式选择控制器」——如果团队并不需要 Gateway API 的增强能力,为了迁移而迁移反而增加复杂度。
三个常见误解
- 「Gateway API 是又一个 Ingress 控制器」——错误。它是一组 API 资源;控制器由 GatewayClass 声明,不同实现可替换,API 本身不跑数据面。
- 「Gateway API 只能做七层路由」——错误。它覆盖 TCP/UDP/TLS 等多种监听协议,HTTPRoute 只是其中最常用的一种。
- 「权重分发要求后端必须健康」——错误。权重是概率语义,不健康的后端由实现层面的健康检查摘除(5.3 节展开),权重本身不表达健康状态。
- 「HTTPRoute 只有挂到 Gateway 才能生效」——错误。
parentRefs也可以指向实现自定义的父亲资源(某些网格、Service 等),Gateway 是最常见而非唯一的挂载目标。
一句话总结本节
Gateway API 用三层资源把入口治理重新建模:GatewayClass 定实现、Gateway 定入口、HTTPRoute 定路由。收成三个要点:
- 角色分离:基础设施提供者、集群运维、应用开发者各管一层,解决 Ingress 的「谁都改」问题。
- 表达增强:匹配条件细到 method/header/query,后端权重让金丝雀开箱即用,跨 namespace 靠 ReferenceGrant 显式授权。
- 契约而非实现:它是声明式基础设施层——API 稳定、控制器可替换,比 Ingress 更彻底地贯彻声明与执行解耦。
下一节把入口放到多集群与网格的更大范围:流量如何在集群之间分发,服务网格又在七层治理里扮演什么角色。
本节 lab
本节把「HTTPRoute 匹配条件与权重分发」落到 gateway.go:
cd private/labs/k8s-net-lab
go test ./gateway -run TestHTTPRouteMatches -v
go test ./gateway -run TestRouteBackendWeighted -v
TestHTTPRouteMatches 验证 hostname 精确拒绝 + PathPrefix 命中 /v1 三条断言;TestRouteBackendWeighted 验证 canary:stable = 1:3 的加权轮询在 4 次 Pick 中严格得到 1:3 分布。前者对应本节匹配条件模型,后者对应后端权重分发语义——声明给的是「想要的流量行为」,lab 验证的是行为被忠实执行。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。