这篇文章已发布一年多。较早的文章可能包含过时内容。请检查页面中的信息自发布以来是否已发生变化。

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 GA 版本发布，标志着该项目的一个重要里程碑。

在稳定 API 的一些核心功能的同时，还增加了一些令人兴奋的新的实验性功能。

后端 TLS 策略

BackendTLSPolicy 是一种新的 Gateway API 类型，用于指定从 Gateway 到后端 Pods 通过 Service API 对象的 TLS 连接配置。它被指定为 Direct PolicyAttachment，没有默认值或覆盖，应用于访问后端的 Service，BackendTLSPolicy 位于与其应用的 Service 相同的命名空间中。所有指向引用 Service 的 Gateway API Route 都应遵守配置的 BackendTLSPolicy。

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

Termination Types

BackendTLSPolicy 的规范包括：

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

示例

使用系统证书

在此示例中，BackendTLSPolicy 配置为使用系统证书连接 TLS 加密的上游连接，其中支持 dev Service 的 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 Service 的 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 的行为：

请求超时:
请求超时是指 Gateway API 实现必须在多长时间内向客户端的 HTTP 请求发送响应。它允许灵活地指定此超时何时开始，可以在接收到整个客户端请求流之前或之后，这取决于具体实现。此超时有效地涵盖了整个请求-响应事务，提高了服务的响应能力。
后端请求超时:
backendRequest 超时对于处理后端的人来说是一项重大改进。它设置了 Gateway 发送到后端服务的单个请求的超时时间。此超时从请求开始到接收到后端完整响应为止。此功能在 Gateway 需要重试连接到后端的情况下特别有用，可确保在各种条件下顺畅通信。

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

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

要开始使用，你可以在 HTTPRoute Rules 中使用 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 超时，确保客户端请求在该时间范围内处理。此外，还为从 Gateway 到名为 timeout-svc 的后端服务的单个请求设置了 2 秒的 backendRequest 超时。

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

网关基础设施标签

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

虽然 API 一直通过 GatewayClass 中的扩展点 -- parametersRef -- 来定制实现特定的内容，但一直没有一种通用的核心方式来表达常见的基础设施定制。

Gateway API v1.0 通过在 Gateway 对象上新增一个 infrastructure 字段为实现这一目标铺平了道路，允许定制底层基础设施。目前，这从两个关键字段开始：labels 和 annotations。设置这些字段后，任何生成的基础设施都将应用提供的 labels 和 annotations。

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

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 实现都支持自动协议选择。在某些情况下，协议在未明确选择加入的情况下会被禁用。

当 Route 的后端引用 Kubernetes Service 时，应用开发者可以使用 ServicePort 的 appProtocol 字段指定协议。

例如，以下 store Kubernetes Service 表示端口 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 - 基于 HTTP 的 WebSocket

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

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

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

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

Kubernetes 集群中哪些策略可用？
特定 Gateway、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 中不断改进。有很多机会可以参与进来，共同定义用于 Ingress 和 Mesh 的 Kubernetes 路由 API 的未来。

如果您对此感兴趣，请加入我们的社区，与我们一起建设 Gateway API 的未来！