API 规范

此页面包含网关 API 的 API 字段规范。

包

• gateway.networking.k8s.io/v1
• gateway.networking.k8s.io/v1beta1
• gateway.networking.k8s.io/v1alpha3
• gateway.networking.k8s.io/v1alpha2

gateway.networking.k8s.io/v1

包 v1 包含 gateway.networking.k8s.io API 组的 API 架构定义。

资源类型

• GRPCRoute
• 网关
• 网关类
• HTTPRoute

GRPCRoute

GRPCRoute 提供了一种路由 gRPC 请求的方法。这包括根据主机名、gRPC 服务、gRPC 方法或 HTTP/2 标头匹配请求的功能。过滤器可用于指定其他处理步骤。后端指定匹配请求将被路由到的位置。

GRPCRoute 在网关 API 中属于扩展支持。在以下规范中，单词“必须”表示支持 GRPCRoute 的实现必须符合所指示的要求，但不支持此路由类型的实现不需要遵循此要求，除非明确指示。

支持 GRPCRoute 和 HTTPS ProtocolType 的实现必须接受 HTTP/2 连接，而无需来自 HTTP/1.1 的初始升级，即通过 ALPN。如果实现不支持此操作，则必须将受影响的监听器的“Accepted”条件设置为“False”，原因是“UnsupportedProtocol”。实现也可以接受来自 HTTP/1 的升级的 HTTP/2 连接。

支持 GRPCRoute 和 HTTP ProtocolType 的实现必须支持明文 TCP 上的 HTTP/2（h2c，https://www.rfc-editor.org/rfc/rfc7540#section-3.1)，而无需来自 HTTP/1.1 的初始升级，即通过先验知识 (https://www.rfc-editor.org/rfc/rfc7540#section-3.4)。如果实现不支持此操作，则必须将受影响的监听器的“Accepted”条件设置为“False”，原因是“UnsupportedProtocol”。实现也可以接受来自 HTTP/1 的升级的 HTTP/2 连接，即没有先验知识。

字段	描述
apiVersion 字符串	gateway.networking.k8s.io/v1
kind 字符串	GRPCRoute
metadata Kubernetes meta/v1.ObjectMeta	有关 metadata 字段的字段，请参考 Kubernetes API 文档。
spec GRPCRouteSpec	Spec 定义了 GRPCRoute 的期望状态。 CommonRouteSpec CommonRouteSpec (CommonRouteSpec 的成员嵌入到此类型中。) hostnames []Hostname (可选) Hostnames 定义了一组主机名，以匹配 GRPC Host 标头以选择 GRPCRoute 来处理请求。这与 RFC 1123 中主机名的定义相匹配，但有两个显著例外 不允许使用 IP。 主机名可以以通配符标签 (*.) 为前缀。通配符标签必须单独出现在第一个标签中。 如果监听器和 GRPCRoute 都指定了主机名，则必须至少有一个相交的主机名，GRPCRoute 才能附加到监听器。例如 具有 test.example.com 作为主机名的监听器匹配没有指定任何主机名或至少指定了 test.example.com 或 *.example.com 之一的 GRPCRoute。 具有 *.example.com 作为主机名的监听器匹配没有指定任何主机名或至少指定了一个与监听器主机名匹配的主机名的 GRPCRoute。例如，test.example.com 和 *.example.com 都将匹配。另一方面，example.com 和 test.example.net 将不匹配。 以通配符标签 (*.) 为前缀的主机名被解释为后缀匹配。这意味着，与 *.example.com 的匹配将同时匹配 test.example.com 和 foo.test.example.com，但不匹配 example.com。 如果监听器和 GRPCRoute 都指定了主机名，则任何与监听器主机名不匹配的 GRPCRoute 主机名都必须被忽略。例如，如果监听器指定了 *.example.com，而 GRPCRoute 指定了 test.example.com 和 test.example.net，则 test.example.net 必须不被视为匹配。 如果监听器和 GRPCRoute 都指定了主机名，并且没有任何一个满足上述条件，则 GRPCRoute 必须不被实现接受。实现必须在相应的 RouteParentStatus 中引发状态为 False 的“Accepted”条件。 如果 HTTPRoute 或 GRPCRoute 类型的路由 (A) 附加到监听器，而该监听器已经附加了其他类型的路由 (B)，并且 A 和 B 的主机名的交集不为空，则实现必须根据以下条件（按顺序）准确地接受这两个路由中的一个： 根据创建时间最老的路由。 按“{namespace}/{name}”字母顺序排列时，第一个出现的路由。 被拒绝的路由必须在相应的 RouteParentStatus 中引发状态为“False”的“Accepted”条件。 支持：核心 rules []GRPCRouteRule (可选) 规则是 gRPC 匹配器、过滤器和操作的列表。
status GRPCRouteStatus	Status 定义了 GRPCRoute 的当前状态。

网关

Gateway 表示通过将监听器绑定到一组 IP 地址的服务流量处理基础设施的实例。

字段	描述
apiVersion 字符串	gateway.networking.k8s.io/v1
kind 字符串	网关
metadata Kubernetes meta/v1.ObjectMeta	有关 metadata 字段的字段，请参考 Kubernetes API 文档。
spec GatewaySpec	Spec 定义了 Gateway 的期望状态。 gatewayClassName ObjectName 此 Gateway 使用的 GatewayClassName。这是 GatewayClass 资源的名称。 listeners []Listener 与此 Gateway 关联的监听器。监听器定义在此 Gateway 的地址上绑定的逻辑端点。必须至少指定一个监听器。 一组监听器中的每个监听器（例如，单个 Gateway 中的监听器）必须是不同的，因为流量流必须能够分配给正好一个监听器。（本节使用“一组监听器”而不是“单个 Gateway 中的监听器”，因为实现可能会将来自多个 Gateway 的配置合并到单个数据平面，这些规则也适用于这种情况）。 实际上，这意味着一组中的每个监听器必须具有端口、协议和（如果协议支持）主机名的唯一组合。 某些端口、协议和 TLS 设置的组合被认为是核心支持，并且必须由实现根据其目标一致性配置文件来支持 HTTP 配置文件 HTTPRoute，端口：80，协议：HTTP HTTPRoute，端口：443，协议：HTTPS，TLS 模式：终止，TLS 密钥对提供 TLS 配置文件 TLSRoute，端口：443，协议：TLS，TLS 模式：直通 “不同的”监听器具有以下属性 实现可以将入站请求匹配到单个不同的监听器。当多个监听器共享字段值（例如，两个具有相同 Port 值的监听器）时，实现可以使用其他监听器字段将请求匹配到这些监听器中的一个。 例如，以下监听器场景是不同的 具有相同 Port 的多个监听器，它们都使用“HTTP”协议，并且它们都具有唯一的主机名值。 多个使用“HTTPS”或“TLS”协议并具有相同端口的监听器，它们都具有唯一的主机名值。 混合使用“TCP”和“UDP”协议监听器，其中没有使用相同协议的监听器具有相同的端口值。 Listener 结构体中的一些字段可能具有影响 Listener 是否不同的值。主机名对于 HTTP 或 HTTPS 协议尤其重要。 当使用主机名值在具有相同端口和相同协议的 Listener 之间进行选择时，每个 Listener 上的主机名值必须不同，才能使 Listener 不同。 当 Listener 基于主机名不同时，入站请求主机名必须从最具体到最不具体的主机名值匹配，以选择正确的 Listener 及其关联的路由集。 精确匹配必须在通配符匹配之前处理，通配符匹配必须在回退（空主机名值）匹配之前处理。例如，"foo.example.com" 优先于 "*.example.com"，"*.example.com" 优先于 ""。 此外，如果存在多个通配符条目，则必须在处理较不具体的通配符条目之前处理更具体的通配符条目。例如，"*.foo.example.com" 优先于 "*.example.com"。这里的精确定义是，通配符字符右侧主机名中点的数量越多，优先级越高。 通配符字符将匹配左侧的任何数量的字符和点，因此 "*.example.com" 将匹配 "foo.bar.example.com" 和 "bar.example.com"。 如果一组 Listener 包含不不同的 Listener，则这些 Listener 发生冲突，实现必须将 Listener 状态中的“冲突”条件设置为“True”。 实现可以选择仅在它们仅接受不包含任何冲突 Listener 的部分 Listener 集时接受具有某些冲突 Listener 的网关。换句话说，实现可能只在它们丢弃所有冲突 Listener 时才接受部分 Listener 集。不选择冲突 Listener 中的任何一个作为获胜者。这也意味着网关在这种情况下必须至少有一个非冲突 Listener，否则它违反了必须至少存在一个 Listener 的要求。 当网关包含冲突 Listener 时，无论它们是否接受网关，实现都必须在网关状态上设置“ListenersNotValid”条件。该条件应在消息中清楚地指示哪些 Listener 发生冲突，以及哪些被接受。此外，这些 Listener 的 Listener 状态应指示哪些 Listener 发生冲突且未被接受。 网关的 Listener 被认为是“兼容”的，如果 它们是不同的。 实现可以在遵守所有 Listener 都在所有分配的地址上可用的地址要求的情况下为它们提供服务。 扩展支持中的兼容组合预计会在不同实现之间有所不同。对于一个实现兼容的组合可能对于另一个实现不兼容。 例如，一个实现无法在同一地址上同时提供 TCP 和 UDP 监听器，或者无法在同一端口上混合使用 HTTPS 和通用 TLS 监听器，则不会认为这些情况是兼容的，即使它们是不同的。 请注意，请求应最多匹配一个 Listener。例如，如果为“foo.example.com”和“*.example.com”定义了 Listener，则对“foo.example.com”的请求应仅使用附加到“foo.example.com” Listener 的路由进行路由（而不是“*.example.com” Listener）。这个概念被称为“Listener 隔离”。不支持 Listener 隔离的实现必须明确记录这一点。 实现可以将单独的网关合并到一组地址上，如果所有网关中的所有 Listener 都是兼容的。 支持：核心 地址 []网关地址 (可选) 为该网关请求的地址。这是可选的，行为可能取决于实现。如果在规范中设置了一个值，并且请求的地址无效或不可用，则实现必须在 GatewayStatus.Addresses 中的关联条目中指示这一点。 地址字段表示对“网关外部”地址的请求，绑定到该网关的流量将使用这些地址。这可能是外部负载均衡器或其他网络基础设施的 IP 地址或主机名，或者流量将发送到的其他地址。 如果未指定任何地址，则实现可能会以实现特定方式调度网关，并分配一组适当的地址。 实现必须将所有 Listener 绑定到它分配给网关的每个 GatewayAddress，并在 GatewayStatus.Addresses 中添加一个相应的条目。 支持：扩展 网关：验证 IP 地址 基础设施 网关基础设施 (可选) 基础设施定义了有关此网关实例的基础设施级别属性。 支持：核心 网关：实验性
status 网关状态	状态定义了网关的当前状态。

网关类

网关类描述了用户可用于创建网关资源的网关类。

建议将此资源用作网关的模板。这意味着网关基于创建网关时网关类的状态，对网关类或关联参数的更改不会传播到现有网关。此建议旨在限制对网关类或关联参数的更改的爆炸半径。如果实现选择将网关类更改传播到现有网关，则实现必须明确记录这一点。

只要有一个或多个网关正在使用网关类，实现应在关联的网关类上添加 gateway-exists-finalizer.gateway.networking.k8s.io 终结器。这确保了与网关关联的网关类在使用时不会被删除。

网关类是集群级别资源。

字段	描述
apiVersion 字符串	gateway.networking.k8s.io/v1
kind 字符串	网关类
metadata Kubernetes meta/v1.ObjectMeta	有关 metadata 字段的字段，请参考 Kubernetes API 文档。
spec 网关类规格	规格定义了网关类的期望状态。 控制器名称 网关控制器 ControllerName 是管理此类网关的控制器的名称。此字段的值必须是域前缀路径。 示例：“example.net/gateway-controller”。 此字段不可变，不能为空。 支持：核心 参数引用 参数引用 (可选) ParametersRef 是对包含与网关类对应的配置参数的资源的引用。如果控制器不需要任何其他配置，则这是可选的。 ParametersRef 可以引用标准 Kubernetes 资源，即 ConfigMap，或实现特定自定义资源。该资源可以是集群范围的或命名空间范围的。 如果找不到引用、引用不支持的类型或当该资源中的数据格式错误时，应拒绝网关类，将“Accepted”状态条件设置为“False”，并设置“InvalidParameters”原因。 此网关类的网关可以提供自己的 parametersRef。当两者都被指定时，合并行为是实现特定的。通常建议网关类提供可以被网关覆盖的默认值。 支持：实现特定 描述 字符串 (可选) 描述有助于使用更多详细信息描述网关类。
status 网关类状态	状态定义了网关类的当前状态。 实现必须在所有指定其控制器名称的网关类资源上填充状态。

HTTPRoute

HTTPRoute 提供了一种路由 HTTP 请求的方法。这包括根据主机名、路径、标头或查询参数匹配请求的功能。过滤器可用于指定其他处理步骤。后端指定应将匹配的请求路由到哪里。

字段	描述
apiVersion 字符串	gateway.networking.k8s.io/v1
kind 字符串	HTTPRoute
metadata Kubernetes meta/v1.ObjectMeta	有关 metadata 字段的字段，请参考 Kubernetes API 文档。
spec HTTPRouteSpec	规格定义了 HTTPRoute 的期望状态。 CommonRouteSpec CommonRouteSpec (CommonRouteSpec 的成员嵌入到此类型中。) hostnames []Hostname (可选) 主机名定义了一组应与 HTTP Host 标头匹配的主机名，以选择用于处理请求的 HTTPRoute。实现必须忽略 HTTP Host 标头中指定的任何端口值，同时执行匹配，并且（在没有任何适用的标头修改配置的情况下）必须将此标头未修改地转发到后端。 主机名的有效值为 RFC 1123 中对主机名的定义，但有两个显著例外 不允许使用 IP。 主机名可以以通配符标签（*.）为前缀。通配符标签必须以第一个标签的形式单独出现。 如果主机名由 Listener 和 HTTPRoute 都指定，则 HTTPRoute 必须至少有一个与 Listener 匹配的交叉主机名才能附加到 Listener。例如 主机名为 test.example.com 的 Listener 匹配没有指定任何主机名或至少指定了 test.example.com 或 *.example.com 中的一个的主机名的 HTTPRoute。 主机名为 *.example.com 的 Listener 匹配没有指定任何主机名或至少指定了一个与 Listener 主机名匹配的主机名的 HTTPRoute。例如，*.example.com、test.example.com 和 foo.test.example.com 都将匹配。另一方面，example.com 和 test.example.net 不会匹配。 以通配符标签 (*.) 为前缀的主机名被解释为后缀匹配。这意味着，与 *.example.com 的匹配将同时匹配 test.example.com 和 foo.test.example.com，但不匹配 example.com。 如果 Listener 和 HTTPRoute 都指定了主机名，则必须忽略任何不匹配 Listener 主机名的 HTTPRoute 主机名。例如，如果 Listener 指定 *.example.com，而 HTTPRoute 指定 test.example.com 和 test.example.net，则 test.example.net 不得被视为匹配。 如果 Listener 和 HTTPRoute 都指定了主机名，并且没有任何一个与上述标准匹配，则 HTTPRoute 不会被接受。实现必须在相应的 RouteParentStatus 中引发状态为 False 的“Accepted”条件。 如果多个 HTTPRoute 指定了交叉主机名（例如，重叠的通配符匹配和精确匹配的主机名），则必须优先考虑来自具有最多数量的 HTTPRoute 中的规则 匹配的非通配符主机名中的字符。 匹配主机名中的字符。 如果在多个路由之间存在平局，则 HTTPRouteMatches 的匹配优先级规则将接管。 支持：核心 rules []HTTPRoute 规则 (可选) 规则是 HTTP 匹配器、过滤器和操作的列表。
status HTTPRoute 状态	状态定义了 HTTPRoute 的当前状态。

地址类型（string 别名）

(出现在： 网关地址，网关状态地址)

AddressType 定义了网络地址如何表示为文本字符串。这可能采用两种形式

• 预定义的骆驼大小写字符串标识符（目前仅限于 IPAddress 或 Hostname）
• 域前缀字符串标识符（如 acme.io/CustomAddressType）

值 IPAddress 和 Hostname 具有扩展支持。

NamedAddress 值已弃用，取而代之的是实现特定的域前缀字符串。

所有其他值，包括域前缀值都具有实现特定支持，这些支持用于实现特定行为。在将来的版本中可能会添加对其他预定义的骆驼大小写标识符的支持。

价值	描述
"主机名"	主机名表示基于 DNS 的入口点。这类似于 Kubernetes 负载均衡器状态中的相应主机名字段。例如，此概念可用于云负载均衡器，其中 DNS 名称用于公开负载均衡器。 支持：扩展
"IP 地址"	数字 IP 地址的文本表示形式。IPv4 地址必须采用点分十进制形式。IPv6 地址必须采用标准 IPv6 文本表示形式（参见 RFC 5952）。 此类型用于特定地址。不支持地址范围（例如，您不能使用 127.0.0.0/24 这样的 CIDR 范围作为 IPAddress）。 支持：扩展
"命名地址"	NamedAddress 提供了一种通过名称引用特定 IP 地址的方法。例如，这可能是在云提供商（如静态 IP）上引用资源的名称或其他唯一标识符。 NamedAddress 类型已弃用，取而代之的是实现特定的域前缀字符串。 支持：实现特定

允许路由

(出现在： 监听器)

AllowedRoutes 定义了哪些路由可以附加到此监听器。

字段	描述
命名空间 路由命名空间	(可选) Namespaces 指示可以将路由附加到此监听器的命名空间。默认情况下，这仅限于此网关的命名空间。 支持：核心
种类 []路由组类型	(可选) Kinds 指定允许绑定到此网关监听器的路由组和类型。如果未指定或为空，则使用监听器协议确定所选路由的类型。 RouteGroupKind 必须与 Listener 的 Protocol 字段中指定的应用程序协议兼容的路由类型相对应。如果实现不支持或无法识别此资源类型，则必须将此 Listener 的“ResolvedRefs”条件设置为 False，并以“InvalidRouteKinds”为原因。 支持：核心

AnnotationKey (string 别名)

AnnotationKey 是网关 API 中注释的键。这用于验证映射（例如 TLS 选项）。这与 Kubernetes 用于注释和其他通用值的“限定名称”验证相匹配。

有效值包括

• 示例
• example.com
• example.com/path
• example.com/path.html

无效值包括

• example~ - “~” 是无效字符
• example.com. - 不能以“.”开头或结尾

AnnotationValue (string 别名)

(出现于： GatewayInfrastructure，GatewayTLSConfig)

AnnotationValue 是网关 API 中注释的值。这用于验证映射（例如 TLS 选项）。这大致与 Kubernetes 注释验证相匹配，尽管在这种情况下长度验证是基于注释结构的整个大小。

BackendObjectReference

(出现于： BackendRef，HTTPRequestMirrorFilter)

BackendObjectReference 定义了特定于 BackendRef 的 ObjectReference 的方式。它包含一些比常规 ObjectReference 更多的字段和功能。

请注意，当指定与本地命名空间不同的命名空间时，需要在引用命名空间中创建 ReferenceGrant 对象，以允许该命名空间的所有者接受引用。有关详细信息，请参阅 ReferenceGrant 文档。

API 对象必须在集群中有效；组和 Kind 必须在集群中注册，该引用才有效。

对组和 Kind 无效的对象的引用无效，并且必须由实现拒绝，并在包含对象上设置适当的条件。

字段	描述
group Group	(可选) Group 是引用的组。例如，“gateway.networking.k8s.io”。如果未指定或为空字符串，则推断核心 API 组。
kind Kind	(可选) Kind 是引用的 Kubernetes 资源类型。例如“Service”。 如果未指定，则默认为“Service”。 ExternalName 服务可以引用可能位于集群之外的 CNAME DNS 记录，因此难以从一致性角度进行推理。它们也可能不安全转发（有关更多信息，请参阅 CVE-2021-25740）。实现 SHOULD NOT 支持 ExternalName 服务。 支持：核心（类型不为 ExternalName 的服务） 支持：特定于实现（类型为 ExternalName 的服务）
name ObjectName	Name 是引用的名称。
namespace Namespace	(可选) Namespace 是后端的命名空间。如果未指定，则推断本地命名空间。 请注意，当指定与本地命名空间不同的命名空间时，需要在引用命名空间中创建 ReferenceGrant 对象，以允许该命名空间的所有者接受引用。有关详细信息，请参阅 ReferenceGrant 文档。 支持：核心
port PortNumber	(可选) Port 指定用于此资源的目标端口号。当引用是 Kubernetes 服务时，Port 是必需的。在这种情况下，端口号是服务端口号，而不是目标端口号。对于其他资源，目标端口可能来自引用资源或此字段。

BackendRef

(出现于： GRPCBackendRef，HTTPBackendRef，TCPRouteRule，TLSRouteRule，UDPRouteRule)

BackendRef 定义了路由如何将请求转发到 Kubernetes 资源。

请注意，当指定与本地命名空间不同的命名空间时，需要在引用命名空间中创建 ReferenceGrant 对象，以允许该命名空间的所有者接受引用。有关详细信息，请参阅 ReferenceGrant 文档。

