API 概述

本文档概述了网关 API。

角色和角色

网关 API 中有 3 个主要角色，如 角色和角色 中所述。

• Ian（他/他）：基础设施提供商
• Chihiro（他们/他们）：集群操作员
• Ana（她/她）：应用程序开发者

资源模型

注意

网关 API 资源位于 gateway.networking.k8s.io API 组中，作为自定义资源定义 (CRD)。下面未限定的资源名称将隐式地位于此 API 组中。

我们的资源模型中有三种主要类型的对象

GatewayClass 定义了一组具有通用配置和行为的网关。

网关 请求一个点，在该点处可以将流量转换为集群内的服务。

路由 描述了通过网关传入的流量如何映射到服务。

GatewayClass

自 v0.5.0 以来为标准频道

GatewayClass 资源是 GA，并且自 v0.5.0 以来一直是标准频道的一部分。有关发布频道的更多信息，请参阅我们的 版本控制指南。

GatewayClass 定义了一组共享通用配置和行为的网关。每个 GatewayClass 将由一个控制器处理，尽管控制器可以处理多个 GatewayClass。

GatewayClass 是一个集群范围的资源。必须定义至少一个 GatewayClass 才能拥有功能齐全的网关。实现网关 API 的控制器通过提供与用户可以从其网关(s)中引用的相关 GatewayClass 资源来实现这一点。

这类似于 IngressClass 用于 Ingress 和 StorageClass 用于 PersistentVolumes。在 Ingress v1beta1 中，与 GatewayClass 最相似的类似物是 ingress-class 注释，而在 IngressV1 中，最相似的类似物是 IngressClass 对象。

网关

自 v0.5.0 以来为标准频道

Gateway 资源是 GA，并且自 v0.5.0 以来一直是标准频道的一部分。有关发布频道的更多信息，请参阅我们的 版本控制指南。

网关描述了如何将流量转换为集群内的服务。也就是说，它定义了一个请求，该请求用于将流量从不知道 Kubernetes 的地方转换为知道 Kubernetes 的地方。例如，由云负载均衡器、集群内代理或外部硬件负载均衡器发送到 Kubernetes 服务的流量。虽然许多用例都有来自集群“外部”的客户端流量，但这并不是必需的。

它定义了对实现 GatewayClass 的配置和行为契约的特定负载均衡器配置的请求。该资源可以由操作员直接创建，也可以由处理 GatewayClass 的控制器创建。

由于网关规范捕获了用户意图，因此它可能不包含规范中所有属性的完整规范。例如，用户可以省略地址、TLS 设置等字段。这允许管理 GatewayClass 的控制器为用户提供这些设置，从而产生更便携的规范。这种行为将使用 GatewayClass 状态对象明确表示。

网关可以附加到一个或多个路由引用，这些引用用于将流量的子集定向到特定服务。

路由资源

路由资源定义了将来自网关的请求映射到 Kubernetes 服务的协议特定规则。

从 v1alpha2 开始，API 包含四种路由资源类型。鼓励使用特定于实现的自定义路由类型来处理其他协议。将来可能会在 API 中添加新的路由类型。

HTTPRoute

自 v0.5.0 以来为标准频道

HTTPRoute 资源是 GA，并且自 v0.5.0 以来一直是标准频道的一部分。有关发布频道的更多信息，请参阅我们的 版本控制指南。

HTTPRoute 用于多路复用 HTTP 或已终止的 HTTPS 连接。它适用于您想要检查 HTTP 流并使用 HTTP 请求数据进行路由或修改的情况，例如使用 HTTP 标头进行路由，或在飞行过程中对其进行修改。

TLSRoute

自 v0.3.0 以来为实验频道

TLSRoute 资源是 Alpha，并且自 v0.3.0 以来一直是实验频道的一部分。有关发布频道的更多信息，请参阅我们的 版本控制指南。

TLSRoute 用于多路复用 TLS 连接，通过 SNI 进行区分。它适用于您想要将 SNI 作为主要路由方法，并且对更高层协议（如 HTTP）的属性不感兴趣的情况。连接的字节流在没有检查的情况下被代理到后端。

TCPRoute 和 UDPRoute

自 v0.3.0 以来为实验频道

TCPRoute 和 UDPRoute 资源是 Alpha，并且自 v0.3.0 以来一直是实验频道的一部分。有关发布频道的更多信息，请参阅我们的 版本控制指南。

