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 特定的规则，用于将流量从 Gateway 监听器映射到后端网络端点的表示。这些端点通常表示为 Service。

Gateway API 被组织成不同的 API 资源类型，这些类型具有相互依赖的关系，以支持组织的面向角色的性质。一个 Gateway 对象与一个且只有一个 GatewayClass 关联；GatewayClass 描述了负责管理此类 Gateway 的网关控制器。一个或多个路由类型（如 HTTPRoute）随后与 Gateway 关联。Gateway 可以过滤可以附加到其 listeners 的路由，形成与路由的双向信任模型。

下图说明了三种稳定的 Gateway API 资源类型之间的关系：

A figure illustrating the relationships of the three stable Gateway API kinds

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 的控制器被配置为管理控制器名称为 example.com/gateway-controller 的 GatewayClass。此类别的 Gateway 将由该实现的控制器管理。

有关此 API 资源类型的完整定义，请参阅 GatewayClass 参考。

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 类型指定了 HTTP 请求从 Gateway 监听器到后端网络端点的路由行为。对于 Service 后端，实现可以将后端网络端点表示为 Service IP 或 Service 的后端 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，将被路由到端口 8080 上的 Service example-svc。

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

请求流

这是一个使用 Gateway 和 HTTPRoute 将 HTTP 流量路由到 Service 的简单示例

A diagram that provides an example of HTTP traffic being routed to a Service by using a Gateway and an HTTPRoute

在此示例中，作为反向代理实现的 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 规范。

最后修改于 2025 年 4 月 9 日太平洋标准时间上午 5:08：更新 Endpoints API 弃用文档 (#49831) (649bda2cbd)