字段	描述
BackendObjectReference BackendObjectReference	(BackendObjectReference 的成员嵌入到此类型中。) BackendObjectReference 引用 Kubernetes 对象。
weight int32	(可选) Weight 指定转发到所引用后端的请求比例。这计算为 weight/(此 BackendRefs 列表中所有权重的总和)。对于非零值，根据实现支持的精度，可能存在与此处定义的精确比例的一些误差。Weight 不是百分比，权重的总和不需要等于 100。 如果只指定了一个后端并且它的权重大于 0，则 100% 的流量将转发到该后端。如果权重设置为 0，则不应转发任何流量到此条目。如果未指定，则权重默认为 1。 对该字段的支持因使用上下文而异。

CommonRouteSpec

(出现于： GRPCRouteSpec，HTTPRouteSpec，TCPRouteSpec，TLSRouteSpec，UDPRouteSpec)

CommonRouteSpec 定义了所有路由必须在其规范中包含的通用属性。

字段

描述

parentRefs []ParentReference

(可选) ParentRefs 引用路由想要附加到的资源（通常是网关）。请注意，引用的父资源需要允许这样做，附加才能完成。对于网关，这意味着网关需要允许来自此类型和命名空间的路由的附加。对于服务，这意味着服务必须在与“生产者”路由相同的命名空间中，或者网格实现必须支持并允许对引用的服务的“消费者”路由。ReferenceGrant 不适用于管理对服务的 ParentRefs - 不可能为与路由不同的命名空间中的服务创建“生产者”路由。 有两种具有“核心”支持的父资源类型 网关（网关一致性配置文件） 服务（网格一致性配置文件，仅限 ClusterIP 服务） 此 API 可以在将来扩展以支持其他类型的父资源。 ParentRefs 必须不同。这意味着： 它们选择不同的对象。如果是这种情况，则 parentRef 条目是不同的。在字段方面，这意味着由 group、kind、namespace 和 name 定义的多部分键必须在路由的所有 parentRef 条目中是唯一的。 它们不选择不同的对象，但对于每个使用的可选字段，每个选择相同对象的 ParentRef 必须将相同的一组可选字段设置为不同的值。如果一个 ParentRef 设置了可选字段的组合，则所有 ParentRef 都必须设置相同的组合。 一些示例 如果一个 ParentRef 设置了 sectionName，则所有引用相同对象的 ParentRef 也必须设置 sectionName。 如果一个 ParentRef 设置了 port，则所有引用相同对象的 ParentRef 也必须设置 port。 如果一个 ParentRef 设置了 sectionName 和 port，则所有引用相同对象的 ParentRef 也必须设置 sectionName 和 port。 可以分别引用可能被实现合并的多个不同对象。例如，一些实现可能选择将兼容的网关监听器合并在一起。如果是这种情况，则应合并附加到这些资源的路由列表。 请注意，对于跨越命名空间边界的 ParentRefs，存在特定规则。跨命名空间引用仅在它们被引用命名空间中的某个内容明确允许的情况下才有效。例如，网关具有 AllowedRoutes 字段，而 ReferenceGrant 提供了一种通用方法来启用其他类型的跨命名空间引用。 gateway:experimental:description 来自路由到同一命名空间中的服务的 ParentRefs 是“生产者”路由，它们将默认路由规则应用于来自任何命名空间到服务的入站连接。 来自路由到不同命名空间中的服务的 ParentRefs 是“消费者”路由，这些路由规则仅应用于源自与路由相同命名空间的出站连接，这些连接的目标是作为路由的 ParentRef 的服务。/gateway:experimental:description

CookieConfig

(出现于： SessionPersistence)

CookieConfig 定义了基于 cookie 的会话持久性的配置。

字段	描述
lifetimeType CookieLifetimeType	(可选) LifetimeType 指定 cookie 是永久的还是基于会话的。永久 cookie 保持到其指定的过期时间（由 Expires 或 Max-Age cookie 属性定义），而会话 cookie 在当前会话结束时被删除。 当设置为“Permanent”时，AbsoluteTimeout 通过 Expires 或 Max-Age cookie 属性指示 cookie 的生命周期，并且是必需的。 当设置为“Session”时，AbsoluteTimeout 指示网关跟踪的 cookie 的绝对生命周期，并且是可选的。 支持：针对“Session”类型的核心 支持：针对“Permanent”类型的扩展

CookieLifetimeType (string 别名)

(出现于： CookieConfig)

价值	描述
"Permanent"	PermanentCookieLifetimeType 指定永久 cookie 的类型。 支持：扩展
"Session"	SessionCookieLifetimeType 指定会话 cookie 的类型。 支持：核心

Duration (string 别名)

(出现于： HTTPRouteTimeouts，SessionPersistence)

Duration 是一个表示时间跨度的字符串值。格式如 GEP-2257 中所述，它是 Golang time.ParseDuration 解析的语法的严格子集。

FromNamespaces (string 别名)

(出现于： RouteNamespaces)

FromNamespaces 指定可以将路由附加到网关的命名空间。

请注意，可以将值添加到此枚举中，实现必须确保未知值不会导致崩溃。

此处的未知值必须导致实现将 Listener 的 Ready 条件设置为 status: False，并以 Invalid 为原因。

价值	描述
"All"	所有命名空间中的路由都可以附加到此网关。
"Same"	仅与网关位于同一命名空间中的路由可以附加到此网关。
"Selector"	仅选择器选择的命名空间中的路由可以附加到此网关。

FrontendTLSValidation

(出现于： GatewayTLSConfig)

FrontendTLSValidation 包含可用于验证启动 TLS 连接的前端的信息。

字段

描述

caCertificateRefs []ObjectReference

CACertificateRefs 包含一个或多个对 Kubernetes 对象的引用，这些对象包含可以作为信任锚点用于验证客户端提供的证书的证书颁发机构的 TLS 证书。 对包含 CA 证书的 Kubernetes ConfigMap 的单个 CA 证书引用具有“核心”支持。实现 MAY 选择支持将多个 CA 证书附加到 Listener，但这是一种特定于实现的行为。 支持：核心 - 对 Kubernetes ConfigMap 的单个引用，其中 CA 证书位于名为 ca.crt 的键中。 支持：特定于实现（多个引用或其他类型的资源）。 对不同命名空间中资源的引用无效，除非目标命名空间中存在允许附加证书的 ReferenceGrant。如果 ReferenceGrant 不允许此引用，则必须将此 Listener 的“ResolvedRefs”条件设置为 False，并以“RefNotPermitted”为原因。

GRPCBackendRef

(出现于： GRPCRouteRule)

GRPCBackendRef 定义了 GRPCRoute 如何转发 gRPC 请求。

请注意，当指定与本地命名空间不同的命名空间时，需要在引用命名空间中创建 ReferenceGrant 对象，以允许该命名空间的所有者接受引用。有关详细信息，请参阅 ReferenceGrant 文档。

gateway:experimental:description

当 BackendRef 指向 Kubernetes 服务时，实现 SHOULD 尊重目标服务端口的 appProtocol 字段（如果已设置）。

支持 appProtocol 的实现 SHOULD 识别 KEP-3726 中定义的 Kubernetes 标准应用程序协议。

如果服务 appProtocol 未指定，实现可以自行推断后端协议。实现可以从引用后端服务的路由类型中推断协议。

如果路由无法使用指定的协议将流量发送到后端，则后端被认为无效。实现必须将“ResolvedRefs”条件设置为“False”，原因是“UnsupportedProtocol”。

/gateway:experimental:description

字段	描述
BackendRef BackendRef	（BackendRef 的成员被嵌入到此类型中。） (可选) BackendRef 是对后端的引用，用于将匹配的请求转发到该后端。 BackendRef 可能由于以下原因无效。在所有情况下，实现必须确保路由上的 ResolvedRefs 条件设置为 status: False，并使用原因和消息来指示错误的根本原因。 BackendRef 无效，如果 它引用了未知或不支持的资源类型。在这种情况下，原因必须设置为 InvalidKind，并且条件的消息必须解释哪种资源类型未知或不受支持。 它引用了不存在的资源。在这种情况下，原因必须设置为 BackendNotFound，并且条件的消息必须解释哪个资源不存在。 它引用了另一个命名空间中的资源，而该引用尚未通过 ReferenceGrant（或等效概念）明确允许。在这种情况下，原因必须设置为 RefNotPermitted，并且条件的消息必须解释哪个跨命名空间引用不被允许。 支持：Kubernetes 服务的核心支持 支持：Kubernetes ServiceImport 的扩展支持 支持：针对任何其他资源的实现特定支持 对权重的支持：核心支持
过滤器 []GRPCRouteFilter	(可选) 在此级别定义的过滤器必须且仅当请求被转发到此处定义的后端时执行。 支持：实现特定支持（为了更广泛地支持过滤器，请使用 GRPCRouteRule 中的 Filters 字段。）

GRPCHeaderMatch

（出现在： GRPCRouteMatch）

GRPCHeaderMatch 描述了如何通过匹配 gRPC 请求头来选择 gRPC 路由。

字段	描述
类型 HeaderMatchType	(可选) Type 指定了如何针对头的值进行匹配。
name GRPCHeaderName	Name 是要匹配的 gRPC 头的名称。 如果多个条目指定等效的头名称，则只应考虑具有等效名称的第一个条目进行匹配。具有等效头名称的后续条目必须被忽略。由于头名称不区分大小写，“foo”和“Foo”被认为是等效的。
值 字符串	Value 是要匹配的 gRPC 头的值。

GRPCHeaderMatchType（string 别名）

GRPCHeaderMatchType 指定了如何比较 gRPC 头值的语义。有效的 GRPCHeaderMatchType 值及其符合级别如下：

• “Exact” - 核心
• “RegularExpression” - 实现特定支持

请注意，将来版本的 API 可能会在此枚举中添加新值，实现必须确保未知值不会导致崩溃。

此处的未知值必须导致实现将路由的 Accepted 条件设置为 status: False，原因是 UnsupportedValue。

价值	描述
"Exact"
"RegularExpression"

GRPCHeaderName（string 别名）

（出现在： GRPCHeaderMatch）

GRPCMethodMatch

（出现在： GRPCRouteMatch）

GRPCMethodMatch 描述了如何通过匹配 gRPC 请求服务和/或方法来选择 gRPC 路由。

Service 和 Method 中至少有一个必须是非空字符串。

字段	描述
类型 GRPCMethodMatchType	(可选) Type 指定了如何针对服务和/或方法进行匹配。支持：核心支持（指定了服务和方法的 Exact） 支持：实现特定支持（指定了方法但未指定服务的 Exact） 支持：实现特定支持（RegularExpression）
服务 字符串	(可选) 要匹配的服务的值。如果为空或省略，将匹配所有服务。 Service 和 Method 中至少有一个必须是非空字符串。
方法 字符串	(可选) 要匹配的方法的值。如果为空或省略，将匹配所有服务。 Service 和 Method 中至少有一个必须是非空字符串。

GRPCMethodMatchType（string 别名）

（出现在： GRPCMethodMatch）

MethodMatchType 指定了如何比较 gRPC 方法和服务的语义。有效的 MethodMatchType 值及其符合级别如下：

• “Exact” - 核心
• “RegularExpression” - 实现特定支持

Exact 方法必须语法正确

• 不得包含 / 字符

价值	描述
"Exact"	精确匹配方法或服务，区分大小写。
"RegularExpression"	如果方法或服务与给定的正则表达式匹配，区分大小写，则匹配成功。 由于 "RegularExpression" 具有实现特定支持的符合性，因此实现可以支持 POSIX、PCRE、RE2 或任何其他正则表达式方言。请阅读实现的文档以确定支持的方言。

GRPCRouteFilter

（出现在： GRPCBackendRef，GRPCRouteRule）

GRPCRouteFilter 定义了在请求或响应生命周期中必须完成的处理步骤。GRPCRouteFilters 旨在作为扩展点，以表达可能在网关实现中完成的处理。一些示例包括请求或响应修改、实现身份验证策略、速率限制和流量整形。API 保证/符合性是根据过滤器的类型定义的。

字段	描述
类型 GRPCRouteFilterType	Type 标识要应用的过滤器的类型。与其他 API 字段一样，类型分为三个符合级别 核心：此包中“支持：核心”定义的过滤器类型及其相应的配置，例如“RequestHeaderModifier”。所有支持 GRPCRoute 的实现都必须支持核心过滤器。 扩展：此包中“支持：扩展”定义的过滤器类型及其相应的配置，例如“RequestMirror”。鼓励实施者支持扩展过滤器。 实现特定：特定供应商定义和支持的过滤器。将来，显示跨多个实现的行为趋同的过滤器将被考虑纳入扩展或核心符合性级别。此类过滤器的特定于过滤器的配置使用 ExtensionRef 字段指定。对于自定义过滤器，Type 必须设置为“ExtensionRef”。 鼓励实施者定义自定义实现类型，以使用实现特定行为扩展核心 API。 如果无法解析对自定义过滤器类型的引用，则必须不跳过该过滤器。相反，本来应该由该过滤器处理的请求必须收到 HTTP 错误响应。 gateway:experimental:validation:Enum=ResponseHeaderModifier;RequestHeaderModifier;RequestMirror;ExtensionRef
requestHeaderModifier HTTPHeaderFilter	(可选) RequestHeaderModifier 定义了用于修改请求头的过滤器的模式。 支持：核心
responseHeaderModifier HTTPHeaderFilter	(可选) ResponseHeaderModifier 定义了用于修改响应头的过滤器的模式。 支持：扩展
requestMirror HTTPRequestMirrorFilter	(可选) RequestMirror 定义了用于镜像请求的过滤器的模式。请求被发送到指定的目的地，但来自该目的地的响应被忽略。 此过滤器可以在同一规则内使用多次。请注意，并非所有实现都能够支持镜像到多个后端。 支持：扩展
extensionRef LocalObjectReference	(可选) ExtensionRef 是对“filter”行为的可选、实现特定扩展。例如，组为“networking.example.net”的资源“myroutefilter”。ExtensionRef 必须不用于核心和扩展过滤器。 支持：实现特定 此过滤器可以在同一规则内使用多次。

GRPCRouteFilterType（string 别名）

（出现在： GRPCRouteFilter）

GRPCRouteFilterType 标识 GRPCRoute 过滤器的类型。

价值	描述
"ExtensionRef"	GRPCRouteFilterExtensionRef 应该用于配置自定义 gRPC 过滤器。 GRPCRouteRule 中的支持：实现特定支持 GRPCBackendRef 中的支持：实现特定支持
"RequestHeaderModifier"	GRPCRouteFilterRequestHeaderModifier 可用于在将 gRPC 请求发送到上游目标之前，从 gRPC 请求中添加或删除 gRPC 头。 GRPCRouteRule 中的支持：核心支持 GRPCBackendRef 中的支持：扩展支持
"RequestMirror"	GRPCRouteFilterRequestMirror 可用于将 gRPC 请求镜像到不同的后端。来自该后端的响应必须被网关忽略。 GRPCRouteRule 中的支持：扩展支持 GRPCBackendRef 中的支持：扩展支持
"ResponseHeaderModifier"	GRPCRouteFilterRequestHeaderModifier 可用于在将 gRPC 响应发送到客户端之前，从 gRPC 响应中添加或删除 gRPC 头。 GRPCRouteRule 中的支持：核心支持 GRPCBackendRef 中的支持：扩展支持

GRPCRouteMatch

(出现于： GRPCRouteRule)

GRPCRouteMatch 定义了用于将请求与给定操作匹配的谓词。多个匹配类型被 AND 运算，即只有在所有条件都满足的情况下，匹配才会评估为 true。

例如，下面的匹配将仅在 gRPC 请求的服务为 foo 并且包含 version: v1 头时匹配该请求

matches:
- method:
type: Exact
service: "foo"
headers:
- name: "version"
value "v1"

字段	描述
方法 GRPCMethodMatch	(可选) Method 指定了 gRPC 请求服务/方法匹配器。如果此字段未指定，则所有服务和方法都将匹配。
头 []GRPCHeaderMatch	(可选) Headers 指定了 gRPC 请求头匹配器。多个匹配值被 AND 运算，这意味着，请求必须匹配所有指定的头才能选择路由。

GRPCRouteRule

（出现在： GRPCRouteSpec）

GRPCRouteRule 定义了根据条件（匹配）匹配 gRPC 请求、处理它（过滤器）并将请求转发到 API 对象（backendRefs）的语义。

字段	描述
匹配 []GRPCRouteMatch	(可选) Matches 定义了用于将规则与传入的 gRPC 请求匹配的条件。每个匹配都是独立的，即如果满足 **任何** 一个匹配条件，则将匹配此规则。 例如，请考虑以下匹配配置 matches: - method: service: foo.bar headers: values: version: 2 - method: service: foo.bar.v2 为了使请求与此规则匹配，它必须满足以下两个条件中的 **任一** 个条件 foo.bar 的服务，并且包含头 version: 2 foo.bar.v2 的服务 请参阅 GRPCRouteMatch 的文档，了解如何指定多个要 AND 运算的匹配条件。 如果未指定任何匹配项，则实现必须匹配每个 gRPC 请求。 从 GRPCRoutes 生成的代理或负载均衡器路由配置必须根据以下标准对规则进行优先级排序，并在出现平局时继续排序。GRPCRoutes 和 HTTPRoutes 之间不得进行合并。具有以下最多数量的规则必须优先处理： 匹配的非通配符主机名中的字符。 匹配主机名中的字符。 匹配服务中的字符数。 匹配方法中的字符数。 头匹配。 如果多个路由之间仍然存在平局，则匹配优先级必须根据以下标准确定，并在出现平局时继续确定 根据创建时间最老的路由。 按“{namespace}/{name}”字母顺序排列时，第一个出现的路由。 如果在已获得优先级的路由内仍然存在平局，则匹配优先级必须授予满足上述标准的第一个匹配规则。
过滤器 []GRPCRouteFilter	(可选) Filters 定义了应用于与该规则匹配的请求的过滤器。 多个行为的排序效果目前未指定。这可能会在将来的 alpha 阶段根据反馈而改变。 此级别的符合性级别是根据过滤器的类型定义的 所有支持 GRPCRoute 的实现都必须支持所有核心过滤器。 鼓励实施者支持扩展过滤器。 实现特定自定义过滤器在实现之间没有 API 保证。 除非在过滤器中明确指示，否则不支持多次指定相同的过滤器。 如果实现无法支持过滤器的组合，则必须清楚地记录该限制。在指定不兼容或不支持的过滤器并导致 Accepted 条件设置为状态 False 的情况下，实现可以使用 IncompatibleFilters 原因来指定此配置错误。 支持：核心
backendRefs []GRPCBackendRef	(可选) BackendRefs 定义了应将匹配请求发送到的后端。 此处的故障行为取决于 BackendRefs 中指定了多少个条目以及有多少个条目无效。 如果 BackendRefs 中的 *所有* 条目都无效，并且此路由规则中也没有指定任何过滤器，则匹配此规则的 *所有* 流量必须收到 UNAVAILABLE 状态。 请参阅 GRPCBackendRef 定义以了解有关导致单个 GRPCBackendRef 无效的规则。 当 GRPCBackendRef 无效时，对于原本应该路由到无效后端的请求，必须返回 UNAVAILABLE 状态。如果指定了多个后端，而其中一些无效，则必须有与原本应该路由到无效后端的请求比例相同的请求接收 UNAVAILABLE 状态。 例如，如果指定了两个具有相同权重的后端，并且其中一个无效，则必须有 50% 的流量接收 UNAVAILABLE 状态。实现可以自行选择如何确定这 50% 的流量。 支持：Kubernetes 服务的核心支持 支持：针对任何其他资源的实现特定支持 对权重的支持：核心支持
sessionPersistence SessionPersistence	(可选) SessionPersistence 定义并配置路由规则的会话持久性。 支持：扩展 网关：实验性

GRPCRouteSpec

（出现在： GRPCRoute，GRPCRoute）

GRPCRouteSpec 定义了 GRPCRoute 的期望状态。

字段	描述
CommonRouteSpec CommonRouteSpec	(CommonRouteSpec 的成员嵌入到此类型中。)
hostnames []Hostname	(可选) Hostnames 定义了一组主机名，以匹配 GRPC Host 标头以选择 GRPCRoute 来处理请求。这与 RFC 1123 中主机名的定义相匹配，但有两个显著例外 不允许使用 IP。 主机名可以以通配符标签 (*.) 为前缀。通配符标签必须单独出现在第一个标签中。 如果监听器和 GRPCRoute 都指定了主机名，则必须至少有一个相交的主机名，GRPCRoute 才能附加到监听器。例如 具有 test.example.com 作为主机名的监听器匹配没有指定任何主机名或至少指定了 test.example.com 或 *.example.com 之一的 GRPCRoute。 具有 *.example.com 作为主机名的监听器匹配没有指定任何主机名或至少指定了一个与监听器主机名匹配的主机名的 GRPCRoute。例如，test.example.com 和 *.example.com 都将匹配。另一方面，example.com 和 test.example.net 将不匹配。 以通配符标签 (*.) 为前缀的主机名被解释为后缀匹配。这意味着，与 *.example.com 的匹配将同时匹配 test.example.com 和 foo.test.example.com，但不匹配 example.com。 如果监听器和 GRPCRoute 都指定了主机名，则任何与监听器主机名不匹配的 GRPCRoute 主机名都必须被忽略。例如，如果监听器指定了 *.example.com，而 GRPCRoute 指定了 test.example.com 和 test.example.net，则 test.example.net 必须不被视为匹配。 如果监听器和 GRPCRoute 都指定了主机名，并且没有任何一个满足上述条件，则 GRPCRoute 必须不被实现接受。实现必须在相应的 RouteParentStatus 中引发状态为 False 的“Accepted”条件。 如果 HTTPRoute 或 GRPCRoute 类型的路由 (A) 附加到监听器，而该监听器已经附加了其他类型的路由 (B)，并且 A 和 B 的主机名的交集不为空，则实现必须根据以下条件（按顺序）准确地接受这两个路由中的一个： 根据创建时间最老的路由。 按“{namespace}/{name}”字母顺序排列时，第一个出现的路由。 被拒绝的路由必须在相应的 RouteParentStatus 中引发状态为“False”的“Accepted”条件。 支持：核心
rules []GRPCRouteRule	(可选) 规则是 gRPC 匹配器、过滤器和操作的列表。

