Gateway API v1.3.0：流量复制、CORS、Gateway 合并和重试预算的改进

作者 Candace Holman (Red Hat) | 译者 Wenjun Lou | 2025.06.02

加入 Kubernetes SIG Network 社区，共同庆祝 Gateway API v1.3.0 正式发布！我们很高兴地宣布，通过推迟这篇博客的发布，现在已经有了多个符合规范的实现可供试用。 API 1.3.0 版本已于 2025 年 4 月 24 日发布。

Gateway API v1.3.0 为 Standard 渠道（Gateway API 的正式发布渠道）带来了一个新功能：基于百分比的流量复制，并引入了三个新的实验性功能：

跨源资源共享（CORS）过滤器
Listener 和 Gateway 合并的标准化机制
重试预算（Retry Budgets）

另请查看完整的发布说明，下次见到 v1.3.0 发布团队时请为他们鼓掌。

升级至 Standard 渠道

对于 Gateway API 的功能来说，升级到 Standard 渠道是一个重要的里程碑。被纳入 Standard 发布渠道表明我们对该 API 接口的稳定性具有高度信心，并且承诺向后兼容。当然，与任何其他 Kubernetes API 一样， Standard 渠道中的功能仍可通过向后兼容的方式不断演进。我们（SIG Network）也确实预计未来会有进一步的优化和改进。有关这一切如何运作的更多信息，请参阅 Gateway API 版本控制策略。

基于百分比的流量复制

负责人：Lior Lieberman、Jake Bennert GEP-3171：基于百分比的流量复制

基于百分比的流量复制是对现有 HTTP 流量复制支持的增强，它允许使用 RequestMirror 过滤器类型将 HTTP 请求复制到另一个后端。流量复制在蓝绿部署中特别有用。它可用于评估流量波动对应用程序性能的影响，而不会影响对客户端的响应。

之前的流量复制功能适用于对 backendRef 的所有请求。基于百分比的流量复制允许用户指定他们想要复制的请求子集，可以通过百分比或分数来指定。当服务接收大量请求时，这特别有用。这个新功能可以用来复制这些请求中的一小部分，而不是复制所有请求。

以下是一个示例，将发送到 "foo-v1" 的流量的 42% 复制到 "foo-v2"：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-filter-mirror
  labels:
    gateway: mirror-gateway
spec:
  parentRefs:
  - name: mirror-gateway
  hostnames:
  - mirror.example
  rules:
  - backendRefs:
    - name: foo-v1
      port: 8080
    filters:
    - type: RequestMirror
      requestMirror:
        backendRef:
          name: foo-v2
          port: 8080
        percent: 42 # 此值必须为整数。

你也可以通过调整分数来实现部分流量复制。以下是一个示例，在发送到 "foo-v1" 的请求中，将每 1000 个中的 5 个复制到 "foo-v2"。

  rules:
  - backendRefs:
    - name: foo-v1
      port: 8080
    filters:
    - type: RequestMirror
      requestMirror:
        backendRef:
          name: foo-v2
          port: 8080
        fraction:
          numerator: 5
          denominator: 1000

实验渠道的新特性

实验渠道（Experimental channel）是 Gateway API 用于试验新功能的渠道，以便在功能成熟之前积累足够信心，再将其升级为 Standard 渠道功能。请注意：实验渠道可能包含后续会被更改或移除的功能。

从 v1.3.0 版本开始，为了区分实验渠道资源和 Standard 渠道资源，所有新的实验性 API 类型都带有 "X" 前缀。出于同样的原因，实验性资源现在被添加到 API 组 gateway.networking.x-k8s.io，而不是 gateway.networking.k8s.io。请注意，使用新的实验渠道资源意味着它们可以与 Standard 渠道资源共存，若要将这些资源迁移到 Standard 渠道，则需要使用 Standard 渠道的名称和 API 组（两者都不包含 "x-k8s" 标识或 "X" 前缀）来重新创建它们。

v1.3 版本引入了两个新的实验性 API 类型：XBackendTrafficPolicy 和 XListenerSet。要使用实验性 API 类型，你需要从下面列出的位置安装实验渠道 Gateway API YAML 文件。