TCPRoute（和 UDPRoute）用于将一个或多个端口映射到单个后端。在这种情况下，您没有可以用于在同一端口上选择不同后端的区分符，因此每个 TCPRoute 实际上都需要监听器上的一个不同端口（一般情况下）。您可以终止 TLS，在这种情况下，未加密的字节流将通过传递到后端。您可以选择不终止 TLS，在这种情况下，加密的字节流将通过传递到后端。

GRPCRoute

自 v1.1.0 以来为标准频道

GRPCRoute 资源是 GA，并且自 v1.1.0 以来一直是标准频道的一部分。有关发布频道的更多信息，请参阅我们的 版本控制指南。

GRPCRoute 用于以惯用方式路由 gRPC 流量。支持 GRPCRoute 的网关需要支持 HTTP/2，而无需从 HTTP/1 进行初始升级，因此 gRPC 流量将得到保证以正确流动。

路由摘要表

下面的“路由鉴别器”列指的是什么信息可以用来允许多个路由共享监听器上的端口。

对象	OSI 层	路由鉴别器	TLS 支持	目的
HTTPRoute	第 7 层	HTTP 协议中的任何内容	仅终止	HTTP 和 HTTPS 路由
TLSRoute	第 4 层和第 7 层之间	SNI 或其他 TLS 属性	直通或终止	TLS 协议的路由，包括 HTTPS，其中不需要检查 HTTP 流。
TCPRoute	第 4 层	目标端口	直通或终止	允许将 TCP 流从监听器转发到后端。
UDPRoute	第 4 层	目标端口	无	允许将 UDP 流从监听器转发到后端。
GRPCRoute	第 7 层	gRPC 协议中的任何内容	仅终止	通过 HTTP/2 和 HTTP/2 明文进行的 gRPC 路由

请注意，通过 HTTPRoute 和 TCPRoute 路由的流量可以在网关和后端之间加密（通常称为重新加密）。无法使用现有的网关 API 资源来配置它，但实现可能会为此提供自定义配置，直到网关 API 定义标准化方法为止。

将路由附加到网关

当路由附加到网关时，它代表应用于网关的配置，该配置配置底层负载均衡器或代理。路由如何以及哪些路由附加到网关由资源本身控制。路由和网关资源具有内置控件来允许或约束它们如何附加。结合 Kubernetes RBAC，这些允许组织强制执行有关如何公开路由以及在哪些网关上公开路由的策略。

路由附加到网关的方式有很多灵活性，可以实现不同的组织策略和责任范围。以下是网关和路由可以具有的不同关系

• 一对一 - 网关和路由可能由单个所有者部署和使用，并且具有一对一关系。
• 一对多 - 网关可以绑定多个路由，这些路由由来自不同命名空间的不同团队拥有。
• 多对一 - 路由也可以绑定到多个网关，允许单个路由同时跨不同 IP、负载均衡器或网络控制应用程序公开。

示例

千寻 在 infra 命名空间中部署了一个名为 shared-gw 的网关，供不同的应用程序团队用来将其应用程序暴露在集群外部。团队 A 和团队 B（分别位于 A 和 B 命名空间中）将其路由附加到此网关。他们彼此不知情，只要他们的路由规则不冲突，他们就可以继续独立运行。团队 C 具有特殊的网络需求（可能是性能、安全或关键性），他们需要一个专用的网关来将其应用程序代理到外部世界。团队 C 在 C 命名空间中部署了自己的网关 dedicated-gw，该网关只能由 C 命名空间中的应用程序使用。

工作原理

以下内容是将路由附加到网关所需的。

1. 路由需要在其 parentRefs 字段中包含引用网关的条目。
2. 网关上的至少一个监听器需要允许这种附加。

引用网关

实验频道

下面描述的 Port 字段目前仅包含在网关 API 的“实验”频道中。有关发布频道的更多信息，请参阅相关文档。

路由可以通过在 parentRef 中指定网关的命名空间（如果路由和网关在同一个命名空间中，则可选）和名称来引用网关。默认情况下，路由将附加到网关的所有监听器，但是它可以使用 parentRef 中的以下字段将选择限制为监听器子集

1. SectionName 当设置 sectionName 时，路由会选择具有指定名称的监听器。
2. Port 当设置 port 时，路由会选择所有监听指定端口并与这种路由类型兼容的协议的监听器。

当 parentRef 中设置了多个字段时，路由会选择满足这些字段中指定的所有条件的监听器。例如，当同时设置了 sectionName 和 port 时，路由会选择具有指定名称并监听指定端口的监听器。

限制路由附加

每个网关监听器可以使用以下机制来限制哪些路由可以附加

