Gateway API v1.2: WebSockets、超时、重试及更多

Kubernetes SIG Network 很高兴地宣布 Gateway API v1.2 通用可用！此版本的 API 于 10 月 3 日发布，我们很高兴地报告现在有许多符合规范的实现供您尝试。

Gateway API v1.2 为 Standard Channel（Gateway API 的 GA 发布通道）带来了一些新特性，引入了一些新的实验性特性，并启动了我们新的发布流程 — 但它也带来了两个你需要注意的重大变更。

重大变更

GRPCRoute 和 ReferenceGrant 的 v1alpha2 版本移除

既然 GRPCRoute 和 ReferenceGrant 的 v1 版本已毕业到 Standard，旧的 v1alpha2 版本已从 Standard 和 Experimental Channel 中移除，以减轻永久支持旧版本会给 Gateway API 社区带来的维护负担。

在升级到 Gateway API v1.2 之前，你需要确认任何 Gateway API 的实现都已升级以支持这些资源的 v1 API 版本，而不是 v1alpha2 API 版本。请注意，即使你一直在 YAML Manifests 中使用 v1，控制器可能仍然使用 v1alpha2，这会导致在本次升级期间失败。此外，Kubernetes 本身会尽力阻止你移除它认为你正在使用的 CRD 版本：请查看发布说明，了解安全升级所需的更多信息。

.status.supportedFeatures 的变更（实验性）

一个小得多的重大变更：Gateway 中的 .status.supportedFeatures 现在是一个对象列表，而不是字符串列表。这些对象有一个单独的 name 字段，因此从字符串进行的转换很简单，但转换为对象为将来提供了更大的灵活性。此 Stanza 尚未出现在 Standard Channel 中。

毕业到 Standard Channel

Gateway API 1.2.0 有四个特性毕业到 Standard Channel，这意味着它们现在可以被视为通用可用。包含在 Standard 发布通道中表示对 API 接口的高度信心，并提供向后兼容的保证。当然，与任何其他 Kubernetes API 一样，Standard Channel 特性可以随着时间的推移通过向后兼容的添加而不断演进，我们当然期望未来对这些新特性进行进一步的完善和改进。有关这一切如何工作的更多信息，请参阅Gateway API 版本控制策略。

HTTPRoute 超时

GEP-1742 在 HTTPRoute 中引入了 timeouts Stanza，允许配置 HTTP 流量的基本超时。这是处理 HTTP 流量时实现良好弹性的一个简单但重要的特性，现在它已是 Standard。

例如，此 HTTPRoute 配置将发往 /face 路径的流量超时设置为 300ms

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: face-with-timeouts
  namespace: faces
spec:
  parentRefs:
    - name: my-gateway
      kind: Gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /face
    backendRefs:
    - name: face
      port: 80
    timeouts:
      request: 300ms

有关更多信息，请查阅HTTP 路由文档。（请注意，这仅适用于 HTTPRoute 超时。GRPCRoute 超时尚未成为 Gateway API 的一部分。）

Gateway 基础设施标签和注解

Gateway API 实现负责创建使每个 Gateway 工作所需的后端基础设施。例如，在 Kubernetes 集群中运行的实现通常会创建 Services 和 Deployments，而基于云的实现可能会创建云负载均衡器资源。在许多情况下，能够将标签或注解传播到这些生成的资源会很有帮助。

在 v1.2.0 中，Gateway 的 infrastructure Stanza 移至 Standard Channel，允许你指定 Gateway API 控制器创建的基础设施的标签和注解。例如，如果你的 Gateway 基础设施在集群内运行，可以使用以下 Gateway 配置指定 Linkerd 和 Istio 注入，从而使基础设施更容易集成到你已安装的任何服务网格中

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: meshed-gateway
  namespace: incoming
spec:
  gatewayClassName: meshed-gateway-class
  listeners:
  - name: http-listener
    protocol: HTTP
    port: 80
  infrastructure:
    labels:
      istio-injection: enabled
    annotations:
      linkerd.io/inject: enabled

有关更多信息，请查阅infrastructure API 参考。

后端协议支持

