Gateway API v1.3.0：请求镜像、CORS、网关合并和重试预算方面的进展

欢迎与 Kubernetes SIG Network 社区一起，庆祝 Gateway API v1.3.0 正式发布！我们也很高兴地宣布，由于推迟了这篇博客的发布，已经有许多符合标准的实现可供尝试。API 的 1.3.0 版本已于大约一个月前的 2025 年 4 月 24 日发布。

Gateway API v1.3.0 为*标准（Standard）*频道（Gateway API 的 GA 发布频道）带来了新功能：*基于百分比的请求镜像*，并引入了三项新的实验性功能：跨源资源共享（CORS）过滤器、监听器和网关合并的标准化机制以及重试预算。

另请参阅完整的发行说明，下次见到 v1.3.0 发布团队时，请为他们喝彩。

升级到 Standard 频道

升级到 Standard 频道是 Gateway API 功能的一项显著成就，因为被纳入 Standard 发布频道意味着对 API 接口的高度信心，并提供了向后兼容性的保证。当然，与任何其他 Kubernetes API 一样，Standard 频道的功能可以通过向后兼容的增补不断演进，我们（SIG Network）当然期望未来会有进一步的完善和改进。有关其工作原理的更多信息，请参阅 Gateway API 版本控制策略。

基于百分比的请求镜像

负责人：Lior Lieberman、Jake Bennert

GEP-3171：基于百分比的请求镜像

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

之前的镜像功能对所有到 backendRef 的请求都有效。
基于百分比的请求镜像允许用户指定他们希望镜像的请求子集，可以按百分比或分数。当服务接收到大量请求时，这尤其有用。这个新功能可以用来镜像其中的一小部分，而不是镜像所有这些请求。

这是一个例子，其中 42% 的到“foo-v1”的请求被镜像到“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 # This value must be an integer.

你还可以使用分数来配置部分镜像。这是一个例子，其中每 1000 个到“foo-v1”的请求中有 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 频道的新增内容

Experimental 频道是 Gateway API 用于试验新功能并在其升级到 Standard 频道之前建立信心的渠道。请注意：Experimental 频道可能包含之后会更改或删除的功能。

从 v1.3.0 版本开始，为了区分 Experimental 频道资源和 Standard 频道资源，任何新的实验性 API kind 都带有前缀“X”。出于同样的原因，实验性资源现在被添加到 API 组 gateway.networking.x-k8s.io 而不是 gateway.networking.k8s.io。请记住，使用新的 Experimental 频道资源意味着它们可以与 Standard 频道资源共存，但将这些资源迁移到 Standard 频道将需要使用 Standard 频道的名称和 API 组（两者都没有“x-k8s”指示符或“X”前缀）重新创建它们。

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

CORS 过滤

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

GEP-1767：CORS 过滤器

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

要使用实验性的 CORS 过滤，你需要安装Experimental 频道的 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

在这种情况下，网关返回一个“*”的*源标头*，这意味着请求的资源可以从任何源引用，一个允许 GET、HEAD 和 POST 动词的*方法标头*（Access-Control-Allow-Methods），以及一个允许 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
• allowHeaders
• allowCredentials
• exposeHeaders
• maxAge

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

XListenerSets（监听器和网关合并的标准化机制）

负责人：Dave Protasowski

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

此版本添加了一个新的实验性 API kind，XListenerSet，它允许将共享的*监听器*列表附加到一个或多个父网关。此外，它扩展了现有的建议，即 Gateway API 实现可以合并来自多个 Gateway 对象的配置。它还

• 在网关的 .spec 中添加了一个新字段 allowedListeners。allowedListeners 字段定义了从哪些命名空间选择允许附加到该网关的 XListenerSet：Same、All、None 或基于 Selector。
• 通过增加 XListenerSet，增加了先前监听器的最大数量（64）。
• 允许将监听器配置（如 TLS）委托给其他命名空间中的应用程序。

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

以下示例显示了一个带有 HTTP 监听器和两个具有唯一主机名和证书的子 HTTPS XListenerSet 的网关。附加到网关的监听器组合包括附加到网关的 XListenerSet 中的两个附加 HTTPS 监听器。此示例说明了将监听器 TLS 配置委托给不同命名空间（“store”和“app”）中的应用程序所有者。HTTPRoute 将名为“foo”的网关监听器和名为“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
    ...

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

此外，如果跨多个网关的所有监听器都兼容，实现可以*合并*单独的网关为一组监听器地址。在 v1.3.0 之前的版本中，合并监听器的管理规定不足。

有了新功能，合并的规范得到了扩展。实现必须将父网关视为拥有其自身和附加的 XListenerSet 的所有监听器的合并列表，并且此监听器列表的验证必须与该列表是单个网关的一部分时一样。在单个网关内，监听器按以下优先级排序

1. 首先是单个监听器（不属于 XListenerSet），
2. 其余监听器按
   • 对象创建时间（最早的优先）排序，如果两个监听器在具有相同时间戳的对象中定义，则
   • 按“{namespace}/{name of listener}”的字母顺序排序

重试预算（XBackendTrafficPolicy）

负责人：Eric Bishop、Mike Morris

GEP-3388：重试预算

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

要使用实验性的重试预算，你需要安装Experimental 频道的 Gateway API XBackendTrafficPolicy yaml。

以下示例显示了一个应用 retryConstraint 的 XBackendTrafficPolicy，该约束表示一个预算，它将重试限制为请求的最大 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 实验性频道的功能。按字母顺序排列

• Airlock Microgateway 4.6
• Cilium main
• Envoy Gateway v1.4.0
• Istio 1.27-dev

参与其中

想知道某个功能何时会添加吗？有很多机会可以参与进来，帮助定义 Kubernetes 路由 API（用于入口和服务网格）的未来。

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

维护者们想感谢*每一位*为 Gateway API 做出贡献的人，无论是以向仓库提交代码、讨论、提出想法还是提供一般支持的形式。没有这个敬业而活跃的社区的支持，我们永远不可能取得如此大的进步。

相关 Kubernetes 博客文章

• 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 月)

• ←上一篇
• 下一篇→