GRPCRouteStatus

（出现在： GRPCRoute，GRPCRoute）

GRPCRouteStatus 定义了 GRPCRoute 的观察状态。

字段	描述
RouteStatus RouteStatus	（RouteStatus 的成员嵌入到此类型中。）

GatewayAddress

（出现在： GatewaySpec）

GatewayAddress 描述可以绑定到网关的地址。

字段	描述
类型 AddressType	(可选) 地址的类型。
值 字符串	地址的值。值的有效性将取决于类型和控制器支持。 例如：1.2.3.4、128::1、my-ip-address。

GatewayClassConditionReason （string 别名）

GatewayClassConditionReason 定义了一组解释为什么引发了特定 GatewayClass 条件类型的理由。

价值	描述
"Accepted"	此理由用于条件为真时的“Accepted”条件。
"InvalidParameters"	此理由用于条件为真时的“Accepted”条件，当 GatewayClass 未被接受是因为 parametersRef 字段引用了不存在或不支持的资源或类型，或者该资源中的数据格式错误时。
"Pending"	此理由用于条件为真时的“Accepted”条件，当请求的控制器尚未就是否接受 GatewayClass 做出决定时。这是新 GatewayClass 上的默认理由。
"SupportedVersion"	此理由用于条件为真时的“SupportedVersion”条件。
"Unsupported"	此理由用于条件为假时的“Accepted”条件，当 GatewayClass 未被接受是因为实现不支持用户定义的 GatewayClass 时。
"UnsupportedVersion"	此理由用于条件为假时的“SupportedVersion”或“Accepted”条件。此条件中应包含一条消息，其中包含在集群中检测到的 CRD 版本和 GatewayClass 支持的 CRD 版本。
"Waiting"	已弃用：请使用“Pending”代替。

GatewayClassConditionType （string 别名）

GatewayClassConditionType 是与 Gateway 资源关联的条件类型。此类型应与 GatewayClassStatus.Conditions 字段一起使用。

价值	描述
"Accepted"	此条件指示 GatewayClass 是否已被 spec.controller 字段中请求的控制器接受。 此条件默认情况下为 Unknown，并且必须由控制器在看到使用其控制器字符串的 GatewayClass 时设置。如果控制器将支持使用此类别的供应网关，则此条件的状态必须设置为 True。否则，此状态必须设置为 False。如果状态设置为 False，则控制器应设置消息和理由作为解释。 此条件为真时可能的原因是 “Accepted” 此条件为假时可能的原因是 “InvalidParameters” “Unsupported” “UnsupportedVersion” 此条件为 Unknown 时可能的原因是 “Pending” 控制器应优先使用 GatewayClassConditionReason 的值作为相应的理由（如果适用）。
"SupportedVersion"	此条件指示 GatewayClass 是否支持集群中存在的 Gateway API CRD 版本。此条件必须由控制器在标记 GatewayClass 为“Accepted”时设置。 Gateway API CRD 的版本由 CRD 上的 gateway.networking.k8s.io/bundle-version 注释定义。如果实现检测到任何 Gateway API CRD 既没有设置此注释，也没有将其设置为实现无法识别或支持的版本，则此条件必须设置为假。 实现可以选择在存在无法识别的 CRD 版本时提供“尽力而为”的支持。这将通过将“Accepted”条件设置为真，将“SupportedVersion”条件设置为假来传达。 或者，实现可以选择不支持具有无法识别版本的 CRD。这将通过将“Accepted”条件设置为假，并将其理由设置为“UnsupportedVersions”来传达。 此条件为真时可能的原因是 “SupportedVersion” 此条件为假时可能的原因是 “UnsupportedVersion” 控制器应优先使用 GatewayClassConditionReason 的值作为相应的理由（如果适用）。 网关：实验性

GatewayClassSpec

（出现在： GatewayClass，GatewayClass）

GatewayClassSpec 反映了网关类别配置。

字段	描述
控制器名称 网关控制器	ControllerName 是管理此类网关的控制器的名称。此字段的值必须是域前缀路径。 示例：“example.net/gateway-controller”。 此字段不可变，不能为空。 支持：核心
参数引用 参数引用	(可选) ParametersRef 是对包含与网关类对应的配置参数的资源的引用。如果控制器不需要任何其他配置，则这是可选的。 ParametersRef 可以引用标准 Kubernetes 资源，即 ConfigMap，或实现特定自定义资源。该资源可以是集群范围的或命名空间范围的。 如果找不到引用、引用不支持的类型或当该资源中的数据格式错误时，应拒绝网关类，将“Accepted”状态条件设置为“False”，并设置“InvalidParameters”原因。 此网关类的网关可以提供自己的 parametersRef。当两者都被指定时，合并行为是实现特定的。通常建议网关类提供可以被网关覆盖的默认值。 支持：实现特定
描述 字符串	(可选) 描述有助于使用更多详细信息描述网关类。

GatewayClassStatus

（出现在： GatewayClass，GatewayClass）

GatewayClassStatus 是 GatewayClass 的当前状态。

字段	描述
conditions []Kubernetes meta/v1.Condition	(可选) Conditions 是控制器对此 GatewayClass 的当前状态。 控制器应优先使用 GatewayClassConditionType 的值来发布条件的类型。
supportedFeatures []SupportedFeature	(可选) SupportedFeatures 是 GatewayClass 支持的功能集。它必须按字母顺序排序。gateway:experimental

GatewayConditionReason （string 别名）

GatewayConditionReason 定义了一组解释为什么引发了特定 Gateway 条件类型的理由。

价值	描述
"Accepted"	此理由用于条件为 True 时的“Accepted”条件。
"AddressNotAssigned"	此理由用于底层实现和网络尚未为网关动态分配地址时的“Programmed”条件。 可以使用此理由的一些示例情况 IPAM 地址耗尽 地址尚未分配 当使用此理由时，实现应提供清楚的消息来解释底层问题，理想情况下还要提供一些有关可能解决问题的操作的提示。
"AddressNotUsable"	此理由用于底层实现（以及网络）无法使用在网关规范中提供的地址时的“Programmed”条件。 可以使用此理由的一些示例情况 找不到命名地址 无法使用提供的静态地址 该地址已被使用 当使用此理由时，实现应在条件消息中提供有关导致问题的地址以及如何解决它的说明性信息。
"Invalid"	此理由用于网关在语法或语义上无效时的“Programmed”和“Accepted”条件。例如，这可能包括未指定的 TLS 配置，或者 TLS 配置中存在一些无法识别或无效的值。
"InvalidParameters"	此理由用于参数引用字段无效时的“Accepted”条件，有关更多详细信息，请参见消息。
"ListenersNotReady"	已弃用：Ready 预留供将来使用
"ListenersNotValid"	此理由用于一个或多个侦听器具有无效或不支持的配置，并且无法在网关上配置时的“Accepted”条件。当“Accepted”为“True”或“False”时，这可能是原因，具体取决于无效的侦听器是否会导致整个网关不被接受。
"NoResources"	此理由用于网关由于可用基础设施资源不足而未调度时的“Programmed”条件。
"NotReconciled"	已弃用：请使用“Pending”代替。
"Pending"	此理由用于状态为“Unknown”且没有控制器协调网关时的“Accepted”和“Programmed”条件。
"Programmed"	此理由用于条件为真时的“Programmed”条件。
"Ready"	已弃用：Ready 预留供将来使用
"Scheduled"	此理由用于条件为 True 时的“Scheduled”条件。 已弃用：请使用带有“Accepted”理由的“Accepted”条件代替。
"UnsupportedAddress"	此理由用于“Accepted”条件，以指示无法接受网关，因为提供的地址是实现不支持的类型。

GatewayConditionType （string 别名）

GatewayConditionType 是与网关关联的条件类型。此类型应与 GatewayStatus.Conditions 字段一起使用。

价值	描述
"Accepted"	当管理网关的控制器在语法和语义上都足够有效以在底层数据平面中生成一些配置时，此条件为真。这并不表示配置是否已传播到底层数据平面。 此条件为真时可能的原因是 “Accepted” “ListenersNotValid” 此条件为假时可能的原因是 “Invalid” “InvalidParameters” “NotReconciled” “UnsupportedAddress” “ListenersNotValid” 此条件为 Unknown 时可能的原因是 “Pending” 控制器可能会使用其他理由引发此条件，但应优先使用上面列出的理由以提高互操作性。
"Programmed"	此条件指示网关是否已生成一些配置，这些配置被认为很快将在底层数据平面中准备就绪。 这是一个正极性摘要条件，因此应始终与设置了 ObservedGeneration 的资源一起出现。 如果控制器在具有所有必需信息来确定条件是否为真之前执行状态更新，则应将其设置为 Unknown。 此条件为真时可能的原因是 “Programmed” 此条件为假时可能的原因是 “Invalid” “Pending” “NoResources” “AddressNotAssigned” 此条件为 Unknown 时可能的原因是 “Pending” 控制器可能会使用其他理由引发此条件，但应优先使用上面列出的理由以提高互操作性。
"Ready"	“Ready” 是一个保留供将来使用的条件类型。实现不应使用它。 如果将来使用，“Ready” 将表示所有配置都确认良好且已完全传播到底层数据平面的最终状态。也就是说，它是一个保证，只要任何东西看到条件为 true，那么连接将立即正确路由。 这是一个非常强大的保证，到目前为止还没有任何实现能够满足它以实施它。如果需要，可以将来讨论此保留。 注意：此条件并非真正“已弃用”，而是“保留”；但是，“已弃用”会触发 Go linter 以提醒使用情况。已弃用：Ready 保留供将来使用
"Scheduled"	已弃用：请使用“Accepted”代替。

GatewayController （string 别名）

（出现在： GatewayClassSpec，RouteParentStatus，PolicyAncestorStatus）

GatewayController 是 Gateway API 控制器的名称。它必须是一个域名前缀路径。

有效值包括

• “example.com/bar”

无效值包括

• “example.com” - 必须包含路径
• “foo.example.com” - 必须包含路径

GatewayInfrastructure

（出现在： GatewaySpec）

GatewayInfrastructure 定义了有关网关实例的基础设施级别属性。

字段	描述
labels map[sigs.k8s.io/gateway-api/apis/v1.AnnotationKey]sigs.k8s.io/gateway-api/apis/v1.AnnotationValue	(可选) 应应用于响应此网关创建的任何资源的标签。 对于创建其他 Kubernetes 对象的实现，这应该是资源上的 metadata.labels 字段。对于其他实现，这指的是任何相关的（实现特定）“标签”概念。 实现可以选择根据需要添加其他特定于实现的标签。 支持：扩展
annotations map[sigs.k8s.io/gateway-api/apis/v1.AnnotationKey]sigs.k8s.io/gateway-api/apis/v1.AnnotationValue	(可选) 应应用于响应此网关创建的任何资源的注释。 对于创建其他 Kubernetes 对象的实现，这应该是资源上的 metadata.annotations 字段。对于其他实现，这指的是任何相关的（实现特定）“注释”概念。 实现可以选择根据需要添加其他特定于实现的注释。 支持：扩展
参数引用 LocalParametersReference	(可选) ParametersRef 是对包含与网关相对应的配置参数的资源的引用。如果控制器不需要任何其他配置，则它是可选的。 这与 GatewayClass 的 parametersRef 具有相同的语义，但是在每个 Gateway 的基础上。 Gateway 的 GatewayClass 可能会提供自己的 parametersRef。当两者都指定时，合并行为是实现特定的。通常建议 GatewayClass 提供可以由 Gateway 覆盖的默认值。 支持：实现特定

GatewaySpec

（出现在： Gateway，Gateway）

GatewaySpec 定义了 Gateway 的期望状态。

Spec 中指定的所有选项并非所有可能的组合都有效。一些无效配置可以通过 CRD 验证同步捕获，但许多情况需要通过 GatewayStatus 块进行异步信号。

字段	描述
gatewayClassName ObjectName	此 Gateway 使用的 GatewayClassName。这是 GatewayClass 资源的名称。
listeners []Listener	与此 Gateway 关联的监听器。监听器定义在此 Gateway 的地址上绑定的逻辑端点。必须至少指定一个监听器。 一组监听器中的每个监听器（例如，单个 Gateway 中的监听器）必须是不同的，因为流量流必须能够分配给正好一个监听器。（本节使用“一组监听器”而不是“单个 Gateway 中的监听器”，因为实现可能会将来自多个 Gateway 的配置合并到单个数据平面，这些规则也适用于这种情况）。 实际上，这意味着一组中的每个监听器必须具有端口、协议和（如果协议支持）主机名的唯一组合。 某些端口、协议和 TLS 设置的组合被认为是核心支持，并且必须由实现根据其目标一致性配置文件来支持 HTTP 配置文件 HTTPRoute，端口：80，协议：HTTP HTTPRoute，端口：443，协议：HTTPS，TLS 模式：终止，TLS 密钥对提供 TLS 配置文件 TLSRoute，端口：443，协议：TLS，TLS 模式：直通 “不同的”监听器具有以下属性 实现可以将入站请求匹配到单个不同的监听器。当多个监听器共享字段值（例如，两个具有相同 Port 值的监听器）时，实现可以使用其他监听器字段将请求匹配到这些监听器中的一个。 例如，以下监听器场景是不同的 具有相同 Port 的多个监听器，它们都使用“HTTP”协议，并且它们都具有唯一的主机名值。 多个使用“HTTPS”或“TLS”协议并具有相同端口的监听器，它们都具有唯一的主机名值。 混合使用“TCP”和“UDP”协议监听器，其中没有使用相同协议的监听器具有相同的端口值。 Listener 结构体中的一些字段可能具有影响 Listener 是否不同的值。主机名对于 HTTP 或 HTTPS 协议尤其重要。 当使用主机名值在具有相同端口和相同协议的 Listener 之间进行选择时，每个 Listener 上的主机名值必须不同，才能使 Listener 不同。 当 Listener 基于主机名不同时，入站请求主机名必须从最具体到最不具体的主机名值匹配，以选择正确的 Listener 及其关联的路由集。 精确匹配必须在通配符匹配之前处理，通配符匹配必须在回退（空主机名值）匹配之前处理。例如，"foo.example.com" 优先于 "*.example.com"，"*.example.com" 优先于 ""。 此外，如果存在多个通配符条目，则必须在处理较不具体的通配符条目之前处理更具体的通配符条目。例如，"*.foo.example.com" 优先于 "*.example.com"。这里的精确定义是，通配符字符右侧主机名中点的数量越多，优先级越高。 通配符字符将匹配左侧的任何数量的字符和点，因此 "*.example.com" 将匹配 "foo.bar.example.com" 和 "bar.example.com"。 如果一组 Listener 包含不不同的 Listener，则这些 Listener 发生冲突，实现必须将 Listener 状态中的“冲突”条件设置为“True”。 实现可以选择仅在它们仅接受不包含任何冲突 Listener 的部分 Listener 集时接受具有某些冲突 Listener 的网关。换句话说，实现可能只在它们丢弃所有冲突 Listener 时才接受部分 Listener 集。不选择冲突 Listener 中的任何一个作为获胜者。这也意味着网关在这种情况下必须至少有一个非冲突 Listener，否则它违反了必须至少存在一个 Listener 的要求。 当网关包含冲突 Listener 时，无论它们是否接受网关，实现都必须在网关状态上设置“ListenersNotValid”条件。该条件应在消息中清楚地指示哪些 Listener 发生冲突，以及哪些被接受。此外，这些 Listener 的 Listener 状态应指示哪些 Listener 发生冲突且未被接受。 网关的 Listener 被认为是“兼容”的，如果 它们是不同的。 实现可以在遵守所有 Listener 都在所有分配的地址上可用的地址要求的情况下为它们提供服务。 扩展支持中的兼容组合预计会在不同实现之间有所不同。对于一个实现兼容的组合可能对于另一个实现不兼容。 例如，一个实现无法在同一地址上同时提供 TCP 和 UDP 监听器，或者无法在同一端口上混合使用 HTTPS 和通用 TLS 监听器，则不会认为这些情况是兼容的，即使它们是不同的。 请注意，请求应最多匹配一个 Listener。例如，如果为“foo.example.com”和“*.example.com”定义了 Listener，则对“foo.example.com”的请求应仅使用附加到“foo.example.com” Listener 的路由进行路由（而不是“*.example.com” Listener）。这个概念被称为“Listener 隔离”。不支持 Listener 隔离的实现必须明确记录这一点。 实现可以将单独的网关合并到一组地址上，如果所有网关中的所有 Listener 都是兼容的。 支持：核心
地址 []网关地址	(可选) 为该网关请求的地址。这是可选的，行为可能取决于实现。如果在规范中设置了一个值，并且请求的地址无效或不可用，则实现必须在 GatewayStatus.Addresses 中的关联条目中指示这一点。 地址字段表示对“网关外部”地址的请求，绑定到该网关的流量将使用这些地址。这可能是外部负载均衡器或其他网络基础设施的 IP 地址或主机名，或者流量将发送到的其他地址。 如果未指定任何地址，则实现可能会以实现特定方式调度网关，并分配一组适当的地址。 实现必须将所有 Listener 绑定到它分配给网关的每个 GatewayAddress，并在 GatewayStatus.Addresses 中添加一个相应的条目。 支持：扩展 网关：验证 IP 地址
基础设施 网关基础设施	(可选) 基础设施定义了有关此网关实例的基础设施级别属性。 支持：核心 网关：实验性

GatewayStatus

（出现在： Gateway，Gateway）

GatewayStatus 定义了 Gateway 的观察状态。

字段	描述
地址 []GatewayStatusAddress	(可选) Addresses 列出了已绑定到 Gateway 的网络地址。 此列表可能在某些情况下与 Spec 中提供的地址不同 没有指定地址，所有地址都是动态分配的 指定和动态地址的组合被分配 指定的地址不可用（例如，已在使用中） 网关：验证 IP 地址
conditions []Kubernetes meta/v1.Condition	(可选) Conditions 描述了 Gateway 的当前状况。 实现应该优先使用 GatewayConditionType 和 GatewayConditionReason 常量来表达 Gateway 条件，以便操作员和工具能够就描述 Gateway 状态的通用词汇达成一致。 已知条件类型为 “Accepted” “Programmed” “Ready”
listeners []ListenerStatus	(可选) Listeners 为 Spec 中定义的每个唯一侦听器端口提供状态。

GatewayStatusAddress

（出现在： GatewayStatus）

GatewayStatusAddress 描述了绑定到 Gateway 的网络地址。

字段	描述
类型 AddressType	(可选) 地址的类型。
值 字符串	地址的值。值的有效性将取决于类型和控制器支持。 例如：1.2.3.4、128::1、my-ip-address。

GatewayTLSConfig

(出现在： 监听器)

GatewayTLSConfig 描述了 TLS 配置。

字段	描述
mode TLSModeType	(可选) Mode 定义了由客户端发起的 TLS 会话的 TLS 行为。有两种可能的模式 Terminate：在 Gateway 处终止下游客户端和 Gateway 之间的 TLS 会话。此模式要求以某种方式指定证书，例如填充 certificateRefs 字段。 Passthrough：TLS 会话不会由 Gateway 终止。这意味着 Gateway 无法解密 TLS 流，除了 TLS 协议的 ClientHello 消息。certificateRefs 字段在此模式下被忽略。 支持：核心
certificateRefs []SecretObjectReference	(可选) CertificateRefs 包含一系列对包含 TLS 证书和私钥的 Kubernetes 对象的引用。这些证书用于为与相关侦听器主机名匹配的请求建立 TLS 握手。 对 Kubernetes Secret 的单个 CertificateRef 具有“核心”支持。实现可以选择支持将多个证书附加到侦听器，但这是一种特定于实现的行为。 对不同命名空间中资源的引用无效，除非目标命名空间中存在允许附加证书的 ReferenceGrant。如果 ReferenceGrant 不允许此引用，则此侦听器的“ResolvedRefs”条件 MUST 设置为 False，原因是“RefNotPermitted”。 当 mode 设置为“Terminate”（默认值）时，此字段必须至少包含一个元素，否则为可选。 CertificateRefs 可以引用标准 Kubernetes 资源，即 Secret，或特定于实现的自定义资源。 支持：核心 - 对类型为 kubernetes.io/tls 的 Kubernetes Secret 的单个引用 支持：特定于实现（多个引用或其他资源类型）
frontendValidation FrontendTLSValidation	(可选) FrontendValidation 包含用于验证前端（客户端）的配置信息。设置此字段将要求客户端在 TLS 握手期间发送用于验证所需的客户端证书。在浏览器中，这可能会导致出现对话框，要求用户指定客户端证书。在验证中接受的证书链的最大深度是特定于实现的。 支持：扩展 网关：实验性
options map[sigs.k8s.io/gateway-api/apis/v1.AnnotationKey]sigs.k8s.io/gateway-api/apis/v1.AnnotationValue	(可选) Options 是一个键值对列表，用于为每个实现启用扩展的 TLS 配置。例如，配置最小 TLS 版本或支持的密码套件。 一组常用键可能会在未来由 API 定义。为了避免任何歧义，特定于实现的定义 MUST 使用域前缀名称，例如 example.com/my-custom-option。未前缀的名称保留给 Gateway API 定义的键名。 支持：实现特定