CORS 过滤

负责人：Liang Li、Eyal Pazz、Rob Scott

GEP-1767：CORS 过滤器

跨源资源共享（CORS）是一种基于 HTTP Header 的机制，允许网页从与提供网页的域不同的源（域名、协议或端口）访问受限资源。此功能添加了一个新的 HTTPRoute filter 类型，称为 "CORS"，用于在响应发送回客户端之前配置跨源请求的处理。

要使用实验性 CORS 过滤，你需要安装实验渠道 Gateway API HTTPRoute yaml。

以下是一个简单的跨源配置示例：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-route-cors
spec:
  parentRefs:
  - name: http-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /resource/foo
    filters:
    - cors:
      - type: CORS
        allowOrigins:
        - *
        allowMethods:
        - GET
        - HEAD
        - POST
        allowHeaders:
        - Accept
        - Accept-Language
        - Content-Language
        - Content-Type
        - Range
    backendRefs:
    - kind: Service
      name: http-route-cors
      port: 80

在这种情况下，Gateway 返回一个 origin header 为 "*"，这意味着请求的资源可以从任何源引用；一个 methods header （Access-Control-Allow-Methods）允许 GET、HEAD 和 POST 方法；此外，还会返回一个 headers header ，允许的字段包括 Accept、Accept-Language、 Content-Language、Content-Type 和 Range。

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, HEAD, POST
Access-Control-Allow-Headers: Accept,Accept-Language,Content-Language,Content-Type,Range

新的 CORS 过滤器中的完整字段列表如下：

allowOrigins：允许的请求来源列表。
allowMethods：允许的 HTTP 方法（如 GET、POST 等）。
allowHeaders：允许携带的请求头字段。
allowCredentials：是否允许携带凭据（如 Cookie、Authorization 头等）。
exposeHeaders：允许客户端访问的响应头字段。
maxAge：预检请求的缓存持续时间（单位：秒）。

有关详细信息，请参阅 CORS 协议。

XListenerSets（Listener 和 Gateway 合并的标准化机制）

负责人：Dave Protasowski

GEP-1713：ListenerSets - 合并多个 Gateway 的标准机制

此版本添加了一个新的实验性 API 类型 XListenerSet，它允许将 listeners 的共享列表附加到一个或多个父 Gateway。此外，它还扩展了现有的建议，即 Gateway API 实现可以合并来自多个 Gateway 对象的配置。它还包括：

向 Gateway 的 .spec 添加了一个新字段 allowedListeners。 allowedListeners 字段定义了从哪些命名空间选择允许附加到该 Gateway 的 XListenerSets： Same（同一命名空间）、All（所有命名空间）、None（不允许）、或基于选择器（Selector）的方式。

通过添加 XListenerSets 增加了之前的监听器最大数量（64）。

允许将监听器配置（如 TLS）委托给其他命名空间中的应用程序。

要使用实验性 XListenerSet，你需要安装实验渠道 Gateway API XListenerSet yaml。

以下示例展示了一个带有 HTTP 监听器和两个子 HTTPS XListenerSets 的 Gateway，每个 XListenerSet 都有唯一的主机名和证书。最终附加到该 Gateway 的监听器集合包含这两个附加的 HTTPS XListenerSet 监听器。此示例说明了将监听器 TLS 配置委托给不同命名空间（"store" 和 "app"）中的应用程序所有者。 HTTPRoute 同时将名为 "foo" 的 Gateway 监听器和一个名为 "second" 的 XListenerSet 监听器设置为其 parentRefs。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-external
  namespace: infra
spec:
  gatewayClassName: example
  allowedListeners:
  - from: All
  listeners:
  - name: foo
    hostname: foo.com
    protocol: HTTP
    port: 80
---
apiVersion: gateway.networking.x-k8s.io/v1alpha1
kind: XListenerSet
metadata:
  name: store
  namespace: store
spec:
  parentRef:
    name: prod-external
  listeners:
  - name: first
    hostname: first.foo.com
    protocol: HTTPS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        group: ""
        name: first-workload-cert