自 Kubernetes v1.20 起，Service 和 EndpointSlice 资源已支持一个稳定的 appProtocol 字段，允许用户指定 Service 支持的 L7 协议。随着KEP 3726 的采纳，Kubernetes 现在支持三个新的 appProtocol 值

kubernetes.io/h2c

如 RFC7540 中所述的基于明文的 HTTP/2

kubernetes.io/ws

如 RFC6445 中所述的基于明文的 WebSocket

kubernetes.io/wss

如 RFC6445 中所述的基于 TLS 的 WebSocket

通过 Gateway API 1.2.0，支持遵从 appProtocol 现已是 Standard。例如，给定以下 Service

apiVersion: v1
kind: Service
metadata:
  name: websocket-service
  namespace: my-namespace
spec:
  selector:
    app.kubernetes.io/name: websocket-app
  ports:
    - name: http
      port: 80
      targetPort: 9376
      protocol: TCP
      appProtocol: kubernetes.io/ws

那么包含此 Service 作为 backendRef 的 HTTPRoute 将自动升级连接以使用 WebSockets，而不是假设连接是纯 HTTP。

有关更多信息，请查阅GEP-1911。

Experimental Channel 的新添加

*Route 资源的命名规则

HTTPRoute 和 GRPCRoute 资源的 rules 字段现在可以命名，以便更容易地引用特定规则，例如

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: multi-color-route
  namespace: faces
spec:
  parentRefs:
    - name: my-gateway
      kind: Gateway
      port: 80
  rules:
  - name: center-rule
    matches:
    - path:
        type: PathPrefix
        value: /color/center
    backendRefs:
    - name: color-center
      port: 80
  - name: edge-rule
    matches:
    - path:
        type: PathPrefix
        value: /color/edge
    backendRefs:
    - name: color-edge
      port: 80

日志记录或状态消息现在可以将这两条规则称为 center-rule 或 edge-rule，而无需被迫通过索引引用它们。有关更多信息，请参阅GEP-995。

HTTPRoute 重试支持

Gateway API 1.2.0 引入了 HTTPRoute 计数重试的实验性支持。例如，以下 HTTPRoute 配置会重试发往 /face 路径的请求最多 3 次，每次重试之间间隔 500ms

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: face-with-retries
  namespace: faces
spec:
  parentRefs:
    - name: my-gateway
      kind: Gateway
      port: 80
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /face
    backendRefs:
    - name: face
      port: 80
    retry:
      codes: [ 500, 502, 503, 504 ]
      attempts: 3
      backoff: 500ms

有关更多信息，请查阅GEP 1731。

HTTPRoute 基于百分比的镜像

Gateway API 长期以来一直支持请求镜像特性，该特性允许将同一请求发送到多个后端。在 Gateway API 1.2.0 中，我们引入了基于百分比的镜像，它允许你指定要镜像到不同后端请求的百分比。例如，以下 HTTPRoute 配置将 42% 的请求镜像到 color-mirror 后端

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: color-mirror-route
  namespace: faces
spec:
  parentRefs:
  - name: mirror-gateway
  hostnames:
  - mirror.example
  rules:
  - backendRefs:
    - name: color
      port: 80
    filters:
    - type: RequestMirror
      requestMirror:
        backendRef:
          name: color-mirror
          port: 80
        percent: 42   # This value must be an integer.

还有一个 fraction Stanza，可以用来代替 percent，以实现对镜像流量量的更精确控制，例如

    ...
    filters:
    - type: RequestMirror
      requestMirror:
        backendRef:
          name: color-mirror
          port: 80
        fraction:
          numerator: 1
          denominator: 10000

此配置将万分之一的请求镜像到 color-mirror 后端，这在请求率非常高的情况下可能很重要。有关更多详细信息，请参阅GEP-1731。

额外的后端 TLS 配置

此版本包含三个与 Gateway 和工作负载（一个后端）之间通信的 TLS 配置相关的添加项

1. Gateway 上的一个新 backendTLS 字段

   这个新字段允许你指定 Gateway 在连接后端时应使用的客户端证书。

