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 渠道中移除，以减轻 Gateway API 社区因永久支持旧版本而产生的维护负担。

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

.status.supportedFeatures 变更（实验性）

一个较小的重大变更：Gateway 中的 .status.supportedFeatures 现在是一个对象列表，而不是字符串列表。这些对象有一个名为 name 的字段，因此从字符串转换过来很简单，但迁移到对象为未来提供了更大的灵活性。这个字段尚未出现在 Standard 渠道中。

毕业到 Standard 渠道的功能

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

HTTPRoute 超时

GEP-1742 在 HTTPRoute 中引入了 timeouts 字段，允许为 HTTP 流量配置基本超时。这是在处理 HTTP 流量时实现适当弹性的一个简单但重要的功能，现在它已成为 Standard 功能。

例如，此 HTTPRoute 配置为到 /face 路径的流量设置了 300 毫秒的超时

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 集群中运行的实现通常会创建 Service 和 Deployment，而基于云的实现可能会创建云负载均衡器资源。在许多情况下，能够将标签或注解传播到这些生成的资源会很有帮助。

在 v1.2.0 中，Gateway 的 infrastructure 字段移至 Standard 渠道，允许你为 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 将自动升级连接以使用 WebSocket，而不是假定连接是纯 HTTP。

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

Experimental 渠道新增功能

为 *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 次，每次重试之间有 500 毫秒的延迟

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 字段，可以用来代替 percent，以便更精确地控制镜像的流量量，例如

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

此配置将每 10,000 个请求中的 1 个镜像到 color-mirror 后端，这在请求率非常高的情况下可能很有用。更多详情，请参见 GEP-1731。

额外的后端 TLS 配置

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

1. Gateway 上新增 backendTLS 字段

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

2. BackendTLSPolicy 上新增 subjectAltNames 字段

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

3. BackendTLSPolicy 上新增 options 字段

   与 Gateway Listener 上的 TLS 选项字段类似，我们相信同样的概念将广泛适用于后端的 TLS 特定配置。

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

更多变更

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

项目更新

除了技术层面，v1.2 版本也标志着 Gateway API 项目本身发展过程中的几个里程碑。

发布流程改进

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

• 范围确定（4-6 周）：维护者和社区确定我们希望在版本中包含的功能集。这里的一个特别重点是将功能从 Experimental 渠道中“移出”——理想情况下是将其移至 Standard，但也可能意味着移除它们。

• GEP 迭代与审查（5-7 周）：贡献者为被接纳到版本中的功能编写或更新 Gateway 增强提案（GEP），重点是围绕功能的设计和毕业标准达成共识。

• 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 负责人——令人高兴的是，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，Experimental 渠道
• Envoy Gateway v1.2.0-rc.1，Experimental 渠道
• Istio v1.24.0-alpha.0，Experimental 渠道
• Kong v3.2.0-244-gea4944bb0，Experimental 渠道
• Traefik v3.2，Experimental 渠道

参与其中

有很多机会可以参与进来，帮助定义 Kubernetes 路由 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

• ←上一篇
• 下一篇→