Gateway API

Gateway API 通过使用可扩展的、角色导向的、协议感知的配置机制来提供网络服务。它是一个附加组件，包含可提供动态基础设施配置和高级流量路由的API 类别。

设计原则

Gateway API 的设计和架构遵从以下原则：

• 角色导向： Gateway API 类别是基于负责管理 Kubernetes 服务网络的组织角色建模的：
  • 基础设施提供者： 管理使用多个独立集群为多个租户提供服务的基础设施，例如，云提供商。
  • 集群操作员： 管理集群，通常关注策略、网络访问、应用程序权限等。
  • 应用程序开发人员： 管理在集群中运行的应用程序，通常关注应用程序级配置和Service 组合。

• 可移植： Gateway API 规范用自定义资源来定义，并受到许多实现的支持。
• 表达能力强： Gateway API 类别支持常见流量路由场景的功能，例如基于标头的匹配、流量加权以及其他只能在Ingress 中使用自定义注解才能实现的功能。
• 可扩展的： Gateway 允许在 API 的各个层链接自定义资源。这使得在 API 结构内的适当位置进行精细定制成为可能。

资源模型

Gateway API 具有四种稳定的 API 类别：

• GatewayClass： 定义一组具有配置相同的网关，由实现该类的控制器管理。

• Gateway： 定义流量处理基础设施（例如云负载均衡器）的一个实例。

• HTTPRoute： 定义特定于 HTTP 的规则，用于将流量从 Gateway 监听器映射到后端网络端点的某种呈现。这些端点通常表示为 Service。

• GRPCRoute： 定义特定于 gRPC 的规则，用于将流量从 Gateway 监听器映射到后端网络端点的某种呈现。这些端点通常表示为 Service。

Gateway API 被组织成不同的 API 类别，这些 API 类别具有相互依赖的关系，以支持组织中角色导向的特点。一个 Gateway 对象只能与一个 GatewayClass 相关联；GatewayClass 描述负责管理此类 Gateway 的网关控制器。各个（可以是多个）路由类别（例如 HTTPRoute）可以关联到此 Gateway 对象。Gateway 可以对能够挂接到其 listeners 的路由进行过滤，从而与路由形成双向信任模型。

下图说明这三个稳定的 Gateway API 类别之间的关系：

GatewayClass

Gateway 可以由不同的控制器实现，通常具有不同的配置。Gateway 必须引用某 GatewayClass，而后者中包含实现该类的控制器的名称。

下面是一个最精简的 GatewayClass 示例：

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: example-class
spec:
  controllerName: example.com/gateway-controller

在此示例中，一个实现了 Gateway API 的控制器被配置为管理某些 GatewayClass 对象，这些对象的控制器名为 example.com/gateway-controller。归属于此类的 Gateway 对象将由此实现的控制器来管理。

有关此 API 类别的完整定义，请参阅GatewayClass。

Gateway

Gateway 用来描述流量处理基础设施的一个实例。Gateway 定义了一个网络端点，该端点可用于处理流量，即对 Service 等后端进行过滤、平衡、拆分等。例如，Gateway 可以代表某个云负载均衡器，或配置为接受 HTTP 流量的集群内代理服务器。

下面是一个典型的 Gateway 资源示例：

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
  namespace: example-namespace
spec:
  gatewayClassName: example-class
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    hostname: "www.example.com"
    allowedRoutes:
      namespaces:
        from: Same

在此示例中，流量处理基础设施的实例被编程为监听 80 端口上的 HTTP 流量。由于未指定 addresses 字段，因此对应实现的控制器负责将地址或主机名设置到 Gateway 之上。该地址用作网络端点，用于处理路由中定义的后端网络端点的流量。

有关此类 API 的完整定义，请参阅 Gateway。

HTTPRoute

HTTPRoute 类别指定从 Gateway 监听器到后端网络端点的 HTTP 请求的路由行为。对于服务后端，实现可以将后端网络端点表示为服务 IP 或服务的支持 EndpointSlices。HTTPRoute 表示将被应用到下层 Gateway 实现的配置。例如，定义新的 HTTPRoute 可能会导致在云负载均衡器或集群内代理服务器中配置额外的流量路由。

