Gateway API

Gateway API

网关（Gateway）API 是一组 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 的规则，用于将流量从网关监听器映射到后端网络端点的表示。这些端点通常表示为 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
spec:
  gatewayClassName: example-class
  listeners:
  - name: http
    protocol: HTTP
    port: 80

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

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

HTTPRoute

HTTPRoute 类别指定从 Gateway 监听器到后端网络端点的 HTTP 请求的路由行为。对于服务后端，实现可以将后端网络端点表示为服务 IP 或服务的支持端点。 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。

请求数据流

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

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

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

标准合规性

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 规范。