组（string 别名）

（出现在： BackendObjectReference，LocalObjectReference，LocalParametersReference，ObjectReference，ParametersReference，ParentReference，RouteGroupKind，SecretObjectReference，LocalPolicyTargetReference，NamespacedPolicyTargetReference，ReferenceGrantFrom，ReferenceGrantTo）

Group 指的是 Kubernetes Group。它必须是空字符串或 RFC 1123 子域。

此验证基于相应的 Kubernetes 验证：https://github.com/kubernetes/apimachinery/blob/02cfb53916346d085a6c6c7c66f882e3c6b0eca6/pkg/util/validation/validation.go#L208

有效值包括

• ”” - 空字符串表示核心 Kubernetes API 组
• “networking.k8s.io”
• “foo.example.com”

无效值包括

• “example.com/bar” - “/” 是一个无效字符

HTTPBackendRef

（出现在： HTTPRouteRule）

HTTPBackendRef 定义了 HTTPRoute 如何转发 HTTP 请求。

字段	描述
BackendRef BackendRef	（BackendRef 的成员被嵌入到此类型中。） (可选) BackendRef 是对后端的引用，用于将匹配的请求转发到该后端。 BackendRef 可能由于以下原因无效。在所有情况下，实现必须确保路由上的 ResolvedRefs 条件设置为 status: False，并使用原因和消息来指示错误的根本原因。 BackendRef 无效，如果 它指的是未知或不支持的资源类型。在这种情况下，Reason 必须设置为 InvalidKind，并且 Condition 的 Message 必须解释哪些资源类型是未知的或不受支持的。 它指的是不存在的资源。在这种情况下，Reason 必须设置为 BackendNotFound，并且 Condition 的 Message 必须解释哪些资源不存在。 它指的是另一个命名空间中的资源，而该引用尚未由 ReferenceGrant（或等效概念）明确允许。在这种情况下，Reason 必须设置为 RefNotPermitted，并且 Condition 的 Message 必须解释哪些跨命名空间引用不被允许。 它指的是具有与给定路由类型不兼容的 appProtocol 的 Kubernetes Service BackendTLSPolicy 对象已安装在集群中，存在引用 Service 的 BackendTLSPolicy，并且实现无法满足要求。在撰写本文时，BackendTLSPolicy 处于实验阶段，但一旦成为标准，这将成为 MUST 要求。 支持：Kubernetes 服务的核心支持 支持：针对任何其他资源的实现特定支持 对权重的支持：核心支持 Kubernetes Service appProtocol 支持：扩展 BackendTLSPolicy 支持：实验性和特定于实现
过滤器 []HTTPRouteFilter	(可选) 仅当请求被转发到此处定义的后端时，才应执行在此级别定义的过滤器。 支持：特定于实现（对于更广泛的过滤器支持，请使用 HTTPRouteRule 中的 Filters 字段。）

HTTPHeader

（出现在： HTTPHeaderFilter）

HTTPHeader 表示 RFC 7230 中定义的 HTTP 标头名称和值。

字段	描述
name HTTPHeaderName	Name 是要匹配的 HTTP 标头的名称。名称匹配 MUST 不区分大小写。（参见 https://tools.ietf.org/html/rfc7230#section-3.2）。 如果多个条目指定等效的标头名称，则必须考虑第一个具有等效名称的条目以进行匹配。必须忽略随后具有等效标头名称的条目。由于标头名称不区分大小写，“foo”和“Foo”被认为是等效的。
值 字符串	Value 是要匹配的 HTTP 标头的值。

HTTPHeaderFilter

（出现在： GRPCRouteFilter，HTTPRouteFilter）

HTTPHeaderFilter 定义了一个过滤器，它修改 HTTP 请求或响应的标头。

字段	描述
set []HTTPHeader	(可选) Set 在操作之前使用给定的标头（名称、值）覆盖请求。 输入：GET /foo HTTP/1.1 my-header: foo 配置：set: - name: “my-header” value: “bar” 输出：GET /foo HTTP/1.1 my-header: bar
add []HTTPHeader	(可选) Add 将给定的标头（名称、值）添加到操作之前的请求中。它附加到与标头名称关联的任何现有值。 输入：GET /foo HTTP/1.1 my-header: foo 配置：add: - name: “my-header” value: “bar,baz” 输出：GET /foo HTTP/1.1 my-header: foo,bar,baz
remove []string	(可选) 从操作之前的 HTTP 请求中删除给定的标头。Remove 的值是 HTTP 标头名称列表。请注意，标头名称不区分大小写（参见 https://datatracker.ietf.org/doc/html/rfc2616#section-4.2)）。 输入：GET /foo HTTP/1.1 my-header1: foo my-header2: bar my-header3: baz 配置：remove: [“my-header1”, “my-header3”] 输出：GET /foo HTTP/1.1 my-header2: bar

HTTPHeaderMatch

（出现在： HTTPRouteMatch）

HTTPHeaderMatch 描述了如何通过匹配 HTTP 请求标头来选择 HTTP 路由。

字段	描述
类型 HeaderMatchType	(可选) Type 指定了如何针对头的值进行匹配。 支持：核心（精确） 支持：实现特定支持（RegularExpression） 由于 RegularExpression HeaderMatchType 具有特定于实现的符合性，因此实现可以支持 POSIX、PCRE 或任何其他正则表达式方言。请阅读实现的文档以确定支持的方言。
name HTTPHeaderName	Name 是要匹配的 HTTP 标头的名称。名称匹配 MUST 不区分大小写。（参见 https://tools.ietf.org/html/rfc7230#section-3.2）。 如果多个条目指定等效的头名称，则只应考虑具有等效名称的第一个条目进行匹配。具有等效头名称的后续条目必须被忽略。由于头名称不区分大小写，“foo”和“Foo”被认为是等效的。 当 HTTP 请求中重复标头时，如何表示它是特定于实现的行为。通常，代理应该遵循 RFC 中的指南：https://www.rfc-editor.org/rfc/rfc7230.html#section-3.2.2 关于处理重复标头的说明，并对“Set-Cookie”进行特殊处理。
值 字符串	Value 是要匹配的 HTTP 标头的值。

HTTPHeaderName (string 别名)

（出现在： HTTPHeader，HTTPHeaderMatch，HTTPQueryParamMatch）

HTTPHeaderName 是 HTTP 标头的名称。

有效值包括：* “Authorization” * “Set-Cookie”

无效值包括

• ”:method” - “:” 是一个无效字符。这意味着此类型目前不支持 HTTP/2 伪标头。

• ”/invalid” - “/” 是一个无效字符

HTTPMethod (string 别名)

（出现在： HTTPRouteMatch）

HTTPMethod 描述了如何通过匹配 RFC 7231 和 RFC 5789 中定义的 HTTP 方法来选择 HTTP 路由。预期值应为大写。

请注意，可以将值添加到此枚举中，实现必须确保未知值不会导致崩溃。

此处未知的值必须导致实现将路由的 Accepted Condition 设置为 status: False，原因是 UnsupportedValue。

价值	描述
"CONNECT"
"DELETE"
"GET"
"HEAD"
"OPTIONS"
"PATCH"
"POST"
"PUT"
"TRACE"

HTTPPathMatch

（出现在： HTTPRouteMatch）

HTTPPathMatch 描述了如何通过匹配 HTTP 请求路径来选择 HTTP 路由。

字段	描述
类型 PathMatchType	(可选) Type 指定了如何与路径 Value 匹配。 支持：核心（精确、PathPrefix） 支持：实现特定支持（RegularExpression）
值 字符串	(可选) 要匹配的 HTTP 路径的值。

HTTPPathModifier

（出现在： HTTPRequestRedirectFilter，HTTPURLRewriteFilter）

HTTPPathModifier 定义了路径修改器的配置。 gateway:experimental

字段	描述
类型 HTTPPathModifierType	Type 定义了路径修改器的类型。API 的未来版本中可能会添加其他类型。 请注意，可以将值添加到此枚举中，实现必须确保未知值不会导致崩溃。 此处未知的值必须导致实现将路由的 Accepted Condition 设置为 status: False，原因是 UnsupportedValue。
replaceFullPath 字符串	(可选) ReplaceFullPath 指定了在重写或重定向期间替换请求的完整路径的值。
replacePrefixMatch 字符串	(可选) ReplacePrefixMatch 指定在重写或重定向期间用于替换请求的前缀匹配的值。例如，对“/foo/bar”的请求，其前缀匹配为“/foo”，ReplacePrefixMatch 为“/xyz”，将被修改为“/xyz/bar”。 请注意，这与 PathPrefix 匹配类型的行为一致。这匹配完整的路径元素。路径元素是指路径中由 / 分隔符分割的标签列表。指定时，尾随 / 将被忽略。例如，路径 /abc、/abc/ 和 /abc/def 都将匹配前缀 /abc，但路径 /abcd 不会匹配。 ReplacePrefixMatch 仅与 PathPrefix HTTPRouteMatch 兼容。在同一个 HTTPRouteRule 上使用任何其他 HTTPRouteMatch 类型将导致实现将路由的接受条件设置为 status: False。 请求路径 前缀匹配 替换前缀 修改后的路径 /foo/bar /foo /xyz /xyz/bar /foo/bar /foo /xyz/ /xyz/bar /foo/bar /foo/ /xyz /xyz/bar /foo/bar /foo/ /xyz/ /xyz/bar /foo /foo /xyz /xyz /foo/ /foo /xyz /xyz/ /foo/bar /foo /bar /foo/ /foo / /foo /foo / /foo/ /foo / / /foo /foo / /

HTTPPathModifierType (string 别名)

(出现在: HTTPPathModifier)

HTTPPathModifierType 定义了路径重定向或重写的类型。

价值	描述
"ReplaceFullPath"	这种类型的修饰符表明完整路径将被指定的值替换。
"ReplacePrefixMatch"	这种类型的修饰符表明任何前缀路径匹配将被替换值替换。例如，路径的前缀匹配为“/foo”，ReplacePrefixMatch 替换值为“/bar”，则匹配请求中“/foo”前缀将被“/bar”替换。 请注意，这与 PathPrefix 匹配类型的行为一致。这匹配完整的路径元素。路径元素是指路径中由 / 分隔符分割的标签列表。指定时，尾随 / 将被忽略。例如，路径 /abc、/abc/ 和 /abc/def 都将匹配前缀 /abc，但路径 /abcd 不会匹配。

HTTPQueryParamMatch

（出现在： HTTPRouteMatch）

HTTPQueryParamMatch 描述了如何通过匹配 HTTP 查询参数来选择 HTTP 路由。

字段	描述
类型 QueryParamMatchType	(可选) Type 指定了如何与查询参数的值进行匹配。 支持: 扩展 (精确) 支持：实现特定支持（RegularExpression） 由于 RegularExpression QueryParamMatchType 具有实现特定的符合性，因此实现可以支持 POSIX、PCRE 或任何其他正则表达式方言。请阅读实现的文档以确定支持的方言。
name HTTPHeaderName	Name 是要匹配的 HTTP 查询参数的名称。这必须是精确的字符串匹配。（参见 https://tools.ietf.org/html/rfc7230#section-2.7.3)）。 如果多个条目指定等效的查询参数名称，则只有第一个具有等效名称的条目 MUST 被视为匹配。后续具有等效查询参数名称的条目 MUST 被忽略。 如果查询参数在 HTTP 请求中重复出现，则行为故意保留未定义，因为不同的数据平面具有不同的功能。但是，建议 实现应该与参数的第一个值匹配（如果数据平面支持），因为这种行为在网关 API 之外的其他负载均衡环境中是预期的。 用户 SHOULD NOT 基于重复的查询参数来路由流量，以防止实现之间潜在的差异。
值 字符串	Value 是要匹配的 HTTP 查询参数的值。

HTTPRequestMirrorFilter

（出现在： GRPCRouteFilter，HTTPRouteFilter）

HTTPRequestMirrorFilter 定义了 RequestMirror 过滤器的配置。

字段

描述

backendRef BackendObjectReference

BackendRef 引用一个资源，镜像请求将被发送到该资源。 镜像请求必须仅发送到此 BackendRef 中的单个目标端点，而与此 BackendRef 中存在多少个端点无关。 如果无法找到被引用者，则此 BackendRef 无效，并且必须从网关中删除。控制器必须确保路由状态上的“ResolvedRefs”条件设置为 status: False，并且不为此后端配置底层实现。 如果存在对现有对象的跨命名空间引用，而该引用未被 ReferenceGrant 允许，则控制器必须确保路由状态上的“ResolvedRefs”条件设置为 status: False，原因是“RefNotPermitted”，并且不为此后端配置底层实现。 在任一错误情况下，ResolvedRefs 条件的消息都应用于提供有关问题的更多详细信息。 支持: Kubernetes 服务的扩展 支持：针对任何其他资源的实现特定支持

HTTPRequestRedirectFilter

(出现在: HTTPRouteFilter)

HTTPRequestRedirect 定义了一个过滤器，该过滤器将重定向请求。此过滤器 MUST NOT 在与 HTTPURLRewrite 过滤器相同的路由规则上使用。

字段	描述
scheme 字符串	(可选) Scheme 是要在响应中 Location 标头值中使用的方案。如果为空，则使用请求的方案。 Scheme 重定向会影响重定向的端口，有关更多信息，请参阅此过滤器的端口字段的文档。 请注意，可以将值添加到此枚举中，实现必须确保未知值不会导致崩溃。 此处未知的值必须导致实现将路由的 Accepted Condition 设置为 status: False，原因是 UnsupportedValue。 支持：扩展
hostname PreciseHostname	(可选) Hostname 是要在响应中 Location 标头值中使用的主机名。如果为空，则使用请求 Host 标头中的主机名。 支持：核心
path HTTPPathModifier	(可选) Path 定义用于修改传入请求路径的参数。然后使用修改后的路径来构造 Location 标头。如果为空，则按原样使用请求路径。 支持：扩展
port PortNumber	(可选) Port 是要在响应中 Location 标头值中使用的端口。 如果未指定端口，则 MUST 使用以下规则派生重定向端口 如果重定向方案不为空，则重定向端口 MUST 是与重定向方案关联的知名端口。具体来说，将“http”重定向到端口 80，将“https”重定向到端口 443。如果重定向方案没有知名端口，则 SHOULD 使用网关的监听器端口。 如果重定向方案为空，则重定向端口 MUST 是网关监听器端口。 实现 SHOULD NOT 在以下情况下在“Location”标头中添加端口号 将使用 HTTP 的 Location 标头（无论是在监听器协议还是方案字段中确定）以及 使用端口 80。 将使用 HTTPS 的 Location 标头（无论是在监听器协议还是方案字段中确定）以及 使用端口 443。 支持：扩展
statusCode int	(可选) StatusCode 是要在响应中使用的 HTTP 状态代码。 请注意，可以将值添加到此枚举中，实现必须确保未知值不会导致崩溃。 此处未知的值必须导致实现将路由的 Accepted Condition 设置为 status: False，原因是 UnsupportedValue。 支持：核心

HTTPRouteFilter

(出现在: HTTPBackendRef, HTTPRouteRule)

HTTPRouteFilter 定义了在请求或响应生命周期中必须完成的处理步骤。HTTPRouteFilter 旨在作为扩展点来表达可能在网关实现中完成的处理。一些示例包括请求或响应修改、实现身份验证策略、速率限制和流量整形。API 保证/符合性基于过滤器的类型定义。

字段	描述
类型 HTTPRouteFilterType	Type 标识要应用的过滤器的类型。与其他 API 字段一样，类型分为三个符合级别 核心: 由本包中“支持: 核心”定义的过滤器类型及其相应的配置，例如“RequestHeaderModifier”。所有实现都必须支持核心过滤器。 扩展：此包中“支持：扩展”定义的过滤器类型及其相应的配置，例如“RequestMirror”。鼓励实施者支持扩展过滤器。 实现特定: 由特定供应商定义和支持的过滤器。将来，跨多个实现显示行为趋同的过滤器将被考虑纳入扩展或核心符合性级别。此类过滤器的过滤器特定配置使用 ExtensionRef 字段指定。Type 应设置为“ExtensionRef”以用于自定义过滤器。 鼓励实施者定义自定义实现类型，以使用实现特定行为扩展核心 API。 如果无法解析对自定义过滤器类型的引用，则必须不跳过该过滤器。相反，本来应该由该过滤器处理的请求必须收到 HTTP 错误响应。 请注意，可以将值添加到此枚举中，实现必须确保未知值不会导致崩溃。 此处未知的值必须导致实现将路由的 Accepted Condition 设置为 status: False，原因是 UnsupportedValue。
requestHeaderModifier HTTPHeaderFilter	(可选) RequestHeaderModifier 定义了用于修改请求头的过滤器的模式。 支持：核心
responseHeaderModifier HTTPHeaderFilter	(可选) ResponseHeaderModifier 定义了用于修改响应头的过滤器的模式。 支持：扩展
requestMirror HTTPRequestMirrorFilter	(可选) RequestMirror 定义了用于镜像请求的过滤器的模式。请求被发送到指定的目的地，但来自该目的地的响应被忽略。 此过滤器可以在同一规则内使用多次。请注意，并非所有实现都能够支持镜像到多个后端。 支持：扩展
requestRedirect HTTPRequestRedirectFilter	(可选) RequestRedirect 定义了用于使用 HTTP 重定向响应请求的过滤器的模式。 支持：核心
urlRewrite HTTPURLRewriteFilter	(可选) URLRewrite 定义了用于在转发期间修改请求的过滤器的模式。 支持：扩展
extensionRef LocalObjectReference	(可选) ExtensionRef 是对“filter”行为的可选、实现特定扩展。例如，组为“networking.example.net”的资源“myroutefilter”。ExtensionRef 必须不用于核心和扩展过滤器。 此过滤器可以在同一规则内使用多次。 支持：实现特定

HTTPRouteFilterType (string 别名)

(出现在: HTTPRouteFilter)

HTTPRouteFilterType 标识 HTTPRoute 过滤器的类型。

价值	描述
"ExtensionRef"	HTTPRouteFilterExtensionRef 应用于配置自定义 HTTP 过滤器。 HTTPRouteRule 中的支持: 实现特定 HTTPBackendRef 中的支持: 实现特定
"RequestHeaderModifier"	HTTPRouteFilterRequestHeaderModifier 可用于在将 HTTP 请求发送到上游目标之前，从 HTTP 请求中添加或删除 HTTP 标头。 HTTPRouteRule 中的支持: 核心 HTTPBackendRef 中的支持: 扩展
"RequestMirror"	HTTPRouteFilterRequestMirror 可用于将 HTTP 请求镜像到不同的后端。网关 MUST 忽略此后端的响应。 HTTPRouteRule 中的支持: 扩展 HTTPBackendRef 中的支持: 扩展
"RequestRedirect"	HTTPRouteFilterRequestRedirect 可用于将请求重定向到其他位置。此过滤器也可用于 HTTP 到 HTTPS 重定向。此过滤器不能与 URLRewrite 过滤器在相同的路由规则或 BackendRef 上使用。 HTTPRouteRule 中的支持: 核心 HTTPBackendRef 中的支持: 扩展
"ResponseHeaderModifier"	HTTPRouteFilterResponseHeaderModifier 可用于在将 HTTP 响应发送到客户端之前，从 HTTP 响应中添加或删除 HTTP 标头。 HTTPRouteRule 中的支持: 扩展 HTTPBackendRef 中的支持: 扩展
"URLRewrite"	HTTPRouteFilterURLRewrite 可用于在转发期间修改请求。在路由规则上最多可以使用一个此类过滤器。此过滤器不能与 RequestRedirect 过滤器在相同的路由规则或 BackendRef 上使用。 HTTPRouteRule 中的支持: 扩展 HTTPBackendRef 中的支持: 扩展

HTTPRouteMatch

（出现在： HTTPRouteRule）

HTTPRouteMatch 定义了用于将请求与给定操作匹配的谓词。多个匹配类型被 AND 连接，即，只有在所有条件都满足的情况下，匹配才将评估为 true。

例如，下面的匹配将仅在 HTTP 请求的路径以 /foo 开头且包含 version: v1 标头时匹配该请求

match:
path:
value: "/foo"
headers:
- name: "version"
value "v1"

字段	描述
path HTTPPathMatch	(可选) Path 指定 HTTP 请求路径匹配器。如果未指定此字段，则提供对“/”路径的默认前缀匹配。
头 []HTTPHeaderMatch	(可选) Headers 指定 HTTP 请求标头匹配器。多个匹配值被 AND 连接，这意味着请求必须匹配所有指定的标头才能选择路由。
queryParams []HTTPQueryParamMatch	(可选) QueryParams 指定 HTTP 查询参数匹配器。多个匹配值被 AND 连接，这意味着请求必须匹配所有指定的查询参数才能选择路由。 支持：扩展
方法 HTTPMethod	(可选) Method 指定 HTTP 方法匹配器。指定时，只有当请求具有指定方法时，才会匹配此路由。 支持：扩展

HTTPRouteRule

