本文已发布一年多。较旧的文章可能包含过时的内容。请检查页面中的信息自发布以来是否已失效。

Gateway API v1.0 中的新实验性功能

作者：Candace Holman (Red Hat)、Dave Protasowski (VMware)、Gaurav K Ghildiyal (Google)、John Howard (Google)、Simone Rodigari (IBM) | 2023 年 11 月 28 日，星期二

最近，Gateway API 宣布了其 v1.0 正式发布，标志着该项目的一个重要里程碑。

除了稳定 API 中的一些核心功能外，还添加了许多令人兴奋的新的实验性功能。

后端 TLS 策略

BackendTLSPolicy 是一种新的 Gateway API 类型，用于通过 Service API 对象指定从网关到后端 Pod 的连接的 TLS 配置。它被指定为直接策略附件，没有默认值或覆盖，应用于访问后端的 Service，其中 BackendTLSPolicy 位于与它所应用的 Service 相同的命名空间中。所有指向引用 Service 的 Gateway API 路由都应遵循配置的 BackendTLSPolicy。

虽然已经提供了配置边缘和直通终止的 TLS 的现有方法，但这个新的 API 对象专门解决了 TLS 的配置，以便将 HTTPS 从网关数据平面传输到后端。这被称为“后端 TLS 终止”，并使网关能够知道如何连接到拥有自己证书的后端 Pod。

Termination Types

BackendTLSPolicy 的规范包括：

targetRef - 定义策略的目标 API 对象。只允许 Service。
tls - 定义 TLS 的配置，包括 hostname、caCertRefs 和 wellKnownCACerts。可以指定 caCertRefs 或 wellKnownCACerts，但不能同时指定两者。
hostname - 定义网关用于连接到后端的服务器名称指示 (SNI)。后端提供的证书必须与此 SNI 匹配。
caCertRefs - 定义一个或多个对包含 PEM 编码 TLS 证书的对象的引用，这些证书用于在网关和后端之间建立 TLS 握手。
wellKnownCACerts - 指定是否可以在网关和后端之间的 TLS 握手中使用系统 CA 证书。

示例

使用系统证书

在此示例中，BackendTLSPolicy 配置为使用系统证书连接 TLS 加密的上游连接，其中支持 dev 服务的 Pod 预计将为 dev.example.com 提供有效证书。

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: BackendTLSPolicy
metadata:
  name: tls-upstream-dev
spec:
  targetRef:
    kind: Service
    name: dev-service
    group: ""
  tls:
    wellKnownCACerts: "System"
    hostname: dev.example.com

使用显式 CA 证书

在此示例中，BackendTLSPolicy 配置为使用配置映射 auth-cert 中定义的证书连接 TLS 加密的上游连接，其中支持 auth 服务的 Pod 预计将为 auth.example.com 提供有效证书。

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: BackendTLSPolicy
metadata:
  name: tls-upstream-auth
spec:
  targetRef:
    kind: Service
    name: auth-service
    group: ""
  tls:
    caCertRefs:
      - kind: ConfigMapReference
        name: auth-cert
        group: ""
    hostname: auth.example.com

以下示意图说明了一个为服务后端配置 TLS 的 BackendTLSPolicy：

flowchart LR client(["client"]) gateway["Gateway"] style gateway fill:#02f,color:#fff httproute["HTTP
Route"] style httproute fill:#02f,color:#fff service["Service"] style service fill:#02f,color:#fff pod1["Pod"] style pod1 fill:#02f,color:#fff pod2["Pod"] style pod2 fill:#02f,color:#fff client -.->|HTTP
request| gateway gateway --> httproute httproute -.->|BackendTLSPolicy|service service --> pod1 & pod2

有关更多信息，请参阅 TLS 文档。

HTTPRoute 超时

Gateway API 最新版本 (v1.0) 的一个关键增强是在 HTTPRoute Rules 中引入了 timeouts 字段。此功能提供了一种动态管理传入 HTTP 请求超时的方法，为您的网关设置增加了精确性和可靠性。

通过超时，开发者可以通过两种基本方式微调其 Gateway API 的行为：

请求超时:
请求超时是网关 API 实现必须向客户端的 HTTP 请求发送响应的持续时间。它提供了在指定此超时何时开始方面的灵活性，可以在接收到整个客户端请求流之前或之后，这使其成为实现特定的。此超时有效地涵盖了整个请求-响应事务，增强了服务的响应能力。
后端请求超时:
backendRequest 超时对于处理后端的人来说是一个游戏规则改变者。它为从网关发送到后端服务的单个请求设置了超时。此超时从请求的启动到从后端接收完整响应为止。此功能在网关需要重试与后端连接的场景中特别有用，确保在各种条件下顺利通信。

值得注意的是，request 超时包含 backendRequest 超时。因此，backendRequest 的值不应超过 request 超时。