2. BackendTLSPolicy 上的一个新 subjectAltNames 字段

   以前，hostname 字段用于配置 Gateway 应发送给后端的 SNI *以及*证书应提供的身份。当指定新的 subjectAltNames 字段时，任何与至少一个指定的 SAN 匹配的证书将被视为有效。这对于 SPIFFE 尤其重要，因为基于 URI 的 SAN 可能不是有效的 SNI。

3. BackendTLSPolicy 上的一个新 options 字段

   与 Gateway Listener 上的 TLS options 字段类似，我们认为相同的概念对于后端 TLS 的 TLS 特定配置将非常有用。

有关更多信息，请查阅GEP-3135。

更多变更

有关此版本中包含的完整变更列表，请参阅v1.2.0 发布说明。

项目更新

除了技术方面，v1.2 版本也标志着 Gateway API 项目自身生命周期中的几个里程碑。

发布流程改进

Gateway API 从未打算成为一个静态 API，并且随着越来越多的项目将其用作构建组件，很明显我们需要为 Gateway API 发布带来更多可预测性。为此，我们很高兴——也略带紧张！——宣布我们已正式确定一个新的发布流程

• 确定范围（4-6 周）：维护者和社区确定我们希望包含在版本中的特性集。这里特别强调的是让特性退出 Experimental Channel——理想情况下是将它们移到 Standard，但也可能意味着移除它们。

• GEP 迭代与评审（5-7 周）：贡献者为版本中接受的特性撰写或更新 Gateway Enhancement Proposals (GEPs)，重点是围绕特性的设计和毕业标准达成共识。

• API 完善与文档（3-5 周）：贡献者在 Gateway API 控制器中实现这些特性并撰写必要的文档。

• SIG Network 评审与发布候选版本（2-4 周）：维护者获得必要的上游评审，构建发布候选版本，并发布新版本。

Gateway API 1.2.0 是第一个使用新流程发布的版本，尽管任何新事物都存在一些常见的不足，我们相信这次发布进行得很顺利。我们已经完成了 Gateway API 1.3 的范围确定阶段，预计将在 2025 年 1 月底左右发布。

gwctl 分离

gwctl CLI 工具已移至其独立的仓库：https://github.com/kubernetes-sigs/gwctl。gwctl 已被证明是 Gateway API 社区的宝贵工具；我们相信，将其移至独立的仓库将使其更易于维护和开发。一如既往，我们欢迎贡献；尽管仍处于实验阶段，gwctl 已有助于使使用 Gateway API 变得更容易一些——特别是对于项目新手！

维护者变更

最后介绍我们对项目本身的变更，我们很高兴地宣布 Mattia Lavacca 已加入 Gateway API 维护者团队！我们也很遗憾地宣布 Keith Mattix 已卸任 GAMMA lead —— 令人欣慰的是，Mike Morris 已回归该职位。我们感谢 Keith 所做的一切，并很高兴 Mattia 和 Mike 的加入。

试用一下

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

要试用该 API，请遵循我们的入门指南。截至本文撰写时，已有五个实现符合 Gateway API v1.2 规范。按字母顺序列出：

• Cilium v1.17.0-pre.1，实验性通道
• Envoy Gateway v1.2.0-rc.1，实验性通道
• Istio v1.24.0-alpha.0，实验性通道
• Kong v3.2.0-244-gea4944bb0，实验性通道
• Traefik v3.2，实验性通道

参与其中

有许多机会参与进来，并帮助定义 Kubernetes Ingress 和服务网格路由 API 的未来。

• 查看用户指南，了解可以解决哪些用例。
• 试用其中一个现有的 Gateway 控制器。
• 或加入我们的社区，与我们一起构建 Gateway API 的未来！

维护者要感谢所有为 Gateway API 做出贡献的每个人，无论是通过代码提交、讨论、想法还是普遍支持。没有这个专注和活跃的社区的支持，我们不可能走到今天。

相关 Kubernetes 博客文章

• Gateway API v1.1: 服务网格、GRPCRoute 及更多
• Gateway API v1.0 中的新实验性特性 11/2023
• Gateway API v1.0: GA 发布 10/2023
• 介绍 ingress2gateway；简化升级到 Gateway API 10/2023
• Gateway API v0.8.0：引入服务网格支持 08/2023

• ←上一篇
• 下一篇→