(出现在: HTTPRouteSpec)

HTTPRouteRule 定义了基于条件（匹配）匹配 HTTP 请求、处理它（过滤器）以及将请求转发到 API 对象（backendRefs）的语义。

字段	描述
匹配 []HTTPRouteMatch	(可选) Matches 定义用于将规则与传入 HTTP 请求匹配的条件。每个匹配都是独立的，即如果任何一个匹配满足，则将匹配此规则。 例如，请考虑以下匹配配置 matches: - path: value: "/foo" headers: - name: "version" value: "v2" - path: value: "/v2/foo" 对于要与此规则匹配的请求，请求必须满足以下两个条件中的任一个 路径以 /foo 为前缀且包含标头 version: v2 路径前缀为 /v2/foo 请参阅 HTTPRouteMatch 的文档，了解如何指定应 AND 连接的多个匹配条件。 如果未指定匹配项，则默认值为对“/”的前缀路径匹配，这将匹配每个 HTTP 请求。 从 HTTPRoutes 生成的代理或负载均衡器路由配置 MUST 基于以下条件优先考虑匹配，并在平局情况下继续。在适用于 Routes 的所有规则中，优先级必须赋予具有以下条件的匹配 “精确”路径匹配。 具有最大字符数的“前缀”路径匹配。 方法匹配。 最大数量的标头匹配。 最大数量的查询参数匹配。 注意: RegularExpression 路径匹配的优先级是实现特定的。 如果多个路由之间仍然存在平局，则匹配优先级必须根据以下标准确定，并在出现平局时继续确定 根据创建时间最老的路由。 按“{namespace}/{name}”字母顺序排列时，第一个出现的路由。 如果在 HTTPRoute 中仍然存在平局，则匹配优先级 MUST 被赋予第一个（按列表顺序）具有满足上述条件的匹配的匹配规则。 当没有规则与请求成功匹配并已附加到请求来自的父级时，MUST 返回 HTTP 404 状态代码。
过滤器 []HTTPRouteFilter	(可选) Filters 定义了应用于与该规则匹配的请求的过滤器。 在可能的情况下，实现 SHOULD 按指定的顺序实现过滤器。 实现 MAY 选择严格地实现此排序，拒绝任何不支持的过滤器组合或顺序。如果实现选择对过滤器排序进行严格解释，则它们 MUST 清楚地记录该行为。 为了拒绝无效的过滤器组合或顺序，实现 SHOULD 认为具有此配置的路由规则无效。如果路由中的所有路由规则都无效，则整个路由将被视为无效。如果只有一部分路由规则无效，则实现 MUST 为路由设置“PartiallyInvalid”条件。 此级别的符合性级别是根据过滤器的类型定义的 所有核心过滤器 MUST 由所有实现支持。 鼓励实施者支持扩展过滤器。 实现特定自定义过滤器在实现之间没有 API 保证。 除非在过滤器中明确指示，否则不支持多次指定相同的过滤器。 所有过滤器预计彼此兼容，除了 URLRewrite 和 RequestRedirect 过滤器，它们不能组合使用。如果实现无法支持其他过滤器组合，它们必须明确记录该限制。在指定了不兼容或不支持的过滤器并导致Accepted条件设置为状态False的情况下，实现可以使用IncompatibleFilters原因来指定此配置错误。 支持：核心
backendRefs []HTTPBackendRef	(可选) BackendRefs 定义了应将匹配请求发送到的后端。 此处的故障行为取决于 BackendRefs 中指定了多少个条目以及有多少个条目无效。 如果 BackendRefs 中所有条目都无效，并且此路由规则中也没有指定任何过滤器，则所有匹配此规则的流量 MUST 收到 500 状态码。 有关使单个 HTTPBackendRef 无效的规则，请参阅 HTTPBackendRef 定义。 当 HTTPBackendRef 无效时，MUST 为原本应路由到无效后端的请求返回 500 状态码。如果指定了多个后端，并且其中一些无效，则原本应路由到无效后端的请求比例 MUST 收到 500 状态码。 例如，如果指定了两个权重相等的后端，并且其中一个无效，则 50% 的流量必须收到 500。实现可以选择如何确定这 50%。 当 HTTPBackendRef 引用一个没有就绪端点的服务时，实现 SHOULD 为对该后端的请求返回 503。如果实现选择这样做，则所有关于 500 响应的上述规则 MUST 也适用于返回 503 的响应。 支持：Kubernetes 服务的核心支持 支持：Kubernetes ServiceImport 的扩展支持 支持：针对任何其他资源的实现特定支持 对权重的支持：核心支持
超时 HTTPRouteTimeouts	(可选) Timeouts 定义了可以为 HTTP 请求配置的超时。 支持：扩展 网关：实验性
sessionPersistence SessionPersistence	(可选) SessionPersistence 定义并配置路由规则的会话持久性。 支持：扩展 网关：实验性

HTTPRouteSpec

（出现在： HTTPRoute， HTTPRoute）

HTTPRouteSpec 定义了 HTTPRoute 的期望状态。

字段	描述
CommonRouteSpec CommonRouteSpec	(CommonRouteSpec 的成员嵌入到此类型中。)
hostnames []Hostname	(可选) 主机名定义了一组应与 HTTP Host 标头匹配的主机名，以选择用于处理请求的 HTTPRoute。实现必须忽略 HTTP Host 标头中指定的任何端口值，同时执行匹配，并且（在没有任何适用的标头修改配置的情况下）必须将此标头未修改地转发到后端。 主机名的有效值为 RFC 1123 中对主机名的定义，但有两个显著例外 不允许使用 IP。 主机名可以以通配符标签（*.）为前缀。通配符标签必须以第一个标签的形式单独出现。 如果主机名由 Listener 和 HTTPRoute 都指定，则 HTTPRoute 必须至少有一个与 Listener 匹配的交叉主机名才能附加到 Listener。例如 主机名为 test.example.com 的 Listener 匹配没有指定任何主机名或至少指定了 test.example.com 或 *.example.com 中的一个的主机名的 HTTPRoute。 主机名为 *.example.com 的 Listener 匹配没有指定任何主机名或至少指定了一个与 Listener 主机名匹配的主机名的 HTTPRoute。例如，*.example.com、test.example.com 和 foo.test.example.com 都将匹配。另一方面，example.com 和 test.example.net 不会匹配。 以通配符标签 (*.) 为前缀的主机名被解释为后缀匹配。这意味着，与 *.example.com 的匹配将同时匹配 test.example.com 和 foo.test.example.com，但不匹配 example.com。 如果 Listener 和 HTTPRoute 都指定了主机名，则必须忽略任何不匹配 Listener 主机名的 HTTPRoute 主机名。例如，如果 Listener 指定 *.example.com，而 HTTPRoute 指定 test.example.com 和 test.example.net，则 test.example.net 不得被视为匹配。 如果 Listener 和 HTTPRoute 都指定了主机名，并且没有任何一个与上述标准匹配，则 HTTPRoute 不会被接受。实现必须在相应的 RouteParentStatus 中引发状态为 False 的“Accepted”条件。 如果多个 HTTPRoute 指定了交叉主机名（例如，重叠的通配符匹配和精确匹配的主机名），则必须优先考虑来自具有最多数量的 HTTPRoute 中的规则 匹配的非通配符主机名中的字符。 匹配主机名中的字符。 如果在多个路由之间存在平局，则 HTTPRouteMatches 的匹配优先级规则将接管。 支持：核心
rules []HTTPRoute 规则	(可选) 规则是 HTTP 匹配器、过滤器和操作的列表。

HTTPRouteStatus

（出现在： HTTPRoute， HTTPRoute）

HTTPRouteStatus 定义了 HTTPRoute 的观察状态。

字段	描述
RouteStatus RouteStatus	（RouteStatus 的成员嵌入到此类型中。）

HTTPRouteTimeouts

（出现在： HTTPRouteRule）

HTTPRouteTimeouts 定义了可以为 HTTPRoute 配置的超时。

字段	描述
请求 持续时间	(可选) Request 指定网关响应 HTTP 请求的最大持续时间。如果网关在满足此截止日期之前无法响应，则网关 MUST 返回超时错误。 例如，在 HTTPRoute 中将rules.timeouts.request字段设置为值10s将导致超时，如果客户端请求花费超过 10 秒才能完成。 将超时设置为零持续时间（例如“0s”）SHOULD 完全禁用超时。无法完全禁用超时的实现 MUST 将零持续时间解释为超时可以设置的最长可能值。 此超时旨在尽可能涵盖整个请求-响应事务，尽管实现 MAY 选择在接收整个请求流之后开始超时，而不是在客户端启动事务后立即开始超时。 当此字段未指定时，请求超时行为是实现特定的。 支持：扩展
backendRequest 持续时间	(可选) BackendRequest 指定网关向后端发出单个请求的超时。这涵盖了从网关首次开始发送请求到从后端接收完整响应的时间。 将超时设置为零持续时间（例如“0s”）SHOULD 完全禁用超时。无法完全禁用超时的实现 MUST 将零持续时间解释为超时可以设置的最长可能值。 与网关的整个客户端 HTTP 事务，由 Request 超时涵盖，可能导致网关向目标后端发出多个调用，例如，如果支持自动重试。 由于 Request 超时包含 BackendRequest 超时，因此 BackendRequest 的值必须 <= Request 超时的值。 支持：扩展

HTTPURLRewriteFilter

(出现在: HTTPRouteFilter)

HTTPURLRewriteFilter 定义了一个在转发过程中修改请求的过滤器。路由规则最多可以使用一个这样的过滤器。这 MUST NOT 与 HTTPRequestRedirect 过滤器在同一路由规则上使用。

支持：扩展

网关：实验性

字段	描述
hostname PreciseHostname	(可选) Hostname 是在转发过程中用于替换 Host 标头值的 value。 支持：扩展
path HTTPPathModifier	(可选) Path 定义路径重写。 支持：扩展

HeaderMatchType（string 别名）

（出现在： GRPCHeaderMatch， HTTPHeaderMatch）

HeaderMatchType 指定如何比较 HTTP 标头值的语义。有效的 HeaderMatchType 值，以及它们的符合性级别，为

• “Exact” - 核心
• “RegularExpression” - 实现特定支持

请注意，可以将值添加到此枚举中，实现必须确保未知值不会导致崩溃。

此处未知的值必须导致实现将路由的 Accepted Condition 设置为 status: False，原因是 UnsupportedValue。

价值	描述
"Exact"
"RegularExpression"

HeaderName（string 别名）

HeaderName 是标头或查询参数的名称。

Hostname（string 别名）

（出现在： GRPCRouteSpec， HTTPRouteSpec， Listener， TLSRouteSpec）

Hostname 是网络主机的完全限定域名。这与 RFC 1123 对主机名的定义相匹配，有两个值得注意的例外

1. 不允许使用 IP。
2. 主机名可以以通配符标签（*.）为前缀。通配符标签必须以第一个标签的形式单独出现。

Hostname 可以是“精确的”，它是一个没有网络主机终止点的域名（例如“foo.example.com”），或者“通配符”，它是一个以单个通配符标签（例如*.example.com）为前缀的域名。

请注意，根据 RFC1035 和 RFC1123，标签必须由小写字母数字字符或“ - ”组成，并且必须以字母数字字符开头和结尾。不允许使用其他标点符号。

Kind（string 别名）

（出现在： BackendObjectReference，LocalObjectReference，LocalParametersReference，ObjectReference，ParametersReference，ParentReference，RouteGroupKind，SecretObjectReference，LocalPolicyTargetReference，NamespacedPolicyTargetReference，ReferenceGrantFrom，ReferenceGrantTo）

Kind 指的是 Kubernetes Kind。

有效值包括

• “Service”
• “HTTPRoute”

无效值包括

• “invalid/kind” - “/” 是无效字符

Listener

（出现在： GatewaySpec）

Listener 体现了网关接受网络连接的逻辑端点的概念。

字段	描述
name SectionName	Name 是 Listener 的名称。此名称 MUST 在网关内唯一。 支持：核心
hostname Hostname	(可选) Hostname 指定要匹配的虚拟主机名，用于定义此概念的协议类型。当未指定时，匹配所有主机名。此字段对于不需要基于主机名匹配的协议会被忽略。 实现 MUST 针对以下每种协议适当地应用主机名匹配 TLS：Listener Hostname MUST 与 SNI 匹配。 HTTP：Listener Hostname MUST 与请求的 Host 标头匹配。 HTTPS：Listener Hostname SHOULD 与如上所述的 TLS 和 HTTP 协议层匹配。如果实现不确保 SNI 和 Host 标头都与 Listener 主机名匹配，则 MUST 明确记录这一点。 对于 HTTPRoute 和 TLSRoute 资源，存在与spec.hostnames数组的交互。当侦听器和路由都指定主机名时，MUST 在路由被接受的值之间存在交集。有关更多信息，请参阅路由特定主机名文档。 以通配符标签 (*.) 为前缀的主机名被解释为后缀匹配。这意味着，与 *.example.com 的匹配将同时匹配 test.example.com 和 foo.test.example.com，但不匹配 example.com。 支持：核心
port PortNumber	Port 是网络端口。多个侦听器可以使用相同的端口，但要遵守侦听器兼容性规则。 支持：核心
协议 ProtocolType	Protocol 指定此侦听器期望接收的网络协议。 支持：核心
tls GatewayTLSConfig	(可选) TLS 是 Listener 的 TLS 配置。如果 Protocol 字段为“HTTPS”或“TLS”，则此字段是必需的。如果 Protocol 字段为“HTTP”、“TCP”或“UDP”，则设置此字段无效。 在 GatewayTLSConfig 中定义的 SNI 与证书的关联是根据此侦听器的 Hostname 字段定义的。 GatewayClass MUST 使用所有可用证书中与任何 TLS 握手匹配的最长 SNI。 支持：核心
allowedRoutes AllowedRoutes	(可选) AllowedRoutes 定义了 MAY 附加到侦听器的路由类型以及这些路由资源 MAY 出现在其中的受信任命名空间。 虽然客户端请求可能匹配多个路由规则，但最终只有一个规则 MAY 接收请求。匹配优先级 MUST 按照以下标准顺序确定 路由类型定义的最具体匹配。 根据创建时间最旧的路由。例如，创建时间为“2020-09-08 01:02:03”的路由优先于创建时间为“2020-09-08 01:02:04”的路由。 如果其他所有内容都相同，则按字母顺序（命名空间/名称）首先出现的路由应优先考虑。例如，foo/bar 优先于 foo/baz。 应实现附加到此侦听器的路由中的所有有效规则。可以忽略无效的路由规则（有时这意味着整个路由）。如果路由规则从有效变为无效，则应放弃对该路由规则的支持以确保一致性。例如，即使由路由规则指定的过滤器无效，该路由中的其余规则也应继续得到支持。 支持：核心

ListenerConditionReason（string 别名）

ListenerConditionReason 定义了一组原因，这些原因解释了为什么引发了特定侦听器条件类型。

价值	描述
"Accepted"	此理由用于条件为 True 时的“Accepted”条件。
"Attached"	当条件为 False 时，此原因与“Detached”条件一起使用。 已弃用：请使用带有“Accepted”理由的“Accepted”条件代替。
"HostnameConflict"	当侦听器与其他侦听器中的主机名冲突时，此原因与“Conflicted”条件一起使用。例如，当同一端口上的多个侦听器在主机名字段中使用example.com时，将使用此原因。
"Invalid"	当侦听器在语法上或语义上无效时，此原因与“Ready”和“Programmed”条件一起使用。
"InvalidCertificateRef"	当侦听器具有 TLS 配置，该配置至少包含一个无效或不存在的 TLS CertificateRef 时，此原因与“ResolvedRefs”条件一起使用。当 CertificateRef 引用不存在或不受支持的资源或种类，或者当该资源中的数据格式错误时，CertificateRef 被视为无效。此原因必须仅在允许引用时使用，可以通过引用与网关相同的命名空间中的对象，或者当 ReferenceGrant 显式地允许跨命名空间引用时。如果引用不允许，则必须改为使用原因 RefNotPermitted。
"InvalidRouteKinds"	当侦听器指定了无效或不支持的路由种类时，此原因与“ResolvedRefs”条件一起使用。
"NoConflicts"	当条件为 False 时，此原因与“Conflicted”条件一起使用。
"Pending"	当侦听器尚未协调或尚未在线并准备接受客户端流量时，此原因与“Accepted”、“Ready”和“Programmed”条件一起使用。
"PortUnavailable"	当侦听器请求无法在网关上使用的端口时，此原因与“Accepted”条件一起使用。此原因可以在许多情况下使用，包括 该端口已被使用。 该端口不受实现支持。
"Programmed"	此理由用于条件为真时的“Programmed”条件。
"ProtocolConflict"	当指定了多个侦听器，它们具有相同的侦听器端口号，但具有冲突的协议规范时，此原因与“Conflicted”条件一起使用。
"Ready"	已弃用：Ready 预留供将来使用
"RefNotPermitted"	当侦听器具有 TLS 配置，该配置引用了另一个命名空间中的对象，而另一个命名空间中的对象没有 ReferenceGrant 显式地允许引用时，此原因与“ResolvedRefs”条件一起使用。
"ResolvedRefs"	当条件为 True 时，此原因与“ResolvedRefs”条件一起使用。
"UnsupportedProtocol"	当侦听器无法附加到网关，因为它不支持其协议类型时，此原因与“Accepted”条件一起使用。

ListenerConditionType（string 别名）

ListenerConditionType 是与侦听器关联的条件类型。此类型应与 ListenerStatus.Conditions 字段一起使用。

价值	描述
"Accepted"	此条件表示侦听器在语法上和语义上都是有效的，并且侦听器规范中使用的所有功能都得到支持。 通常，当提供的配置将生成至少一些数据平面配置时，侦听器将被标记为已接受。 例如，使用不受支持协议的监听器永远不会生成任何数据平面配置，因此其 Accepted 设置为 false。 反之，没有路由的监听器将能够生成数据平面配置，因此其 Accepted 设置为 true。 此条件为真时可能的原因是 “Accepted” 此条件为假时可能的原因是 “端口不可用” “不支持的协议” 此条件为 Unknown 时可能的原因是 “Pending” 控制器可能会使用其他理由引发此条件，但应优先使用上面列出的理由以提高互操作性。
"冲突"	此状态表示控制器无法解决此监听器的冲突规范要求。如果监听器发生冲突，则其网络端口不应配置在任何网络元素上。 此条件为真时可能的原因是 “主机名冲突” “协议冲突” 此条件为假时可能的原因是 “无冲突” 控制器可能会使用其他理由引发此条件，但应优先使用上面列出的理由以提高互操作性。
"已分离"	已弃用：请使用“Accepted”代替。
"Programmed"	此状态指示监听器是否已生成一些配置，这些配置将很快在底层数据平面中准备就绪。 这是一个正极性摘要条件，因此应始终与设置了 ObservedGeneration 的资源一起出现。 如果控制器在具有所有必需信息来确定条件是否为真之前执行状态更新，则应将其设置为 Unknown。 此条件为真时可能的原因是 “Programmed” 此条件为假时可能的原因是 “Invalid” “Pending” 此条件为 Unknown 时可能的原因是 “Pending” 控制器可能会使用其他理由引发此条件，但应优先使用上面列出的理由以提高互操作性。
"Ready"	“准备就绪”是一种为将来使用而保留的状态类型。实现中不应使用它。注意：此状态并非真正“已弃用”，而是“保留”；但是，已弃用会触发 Go linter 提醒使用情况。 如果将来使用，“Ready” 将表示所有配置都确认良好且已完全传播到底层数据平面的最终状态。也就是说，它是一个保证，只要任何东西看到条件为 true，那么连接将立即正确路由。 这是一个非常强大的保证，到目前为止还没有任何实现能够满足它以实施它。如果需要，可以将来讨论此保留。 已弃用：Ready 预留供将来使用
"ResolvedRefs"	此状态指示控制器是否能够解析监听器的所有对象引用。 此条件为真时可能的原因是 “已解析引用” 此条件为假时可能的原因是 “无效证书引用” “无效路由种类” “引用不允许” 控制器可能会使用其他理由引发此条件，但应优先使用上面列出的理由以提高互操作性。

ListenerStatus

（出现在： GatewayStatus）

ListenerStatus 是与监听器关联的状态。

字段	描述
name SectionName	名称是此状态对应的监听器名称。
支持的种类 []路由组类型	SupportedKinds 是一个列表，指示此监听器支持的种类。这必须代表实现对此监听器配置支持的种类。 如果在 Spec 中指定了不受支持的种类，则这些种类必须不显示在此列表中，并且实现必须将“已解析引用”状态设置为“False”，并使用“无效路由种类”原因。如果同时指定了有效的和无效的路由种类，则实现必须引用已指定的有效路由种类。
附加的路由 int32	AttachedRoutes 表示已成功附加到此监听器的路由总数。 将路由成功附加到监听器仅基于相应监听器的 AllowedRoutes 字段和路由的 ParentRefs 字段的组合。当路由被监听器的 AllowedRoutes 字段选中，并且路由具有选择整个网关资源或特定监听器作为父资源的有效 ParentRef 时，路由将成功附加到监听器（有关附加语义的更多详细信息，请参阅有关各种路由种类 ParentRefs 字段的文档）。监听器或路由状态不会影响成功附加，即 AttachedRoutes 字段计数必须为具有状态 Accepted: false 的监听器设置，并且必须计算可能具有状态 Accepted: false 的已成功附加的路由。 此字段的用途包括对路由附加进行故障排除，以及测量监听器更改的爆炸半径/影响。
conditions []Kubernetes meta/v1.Condition	状态描述此监听器的当前状态。