配置这些超时的能力为您的 Kubernetes 服务增加了新的可靠性层。无论是确保客户端请求在指定时间内处理，还是管理后端服务通信，Gateway API 的超时都提供了您所需的控制和可预测性。

要开始使用，您可以在 HTTPRoute 规则中使用 Timeouts 字段定义超时，将其类型指定为 Duration。零值超时 (0s) 会禁用超时，而有效的非零值超时应至少为 1 毫秒。

以下是在 HTTPRoute 中设置请求和后端请求超时的示例

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: timeout-example
spec:
  parentRefs:
  - name: example-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /timeout
    timeouts:
      request: 10s
      backendRequest: 2s
    backendRefs:
    - name: timeout-svc
      port: 8080

在此示例中，定义了 10 秒的 request 超时，确保客户端请求在此时间范围内处理。此外，为从网关到名为 timeout-svc 的后端服务的单个请求设置了 2 秒的 backendRequest 超时。

这些新的 HTTPRoute 超时为 Kubernetes 用户提供了更多控制和灵活性来管理网络通信，有助于确保客户端和后端都获得更顺畅、更可预测的体验。有关更多详细信息和示例，请参阅官方超时 API 文档。

网关基础设施标签

虽然 Gateway API 为不同的实现提供了通用的 API，但每个实现都会在底层创建不同的资源来应用用户的意图。这可能包括配置云负载均衡器、创建集群内 Pod 和服务等等。

虽然 API 始终提供了一个扩展点——GatewayClass 中的 parametersRef ——用于自定义特定于实现的事物，但没有一种通用的核心方式来表达常见的基础设施自定义。

Gateway API v1.0 通过 Gateway 对象上的新 infrastructure 字段为此铺平了道路，允许自定义底层基础设施。目前，这从两个关键字段开始：标签和注解。设置这些字段后，任何生成的基础设施都将设置提供的标签和注解。

例如，我可能希望将一个应用程序的所有资源组合在一起

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: hello-world
spec:
  infrastructure:
    labels:
      app.kubernetes.io/name: hello-world

未来，我们正在研究更常见的基础设施配置，例如资源大小。

有关更多信息，请参阅此功能的文档。

支持 Websockets、HTTP/2 等！

并非所有 Gateway API 实现都支持自动协议选择。在某些情况下，如果未明确选择加入，则会禁用协议。

当路由的后端引用 Kubernetes 服务时，应用程序开发人员可以使用 ServicePort appProtocol 字段指定协议。

例如，以下 store Kubernetes 服务表明端口 8080 支持 HTTP/2 Prior Knowledge。

apiVersion: v1
kind: Service
metadata:
  name: store
spec:
  selector:
    app: store
  ports:
  - protocol: TCP
    appProtocol: kubernetes.io/h2c
    port: 8080
    targetPort: 8080

目前，Gateway API 具有以下一致性测试

kubernetes.io/h2c - HTTP/2 Prior Knowledge
kubernetes.io/ws - WebSocket over HTTP

有关更多信息，请参阅后端协议选择的文档。

`gwctl`，我们新的 Gateway API 命令行工具

gwctl 是一个命令行工具，旨在替代 kubectl 以查看 Gateway API 资源。

与 Gateway v1.0 版本捆绑在一起的 gwctl 的初始版本包含用于管理 Gateway API 策略的有用功能。Gateway API 策略作为强大的扩展机制，用于修改 Gateway 资源的行为。使用策略的一个挑战是可能很难发现哪些策略正在影响哪些 Gateway 资源。gwctl 通过回答以下问题来帮助弥合这一差距：

Kubernetes 集群中有哪些策略可用？
哪些策略附加到特定的网关、HTTPRoute 等？
如果策略应用于 Gateway 资源层次结构中的多个资源，那么影响特定资源的有效策略是什么？（例如，如果 HTTP 请求超时策略同时应用于 HTTPRoute 及其父 Gateway，则 HTTPRoute 的有效超时是多少？）

gwctl 仍处于开发的早期阶段，因此可能有些粗糙。请按照存储库中的说明安装并试用 gwctl。

示例

以下是一些如何使用 gwctl 的示例

# List all policies in the cluster. This will also give the resource they bind
# to.
gwctl get policies -A
# List all available policy types.
gwctl get policycrds
# Describe all HTTPRoutes in namespace ns2. (Output includes effective policies)
gwctl describe httproutes -n ns2
# Describe a single HTTPRoute in the default namespace. (Output includes
# effective policies)
gwctl describe httproutes my-httproute-1
# Describe all Gateways across all namespaces. (Output includes effective
# policies)
gwctl describe gateways -A
# Describe a single GatewayClass. (Output includes effective policies)
gwctl describe gatewayclasses foo-com-external-gateway-class

参与进来

这些项目以及更多项目正在 Gateway API 中不断改进。有很多机会可以参与进来，帮助定义 Kubernetes 入口和网格路由 API 的未来。

如果您对此感兴趣，请加入我们的社区，帮助我们共同构建 Gateway API 的未来！