中文内容

已翻译official company source英文原文2026-04-21

Gateway API v1.5：将功能推进至稳定版

Tuesday, April 21, 2026

Kubernetes SIG Network 社区发布了 Gateway API（v1.5）！1.5 版本于 2026 年 2 月 27 日发布，是我们迄今为止规模最大的一次发布，重点是将现有的实验性功能推进至标准版（稳定版）。

Gateway API v1.5.1 补丁版本现已可用。

Gateway API v1.5 将六项广受期待的功能提升至标准通道（Gateway API 的 GA 发布通道）：

正文：ListenerSet
正文：TLSRoute
HTTPRoute CORS 过滤器
客户端证书验证
网关 TLS 发起的证书选择
正文：ReferenceGrant

特别感谢 Gateway API 贡献者为此次发布所付出的努力。

新的发布流程

自 Gateway API v1.5 起，该项目已转向发布列车模型，即在功能冻结日期，任何已准备就绪的功能都会随版本发布。

这同时适用于 Experimental 和 Standard，也适用于文档——如果文档尚未准备好发布，那么该功能也尚未准备好发布。

我们的目标是借此形成更可靠的发布节奏（因为我们的工作基于 SIG Release 在 Kubernetes 本身上所做的出色工作）。作为这一变更的一部分，我们还在发布团队中引入了 Release Manager 和 Release Shadow 角色。非常感谢 Flynn（Buoyant）和 Beka Modebadze（Google）在协调和打磨我们发布流程中不完善之处方面所做的出色工作。他们两位也将在下一次发布中继续担任这一角色。

新的标准功能

正文：ListenerSet

负责人：Dave Protasowski，David Jumani

正文：GEP-1713

为什么选择 ListenerSet？

在 ListenerSet 之前，所有监听器都必须直接在 Gateway 对象上指定。虽然这对于简单用例运行良好，但在更复杂或多租户环境中带来了挑战：

平台团队和应用团队通常需要协调对同一个 Gateway 的变更
难以安全地委派单个监听器的所有权
扩展现有 Gateway 需要直接修改原始资源

ListenerSet 通过允许独立定义监听器，然后将其合并到目标 Gateway 上，从而解决了这些限制。

ListenerSet 还支持将超过 64 个监听器附加到单个共享 Gateway。这对于大规模部署以及每个监听器具有多个主机名的场景至关重要。

尽管 ListenerSet 功能显著增强了可扩展性，但 Gateway 中的 listener 字段仍然是必填要求，并且 Gateway 必须至少有一个有效的监听器。

工作原理

ListenerSet 附加到 Gateway，并提供一个或多个监听器。Gateway 控制器负责合并来自 Gateway 资源本身以及任何已附加的 ListenerSet 资源的监听器。

在此示例中，中央基础设施团队定义了一个带有默认 HTTP 监听器的 Gateway，而两个不同的应用团队在各自独立的命名空间中定义了自己的 ListenerSet 资源。这两个 ListenerSet 都附加到同一个 Gateway，并提供额外的 HTTPS 监听器。

---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
  namespace: infra
spec:
  gatewayClassName: example-gateway-class
  allowedListeners:
    namespaces:
      from: All # A selector lets you fine tune this
  listeners:
  - name: http
    protocol: HTTP
    port: 80
---
apiVersion: gateway.networking.k8s.io/v1
kind: ListenerSet
metadata:
  name: team-a-listeners
  namespace: team-a
spec:
  parentRef:
    name: example-gateway
    namespace: infra
  listeners:
  - name: https-a
    protocol: HTTPS
    port: 443
    hostname: a.example.com
    tls:
      certificateRefs:
      - name: a-cert
---
apiVersion: gateway.networking.k8s.io/v1
kind: ListenerSet
metadata:
  name: team-b-listeners
  namespace: team-b
spec:
  parentRef:
    name: example-gateway
    namespace: infra
  listeners:
  - name: https-b
    protocol: HTTPS
    port: 443
    hostname: b.example.com
    tls:
      certificateRefs:
      - name: b-cert

正文：TLSRoute

负责人：Rostislav Bobrovsky、Ricardo Pchevuzinske Katz

正文：GEP-2643

TLSRoute 资源允许你通过匹配客户端在 TLS 握手期间提供的服务器名称指示（SNI）来路由请求，并将流量导向适当的 Kubernetes 后端。

使用 TLSRoute 时，Gateway 的 TLS 监听器可以配置为两种模式之一：Passthrough 或 Terminate。

如果你在 v1.4 或更早的 Experimental 版本之上安装 Gateway API v1.5 Standard，你现有的 Experimental TLSRoutes 将无法使用。这是因为它们将以 v1alpha2 或 v1alpha3 版本存储，而这些版本不包含在 v1.5 Standard YAML 中。如果这适用于你，请继续在 v1.5.1 及后续版本中使用 Experimental，或者你需要下载并将 TLSRoutes 迁移到 v1，该版本存在于 Standard YAML 中。