---
apiVersion: gateway.networking.x-k8s.io/v1alpha1
kind: XListenerSet
metadata:
  name: app
  namespace: app
spec:
  parentRef:
    name: prod-external
  listeners:
  - name: second
    hostname: second.foo.com
    protocol: HTTPS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        group: ""
        name: second-workload-cert
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httproute-example
spec:
  parentRefs:
  - name: app
    kind: XListenerSet
    sectionName: second
  - name: parent-gateway
    kind: Gateway
    sectionName: foo
    ...

Gateway 中的每个监听器必须具有唯一的 port、protocol 组合（如果协议支持，还包括 hostname），以便所有监听器都兼容，并且不会在它们应该接收的流量上发生冲突。

此外，如果这些 Gateway 上的所有监听器都兼容，实现可以将单独的 Gateway 合并为单个监听器地址集。在 v1.3.0 之前的版本中，合并监听器的管理规范不足。

通过新功能，合并规范得到了扩展。实现必须将父 Gateway 视为具有来自自身和附加的 XListenerSets 的所有监听器的合并列表，并且对该监听器列表的验证行为应与其作为单个 Gateway 的一部分。在单个 Gateway 内，监听器使用以下优先级排序：

首先是单个监听器（而不是 XListenerSet 的一部分），

其余监听器按以下顺序排序：
- 按对象创建时间排序（最早创建的优先）；
- 如果两个监听器所在的对象具有相同的时间戳，则按照 {namespace}/{监听器名称} 的字母顺序排序

重试预算（Retry budgets）（XBackendTrafficPolicy）

负责人：Eric Bishop、Mike Morris

GEP-3388：重试预算（Retry budgets）

此功能允许你为目标服务的所有端点配置重试预算（Retry budgets）。用于在达到配置的阈值后限制额外的客户端重试。配置预算时，可以指定可能包含重试在内的活动请求的最大百分比，以及在计算重试阈值时考虑请求的时间间隔。此规范的开发将现有的实验性 API 类型 BackendLBPolicy 更改为新的实验性 API 类型 XBackendTrafficPolicy，以减少具有共同点的策略资源的扩散。

要使用实验性重试预算（Retry budgets），你需要安装实验渠道 Gateway API XBackendTrafficPolicy yaml。

以下示例显示了一个 XBackendTrafficPolicy，它应用了一个 retryConstraint （重试约束），表示一个重试预算（Retry budgets），将重试限制为最多 20% 的请求，持续时间为 10 秒，并且在 1 秒内最少重试 3 次。

apiVersion: gateway.networking.x-k8s.io/v1alpha1
kind: XBackendTrafficPolicy
metadata:
  name: traffic-policy-example
spec:
  retryConstraint:
    budget:
      percent: 20
      interval: 10s
    minRetryRate:
      count: 3
      interval: 1s
    ...

试用

与其他 Kubernetes API 不同，你不需要升级到最新版本的 Kubernetes 来获取最新版本的 Gateway API。只要你运行的是 Kubernetes 1.26 或更高版本，你就可以使用此版本的 Gateway API 启动和运行。

要试用 API，请按照入门指南操作。截至本文撰写时，已有四个实现符合 Gateway API v1.3 实验渠道功能。按字母顺序排列：

参与其中

想知道何时会添加功能？有很多机会参与并帮助定义 Kubernetes API 路由的未来，包括 Ingress 和服务网格。

查看用户指南了解可以解决哪些用例。
试用现有的 Gateway 控制器之一。
或者加入我们的社区，帮助我们共同构建 Gateway API 的未来！

维护者衷心感谢所有为 Gateway API 做出贡献的人，无论是通过提交代码、讨论、想法还是提供其他支持。没有这个充满热情和活力的社区，我们永远无法取得如此进展。

Gateway API v1.2：WebSockets、超时、重试等（2024 年 11 月）
Gateway API v1.1：服务网格、GRPCRoute 和更多变化（2024 年 5 月）
Gateway API v1.0 中的新实验功能（2023 年 11 月）
Gateway API v1.0：正式发布（GA）（2023 年 10 月）