LocalObjectReference

(出现在： GRPCRouteFilter、HTTPRouteFilter、BackendTLSPolicyValidation)

LocalObjectReference 标识引用者命名空间内的 API 对象。API 对象必须在集群中有效；组和种类必须在集群中注册，才能使此引用有效。

对组和 Kind 无效的对象的引用无效，并且必须由实现拒绝，并在包含对象上设置适当的条件。

字段	描述
group Group	Group 是引用的组。例如，“gateway.networking.k8s.io”。如果未指定或为空字符串，则推断核心 API 组。
kind Kind	种类是引用的种类。例如“HTTPRoute”或“Service”。
name ObjectName	Name 是引用的名称。

LocalParametersReference

(出现在： GatewayInfrastructure)

LocalParametersReference 标识命名空间内包含控制器特定配置资源的 API 对象。

字段	描述
group Group	组是引用的组。
kind Kind	种类是引用的种类。
name 字符串	Name 是引用的名称。

命名空间（string 别名）

(出现在： BackendObjectReference、ObjectReference、ParametersReference、ParentReference、SecretObjectReference、NamespacedPolicyTargetReference、ReferenceGrantFrom)

命名空间指的是 Kubernetes 命名空间。它必须是 RFC 1123 标签。

此验证基于相应的 Kubernetes 验证：https://github.com/kubernetes/apimachinery/blob/02cfb53916346d085a6c6c7c66f882e3c6b0eca6/pkg/util/validation/validation.go#L187

此验证用于此处命名空间名称验证：https://github.com/kubernetes/apimachinery/blob/02cfb53916346d085a6c6c7c66f882e3c6b0eca6/pkg/api/validation/generic.go#L63

有效值包括

• “example”

无效值包括

• “example.com” - “.” 是无效字符

ObjectName（string 别名）

(出现在： BackendObjectReference、GatewaySpec、LocalObjectReference、ObjectReference、ParentReference、SecretObjectReference、LocalPolicyTargetReference、NamespacedPolicyTargetReference、ReferenceGrantTo)

ObjectName 指的是 Kubernetes 对象的名称。对象名称可以有多种形式，包括 RFC 1123 子域、RFC 1123 标签或 RFC 1035 标签。

ObjectReference

(出现在： FrontendTLSValidation)

ObjectReference 标识 API 对象，包括其命名空间。

API 对象必须在集群中有效；组和 Kind 必须在集群中注册，该引用才有效。

对组和 Kind 无效的对象的引用无效，并且必须由实现拒绝，并在包含对象上设置适当的条件。

字段	描述
group Group	Group 是引用的组。例如，“gateway.networking.k8s.io”。如果未指定或为空字符串，则推断核心 API 组。
kind Kind	种类是引用的种类。例如“ConfigMap”或“Service”。
name ObjectName	Name 是引用的名称。
namespace Namespace	(可选) 命名空间是所引用对象的命名空间。未指定时，将推断本地命名空间。 请注意，当指定与本地命名空间不同的命名空间时，需要在引用命名空间中创建 ReferenceGrant 对象，以允许该命名空间的所有者接受引用。有关详细信息，请参阅 ReferenceGrant 文档。 支持：核心

ParametersReference

(出现在： GatewayClassSpec)

ParametersReference 标识包含控制器特定配置资源的 API 对象，该对象位于集群中。

字段	描述
group Group	组是引用的组。
kind Kind	种类是引用的种类。
name 字符串	Name 是引用的名称。
namespace Namespace	(可选) 命名空间是引用的命名空间。此字段在引用命名空间范围的资源时是必需的，在引用集群范围的资源时必须取消设置。

ParentReference

(出现在： CommonRouteSpec、RouteParentStatus、PolicyAncestorStatus)

ParentReference 标识可以被视为此资源（通常是路由）的父级的 API 对象（通常是网关）。唯一具有“核心”支持的父资源种类是网关。此 API 可能会在将来扩展以支持其他种类的父资源，例如 HTTPRoute。

请注意，跨命名空间边界的 ParentRefs 有特定规则。跨命名空间引用只有在它们被引用的命名空间中的某个内容明确允许时才有效。例如：网关具有 AllowedRoutes 字段，ReferenceGrant 提供了一种通用方式来启用任何其他种类的跨命名空间引用。

API 对象必须在集群中有效；组和 Kind 必须在集群中注册，该引用才有效。

字段	描述
group Group	(可选) 组是引用的组。未指定时，将推断“gateway.networking.k8s.io”。要设置核心 API 组（例如“Service”种类引用），组必须明确设置为“” （空字符串）。 支持：核心
kind Kind	(可选) 种类是引用的种类。 有两种具有“核心”支持的父资源类型 网关（网关一致性配置文件） 服务（网格一致性配置文件，仅限 ClusterIP 服务） 对其他资源的支持是实现特定的。
namespace Namespace	(可选) 命名空间是引用的命名空间。未指定时，它指的是路由的本地命名空间。 请注意，跨命名空间边界的 ParentRefs 有特定规则。跨命名空间引用只有在它们被引用的命名空间中的某个内容明确允许时才有效。例如：网关具有 AllowedRoutes 字段，ReferenceGrant 提供了一种通用方式来启用任何其他种类的跨命名空间引用。 gateway:experimental:description 来自路由到同一命名空间中的服务的 ParentRefs 是“生产者”路由，它们将默认路由规则应用于来自任何命名空间到服务的入站连接。 来自路由到不同命名空间中的服务的 ParentRefs 是“消费者”路由，这些路由规则仅应用于源自与路由相同命名空间的出站连接，这些连接的目标是作为路由的 ParentRef 的服务。/gateway:experimental:description 支持：核心
name ObjectName	Name 是引用的名称。 支持：核心
部分名称 SectionName	(可选) SectionName 是目标资源中某个部分的名称。在以下资源中，SectionName 被解释为以下内容 网关：监听器名称。当同时指定端口（实验性）和 SectionName 时，选定监听器的名称和端口必须与两个指定的值匹配。 服务：端口名称。当同时指定端口（实验性）和 SectionName 时，选定监听器的名称和端口必须与两个指定的值匹配。 实现可以自由选择支持将路由附加到其他资源。如果是这种情况，则必须明确记录 SectionName 的解释方式。 未指定（空字符串）时，它将引用整个资源。出于状态目的，如果父资源中的至少一个部分接受附加，则附加被视为成功。例如，网关监听器可以通过路由种类、命名空间或主机名来限制哪些路由可以附加到它们。如果 2 个网关监听器中的 1 个接受来自引用路由的附加，则路由必须被视为已成功附加。如果没有任何网关监听器接受来自此路由的附加，则路由必须被视为已从网关分离。 支持：核心
port PortNumber	(可选) 端口是此路由所针对的网络端口。它可以根据父资源类型进行不同的解释。 当父资源是网关时，这会针对所有在指定端口上监听并同时支持此种路由（并选择此路由）的监听器。除非路由中指定的网络行为必须应用于特定端口，而不是应用于端口可能更改的监听器，否则不建议设置 Port。当同时指定端口和 SectionName 时，选定监听器的名称和端口必须与两个指定的值匹配。 gateway:experimental:description 当父资源是服务时，这会针对服务规范中的特定端口。当同时指定端口（实验性）和 SectionName 时，选定端口的名称和端口必须与两个指定的值匹配。 /gateway:experimental:description 实现可以自由选择支持其他父资源。支持其他类型父资源的实现必须明确记录端口的解释方式/是否解释。 出于状态目的，只要父资源部分接受附加，附加就被视为成功。例如，网关监听器可以通过路由种类、命名空间或主机名来限制哪些路由可以附加到它们。如果 2 个网关监听器中的 1 个接受来自引用路由的附加，则路由必须被视为已成功附加。如果没有任何网关监听器接受来自此路由的附加，则路由必须被视为已从网关分离。 支持：扩展

PathMatchType（string 别名）

(出现在： HTTPPathMatch)

PathMatchType 指定如何比较 HTTP 路径的语义。有效的 PathMatchType 值及其一致性级别如下

• “Exact” - 核心
• “PathPrefix” - 核心
• “RegularExpression” - 实现特定支持

PathPrefix 和 Exact 路径必须在语法上有效

• 必须以 / 字符开头
• 不能包含连续的 / 字符（例如 /foo///、//）。

请注意，可以将值添加到此枚举中，实现必须确保未知值不会导致崩溃。

此处未知的值必须导致实现将路由的 Accepted Condition 设置为 status: False，原因是 UnsupportedValue。

价值	描述
"Exact"	精确匹配 URL 路径，并且区分大小写。这意味着，/abc 上的精确路径匹配将仅匹配对 /abc 的请求，而不是 /abc/、/Abc 或 /abcd。
"PathPrefix"	基于 URL 路径前缀匹配，并以 / 分隔。匹配区分大小写，并按路径元素逐个进行。路径元素指的是路径中以 / 分隔符分隔的标签列表。如果指定，则会忽略尾部的 /。 例如，路径 /abc、/abc/ 和 /abc/def 将全部匹配前缀 /abc，但路径 /abcd 则不会匹配。 “PathPrefix” 在语义上等效于 Kubernetes Ingress API 中的“Prefix” 路径类型。
"RegularExpression"	如果 URL 路径与给定的正则表达式匹配，则匹配，并且区分大小写。 由于 "RegularExpression" 具有实现特定支持的符合性，因此实现可以支持 POSIX、PCRE、RE2 或任何其他正则表达式方言。请阅读实现的文档以确定支持的方言。

PortNumber（int32 别名）

(出现在： BackendObjectReference、HTTPRequestRedirectFilter、Listener、ParentReference)

PortNumber 定义网络端口。

PreciseHostname（string 别名）

(出现在： HTTPRequestRedirectFilter、HTTPURLRewriteFilter、BackendTLSPolicyValidation)

PreciseHostname 是网络主机的完全限定域名。这与 RFC 1123 中对主机名的定义相匹配，但有一个显著的例外：不允许使用数字 IP 地址。

请注意，根据 RFC1035 和 RFC1123，标签必须由小写字母数字字符或“ - ”组成，并且必须以字母数字字符开头和结尾。不允许使用其他标点符号。

ProtocolType（string 别名）

(出现在： 监听器)

ProtocolType 定义了 Listener 接受的应用程序协议。实现不需要接受所有定义的协议。如果实现不支持指定的协议，则 MUST 将受影响的 Listener 的“Accepted”条件设置为 False，原因是“UnsupportedProtocol”。

核心 ProtocolType 值列于下表。

如果核心 ProtocolType 不存在，实现可以定义自己的协议。此类定义必须使用带前缀的名称，例如 mycompany.com/my-custom-protocol。无前缀的名称保留用于核心协议。实现定义的任何协议都将属于特定于实现的符合性。

有效值包括

• “HTTP” - 核心支持
• “example.com/bar” - 特定于实现的支持

无效值包括

• “example.com” - 如果使用域名，则必须包含路径
• “foo.example.com” - 如果使用域名，则必须包含路径

价值	描述
"HTTP"	接受通过 TCP 的明文 HTTP/1.1 会话。实现 MAY 也支持通过明文的 HTTP/2。如果实现支持通过“HTTP”监听器上的明文传输 HTTP/2，则 MUST 由实现明确记录。
"HTTPS"	接受通过 TLS 的 HTTP/1.1 或 HTTP/2 会话。
"TCP"	接受 TCP 会话。
"TLS"	接受通过 TCP 的 TLS 会话。
"UDP"	接受 UDP 数据包。

QueryParamMatchType (string 别名)

(出现在： HTTPQueryParamMatch)

QueryParamMatchType 指定了如何比较 HTTP 查询参数值的语义。有效的 QueryParamMatchType 值及其符合性级别如下：

• “Exact” - 核心
• “RegularExpression” - 实现特定支持

请注意，可以将值添加到此枚举中，实现必须确保未知值不会导致崩溃。

此处未知的值必须导致实现将路由的 Accepted Condition 设置为 status: False，原因是 UnsupportedValue。

价值	描述
"Exact"
"RegularExpression"

RouteConditionReason (string 别名)

RouteConditionReason 是路由条件的原因。

价值	描述
"Accepted"	当路由被网关接受时，此原因与“Accepted”条件一起使用。
"BackendNotFound"	当路由的其中一个规则引用了一个不存在的资源时，此原因与“ResolvedRefs”条件一起使用。
"IncompatibleFilters"	当路由规则上存在不兼容的过滤器时（例如，如果 URLRewrite 和 RequestRedirect 同时存在于 HTTPRoute 上），此原因与“Accepted”条件一起使用。
"InvalidKind"	当路由的其中一个规则引用了一个未知或不支持的组和/或类型时，此原因与“ResolvedRefs”条件一起使用。
"NoMatchingListenerHostname"	当网关没有兼容的监听器，其主机名与路由匹配时，此原因与“Accepted”条件一起使用。
"NoMatchingParent"	当没有匹配的父资源时，此原因与“Accepted”条件一起使用。在网关的情况下，当路由 ParentRef 指定了与网关中的任何监听器不匹配的端口和/或节名称时，可能会发生这种情况。
"NotAllowedByListeners"	当路由未被网关接受，因为网关没有监听器，其允许的路由标准允许路由时，此原因与“Accepted”条件一起使用。
"Pending"	此原因与“Accepted”条件一起使用，当控制器尚未协调路由时。
"RefNotPermitted"	当监听器的其中一个路由的 BackendRef 指向另一个命名空间中的对象时，该对象在另一个命名空间中没有明确允许引用的 ReferenceGrant，此原因与“ResolvedRefs”条件一起使用。
"ResolvedRefs"	当条件为 True 时，此原因与“ResolvedRefs”条件一起使用。
"UnsupportedProtocol"	当路由的其中一个规则引用了一个资源，该资源具有此实现不支持的应用程序协议时，此原因与“ResolvedRefs”条件一起使用。
"UnsupportedValue"	当枚举的值不被识别时，此原因与“Accepted”条件一起使用。

RouteConditionType (string 别名)

RouteConditionType 是路由的条件类型。

价值	描述
"Accepted"	此条件指示路由是否被网关接受或拒绝，以及原因。 此条件为真时可能的原因是 “Accepted” 此条件为假时可能的原因是 “NotAllowedByListeners” “NoMatchingListenerHostname” “NoMatchingParent” “UnsupportedValue” 此条件为 Unknown 时可能的原因是 “Pending” 控制器可能会使用其他理由引发此条件，但应优先使用上面列出的理由以提高互操作性。
"PartiallyInvalid"	此条件指示路由包含有效规则和无效规则的组合。 当这种情况发生时，实现 MUST 采用以下方法之一 1) 丢弃规则：使用这种方法，实现将丢弃无效的路由规则，直到它们再次完全有效。此条件的消息 MUST 以“Dropped Rule”为前缀，并包含有关哪些规则被丢弃的信息。在这种状态下，“Accepted”条件 MUST 设置为“True”，并使用资源的最新代。 恢复到最后一个已知良好状态应该只由具有恢复该状态的方法的实现来执行，以防它们在重新启动时需要恢复。 如果路由完全有效、完全无效或未被接受，则此条件 MUST NOT 设置。由此推断，这意味着此条件 MUST 仅在为“True”时设置。 此条件为真时可能的原因是 “UnsupportedValue” 控制器可能会使用其他理由引发此条件，但应优先使用上面列出的理由以提高互操作性。
"ResolvedRefs"	此条件指示控制器是否能够解析路由的所有对象引用。 此条件为真时可能的原因是 “已解析引用” 此条件为假时可能的原因是 “引用不允许” “InvalidKind” “BackendNotFound” “不支持的协议” 控制器可能会使用其他理由引发此条件，但应优先使用上面列出的理由以提高互操作性。

RouteGroupKind

(出现在： AllowedRoutes, ListenerStatus)

RouteGroupKind 指示路由资源的组和类型。

字段	描述
group Group	(可选) Group 是路由的组。
kind Kind	Kind 是路由的类型。

RouteNamespaces

(出现在： AllowedRoutes)

RouteNamespaces 指示应从哪些命名空间中选择路由。

字段	描述
from FromNamespaces	(可选) From 指示将从哪里为该网关选择路由。可能的值为 All：此网关可以使用所有命名空间中的路由。 Selector：此网关可以使用选择器选择的命名空间中的路由。 Same：此网关只能使用同一命名空间中的路由。 支持：核心
selector Kubernetes meta/v1.LabelSelector	(可选) 当 From 设置为“Selector”时，必须指定 Selector。在这种情况下，此网关只会选择与该 Selector 匹配的命名空间中的路由。此字段对于“From”的其他值将被忽略。 支持：核心

RouteParentStatus

(出现在： RouteStatus)

RouteParentStatus 描述了路由相对于关联父资源的状态。