Passthrough 模式

Passthrough 模式专为严格的安全要求而设计。它非常适用于以下场景：流量必须保持端到端加密，直到到达目标后端；外部客户端和后端需要彼此直接进行身份验证；或者无法在 Gateway 上存储证书。此配置也适用于需要加密 TCP 流而非标准 HTTP 流量的情况。

在此模式下，加密的字节流会被直接代理到目标后端。Gateway 无法访问私钥或未加密的数据。

以下 TLSRoute 附加到一个配置为 Passthrough 模式的监听器。它将仅匹配具有 foo.example.com SNI 主机名的 TLS 握手，并应用其路由规则，将加密的 TCP 流传递到配置的后端：

---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
spec:
  gatewayClassName: example-gateway-class
  listeners:
  - name: tls-passthrough
    protocol: TLS
    port: 8443
    tls:
      mode: Passthrough
---
apiVersion: gateway.networking.k8s.io/v1
kind: TLSRoute
metadata:
  name: foo-route
spec:
  parentRefs:
  - name: example-gateway
    sectionName: tls-passthrough
  hostnames:
  - "foo.example.com"
  rules:
  - backendRefs:
    - name: foo-svc
      port: 8443

终止模式

终止模式提供了直接在 Gateway 集中管理 TLS 证书的便利。

在此模式下，TLS 会话在 Gateway 处完全终止，随后 Gateway 会将解密后的载荷作为明文 TCP 流路由到目标后端。

以下 TLSRoute 附加到一个配置为终止模式的监听器。它将仅匹配带有 bar.example.com SNI 主机名的 TLS 握手，并应用其路由规则，将解密后的 TCP 流传递到配置的后端：

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
spec:
  gatewayClassName: example-gateway-class
  listeners:
  - name: tls-terminate
    protocol: TLS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
      - name: tls-terminate-certificate
---
apiVersion: gateway.networking.k8s.io/v1
kind: TLSRoute
metadata:
  name: bar-route
spec:
  parentRefs:
  - name: example-gateway
    sectionName: tls-terminate
  hostnames:
  - "bar.example.com"
  rules:
  - backendRefs:
    - name: bar-svc
      port: 8080

HTTPRoute CORS 过滤器

负责人：Damian Sawicki、Ricardo Pchevuzinske Katz、Norwin Schnyder、Huabing (Robin) Zhao、LiangLliu，

正文：GEP-1767

跨源资源共享（CORS）是一种基于 HTTP 标头的安全机制，允许（或拒绝）网页访问来自与提供该网页的域不同源的服务器资源。更多信息请参阅我们的文档页面。HTTPRoute 资源可用于配置跨源资源共享（CORS）。以下 HTTPRoute 允许来自 https://app.example 的请求：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: cors
spec:
  parentRefs:
  - name: same-namespace
  rules:
  - matches:
    - path:
       type: PathPrefix
       value: /cors-behavior-creds-false
    backendRefs:
    - name: infra-backend-v1
       port: 8080
    filters:
    - cors:
      allowOrigins:
        - https://app.example
      type: CORS

除了指定特定来源列表外，你也可以指定单个通配符（"*"），这将允许任何来源。还允许在列表中使用半指定来源，其中通配符出现在协议之后并位于主机名开头，例如 https://*.bar.com：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: cors
spec:
  parentRefs:
  - name: same-namespace
  rules:
  - matches:
    - path:
      type: PathPrefix
      value: /cors-behavior-creds-false
    backendRefs:
    - name: infra-backend-v1
      port: 8080
    filters:
    - cors:
      allowOrigins:
        - https://www.baz.com
        - https://*.bar.com
        - https://*.foo.com
      type: CORS

HTTPRoute 过滤器允许配置 CORS 设置。请参见下方支持选项列表：

allowCredentialsSpecifies whether the browser is allowed to include credentials (such as cookies and HTTP authentication) in the CORS request.allowMethodsThe HTTP methods that are allowed for CORS requests.allowHeadersThe HTTP headers that are allowed for CORS requests.exposeHeadersThe HTTP headers that are exposed to the client.maxAgeThe maximum time in seconds that the browser should cache the preflight response.

一个综合示例：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: cors-allow-credentials
spec:
  parentRefs:
  - name: same-namespace
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /cors-behavior-creds-true
    backendRefs:
    - name: infra-backend-v1
      port: 8080
    filters:
    - cors:
        allowOrigins:
        - "https://www.foo.example.com"
        - "https://*.bar.example.com"
        allowMethods:
        - GET
        - OPTIONS
        allowHeaders:
        - "*"
        exposeHeaders:
        - "x-header-3"
        - "x-header-4"
        allowCredentials: true
        maxAge: 3600
      type: CORS

Gateway 客户端证书验证

