《Kubernetes 分布式系统原理深入解析》5.2 Gateway API 资源模型

Gateway API 是 Ingress 的进化:把入口抽象成 GatewayClass、Gateway、HTTPRoute 三层资源,按角色分离(基础设施提供者/集群运维/应用开发者)并支持跨 namespace 引用与后端权重分发。本节对比 Ingress 的局限与 Gateway API 的动机,拆解匹配条件(Exact/PathPrefix/host)与加权后端语义,并说明它为什么是『声明式基础设施层』而不是又一个控制器。lab 用 gateway.go 验证 HTTPRoute 匹配与权重分发。

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 的设计方向:

维度IngressGateway API
结构单一扁平资源,规则全塞一起分层:Class/Gateway/Route
角色谁都能改,无边界按角色划分归属
跨 namespace后端必须同 namespace通过 ReferenceGrant 显式授权
表达能力path/host 为主host+path+method+header+query
流量分割无原生支持后端权重,开箱即用

其中「谁都能改」最致命:Ingress 只有一个对象,平台团队和应用团队都改它,导致入口配置互相踩踏。Gateway API 的解法是分对象:基础设施团队管 Gateway(监听什么端口、用什么证书),应用团队管 HTTPRoute(流量怎么路由)。分对象就是分职责。

三层资源模型与角色分离

Gateway API 的核心是三个资源,对应三个角色:

资源作用域谁创建表达什么
GatewayClass集群级基础设施提供者「这类 Gateway 由哪个控制器实现」
Gatewaynamespace 级集群运维「这个入口监听什么,用什么协议/证书」
HTTPRoutenamespace 级应用开发者「这些请求怎么路由到我的后端」

三者是引用关系: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.typeExact / PathPrefix / RegularExpressionPathPrefix: /v1
方法methodHTTP 方法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 验证的是行为被忠实执行。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图