字段	描述
parentRef ParentReference	ParentRef 与规范中的 ParentRef 相对应，该结构描述了 RouteParentStatus 的状态。
控制器名称 网关控制器	ControllerName 是一个域/路径字符串，指示写入此状态的控制器的名称。这与 GatewayClass 上的 controllerName 字段相对应。 示例：“example.net/gateway-controller”。 此字段的格式为 DOMAIN“/”PATH，其中 DOMAIN 和 PATH 是有效的 Kubernetes 名称 (https://kubernetes.ac.cn/docs/concepts/overview/working-with-objects/names/#names). 控制器 MUST 在写入状态时填充此字段。控制器应该确保用其 ControllerName 填充状态的条目在不再需要时被清除。
conditions []Kubernetes meta/v1.Condition	Conditions 描述了路由相对于网关的状态。请注意，路由的可用性也取决于网关自身的狀態条件和监听器狀態。 如果路由的 ParentRef 指定了一个现有的网关，该网关支持此类路由并且该网关的控制器具有足够的访问权限，则该网关的控制器 MUST 在路由上设置“Accepted”条件，以指示路由是否被网关接受或拒绝，以及原因。 如果路由的至少一个规则由网关实现，则路由 MUST 被视为“Accepted”。 在某些情况下，“Accepted”条件可能由于缺乏控制器可见性而未被设置，包括以下情况： 路由引用一个不存在的父资源。 路由的类型是控制器不支持的类型。 路由位于控制器无权访问的命名空间中。

RouteStatus

(出现在： GRPCRouteStatus, HTTPRouteStatus, TCPRouteStatus, TLSRouteStatus, UDPRouteStatus)

RouteStatus 定义了所有路由 MUST 在其状态中包含的通用属性。

字段	描述
parents []RouteParentStatus	Parents 是与路由关联的父资源（通常是网关）列表，以及路由相对于每个父资源的状态。当此路由附加到父资源时，管理父资源的控制器必须在控制器第一次看到路由时向此列表添加一个条目，并且应该在路由或网关被修改时适当地更新条目。 请注意，此 API 的实现无法解析的父资源引用不会添加到此列表中。此 API 的实现只能填充其负责的网关/父资源的路由状态。 此列表中最多表示 32 个网关。空列表表示路由未附加到任何网关。

SecretObjectReference

(出现于： GatewayTLSConfig)

SecretObjectReference 标识一个 API 对象，包括其命名空间，默认为 Secret。

API 对象必须在集群中有效；组和 Kind 必须在集群中注册，该引用才有效。

对组和 Kind 无效的对象的引用无效，并且必须由实现拒绝，并在包含对象上设置适当的条件。

字段	描述
group Group	(可选) Group 是引用的组。例如，“gateway.networking.k8s.io”。如果未指定或为空字符串，则推断核心 API 组。
kind Kind	(可选) Kind 是引用的类型。例如“Secret”。
name ObjectName	Name 是引用的名称。
namespace Namespace	(可选) 命名空间是所引用对象的命名空间。未指定时，将推断本地命名空间。 请注意，当指定与本地命名空间不同的命名空间时，需要在引用命名空间中创建 ReferenceGrant 对象，以允许该命名空间的所有者接受引用。有关详细信息，请参阅 ReferenceGrant 文档。 支持：核心

SectionName (string 别名)

(出现在： Listener, ListenerStatus, ParentReference, LocalPolicyTargetReferenceWithSectionName)

SectionName 是 Kubernetes 资源中节的名称。

在以下资源中，SectionName 被解释为：

• Gateway：监听器名称
• HTTPRoute：HTTPRouteRule 名称
• Service：端口名称

节名称可以有多种形式，包括 RFC 1123 子域、RFC 1123 标签或 RFC 1035 标签。

此验证基于相应的 Kubernetes 验证：https://github.com/kubernetes/apimachinery/blob/02cfb53916346d085a6c6c7c66f882e3c6b0eca6/pkg/util/validation/validation.go#L208

有效值包括

• “example”
• “foo-example”
• “example.com”
• “foo.example.com”

无效值包括

• “example.com/bar” - “/” 是一个无效字符

SessionPersistence

(出现在： GRPCRouteRule, HTTPRouteRule, BackendLBPolicySpec)

SessionPersistence 定义了 SessionPersistence 的期望状态。

字段	描述
sessionName 字符串	(可选) SessionName 定义了持久会话令牌的名称，该令牌可能反映在 cookie 或标题中。用户应避免重复使用会话名称，以防止意外后果，例如拒绝或不可预测的行为。 支持：实现特定
absoluteTimeout 持续时间	(可选) AbsoluteTimeout 定义了持久会话的绝对超时时间。一旦 AbsoluteTimeout 持续时间过去，会话就变得无效。 支持：扩展
idleTimeout 持续时间	(可选) IdleTimeout 定义了持久会话的空闲超时时间。一旦会话空闲时间超过指定的 IdleTimeout 持续时间，会话就变得无效。 支持：扩展
类型 SessionPersistenceType	(可选) Type 定义了会话持久性的类型，例如通过使用标题或 cookie。默认为基于 cookie 的会话持久性。 支持：对于“Cookie”类型，核心支持。 支持：对于“Header”类型，扩展支持。
cookieConfig CookieConfig	(可选) CookieConfig 提供特定于基于 cookie 的会话持久性的配置设置。 支持：核心

SessionPersistenceType (string 别名)

(出现于： SessionPersistence)

价值	描述
"Cookie"	CookieBasedSessionPersistence 指定基于 cookie 的会话持久性。 支持：核心
"Header"	HeaderBasedSessionPersistence 指定基于标题的会话持久性。 支持：扩展

SupportedFeature (string 别名)

(出现在： GatewayClassStatus)

SupportedFeature 用于描述由符合性测试覆盖的不同功能。

TLSModeType (string 别名)

(出现于： GatewayTLSConfig)

TLSModeType 类型定义了网关如何处理 TLS 会话。

请注意，可以将值添加到此枚举中，实现必须确保未知值不会导致崩溃。

此处的未知值必须导致实现将 Listener 的 Ready 条件设置为 status: False，并以 Invalid 为原因。

价值	描述
"Passthrough"	在这种模式下，网关不会终止 TLS 会话。这意味着网关无法解密 TLS 流，除了 TLS 协议的 ClientHello 消息。 请注意，SSL 直通仅由 TLSRoute 支持。
“终止”	在此模式下，下游客户端与网关之间的 TLS 会话将在网关处终止。

---

gateway.networking.k8s.io/v1beta1

包 v1beta1 包含 gateway.networking.k8s.io API 组的 API 架构定义。

资源类型

• 网关
• 网关类
• HTTPRoute
• ReferenceGrant

网关

Gateway 表示通过将监听器绑定到一组 IP 地址的服务流量处理基础设施的实例。

字段	描述
apiVersion 字符串	gateway.networking.k8s.io/v1beta1
kind 字符串	网关
metadata Kubernetes meta/v1.ObjectMeta	有关 metadata 字段的字段，请参考 Kubernetes API 文档。
spec GatewaySpec	Spec 定义了 Gateway 的期望状态。 gatewayClassName ObjectName 此 Gateway 使用的 GatewayClassName。这是 GatewayClass 资源的名称。 listeners []Listener 与此 Gateway 关联的监听器。监听器定义在此 Gateway 的地址上绑定的逻辑端点。必须至少指定一个监听器。 一组监听器中的每个监听器（例如，单个 Gateway 中的监听器）必须是不同的，因为流量流必须能够分配给正好一个监听器。（本节使用“一组监听器”而不是“单个 Gateway 中的监听器”，因为实现可能会将来自多个 Gateway 的配置合并到单个数据平面，这些规则也适用于这种情况）。 实际上，这意味着一组中的每个监听器必须具有端口、协议和（如果协议支持）主机名的唯一组合。 某些端口、协议和 TLS 设置的组合被认为是核心支持，并且必须由实现根据其目标一致性配置文件来支持 HTTP 配置文件 HTTPRoute，端口：80，协议：HTTP HTTPRoute，端口：443，协议：HTTPS，TLS 模式：终止，TLS 密钥对提供 TLS 配置文件 TLSRoute，端口：443，协议：TLS，TLS 模式：直通 “不同的”监听器具有以下属性 实现可以将入站请求匹配到单个不同的监听器。当多个监听器共享字段值（例如，两个具有相同 Port 值的监听器）时，实现可以使用其他监听器字段将请求匹配到这些监听器中的一个。 例如，以下监听器场景是不同的 具有相同 Port 的多个监听器，它们都使用“HTTP”协议，并且它们都具有唯一的主机名值。 多个使用“HTTPS”或“TLS”协议并具有相同端口的监听器，它们都具有唯一的主机名值。 混合使用“TCP”和“UDP”协议监听器，其中没有使用相同协议的监听器具有相同的端口值。 Listener 结构体中的一些字段可能具有影响 Listener 是否不同的值。主机名对于 HTTP 或 HTTPS 协议尤其重要。 当使用主机名值在具有相同端口和相同协议的 Listener 之间进行选择时，每个 Listener 上的主机名值必须不同，才能使 Listener 不同。 当 Listener 基于主机名不同时，入站请求主机名必须从最具体到最不具体的主机名值匹配，以选择正确的 Listener 及其关联的路由集。 精确匹配必须在通配符匹配之前处理，通配符匹配必须在回退（空主机名值）匹配之前处理。例如，"foo.example.com" 优先于 "*.example.com"，"*.example.com" 优先于 ""。 此外，如果存在多个通配符条目，则必须在处理较不具体的通配符条目之前处理更具体的通配符条目。例如，"*.foo.example.com" 优先于 "*.example.com"。这里的精确定义是，通配符字符右侧主机名中点的数量越多，优先级越高。 通配符字符将匹配左侧的任何数量的字符和点，因此 "*.example.com" 将匹配 "foo.bar.example.com" 和 "bar.example.com"。 如果一组 Listener 包含不不同的 Listener，则这些 Listener 发生冲突，实现必须将 Listener 状态中的“冲突”条件设置为“True”。 实现可以选择仅在它们仅接受不包含任何冲突 Listener 的部分 Listener 集时接受具有某些冲突 Listener 的网关。换句话说，实现可能只在它们丢弃所有冲突 Listener 时才接受部分 Listener 集。不选择冲突 Listener 中的任何一个作为获胜者。这也意味着网关在这种情况下必须至少有一个非冲突 Listener，否则它违反了必须至少存在一个 Listener 的要求。 当网关包含冲突 Listener 时，无论它们是否接受网关，实现都必须在网关状态上设置“ListenersNotValid”条件。该条件应在消息中清楚地指示哪些 Listener 发生冲突，以及哪些被接受。此外，这些 Listener 的 Listener 状态应指示哪些 Listener 发生冲突且未被接受。 网关的 Listener 被认为是“兼容”的，如果 它们是不同的。 实现可以在遵守所有 Listener 都在所有分配的地址上可用的地址要求的情况下为它们提供服务。 扩展支持中的兼容组合预计会在不同实现之间有所不同。对于一个实现兼容的组合可能对于另一个实现不兼容。 例如，一个实现无法在同一地址上同时提供 TCP 和 UDP 监听器，或者无法在同一端口上混合使用 HTTPS 和通用 TLS 监听器，则不会认为这些情况是兼容的，即使它们是不同的。 请注意，请求应最多匹配一个 Listener。例如，如果为“foo.example.com”和“*.example.com”定义了 Listener，则对“foo.example.com”的请求应仅使用附加到“foo.example.com” Listener 的路由进行路由（而不是“*.example.com” Listener）。这个概念被称为“Listener 隔离”。不支持 Listener 隔离的实现必须明确记录这一点。 实现可以将单独的网关合并到一组地址上，如果所有网关中的所有 Listener 都是兼容的。 支持：核心 地址 []网关地址 (可选) 为该网关请求的地址。这是可选的，行为可能取决于实现。如果在规范中设置了一个值，并且请求的地址无效或不可用，则实现必须在 GatewayStatus.Addresses 中的关联条目中指示这一点。 地址字段表示对“网关外部”地址的请求，绑定到该网关的流量将使用这些地址。这可能是外部负载均衡器或其他网络基础设施的 IP 地址或主机名，或者流量将发送到的其他地址。 如果未指定任何地址，则实现可能会以实现特定方式调度网关，并分配一组适当的地址。 实现必须将所有 Listener 绑定到它分配给网关的每个 GatewayAddress，并在 GatewayStatus.Addresses 中添加一个相应的条目。 支持：扩展 网关：验证 IP 地址 基础设施 网关基础设施 (可选) 基础设施定义了有关此网关实例的基础设施级别属性。 支持：核心 网关：实验性
status 网关状态	状态定义了网关的当前状态。

网关类

网关类描述了用户可用于创建网关资源的网关类。

建议将此资源用作网关的模板。这意味着网关基于创建网关时网关类的状态，对网关类或关联参数的更改不会传播到现有网关。此建议旨在限制对网关类或关联参数的更改的爆炸半径。如果实现选择将网关类更改传播到现有网关，则实现必须明确记录这一点。

只要有一个或多个网关正在使用网关类，实现应在关联的网关类上添加 gateway-exists-finalizer.gateway.networking.k8s.io 终结器。这确保了与网关关联的网关类在使用时不会被删除。

网关类是集群级别资源。

字段	描述
apiVersion 字符串	gateway.networking.k8s.io/v1beta1
kind 字符串	网关类
metadata Kubernetes meta/v1.ObjectMeta	有关 metadata 字段的字段，请参考 Kubernetes API 文档。
spec 网关类规格	规格定义了网关类的期望状态。 控制器名称 网关控制器 ControllerName 是管理此类网关的控制器的名称。此字段的值必须是域前缀路径。 示例：“example.net/gateway-controller”。 此字段不可变，不能为空。 支持：核心 参数引用 参数引用 (可选) ParametersRef 是对包含与网关类对应的配置参数的资源的引用。如果控制器不需要任何其他配置，则这是可选的。 ParametersRef 可以引用标准 Kubernetes 资源，即 ConfigMap，或实现特定自定义资源。该资源可以是集群范围的或命名空间范围的。 如果找不到引用、引用不支持的类型或当该资源中的数据格式错误时，应拒绝网关类，将“Accepted”状态条件设置为“False”，并设置“InvalidParameters”原因。 此网关类的网关可以提供自己的 parametersRef。当两者都被指定时，合并行为是实现特定的。通常建议网关类提供可以被网关覆盖的默认值。 支持：实现特定 描述 字符串 (可选) 描述有助于使用更多详细信息描述网关类。
status 网关类状态	状态定义了网关类的当前状态。 实现必须在所有指定其控制器名称的网关类资源上填充状态。

HTTPRoute

HTTPRoute 提供了一种路由 HTTP 请求的方法。这包括根据主机名、路径、标头或查询参数匹配请求的功能。过滤器可用于指定其他处理步骤。后端指定应将匹配的请求路由到哪里。

字段	描述
apiVersion 字符串	gateway.networking.k8s.io/v1beta1
kind 字符串	HTTPRoute
metadata Kubernetes meta/v1.ObjectMeta	有关 metadata 字段的字段，请参考 Kubernetes API 文档。
spec HTTPRouteSpec	规格定义了 HTTPRoute 的期望状态。 CommonRouteSpec CommonRouteSpec (CommonRouteSpec 的成员嵌入到此类型中。) hostnames []Hostname (可选) 主机名定义了一组应与 HTTP Host 标头匹配的主机名，以选择用于处理请求的 HTTPRoute。实现必须忽略 HTTP Host 标头中指定的任何端口值，同时执行匹配，并且（在没有任何适用的标头修改配置的情况下）必须将此标头未修改地转发到后端。 主机名的有效值为 RFC 1123 中对主机名的定义，但有两个显著例外 不允许使用 IP。 主机名可以以通配符标签（*.）为前缀。通配符标签必须以第一个标签的形式单独出现。 如果主机名由 Listener 和 HTTPRoute 都指定，则 HTTPRoute 必须至少有一个与 Listener 匹配的交叉主机名才能附加到 Listener。例如 主机名为 test.example.com 的 Listener 匹配没有指定任何主机名或至少指定了 test.example.com 或 *.example.com 中的一个的主机名的 HTTPRoute。 主机名为 *.example.com 的 Listener 匹配没有指定任何主机名或至少指定了一个与 Listener 主机名匹配的主机名的 HTTPRoute。例如，*.example.com、test.example.com 和 foo.test.example.com 都将匹配。另一方面，example.com 和 test.example.net 不会匹配。 以通配符标签 (*.) 为前缀的主机名被解释为后缀匹配。这意味着，与 *.example.com 的匹配将同时匹配 test.example.com 和 foo.test.example.com，但不匹配 example.com。 如果 Listener 和 HTTPRoute 都指定了主机名，则必须忽略任何不匹配 Listener 主机名的 HTTPRoute 主机名。例如，如果 Listener 指定 *.example.com，而 HTTPRoute 指定 test.example.com 和 test.example.net，则 test.example.net 不得被视为匹配。 如果 Listener 和 HTTPRoute 都指定了主机名，并且没有任何一个与上述标准匹配，则 HTTPRoute 不会被接受。实现必须在相应的 RouteParentStatus 中引发状态为 False 的“Accepted”条件。 如果多个 HTTPRoute 指定了交叉主机名（例如，重叠的通配符匹配和精确匹配的主机名），则必须优先考虑来自具有最多数量的 HTTPRoute 中的规则 匹配的非通配符主机名中的字符。 匹配主机名中的字符。 如果在多个路由之间存在平局，则 HTTPRouteMatches 的匹配优先级规则将接管。 支持：核心 rules []HTTPRoute 规则 (可选) 规则是 HTTP 匹配器、过滤器和操作的列表。
status HTTPRoute 状态	状态定义了 HTTPRoute 的当前状态。

引用授权

引用授权标识其他命名空间中信任以引用与策略相同命名空间中指定资源类型的资源类型。

每个引用授权可以用于表示一个唯一的信任关系。可以使用其他引用授权来添加到它们定义所在的命名空间中对入站引用的受信任源集。

所有网关 API 中的跨命名空间引用（跨命名空间网关路由附加除外）都需要引用授权。

引用授权是一种运行时验证形式，允许用户断言哪些跨命名空间对象引用是允许的。支持引用授权的实现 MUST NOT 允许没有授权的跨命名空间引用，并且 MUST 在撤消授权时响应撤销授权允许的访问。

字段	描述
apiVersion 字符串	gateway.networking.k8s.io/v1beta1
kind 字符串	ReferenceGrant
metadata Kubernetes meta/v1.ObjectMeta	有关 metadata 字段的字段，请参考 Kubernetes API 文档。
spec 引用授权规范	Spec 定义了引用授权的期望状态。 from []ReferenceGrantFrom From 描述了可以引用“To”中描述的资源的受信任命名空间和类型。此列表中的每个条目 MUST 被认为是引用可以从其有效的位置，或者换句话说，条目 MUST 使用 OR 结合。 支持：核心 到 []ReferenceGrantTo To 描述了“From”中描述的资源可能引用的资源。此列表中的每个条目 MUST 被认为是引用可以有效的位置，或者换句话说，条目 MUST 使用 OR 结合。 支持：核心

ReferenceGrantFrom

（出现在： ReferenceGrantSpec）

ReferenceGrantFrom 描述了受信任的命名空间和类型。

字段	描述
group Group	Group 是被引用对象的组。当为空时，将推断 Kubernetes 核心 API 组。 支持：核心
kind Kind	Kind 是被引用对象的类型。虽然实现可能支持其他资源，但以下类型是此字段的“核心”支持级别的一部分。 当用于允许 SecretObjectReference 时 网关 当用于允许 BackendObjectReference 时 GRPCRoute HTTPRoute TCPRoute TLSRoute UDPRoute
namespace Namespace	Namespace 是被引用对象的命名空间。 支持：核心

ReferenceGrantSpec

（出现在： ReferenceGrant，ReferenceGrant）

ReferenceGrantSpec 标识了网关 API 中受信任的跨命名空间关系。

字段	描述
from []ReferenceGrantFrom	From 描述了可以引用“To”中描述的资源的受信任命名空间和类型。此列表中的每个条目 MUST 被认为是引用可以从其有效的位置，或者换句话说，条目 MUST 使用 OR 结合。 支持：核心
到 []ReferenceGrantTo	To 描述了“From”中描述的资源可能引用的资源。此列表中的每个条目 MUST 被认为是引用可以有效的位置，或者换句话说，条目 MUST 使用 OR 结合。 支持：核心

ReferenceGrantTo

（出现在： ReferenceGrantSpec）

ReferenceGrantTo 描述了哪些 Kind 允许作为引用的目标。

字段	描述
group Group	Group 是被引用对象的组。当为空时，将推断 Kubernetes 核心 API 组。 支持：核心
kind Kind	Kind 是被引用对象的类型。虽然实现可能支持其他资源，但以下类型是此字段的“核心”支持级别的一部分 当用于允许 SecretObjectReference 时为 Secret 当用于允许 BackendObjectReference 时为 Service
name ObjectName	(可选) Name 是被引用对象的名称。当未指定时，此策略引用本地命名空间中指定 Group 和 Kind 的所有资源。

---

gateway.networking.k8s.io/v1alpha3

包 v1alpha3 包含 gateway.networking.k8s.io API 组的 API 架构定义。

资源类型

• BackendTLSPolicy

后端 TLS 策略

BackendTLSPolicy 提供了一种方法来配置网关如何通过 TLS 连接到后端。

字段	描述
apiVersion 字符串	gateway.networking.k8s.io/v1alpha3
kind 字符串	BackendTLSPolicy
metadata Kubernetes meta/v1.ObjectMeta	有关 metadata 字段的字段，请参考 Kubernetes API 文档。
spec BackendTLSPolicySpec	Spec 定义了 BackendTLSPolicy 的期望状态。 targetRefs []LocalPolicyTargetReferenceWithSectionName TargetRefs 标识要将策略应用到的 API 对象。只有服务具有扩展支持。实现 MAY 支持其他对象，以及实现特定的支持。请注意，默认情况下，此配置适用于整个引用的资源，但此默认值将来可能会更改，以提供更细粒度的策略应用。 支持: Kubernetes 服务的扩展 支持：针对任何其他资源的实现特定支持 验证 BackendTLSPolicyValidation Validation 包含后端 TLS 验证配置。
status 策略状态	Status 定义了 BackendTLSPolicy 的当前状态。

BackendTLSPolicySpec

（出现在： BackendTLSPolicy）

BackendTLSPolicySpec 定义了 BackendTLSPolicy 的期望状态。

支持：扩展

字段	描述
targetRefs []LocalPolicyTargetReferenceWithSectionName	TargetRefs 标识要将策略应用到的 API 对象。只有服务具有扩展支持。实现 MAY 支持其他对象，以及实现特定的支持。请注意，默认情况下，此配置适用于整个引用的资源，但此默认值将来可能会更改，以提供更细粒度的策略应用。 支持: Kubernetes 服务的扩展 支持：针对任何其他资源的实现特定支持
验证 BackendTLSPolicyValidation	Validation 包含后端 TLS 验证配置。

BackendTLSPolicyValidation

（出现在： BackendTLSPolicySpec）

BackendTLSPolicyValidation 包含后端 TLS 验证配置。

字段	描述
caCertificateRefs []LocalObjectReference	(可选) CACertificateRefs 包含一个或多个对包含 PEM 编码 TLS CA 证书捆绑包的 Kubernetes 对象的引用，该证书捆绑包用于验证网关与后端 Pod 之间的 TLS 握手。 如果 CACertificateRefs 为空或未指定，则必须指定 WellKnownCACertificates。只能指定 CACertificateRefs 或 WellKnownCACertificates 中的一个，不能同时指定两者。如果 CACertifcateRefs 为空或未指定，则如果实现支持，则 MUST 代替使用 WellKnownCACertificates 的配置。 目前，对不同命名空间中资源的引用无效，尽管我们将来会重新审视这一点。 对 Kubernetes ConfigMap 类型的单个 CACertificateRef 具有“核心”支持。实现 MAY 选择支持将多个证书附加到后端，但此行为是实现特定的。 支持：核心 - 对 Kubernetes ConfigMap 的可选单个引用，CA 证书位于名为 ca.crt 的键中。 支持：特定于实现（多个引用或其他类型的资源）。
wellKnownCACertificates WellKnownCACertificatesType	(可选) WellKnownCACertificates 指定是否可以在网关与后端 Pod 之间的 TLS 握手中使用系统 CA 证书。 如果 WellKnownCACertificates 未指定或为空（“”），则必须使用至少一个条目为 CACertificateRefs 指定有效配置。只能指定 CACertificateRefs 或 WellKnownCACertificates 中的一个，不能同时指定两者。如果实现不支持 WellKnownCACertificates 字段或提供的价值不受支持，则策略上的状态条件 MUST 更新为包含 Accepted：False 条件，原因：无效。 支持：实现特定
hostname PreciseHostname	主机名在网关与后端之间的连接中用于两个目的 主机名 MUST 用作连接到后端的 SNI（RFC 6066）。 主机名 MUST 用于身份验证，并且 MUST 与匹配的后端提供的证书相匹配。 支持：核心

WellKnownCACertificatesType (string 别名)

（出现在： BackendTLSPolicyValidation）

WellKnownCACertificatesType 是在 caCertificateRefs 字段未指定时将使用的 CA 证书类型。

价值	描述
“系统”	WellKnownCACertificatesSystem 表示应使用众所周知的系统 CA 证书。

---

gateway.networking.k8s.io/v1alpha2

包 v1alpha2 包含 gateway.networking.k8s.io API 组的 API 架构定义。

资源类型

• 后端负载均衡策略
• ReferenceGrant
• TCPRoute
• TLSRoute
• UDPRoute

后端负载均衡策略

BackendLBPolicy 提供了一种方法来定义后端的负载均衡规则。

字段	描述
apiVersion 字符串	gateway.networking.k8s.io/v1alpha2
kind 字符串	后端负载均衡策略
metadata Kubernetes meta/v1.ObjectMeta	有关 metadata 字段的字段，请参考 Kubernetes API 文档。
spec BackendLBPolicySpec	Spec 定义了 BackendLBPolicy 的期望状态。 targetRefs []LocalPolicyTargetReference TargetRef 标识要将策略应用到的 API 对象。当前，后端（即服务、服务导入或任何实现特定的 backendRef）是唯一有效的 API 目标引用。 sessionPersistence SessionPersistence (可选) SessionPersistence 为后端定义并配置会话持久性。 支持：扩展
status 策略状态	Status 定义了 BackendLBPolicy 的当前状态。

引用授权

引用授权标识其他命名空间中信任以引用与策略相同命名空间中指定资源类型的资源类型。

每个引用授权可以用于表示一个唯一的信任关系。可以使用其他引用授权来添加到它们定义所在的命名空间中对入站引用的受信任源集。

所有网关 API 中的跨命名空间引用都需要引用授权（跨命名空间路由网关附加除外，该附加由网关上的 AllowedRoutes 配置控制，以及跨命名空间服务 ParentRefs 在“使用者”网格路由上，该路由定义仅适用于路由命名空间中工作负载的路由规则）。允许从路由到服务的引用的引用授权仅适用于 BackendRefs。

引用授权是一种运行时验证形式，允许用户断言哪些跨命名空间对象引用是允许的。支持引用授权的实现 MUST NOT 允许没有授权的跨命名空间引用，并且 MUST 在撤消授权时响应撤销授权允许的访问。

字段	描述
apiVersion 字符串	gateway.networking.k8s.io/v1alpha2
kind 字符串	ReferenceGrant
metadata Kubernetes meta/v1.ObjectMeta	有关 metadata 字段的字段，请参考 Kubernetes API 文档。
spec 引用授权规范	Spec 定义了引用授权的期望状态。 from []ReferenceGrantFrom From 描述了可以引用“To”中描述的资源的受信任命名空间和类型。此列表中的每个条目 MUST 被认为是引用可以从其有效的位置，或者换句话说，条目 MUST 使用 OR 结合。 支持：核心 到 []ReferenceGrantTo To 描述了“From”中描述的资源可能引用的资源。此列表中的每个条目 MUST 被认为是引用可以有效的位置，或者换句话说，条目 MUST 使用 OR 结合。 支持：核心

TCPRoute

TCPRoute 提供了一种方法来路由 TCP 请求。当与网关监听器结合使用时，它可以用于将监听器指定的端口上的连接转发到 TCPRoute 指定的一组后端。

字段	描述
apiVersion 字符串	gateway.networking.k8s.io/v1alpha2
kind 字符串	TCPRoute
metadata Kubernetes meta/v1.ObjectMeta	有关 metadata 字段的字段，请参考 Kubernetes API 文档。
spec TCPRouteSpec	Spec 定义了 TCPRoute 的期望状态。 CommonRouteSpec CommonRouteSpec (CommonRouteSpec 的成员嵌入到此类型中。) rules []TCPRouteRule Rules 是 TCP 匹配器和操作的列表。
status TCPRouteStatus	Status 定义了 TCPRoute 的当前状态。

TLSRoute

TLSRoute 资源类似于 TCPRoute，但可以配置为匹配 TLS 特定的元数据。这允许更灵活地匹配给定 TLS 监听器的流。

如果您需要将流量转发到 TLS 监听器的单个目标，可以选择使用具有 TLS 监听器的 TCPRoute。

字段	描述
apiVersion 字符串	gateway.networking.k8s.io/v1alpha2
kind 字符串	TLSRoute
metadata Kubernetes meta/v1.ObjectMeta	有关 metadata 字段的字段，请参考 Kubernetes API 文档。
spec TLSRouteSpec	Spec 定义了 TLSRoute 的期望状态。 CommonRouteSpec CommonRouteSpec (CommonRouteSpec 的成员嵌入到此类型中。) hostnames []Hostname (可选) Hostnames 定义了一组 SNI 名称，这些名称应该与 TLS 握手时 TLS ClientHello 消息的 SNI 属性匹配。这与 RFC 1123 中主机名的定义相匹配，但有两个显著例外 根据 RFC 6066，SNI 名称中不允许使用 IP 地址。 主机名可以以通配符标签（*.）为前缀。通配符标签必须以第一个标签的形式单独出现。 如果监听器和 TLSRoute 都指定了主机名，那么 TLSRoute 至少必须有一个与监听器主机名相交的主机名才能附加到监听器。例如 主机名为 test.example.com 的监听器匹配主机名为空或至少指定了 test.example.com 或 *.example.com 之一的主机名。 主机名为 *.example.com 的监听器匹配主机名为空或至少指定了一个与监听器主机名匹配的主机名的 TLSRoute。例如，test.example.com 和 *.example.com 都匹配。另一方面，example.com 和 test.example.net 不匹配。 如果监听器和 TLSRoute 都指定了主机名，则所有不符合上述条件的 TLSRoute 主机名 MUST 被忽略。例如，如果监听器指定了 *.example.com，而 TLSRoute 指定了 test.example.com 和 test.example.net，则 test.example.net 必须不被视为匹配。 如果监听器和 TLSRoute 都指定了主机名，并且没有一个符合上述条件，则 TLSRoute 不会被接受。实现必须在相应的 RouteParentStatus 中引发状态为 False 的“Accepted”条件。 支持：核心 rules []TLSRouteRule Rules 是 TLS 匹配器和操作的列表。
status TLSRouteStatus	Status 定义了 TLSRoute 的当前状态。

UDPRoute

UDPRoute 提供了一种方法来路由 UDP 流量。当与网关监听器结合使用时，它可以用于将监听器指定的端口上的流量转发到 UDPRoute 指定的一组后端。

字段	描述
apiVersion 字符串	gateway.networking.k8s.io/v1alpha2
kind 字符串	UDPRoute
metadata Kubernetes meta/v1.ObjectMeta	有关 metadata 字段的字段，请参考 Kubernetes API 文档。
spec UDPRouteSpec	Spec 定义了 UDPRoute 的期望状态。 CommonRouteSpec CommonRouteSpec (CommonRouteSpec 的成员嵌入到此类型中。) rules []UDPRouteRule Rules 是 UDP 匹配器和操作的列表。
status UDPRouteStatus	Status 定义了 UDPRoute 的当前状态。

BackendLBPolicySpec

（出现在： BackendLBPolicy）

BackendLBPolicySpec 定义了 BackendLBPolicy 的期望状态。注意：没有 Override 或 Default 策略配置。

字段	描述
targetRefs []LocalPolicyTargetReference	TargetRef 标识要将策略应用到的 API 对象。当前，后端（即服务、服务导入或任何实现特定的 backendRef）是唯一有效的 API 目标引用。
sessionPersistence SessionPersistence	(可选) SessionPersistence 为后端定义并配置会话持久性。 支持：扩展

GRPCRoute

字段	描述
metadata Kubernetes meta/v1.ObjectMeta	有关 metadata 字段的字段，请参考 Kubernetes API 文档。
spec GRPCRouteSpec	Spec 定义了 GRPCRoute 的期望状态。 CommonRouteSpec CommonRouteSpec (CommonRouteSpec 的成员嵌入到此类型中。) hostnames []Hostname (可选) Hostnames 定义了一组主机名，以匹配 GRPC Host 标头以选择 GRPCRoute 来处理请求。这与 RFC 1123 中主机名的定义相匹配，但有两个显著例外 不允许使用 IP。 主机名可以以通配符标签 (*.) 为前缀。通配符标签必须单独出现在第一个标签中。 如果监听器和 GRPCRoute 都指定了主机名，则必须至少有一个相交的主机名，GRPCRoute 才能附加到监听器。例如 具有 test.example.com 作为主机名的监听器匹配没有指定任何主机名或至少指定了 test.example.com 或 *.example.com 之一的 GRPCRoute。 具有 *.example.com 作为主机名的监听器匹配没有指定任何主机名或至少指定了一个与监听器主机名匹配的主机名的 GRPCRoute。例如，test.example.com 和 *.example.com 都将匹配。另一方面，example.com 和 test.example.net 将不匹配。 以通配符标签 (*.) 为前缀的主机名被解释为后缀匹配。这意味着，与 *.example.com 的匹配将同时匹配 test.example.com 和 foo.test.example.com，但不匹配 example.com。 如果监听器和 GRPCRoute 都指定了主机名，则任何与监听器主机名不匹配的 GRPCRoute 主机名都必须被忽略。例如，如果监听器指定了 *.example.com，而 GRPCRoute 指定了 test.example.com 和 test.example.net，则 test.example.net 必须不被视为匹配。 如果监听器和 GRPCRoute 都指定了主机名，并且没有任何一个满足上述条件，则 GRPCRoute 必须不被实现接受。实现必须在相应的 RouteParentStatus 中引发状态为 False 的“Accepted”条件。 如果 HTTPRoute 或 GRPCRoute 类型的路由 (A) 附加到监听器，而该监听器已经附加了其他类型的路由 (B)，并且 A 和 B 的主机名的交集不为空，则实现必须根据以下条件（按顺序）准确地接受这两个路由中的一个： 根据创建时间最老的路由。 按“{namespace}/{name}”字母顺序排列时，第一个出现的路由。 被拒绝的路由必须在相应的 RouteParentStatus 中引发状态为“False”的“Accepted”条件。 支持：核心 rules []GRPCRouteRule (可选) 规则是 gRPC 匹配器、过滤器和操作的列表。
status GRPCRouteStatus	Status 定义了 GRPCRoute 的当前状态。

LocalPolicyTargetReference

（出现在： BackendLBPolicySpec，LocalPolicyTargetReferenceWithSectionName）

LocalPolicyTargetReference 用于标识要应用直接或继承策略的 API 对象。这应作为可以针对网关 API 资源的策略资源的一部分使用。有关此策略附加模型的工作原理以及策略资源示例的更多信息，请参阅网关 API 的策略附加文档。

字段	描述
group Group	Group 是目标资源的组。
kind Kind	Kind 是目标资源的类型。
name ObjectName	Name 是目标资源的名称。

LocalPolicyTargetReferenceWithSectionName

（出现在： BackendTLSPolicySpec）

LocalPolicyTargetReferenceWithSectionName 用于标识要应用直接策略的 API 对象。这应作为可以针对单个资源的策略资源的一部分使用。有关此策略附加模式的工作原理以及策略资源示例的更多信息，请参阅网关 API 的策略附加文档。

注意：这仅应在实际需要引用 SectionName 时用于直接策略附加。在所有其他情况下，应使用 LocalPolicyTargetReference。

字段	描述
LocalPolicyTargetReference LocalPolicyTargetReference	(LocalPolicyTargetReference 的成员嵌套在此类型中。)
部分名称 SectionName	(可选) SectionName 是目标资源中某个部分的名称。当未指定时，此 targetRef 会针对整个资源。在以下资源中，SectionName 被解释为： Gateway：监听器名称 HTTPRoute：HTTPRouteRule 名称 Service：端口名称 如果指定了 SectionName，但在目标对象上不存在，则策略必须无法附加，并且策略实现应在策略的状态中记录 ResolvedRefs 或类似的条件。

NamespacedPolicyTargetReference

NamespacedPolicyTargetReference 用于标识要应用直接或继承策略的 API 对象，该对象可能位于不同的命名空间中。这仅应作为需要能够针对不同命名空间中资源的策略资源的一部分使用。有关此策略附加模型的工作原理以及策略资源示例的更多信息，请参阅网关 API 的策略附加文档。

字段	描述
group Group	Group 是目标资源的组。
kind Kind	Kind 是目标资源的类型。
name ObjectName	Name 是目标资源的名称。
namespace Namespace	(可选) Namespace 是被引用的对象的命名空间。当未指定时，将推断本地命名空间。即使策略针对不同命名空间中的资源，它也必须仅应用于来自与策略相同命名空间的流量。

PolicyAncestorStatus

(出现在： PolicyStatus)

PolicyAncestorStatus 描述了路由相对于关联的祖先的状态。

祖先是指作为策略的目标的对象，或者在对象层次结构中位于其上方的对象。例如，如果策略针对服务，则策略的祖先依次是服务、HTTPRoute、网关和网关类。几乎总是，在此层次结构中，网关将是最有用的放置策略状态的对象，因此我们建议实现应使用网关作为 PolicyAncestorStatus 对象，除非设计者有非常充分的理由这样做。

在策略附加的上下文中，祖先用于区分哪些资源会导致此策略的独特应用。例如，如果策略针对服务，则它可能对每个附加的网关都有不同的结果。

针对相同资源的策略可能会产生不同的效果，具体取决于这些资源的祖先。例如，针对相同服务的不同网关可能具有不同的功能，尤其是如果它们具有不同的底层实现。

例如，在 BackendTLSPolicy 中，策略附加到用作 HTTPRoute 中的后端的服务，而 HTTPRoute 本身附加到网关。在这种情况下，与状态相关的对象是网关，它也是此状态中引用的祖先对象。

请注意，父级也是祖先，因此对于父级是状态相关对象的那些对象，仍然应使用此结构。

此结构旨在用于切片中，切片实际上是映射，其复合键由 AncestorRef 和 ControllerName 组成。

字段	描述
ancestorRef ParentReference	AncestorRef 与规范中的 ParentRef 相对应，此 PolicyAncestorStatus 结构描述了其状态。
控制器名称 网关控制器	ControllerName 是一个域/路径字符串，指示写入此状态的控制器的名称。这与 GatewayClass 上的 controllerName 字段相对应。 示例：“example.net/gateway-controller”。 此字段的格式为 DOMAIN“/”PATH，其中 DOMAIN 和 PATH 是有效的 Kubernetes 名称 (https://kubernetes.ac.cn/docs/concepts/overview/working-with-objects/names/#names). 控制器 MUST 在写入状态时填充此字段。控制器应该确保用其 ControllerName 填充状态的条目在不再需要时被清除。
conditions []Kubernetes meta/v1.Condition	Conditions 描述了策略相对于给定祖先的状态。

PolicyConditionReason (string 别名)

PolicyConditionReason 是策略条件的原因。

价值	描述
"Accepted"	PolicyReasonAccepted 用于“已接受”条件，当策略已被目标资源接受时。
"冲突"	PolicyReasonConflicted 用于“已接受”条件，当策略未被目标资源接受，因为存在另一个针对相同资源的策略，并且无法合并时。
"Invalid"	PolicyReasonInvalid 用于“已接受”条件，当策略在语法或语义上无效时。
"TargetNotFound"	PolicyReasonTargetNotFound 用于“已接受”条件，当策略附加到无效的目标资源时。

PolicyConditionType (string 别名)

PolicyConditionType 是策略条件的类型。此类型应与策略资源 Status.Conditions 字段一起使用。

价值	描述
"Accepted"	PolicyConditionAccepted 指示策略是否已被目标资源接受或拒绝，以及原因。 此条件为真时可能的原因是 “Accepted” 此条件为假时可能的原因是 “Conflicted” “Invalid” “TargetNotFound”

PolicyStatus

(出现在： BackendLBPolicy, BackendTLSPolicy)

PolicyStatus 定义了所有策略应在其状态中包含的公共属性。

字段

描述

ancestors []PolicyAncestorStatus

Ancestors 是与策略关联的祖先资源（通常是网关）列表，以及策略相对于每个祖先的状态。当此策略附加到父级时，管理父级和祖先的控制器必须在控制器首次看到策略时在此列表中添加一个条目，并且在相关祖先被修改时应相应地更新该条目。 请注意，选择相关祖先留给策略设计人员；策略设计的一个重要部分是设计命名此状态的正确对象级别。 另请注意，实现仅必须为它们负责的祖先资源填充祖先状态。实现必须使用 ControllerName 字段来唯一标识它们负责的此列表中的条目。 请注意，为了实现这一点，PolicyAncestorStatus 结构的列表必须被视为具有复合键的映射，该复合键由 AncestorRef 和 ControllerName 字段组合而成。 此列表中最多表示 16 个祖先。空列表表示策略与任何祖先都不相关。 如果此切片已满，实现不得添加其他条目。相反，它们必须将策略视为不可实现，并在任何相关资源（例如此处将引用的祖先）上发出信号。例如，如果此列表在 BackendTLSPolicy 中已满，则没有其他网关能够引用 BackendTLSPolicy 目标的服务。

TCPRouteRule

(出现在： TCPRouteSpec)

TCPRouteRule 是给定规则的配置。

字段	描述
backendRefs []BackendRef	BackendRefs 定义应将匹配的请求发送到的后端。如果未指定或无效（引用不存在的资源或没有端点的服务），则底层实现必须主动拒绝对该后端的连接尝试。连接拒绝必须尊重权重；如果请求对无效后端进行 80% 的连接，则必须拒绝 80% 的连接。 支持：Kubernetes 服务的核心支持 支持：Kubernetes ServiceImport 的扩展支持 支持：针对任何其他资源的实现特定支持 对权重的支持：扩展

TCPRouteSpec

(出现在： TCPRoute)

TCPRouteSpec 定义了 TCPRoute 的期望状态。

字段	描述
CommonRouteSpec CommonRouteSpec	(CommonRouteSpec 的成员嵌入到此类型中。)
rules []TCPRouteRule	Rules 是 TCP 匹配器和操作的列表。

TCPRouteStatus

(出现在： TCPRoute)

TCPRouteStatus 定义了 TCPRoute 的观察状态。

字段	描述
RouteStatus RouteStatus	（RouteStatus 的成员嵌入到此类型中。）

TLSRouteRule

(出现在： TLSRouteSpec)

TLSRouteRule 是给定规则的配置。

字段	描述
backendRefs []BackendRef	BackendRefs 定义应将匹配的请求发送到的后端。如果未指定或无效（引用不存在的资源或没有端点的服务），则规则不会执行任何转发；如果未指定会导致发送响应的过滤器，则底层实现必须通过拒绝连接或返回 500 状态代码来主动拒绝对该后端的请求尝试。请求拒绝必须尊重权重；如果请求对无效后端进行 80% 的请求，则必须拒绝 80% 的请求。 支持：Kubernetes 服务的核心支持 支持：Kubernetes ServiceImport 的扩展支持 支持：针对任何其他资源的实现特定支持 对权重的支持：扩展

TLSRouteSpec

(出现在： TLSRoute)

TLSRouteSpec 定义了 TLSRoute 资源的期望状态。

字段	描述
CommonRouteSpec CommonRouteSpec	(CommonRouteSpec 的成员嵌入到此类型中。)
hostnames []Hostname	(可选) Hostnames 定义了一组 SNI 名称，这些名称应该与 TLS 握手时 TLS ClientHello 消息的 SNI 属性匹配。这与 RFC 1123 中主机名的定义相匹配，但有两个显著例外 根据 RFC 6066，SNI 名称中不允许使用 IP 地址。 主机名可以以通配符标签（*.）为前缀。通配符标签必须以第一个标签的形式单独出现。 如果监听器和 TLSRoute 都指定了主机名，那么 TLSRoute 至少必须有一个与监听器主机名相交的主机名才能附加到监听器。例如 主机名为 test.example.com 的监听器匹配主机名为空或至少指定了 test.example.com 或 *.example.com 之一的主机名。 主机名为 *.example.com 的监听器匹配主机名为空或至少指定了一个与监听器主机名匹配的主机名的 TLSRoute。例如，test.example.com 和 *.example.com 都匹配。另一方面，example.com 和 test.example.net 不匹配。 如果监听器和 TLSRoute 都指定了主机名，则所有不符合上述条件的 TLSRoute 主机名 MUST 被忽略。例如，如果监听器指定了 *.example.com，而 TLSRoute 指定了 test.example.com 和 test.example.net，则 test.example.net 必须不被视为匹配。 如果监听器和 TLSRoute 都指定了主机名，并且没有一个符合上述条件，则 TLSRoute 不会被接受。实现必须在相应的 RouteParentStatus 中引发状态为 False 的“Accepted”条件。 支持：核心
rules []TLSRouteRule	Rules 是 TLS 匹配器和操作的列表。

TLSRouteStatus

(出现在： TLSRoute)

TLSRouteStatus 定义了 TLSRoute 的观察状态。

字段	描述
RouteStatus RouteStatus	（RouteStatus 的成员嵌入到此类型中。）

UDPRouteRule

(出现在： UDPRouteSpec)

UDPRouteRule 是给定规则的配置。

字段	描述
backendRefs []BackendRef	BackendRefs 定义应将匹配的请求发送到的后端。如果未指定或无效（引用不存在的资源或没有端点的服务），则底层实现必须主动拒绝对该后端的连接尝试。数据包丢弃必须尊重权重；如果请求对无效后端进行 80% 的数据包，则必须丢弃 80% 的数据包。 支持：Kubernetes 服务的核心支持 支持：Kubernetes ServiceImport 的扩展支持 支持：针对任何其他资源的实现特定支持 对权重的支持：扩展

UDPRouteSpec

(出现在： UDPRoute)

UDPRouteSpec 定义了 UDPRoute 的期望状态。

字段	描述
CommonRouteSpec CommonRouteSpec	(CommonRouteSpec 的成员嵌入到此类型中。)
rules []UDPRouteRule	Rules 是 UDP 匹配器和操作的列表。

UDPRouteStatus

(出现在： UDPRoute)

UDPRouteStatus 定义了 UDPRoute 的观察状态。

字段	描述
RouteStatus RouteStatus	（RouteStatus 的成员嵌入到此类型中。）

---

使用 gen-crd-api-reference-docs 生成。