负责人：Arko Dasgupta，Katarzyna Łach，Norwin Schnyder

正文：GEP-91

客户端证书验证，也称为双向 TLS（mTLS），是一种安全机制，其中客户端向服务器提供证书以证明其身份。这与标准 TLS 不同，在标准 TLS 中，只有服务器向客户端出示证书。在 Gateway API 的上下文中，前端 mTLS 意味着 Gateway 会在允许连接继续到后端服务之前验证客户端的证书。此验证通过将客户端证书与 Gateway 上配置的一组受信任证书颁发机构（CA）进行比对来完成。该 API 之所以被设计成这种方式，是为了解决与连接复用相关的关键安全漏洞，同时仍提供一定程度的灵活性。

配置概述

客户端验证使用 frontendValidation 结构体进行定义，该结构体指定 Gateway 应如何验证客户端的身份。

caCertificateRefs：对 Kubernetes 对象（通常为 ConfigMap）的引用列表，这些对象包含 PEM 编码的 CA 证书包，用作信任锚点，以验证客户端的证书。
mode：定义验证行为。AllowValidOnly（默认）：仅当客户端提供通过指定 CA 证书包验证的有效证书时，Gateway 才接受连接。AllowInsecureFallback：即使客户端证书缺失或验证失败，Gateway 也接受连接。此模式通常将授权委托给后端，应谨慎使用。

验证可以全局应用于 Gateway，也可以针对特定端口进行覆盖：

默认配置：除非定义了按端口覆盖配置，否则此配置适用于 Gateway 上的所有 HTTPS 监听器。
按端口配置：这允许进行精细化控制，覆盖处理特定端口流量的所有监听器的默认配置。

示例：

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: client-validation-basic
spec:
  gatewayClassName: acme-lb
  tls:
    frontend:
      default:
        validation:
          caCertificateRefs:
          - kind: ConfigMap
            group: ""
            name: foo-example-com-ca-cert
      perPort:
      - port: 8443
        tls:
          validation:
            caCertificateRefs:
            - kind: ConfigMap
              group: ""
              name: foo-example-com-ca-cert
            mode: "AllowInsecureFallback"
  listeners:
  - name: foo-https
    protocol: HTTPS
    port: 443
    hostname: foo.example.com
    tls:
      certificateRefs:
      - kind: Secret
        group: ""
        name: foo-example-com-cert
  - name: bar-https
    protocol: HTTPS
    port: 8443
    hostname: bar.example.com
    tls:
      certificateRefs:
      - kind: Secret
        group: ""
        name: bar-example-com-cert

Gateway TLS 发起的证书选择

负责人：Marcin Kosieradzki、Rob Scott、Norwin Schnyder、Lior Lieberman、Katarzyna Lach

正文：GEP-3155

用于上游连接的双向 TLS（mTLS）要求 Gateway 向后端提供客户端证书，同时验证后端的证书。这可确保后端只接受来自授权 Gateway 的连接。

Gateway 的客户端证书配置

要配置 Gateway 在连接到后端时使用的客户端证书，请使用 Gateway 资源中的 tls.backend.clientCertificateRef 字段。此配置适用于该 Gateway 作为客户端所管理的所有上游连接。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: backend-tls
spec:
  gatewayClassName: acme-lb
  tls:
    backend:
      clientCertificateRef:
        kind: Secret
        group: "" # empty string means core API group
        name: foo-example-cert
  listeners:
  - name: foo-http
    protocol: HTTP
    port: 80
    hostname: foo.example.com

ReferenceGrant 资源在一年多的时间里没有发生变化，我们预计它也不会再进一步变化，因此其版本已提升到 v1，现在正式进入 Standard 渠道，并遵循 GA API 契约（即不引入破坏性变更）。

试试看

与其他 Kubernetes API 不同，你不需要升级到最新版本的 Kubernetes 即可获得最新版本的 Gateway API。只要你运行的是 Kubernetes 1.30 或更高版本，就能开始使用此版本的 Gateway API。

要试用该 API，请遵循《入门指南》。

截至撰写本文时，已有七个实现完全符合 Gateway API v1.5。按字母顺序排列：

正文：Agentgateway
正文：Airlock Microgateway
正文：GKE Gateway
正文：HAProxy Ingress
正文：kgateway
正文：NGINX Gateway Fabric
正文：Traefik Proxy

参与进来

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

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

维护者们要感谢所有为 Gateway API 做出贡献的人，无论是向代码仓库提交代码、参与讨论、提出想法，还是提供一般性支持。没有这个专注而活跃的社区的支持，我们不可能取得这样的进展。

本文于 2026 年 4 月进行了编辑，以更正 Gateway API 1.5.0 的发布日期。

Last modified April 24, 2026 at 8:24 AM PST: Add edit acknowledgement as suggested by LMKTFY (4da4aa8b6e)

Gateway API v1.5：将功能移至稳定版