下面是一个最典型的 HTTPRoute 示例：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: example-httproute
spec:
  parentRefs:
  - name: example-gateway
  hostnames:
  - "www.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /login
    backendRefs:
    - name: example-svc
      port: 8080

在此示例中，来自 Gateway example-gateway 的 HTTP 流量，如果 Host: 的标头设置为 www.example.com 且请求路径指定为 /login，将被路由到 Service example-svc 的 8080 端口。

有关此类 API 的完整定义，请参阅HTTPRoute。

GRPCRoute

GRPCRoute 类别给出将 gRPC 请求从 Gateway 监听器转发到后端网络端点的路由行为。对于 Service 后端，其中一种实现方式可以将后端网络端点表示为 Service IP，或支撑此 Service 的若干 EndpointSlice。GRPCRoute 表示的是一些要应用于底层 Gateway 实现的配置。例如，定义一个新的 GRPCRoute 的操作可能会意味着要在云负载均衡器或集群内代理服务器中配置额外的流量路由。

支持 GRPCRoute 的 Gateway 必须支持 HTTP/2，且无需从 HTTP/1 升级，以确保 gRPC 流量能够正常传输。

以下是一个典型的 GRPCRoute 示例：

apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: example-grpcroute
spec:
  parentRefs:
  - name: example-gateway
  hostnames:
  - "svc.example.com"
  rules:
  - backendRefs:
    - name: example-svc
      port: 50051

在此示例中，来自 Gateway example-gateway 且主机设置为 svc.example.com 的 gRPC流量将被定向到同一名字空间中 example-svc 服务的 50051 端口上。

GRPCRoute 允许匹配特定的 gRPC 服务，如下所示：

apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: example-grpcroute
spec:
  parentRefs:
  - name: example-gateway
  hostnames:
  - "svc.example.com"
  rules:
  - matches:
    - method:
        service: com.example
        method: Login
    backendRefs:
    - name: foo-svc
      port: 50051

在这种情况下，GRPCRoute 将匹配发往 svc.example.com 的所有流量，并应用其路由规则将流量转发到正确的后端。由于仅指定了一个匹配条件，只有发往svc.example.com 的 com.example.User.Login 方法请求会被转发。其他请求方法的 RPC 调用都不会被此路由匹配。

有关这种 API 类别的完整定义，请参阅GRPCRoute 参考文档。

请求数据流

以下是使用 Gateway 和 HTTPRoute 将 HTTP 流量路由到服务的简单示例：

在此示例中，实现为反向代理的 Gateway 的请求数据流如下：

1. 客户端开始准备 URL 为 http://www.example.com 的 HTTP 请求。
2. 客户端的 DNS 解析器查询目标名称并了解与 Gateway 关联的一个或多个 IP 地址的映射。
3. 客户端向 Gateway IP 地址发送请求；反向代理接收 HTTP 请求并使用 Host: 标头来匹配基于 Gateway 和附加的 HTTPRoute 所获得的配置。
4. 可选的，反向代理可以根据 HTTPRoute 的匹配规则进行请求头和（或）路径匹配。
5. 可选地，反向代理可以修改请求；例如，根据 HTTPRoute 的过滤规则添加或删除标头。
6. 最后，反向代理将请求转发到一个或多个后端。

标准合规性

Gateway API 涵盖广泛的功能并得到广泛实现。这种组合需要明确的标准合规性定义和测试，以确保 API 在任何地方使用时都能提供一致的体验。

请参阅合规性相关的文档，以了解发布渠道、支持级别和运行合规性测试等详细信息。

从 Ingress 迁移

Gateway API 是 Ingress API 的后继者。但是其中不包括 Ingress 类型。因此，需要将现有 Ingress 资源一次性转换为 Gateway API 资源。

有关将 Ingress 资源迁移到 Gateway API 资源的详细信息，请参阅Ingress 迁移指南。

接下来

Gateway API 资源不是由 Kubernetes 原生实现的，而是被定义为受广泛实现支持的自定义资源。用户需要安装 Gateway API CRD或按照所选实现的安装说明进行操作。安装完成后，使用入门指南来帮助你快速开始使用 Gateway API。

有关所有 Gateway API 类型的其他详细信息，请参阅 API 规范。