1. Hostname: 当监听器上的 hostname 字段设置时，附加的路由指定 hostnames 字段必须至少具有一个重叠的值。
2. Namespaces: 监听器上的 allowedRoutes.namespaces 字段可用于限制路由的附加位置。namespaces.from 字段支持以下值
   • Same 是默认选项。只有与该网关位于同一命名空间中的路由才能附加。
   • All 将允许来自所有命名空间的路由附加。
   • Selector 表示来自由命名空间标签选择器选择的命名空间子集的路由可以附加到该网关。当使用 Selector 时，必须使用 namespaces.selector 字段来指定标签选择器。此字段不支持 All 或 Same。
3. Kinds: 监听器上的 allowedRoutes.kinds 字段可用于限制可能附加的路由类型。

如果没有指定上述任何内容，网关监听器将信任来自同一命名空间并支持监听器协议的路由。

更多网关 - 路由附加示例

以下 my-route 路由希望附加到 gateway-api-example-ns1 中的 foo-gateway，并且不会附加到任何其他网关。请注意，foo-gateway 位于不同的命名空间。foo-gateway 必须允许来自 gateway-api-example-ns2 命名空间中的 HTTPRoute 的附加。

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-route
  namespace: gateway-api-example-ns2
spec:
  parentRefs:
  - kind: Gateway
    name: foo-gateway
    namespace: gateway-api-example-ns1
  rules:
  - backendRefs:
    - name: foo-svc
      port: 8080

此 foo-gateway 允许 my-route HTTPRoute 附加。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: foo-gateway
  namespace: gateway-api-example-ns1
spec:
  gatewayClassName: foo-lb
  listeners:
  - name: prod-web
    port: 80
    protocol: HTTP
    allowedRoutes:
      kinds:
      - kind: HTTPRoute
      namespaces:
        from: Selector
        selector:
          matchLabels:
            # This label is added automatically as of K8s 1.22
            # to all namespaces
            kubernetes.io/metadata.name: gateway-api-example-ns2

为了提供更宽松的示例，以下网关将允许所有 HTTPRoute 资源从具有“expose-apps: true”标签的命名空间附加。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-gateway
  namespace: gateway-api-example-ns1
spec:
  gatewayClassName: foo-lb
  listeners:
  - name: prod-web
    port: 80
    protocol: HTTP
    allowedRoutes:
      kinds:
      - kind: HTTPRoute
      namespaces:
        from: Selector
        selector:
          matchLabels:
            expose-apps: "true"

组合类型

GatewayClass、Gateway、xRoute 和 Service（s）的组合定义了一个可实现的负载均衡器。下图说明了不同资源之间的关系

请求流

使用反向代理实现的网关的典型南北 API 请求流如下

1. 客户端向http://foo.example.com发出请求。
2. DNS 将名称解析为 Gateway 地址。
3. 反向代理在 Listener 上接收请求，并使用Host 标头来匹配 HTTPRoute。
4. 可选地，反向代理可以根据 HTTPRoute 的 match 规则执行请求标头和/或路径匹配。
5. 可选地，反向代理可以修改请求，例如添加/删除标头，这基于 HTTPRoute 的 filter 规则。
6. 最后，反向代理根据 HTTPRoute 的 backendRefs 规则将请求转发到集群中的一个或多个对象，例如 Service。

TLS 配置

TLS 在网关监听器上配置，并且可以跨命名空间引用。

有关 TLS 的深入了解，请参阅TLS 详细信息指南。

将路由附加到服务

当使用网关 API 配置服务网格时，路由将直接附加到服务，代表应应用于定向到该服务的任何流量的配置。路由如何以及哪些路由附加到给定服务由路由本身控制（与 Kubernetes RBAC 协同工作），如GAMMA 路由文档中所述。

扩展点

API 中提供了一些扩展点，以灵活地解决通用 API 无法解决的大量用例。

以下是 API 中扩展点的摘要

• BackendRefs: 此扩展点应用于将流量转发到除核心 Kubernetes Service 资源以外的网络端点。示例包括 S3 存储桶、Lambda 函数、文件服务器等。
• HTTPRouteFilter: HTTPRoute 中的此 API 类型提供了一种方法来挂钩到 HTTP 请求的请求/响应生命周期。
• 自定义路由: 如果上述扩展点都不足以满足用例，实现者可以选择创建针对 API 目前不支持的协议的自定义路由资源。自定义路由类型需要共享与核心路由类型相同的字段。这些包含在 CommonRouteSpec 和 RouteStatus 中。

在使用没有先例的扩展点时，请告知社区。随着我们了解有关扩展点使用情况的更多信息，我们希望找到共同点并将功能提升到核心/扩展 API 符合性。