第 14 章 GRPCRoute [gateway.networking.k8s.io/v1]

hostnames

数组（字符串）

hostnames 定义一组与 GRPC Host 标头匹配的主机名，以选择处理请求的 GRPCRoute。这与主机名的 RFC 1123 定义匹配，并带有 2 值得例外：

1.不允许使用 IP。2.主机名可以带有通配符标签前缀(.<)。通配符标签需要自行显示，作为第一个标签。

如果主机名由 Listener 和 GRPCRoute 指定，则必须至少有一个用于 GRPCRoute 的交集主机名才能附加到 Listener。例如：

* 使用 test.example.com 作为主机名的 Listener 与未指定任何主机名的 GRPCRoutes 匹配，或者至少指定了 test.example.com 或 3.0. example.com 之一。* 带有 2.2. example.com 作为主机名的 Listener 与未指定任何主机名的 GRPCRoutes 匹配，或者至少指定了与 Listener 主机名匹配的主机名。例如： test.example.com 和 \*.example.com 均匹配。另一方面，example.com 和 test.example.net 不匹配。

带有通配符标签(MyPlaybooks)前缀的主机名被解释为后缀匹配。这意味着，对于 2.2. example.com 的匹配 将匹配 test.example.com 和 foo.test.example.com，但不匹配 example.com。

如果 Listener 和 GRPCRoute 都指定了主机名，则忽略任何与 Listener 主机名不匹配的 GRPCRoute 主机名。例如，如果指定了 Listener. example.com，并且 GRPCRoute 指定 test.example.com 和 test.example.net，则test.example.net 必须被视为匹配项。

如果 Listener 和 GRPCRoute 都指定了主机名，并且与上述条件都不匹配，则实施不接受 GRPCRoute MUST。实现 MUST 引发 'Accepted' Condition，其状态在对应的 RouteParentStatus 中。

如果类型为 HTTPRoute 或 GRPCRoute 的 Route (A)附加到 Listener，并且侦听器已附加了其他类型的路由(B)，并且 A 和 B 主机名的交集是非空的，那么实施 MUST 接受这两个路由之一，具体由以下条件确定：

* 基于创建时间戳的最旧的路由。* 路由以字母顺序按 "{namespace}/{name}" 开头。

拒绝的路由在对应的 RouteParentStatus 中引发 'Accepted' 条件，状态为 'False'。

支持：Core

parentRefs

数组

ParentRefs 引用路由要附加到的资源（通常为 Gateway）。请注意，引用的父资源需要允许此附加完成。对于网关，这意味着网关需要允许从此类和命名空间的 Routes 进行附加。对于服务，这意味着 Service 必须位于同一命名空间中用于 "producer" 路由，或者网格实现必须支持并允许所引用服务的 "consumer" 路由。ReferenceGrant 不适用于管理对 Services 的 ParentRefs to Services - 无法在与 Route 不同的命名空间中为服务创建 "producer" 路由。

支持"Core"支持的父资源有两种：

* gateway (Gateway conformance profile)* Service (Mesh conformance profile, only ClusterIP Services)

以后可能会扩展此 API，以支持其他类型的父资源。

ParentRefs 必须 不同。这意味着：

* 它们选择不同的对象。如果是这种情况，则 parentRef 条目会有所不同。就字段而言，这意味着由 组,kind,namespace, 和 name 定义的多部分键必须在 Route 中的所有 parentRef 条目中唯一。* 它们没有选择不同的对象，但每个可选字段都使用的每个可选字段，每个选择同一对象的 ParentRef 都必须将相同的可选字段设置为不同的值。如果一个 ParentRef 设置可选字段的组合，则所有字段都必须设置相同的组合。

一些示例：

* 如果一个 ParentRef 设置 sectionName，则引用同一对象的所有 ParentRefs 还必须设置 sectionName。* 如果一个 ParentRef 设置 端口，则引用同一对象的所有 ParentRefs 也必须设置 端口。* 如果一个 ParentRef 设置 sectionName 和端口，则引用同一对象的所有 ParentRefs 还必须设置 sectionName 和端口。

可以单独引用多个不同的对象，这些对象可能会被实施折叠。例如，一些实现可能会选择将兼容的网关 Listeners 合并在一起。如果是这种情况，则也应合并附加到这些资源的路由列表。

请注意，对于跨命名空间边界的 ParentRefs，有特定的规则。只有跨命名空间引用被引用的命名空间中明确允许时才有效。例如，Gateway 具有 AllowedRoutes 字段，ReferenceGrant 提供了启用其他类型的跨命名空间参考的通用方法。

parentRefs[]

object

ParentReference 识别一个 API 对象（通常是网关），它被视为此资源的父项（通常是路由）。支持"Core"支持的父资源有两种：

* gateway (Gateway conformance profile)* Service (Mesh conformance profile, only ClusterIP Services)

以后可能会扩展此 API，以支持其他类型的父资源。

API 对象必须在集群中有效；集群中必须注册 Group 和 Kind，以便此引用有效。

rules

数组

规则是 GRPC 匹配器、过滤器和操作的列表。

rules[]

object

GRPCRouteRule 根据条件（匹配）、处理它(filters)并将请求转发到 API 对象(backendRefs)，定义与 gRPC 请求匹配的语义。

group

string

组是引用的组。如果未指定，"gateway.networking.k8s.io" 将推断出来。要设置核心 API 组（如 "Service" kind referent），Group 必须明确设置为 "" （空字符串）。

支持：Core

kind

string

kind 是引用的类型。

支持"Core"支持的父资源有两种：

* gateway (Gateway conformance profile)* Service (Mesh conformance profile, only ClusterIP Services)

对其他资源的支持是特定于实施的。

name

string

name 是引用的名称。

支持：Core

namespace

string

namespace 是引用的命名空间。如果未指定，这指的是 Route 的本地命名空间。

请注意，对于跨命名空间边界的 ParentRefs 有特定的规则。只有跨命名空间引用被引用的命名空间中明确允许时才有效。例如： Gateway 具有 AllowedRoutes 字段，ReferenceGrant 提供了一种通用方法来启用其他类型的跨命名空间引用。

支持：Core

port

整数

port 是此 Route 目标的网络端口。它可以根据父资源的类型进行解释。

当父资源是网关时，此目标是在支持此类 Route （并选择此路由）的指定端口上侦听所有的监听程序。不建议设置 Port，除非 Route 中指定的网络行为必须应用到特定端口，而不是可以更改其端口的监听程序。当同时指定了 Port 和 sectionName 时，所选监听器的名称和端口必须与两个指定的值匹配。

实施 MAY 选择支持其他父资源。支持其他类型的父资源的实施必须清楚地记录/如果端口的解释方式。

对于状态，只要父资源接受部分，则附加被视为成功。例如，网关监听程序可以通过 Route kind、namespace 或 hostname 来限制哪些 Routes 可以附加到它们。如果 2 网关监听程序的 1 个接受来自引用路由的附件，则路由必须被视为成功附加。如果没有网关监听程序接受来自此 Route 的附件，则路由必须被视为与网关分离。

支持：扩展

sectionName

string

SectionName 是目标资源中的一个部分的名称。在以下资源中，sectionName 被解释为：

* gateway: Listener 名称。当同时指定了 Port (experimental)和 SectionName 时，所选监听器的名称和端口必须与两个指定的值匹配。* service: 端口名称。当同时指定了 Port (experimental)和 SectionName 时，所选监听器的名称和端口必须与两个指定的值匹配。

实施 MAY 选择支持将路由附加到其他资源。如果是这种情况，它们必须清楚地记录 SectionName 的解释方式。

如果未指定（空字符串），这将引用整个资源。对于状态，如果父资源中的至少一个部分接受它，则附加被视为成功。例如，网关监听程序可以通过 Route kind、namespace 或 hostname 来限制哪些 Routes 可以附加到它们。如果 2 网关监听程序的 1 个接受来自引用路由的附件，则路由必须被视为成功附加。如果没有网关监听程序接受来自此 Route 的附件，则路由必须被视为与网关分离。

支持：Core

backendRefs

数组

BackendRefs 定义应发送匹配的请求的后端。

此处的故障行为取决于指定的 BackendRefs 数量以及无效的后端。

如果 BackendRefs 中的所有 条目都无效，且没有在此路由规则中指定过滤器，则 与这个 规则匹配的所有流量都必须接收 UNAVAILABLE 状态。

有关使单个 GRPCBackendRef 无效的规则，请参阅 GRPCBackendRef 定义。

当 GRPCBackendRef 无效时，必须为其他路由到无效后端的请求返回 UNAVAILABLE 状态。如果指定了多个后端，一些后端无效，否则将路由到无效的后端所需的请求比例需要接收 UNAVAILABLE 状态。

例如，如果指定了两个后端，并带有相等的权重，一个无效，50% 的流量需要接收 UNAVAILABLE 状态。实施可能会选择 50% 的决定方式。

支持 ：Kubernetes Service 的核心

支持：特定于任何其他资源的实现

对权重的支持： Core

backendRefs[]

object

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

请注意，当指定与本地命名空间不同的命名空间时，引用命名空间中需要一个 ReferenceGrant 对象，以允许该命名空间的所有者接受引用。详情请查看 ReferenceGrant 文档。

过滤器

数组

过滤器定义应用到与此规则匹配的请求的过滤器。

当前未指定多个行为的排序效果。这可以根据 alpha 阶段中的反馈来改变。

此级别上的一致性级别会根据过滤器类型定义：

- 所有核心过滤器都必须受到支持 GRPCRoute 的所有实现支持。- 鼓励实施器支持扩展过滤器。- 特定于实施的自定义过滤器在实现过程中没有 API 保证。

除非在过滤器中明确指定，否则不支持多次指定同一过滤器。

如果实施无法支持过滤器的组合，它必须清楚地记录该限制。如果指定了不兼容或不支持的过滤器，并导致 Accepted 条件被设置为 False 状态，则实现可能会使用 IncompatibleFilters reason 来指定此配置错误。

支持：Core

filters[]

object

GRPCRouteFilter 定义在请求或响应生命周期内必须完成的处理步骤。GRPCRouteFilters 充当一个扩展点，用于表达在网关实施中可能完成的处理。有些示例包括请求或响应修改、实施身份验证策略、速率限制和流量控制。API 保证/格式根据过滤器的类型定义。

matches

数组

matches 定义用于与传入 gRPC 请求匹配的规则的条件。每个匹配项都独立，例如，如果 满足任何 其中一个匹配项，则此规则将匹配。

例如，使用以下内容匹配配置：

matches: - method: service: foo.bar headers: values: version: 2 - method: service: foo.bar.v2

要针对此规则匹配请求，它必须满足两个条件的 EITHER：

- foo.bar AND 的服务包含标头 版本：2- service of foo.bar.v2

有关如何指定要同时指定多个匹配条件的信息，请参阅 GRPCRouteMatch 文档。

如果没有指定匹配项，实施必须匹配每个 gRPC 请求。

从 GRPCRoutes MUST 生成的代理或负载均衡器路由配置根据以下条件确定规则的优先级，继续绑定。GRPCRoutes 和 HTTPRoutes 之间不进行合并。优先级必须为具有最大数量的规则指定：

* 在匹配非通配符主机名中的字符。* 匹配主机名中的字符。* 匹配服务中的字符。* 匹配方法中的字符。* 标头匹配。

如果绑定仍存在于多个路由中，则按以下条件顺序确定匹配的优先级，继续绑定：

* 基于创建时间戳的最旧的路由。* 路由以字母顺序按 "{namespace}/{name}" 开头。

如果绑定仍存在于给定优先级的路由中，则必须为满足上述条件的第一个匹配规则授予匹配的优先级。

matches[]

object

GRPCRouteMatch 定义用于将请求与给定操作匹配的 predicate。多个匹配类型是 AND，即仅在满足所有条件时，匹配才会评估为 true。

例如，只有在服务是 foo 且包含 version: v1 标头时，以下匹配才会与 gRPC 请求匹配：

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

过滤器

数组

只有当请求被转发到此处定义的后端时，才会执行此级别中定义的过滤器。

支持：特定于实现的（对于更广泛的过滤器支持，请使用 GRPCRouteRule 中的 Filters 字段。）

filters[]

object

GRPCRouteFilter 定义在请求或响应生命周期内必须完成的处理步骤。GRPCRouteFilters 充当一个扩展点，用于表达在网关实施中可能完成的处理。有些示例包括请求或响应修改、实施身份验证策略、速率限制和流量控制。API 保证/格式根据过滤器的类型定义。

group

string

组是引用的组。例如："gateway.networking.k8s.io"。如果未指定或空字符串时，核心 API 组将被推断出来。

kind

string

kind 是引用的 Kubernetes 资源类型。例如 "Service"。

如果没有指定，则默认为 "Service"。

ExternalName 服务可以引用集群中可能位于的 CNAME DNS 记录，因此很难考虑一致性。它们也可能不安全（请参阅 CVE-2021-25740 了解更多信息）。实施 SHOULD 不支持 ExternalName 服务。

Support: Core （带有 ExternalName 以外的类型的服务）

支持：特定于实现的（类型为 ExternalName 的服务）

name

string

name 是引用的名称。

namespace

string

namespace 是后端的命名空间。如果未指定，本地命名空间将被推断出来。

请注意，当指定与本地命名空间不同的命名空间时，引用命名空间中需要一个 ReferenceGrant 对象，以允许该命名空间的所有者接受引用。详情请查看 ReferenceGrant 文档。

支持：Core

port

整数

port 指定用于此资源的目标端口号。当引用是 Kubernetes 服务时，需要端口。在本例中，端口号是服务端口号，而不是目标端口。对于其他资源，目的地端口可能源自引用资源或此字段。

weight

整数

weight 指定转发到引用的后端的请求的比例。这被计算为 weight/ （这个 BackendRefs 列表中有所有权重）。对于非零值，可能会有一些来自此处定义的确切比例的 epsilon，具体取决于实施支持的精度。weight 不是一个百分比，权重的总和不需要等于 100。

如果只指定一个后端，且它的权重大于 0，则会将 100% 的流量转发到那个后端。如果 weight 设为 0，则不应为这个条目转发流量。如果未指定，则权重默认为 1。

对此字段的支持因使用的上下文而异。

extensionRef

object

ExtensionRef 是 "filter" 行为的可选、特定于实现的扩展。例如，组 "networking.example.net" 中的资源 "myroutefilter"。ExtensionRef MUST 不用于核心和扩展过滤器。

支持：特定于实施

此过滤器可以在同一规则内多次使用。

requestHeaderModifier

object

RequestHeaderModifier 定义修改请求标头的过滤器的模式。

支持：Core

requestMirror

object

RequestMirror 为镜像请求的过滤器定义一个模式。请求将发送到指定的目的地，但来自该目的地的响应将被忽略。

此过滤器可以在同一规则内多次使用。请注意，并非所有实施都能够支持镜像到多个后端。

支持：扩展

responseHeaderModifier

object

ResponseHeaderModifier 为修改响应标头的过滤器定义模式。

支持：扩展

type

string

Type 标识要应用的过滤器类型。与其他 API 字段一样，类型被分为三个一致性级别：

- core ：过滤类型及其在这个软件包中"Support: Core"定义的相应配置，例如："RequestHeaderModifier".支持 GRPCRoute 的所有实施都必须支持核心过滤器。

- Extended: Filter type 及其对应的配置由这个软件包中的"Support: Extended"定义，例如："RequestMirror"。我们鼓励实施人员支持扩展过滤器。

- 特定于实现的：由特定供应商定义和支持的过滤器。未来，显示多个实施中行为的过滤器将被视为扩展或核心一致性级别。这些过滤器的特定于过滤器的配置使用 ExtensionRef 字段指定。对于自定义 过滤器，type MUST 设置为 "ExtensionRef"。

我们鼓励实施人员定义自定义实施类型，以使用特定于实施的行为来扩展核心 API。

如果无法解析对自定义过滤器类型的引用，则不会跳过过滤器。相反，已由该过滤器处理的请求接收 HTTP 错误响应。

group

string

组是引用的组。例如："gateway.networking.k8s.io"。如果未指定或空字符串时，核心 API 组将被推断出来。

kind

string

kind 是引用的类型。例如 "HTTPRoute" 或 "Service"。

name

string

name 是引用的名称。

add

数组

在操作前，将给定标头（名称、值）添加到请求。它将附加到与标头名称关联的任何现有值。

input: GET /foo HTTP/1.1 my-header: foo

config: add: - name: "my-header" value: "bar,baz"

输出：GET /foo HTTP/1.1 my-header: foo,bar,baz

add[]

object

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

remove

数组（字符串）

在操作前，从 HTTP 请求中删除给定标头。Remove 的值是 HTTP 标头名称列表。请注意，标头名称区分大小写（请参阅 https://datatracker.ietf.org/doc/html/rfc2616#section-4.2）。

input: GET /foo HTTP/1.1 my-header1: foo my-header2: bar my-header3: baz

config: remove: ["my-header1", "my-header3"]

输出：GET /foo HTTP/1.1 my-header2: bar

set

数组

在操作前，使用给定标头（名称、值）设置覆盖请求。

input: GET /foo HTTP/1.1 my-header: foo

config: set: - name: "my-header" value: "bar"

输出：GET /foo HTTP/1.1 my-header: bar

set[]

object

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

name

string

name 是要匹配的 HTTP 标头的名称。名称匹配必须不区分大小写。（请参阅 https://tools.ietf.org/html/rfc7230#section-3.2）。

如果多个条目指定了等同的标头名称，则第一个带有等效名称的条目必须视为匹配项。带有等同标头名称的后续条目必须忽略。由于标头名称的问题单识别，"foo"和 "Foo" 被视为等同。

value

string

value 是要匹配的 HTTP 标头的值。

name

string

name 是要匹配的 HTTP 标头的名称。名称匹配必须不区分大小写。（请参阅 https://tools.ietf.org/html/rfc7230#section-3.2）。

如果多个条目指定了等同的标头名称，则第一个带有等效名称的条目必须视为匹配项。带有等同标头名称的后续条目必须忽略。由于标头名称的问题单识别，"foo"和 "Foo" 被视为等同。

value

string

value 是要匹配的 HTTP 标头的值。

backendRef

object

BackendRef 引用发送镜像请求的资源。

镜像请求必须只发送到此 BackendRef 中的单个目标端点，无论此 BackendRef 中有多少端点。

如果无法找到引用，则此 BackendRef 无效，且必须从网关中丢弃。控制器必须确保将 Route 状态上的 "ResolvedRefs" 条件设置为 status: False，而不是在底层实现中配置此后端。

如果对 ReferenceGrant 不允许 的现有 对象有一个跨命名空间引用，控制器必须确保 Route 上的 "ResolvedRefs" 条件被设置为 status: False，并带有 "RefNotPermitted" 原因，且不会在底层实现中配置此后端。

在任一错误情况下，应该使用 ResolvedRefs Condition 的消息来提供有关此问题的更多详情。

支持：为 Kubernetes Service 扩展

支持：特定于任何其他资源的实现

部分

object

fraction 代表应镜像到 BackendRef 的请求的比例。

只能指定 Fraction 或 Percent 之一。如果没有指定字段，则会镜像 100% 的请求。

百分比

整数

percent 代表应镜像到 BackendRef 的请求百分比。其最小值为 0 （代表请求 0%，其最大值为 100 （代表 100% 的请求）。

只能指定 Fraction 或 Percent 之一。如果没有指定字段，则会镜像 100% 的请求。

group

string

组是引用的组。例如："gateway.networking.k8s.io"。如果未指定或空字符串时，核心 API 组将被推断出来。

kind

string

kind 是引用的 Kubernetes 资源类型。例如 "Service"。

如果没有指定，则默认为 "Service"。

ExternalName 服务可以引用集群中可能位于的 CNAME DNS 记录，因此很难考虑一致性。它们也可能不安全（请参阅 CVE-2021-25740 了解更多信息）。实施 SHOULD 不支持 ExternalName 服务。

Support: Core （带有 ExternalName 以外的类型的服务）

支持：特定于实现的（类型为 ExternalName 的服务）

name

string

name 是引用的名称。

namespace

string

namespace 是后端的命名空间。如果未指定，本地命名空间将被推断出来。

请注意，当指定与本地命名空间不同的命名空间时，引用命名空间中需要一个 ReferenceGrant 对象，以允许该命名空间的所有者接受引用。详情请查看 ReferenceGrant 文档。

支持：Core

port

整数

port 指定用于此资源的目标端口号。当引用是 Kubernetes 服务时，需要端口。在本例中，端口号是服务端口号，而不是目标端口。对于其他资源，目的地端口可能源自引用资源或此字段。

denominator

整数

numerator

整数

add

数组

在操作前，将给定标头（名称、值）添加到请求。它将附加到与标头名称关联的任何现有值。

input: GET /foo HTTP/1.1 my-header: foo

config: add: - name: "my-header" value: "bar,baz"

输出：GET /foo HTTP/1.1 my-header: foo,bar,baz

add[]

object

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

remove

数组（字符串）

在操作前，从 HTTP 请求中删除给定标头。Remove 的值是 HTTP 标头名称列表。请注意，标头名称区分大小写（请参阅 https://datatracker.ietf.org/doc/html/rfc2616#section-4.2）。

input: GET /foo HTTP/1.1 my-header1: foo my-header2: bar my-header3: baz

config: remove: ["my-header1", "my-header3"]

输出：GET /foo HTTP/1.1 my-header2: bar

set

数组

在操作前，使用给定标头（名称、值）设置覆盖请求。

input: GET /foo HTTP/1.1 my-header: foo

config: set: - name: "my-header" value: "bar"

输出：GET /foo HTTP/1.1 my-header: bar

set[]

object

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

name

string

name 是要匹配的 HTTP 标头的名称。名称匹配必须不区分大小写。（请参阅 https://tools.ietf.org/html/rfc7230#section-3.2）。

如果多个条目指定了等同的标头名称，则第一个带有等效名称的条目必须视为匹配项。带有等同标头名称的后续条目必须忽略。由于标头名称的问题单识别，"foo"和 "Foo" 被视为等同。

value

string

value 是要匹配的 HTTP 标头的值。

name

string

name 是要匹配的 HTTP 标头的名称。名称匹配必须不区分大小写。（请参阅 https://tools.ietf.org/html/rfc7230#section-3.2）。

如果多个条目指定了等同的标头名称，则第一个带有等效名称的条目必须视为匹配项。带有等同标头名称的后续条目必须忽略。由于标头名称的问题单识别，"foo"和 "Foo" 被视为等同。

value

string

value 是要匹配的 HTTP 标头的值。

extensionRef

object

ExtensionRef 是 "filter" 行为的可选、特定于实现的扩展。例如，组 "networking.example.net" 中的资源 "myroutefilter"。ExtensionRef MUST 不用于核心和扩展过滤器。

支持：特定于实施

此过滤器可以在同一规则内多次使用。

requestHeaderModifier

object

RequestHeaderModifier 定义修改请求标头的过滤器的模式。

支持：Core

requestMirror

object

RequestMirror 为镜像请求的过滤器定义一个模式。请求将发送到指定的目的地，但来自该目的地的响应将被忽略。

此过滤器可以在同一规则内多次使用。请注意，并非所有实施都能够支持镜像到多个后端。

支持：扩展

responseHeaderModifier

object

ResponseHeaderModifier 为修改响应标头的过滤器定义模式。

支持：扩展

type

string

Type 标识要应用的过滤器类型。与其他 API 字段一样，类型被分为三个一致性级别：

- core ：过滤类型及其在这个软件包中"Support: Core"定义的相应配置，例如："RequestHeaderModifier".支持 GRPCRoute 的所有实施都必须支持核心过滤器。

- Extended: Filter type 及其对应的配置由这个软件包中的"Support: Extended"定义，例如："RequestMirror"。我们鼓励实施人员支持扩展过滤器。

- 特定于实现的：由特定供应商定义和支持的过滤器。未来，显示多个实施中行为的过滤器将被视为扩展或核心一致性级别。这些过滤器的特定于过滤器的配置使用 ExtensionRef 字段指定。对于自定义 过滤器，type MUST 设置为 "ExtensionRef"。

我们鼓励实施人员定义自定义实施类型，以使用特定于实施的行为来扩展核心 API。

如果无法解析对自定义过滤器类型的引用，则不会跳过过滤器。相反，已由该过滤器处理的请求接收 HTTP 错误响应。

group

string

组是引用的组。例如："gateway.networking.k8s.io"。如果未指定或空字符串时，核心 API 组将被推断出来。

kind

string

kind 是引用的类型。例如 "HTTPRoute" 或 "Service"。

name

string

name 是引用的名称。

add

数组

在操作前，将给定标头（名称、值）添加到请求。它将附加到与标头名称关联的任何现有值。

input: GET /foo HTTP/1.1 my-header: foo

config: add: - name: "my-header" value: "bar,baz"

输出：GET /foo HTTP/1.1 my-header: foo,bar,baz

add[]

object

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

remove

数组（字符串）

在操作前，从 HTTP 请求中删除给定标头。Remove 的值是 HTTP 标头名称列表。请注意，标头名称区分大小写（请参阅 https://datatracker.ietf.org/doc/html/rfc2616#section-4.2）。

input: GET /foo HTTP/1.1 my-header1: foo my-header2: bar my-header3: baz

config: remove: ["my-header1", "my-header3"]

输出：GET /foo HTTP/1.1 my-header2: bar

set

数组

在操作前，使用给定标头（名称、值）设置覆盖请求。

input: GET /foo HTTP/1.1 my-header: foo

config: set: - name: "my-header" value: "bar"

输出：GET /foo HTTP/1.1 my-header: bar

set[]

object

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

name

string

name 是要匹配的 HTTP 标头的名称。名称匹配必须不区分大小写。（请参阅 https://tools.ietf.org/html/rfc7230#section-3.2）。

如果多个条目指定了等同的标头名称，则第一个带有等效名称的条目必须视为匹配项。带有等同标头名称的后续条目必须忽略。由于标头名称的问题单识别，"foo"和 "Foo" 被视为等同。

value

string

value 是要匹配的 HTTP 标头的值。

name

string

name 是要匹配的 HTTP 标头的名称。名称匹配必须不区分大小写。（请参阅 https://tools.ietf.org/html/rfc7230#section-3.2）。

如果多个条目指定了等同的标头名称，则第一个带有等效名称的条目必须视为匹配项。带有等同标头名称的后续条目必须忽略。由于标头名称的问题单识别，"foo"和 "Foo" 被视为等同。

value

string

value 是要匹配的 HTTP 标头的值。

backendRef

object

BackendRef 引用发送镜像请求的资源。

镜像请求必须只发送到此 BackendRef 中的单个目标端点，无论此 BackendRef 中有多少端点。

如果无法找到引用，则此 BackendRef 无效，且必须从网关中丢弃。控制器必须确保将 Route 状态上的 "ResolvedRefs" 条件设置为 status: False，而不是在底层实现中配置此后端。

如果对 ReferenceGrant 不允许 的现有 对象有一个跨命名空间引用，控制器必须确保 Route 上的 "ResolvedRefs" 条件被设置为 status: False，并带有 "RefNotPermitted" 原因，且不会在底层实现中配置此后端。

在任一错误情况下，应该使用 ResolvedRefs Condition 的消息来提供有关此问题的更多详情。

支持：为 Kubernetes Service 扩展

支持：特定于任何其他资源的实现

部分

object

fraction 代表应镜像到 BackendRef 的请求的比例。

只能指定 Fraction 或 Percent 之一。如果没有指定字段，则会镜像 100% 的请求。

百分比

整数

percent 代表应镜像到 BackendRef 的请求百分比。其最小值为 0 （代表请求 0%，其最大值为 100 （代表 100% 的请求）。

只能指定 Fraction 或 Percent 之一。如果没有指定字段，则会镜像 100% 的请求。

group

string

组是引用的组。例如："gateway.networking.k8s.io"。如果未指定或空字符串时，核心 API 组将被推断出来。

kind

string

kind 是引用的 Kubernetes 资源类型。例如 "Service"。

如果没有指定，则默认为 "Service"。

ExternalName 服务可以引用集群中可能位于的 CNAME DNS 记录，因此很难考虑一致性。它们也可能不安全（请参阅 CVE-2021-25740 了解更多信息）。实施 SHOULD 不支持 ExternalName 服务。

Support: Core （带有 ExternalName 以外的类型的服务）

支持：特定于实现的（类型为 ExternalName 的服务）

name

string

name 是引用的名称。

namespace

string

namespace 是后端的命名空间。如果未指定，本地命名空间将被推断出来。

请注意，当指定与本地命名空间不同的命名空间时，引用命名空间中需要一个 ReferenceGrant 对象，以允许该命名空间的所有者接受引用。详情请查看 ReferenceGrant 文档。

支持：Core

port

整数

port 指定用于此资源的目标端口号。当引用是 Kubernetes 服务时，需要端口。在本例中，端口号是服务端口号，而不是目标端口。对于其他资源，目的地端口可能源自引用资源或此字段。

denominator

整数

numerator

整数

add

数组

在操作前，将给定标头（名称、值）添加到请求。它将附加到与标头名称关联的任何现有值。

input: GET /foo HTTP/1.1 my-header: foo

config: add: - name: "my-header" value: "bar,baz"

输出：GET /foo HTTP/1.1 my-header: foo,bar,baz

add[]

object

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

remove

数组（字符串）

在操作前，从 HTTP 请求中删除给定标头。Remove 的值是 HTTP 标头名称列表。请注意，标头名称区分大小写（请参阅 https://datatracker.ietf.org/doc/html/rfc2616#section-4.2）。

input: GET /foo HTTP/1.1 my-header1: foo my-header2: bar my-header3: baz

config: remove: ["my-header1", "my-header3"]

输出：GET /foo HTTP/1.1 my-header2: bar

set

数组

在操作前，使用给定标头（名称、值）设置覆盖请求。

input: GET /foo HTTP/1.1 my-header: foo

config: set: - name: "my-header" value: "bar"

输出：GET /foo HTTP/1.1 my-header: bar

set[]

object

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

name

string

name 是要匹配的 HTTP 标头的名称。名称匹配必须不区分大小写。（请参阅 https://tools.ietf.org/html/rfc7230#section-3.2）。

如果多个条目指定了等同的标头名称，则第一个带有等效名称的条目必须视为匹配项。带有等同标头名称的后续条目必须忽略。由于标头名称的问题单识别，"foo"和 "Foo" 被视为等同。

value

string

value 是要匹配的 HTTP 标头的值。

name

string

name 是要匹配的 HTTP 标头的名称。名称匹配必须不区分大小写。（请参阅 https://tools.ietf.org/html/rfc7230#section-3.2）。

如果多个条目指定了等同的标头名称，则第一个带有等效名称的条目必须视为匹配项。带有等同标头名称的后续条目必须忽略。由于标头名称的问题单识别，"foo"和 "Foo" 被视为等同。

value

string

value 是要匹配的 HTTP 标头的值。

标头

数组

标头指定 gRPC 请求标头匹配器。多个匹配值是 ANDed，这意味着请求需要匹配所有指定的标头才能选择路由。

headers[]

object

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

方法

object

method 指定 gRPC 请求服务/方法匹配器。如果没有指定此字段，则所有服务和方法都将匹配。

name

string

name 是要匹配的 gRPC 标头的名称。

如果多个条目指定了等同的标头名称，则只有具有等同名称的第一个条目才被认为是匹配的。带有等同标头名称的后续条目必须忽略。由于标头名称的问题单识别，"foo"和 "Foo" 被视为等同。

type

string

type 指定如何与标头值匹配。

value

string

value 是要匹配的 gRPC 标头的值。

method

string

要匹配的方法值。如果留空或省略，将匹配所有服务。

至少一个服务和方法必须是非空字符串。

service

string

要匹配的服务的值。如果留空或省略，将匹配任何服务。

至少一个服务和方法必须是非空字符串。

type

string

type 指定如何与服务和/或方法匹配。支持：Core （指定服务和方法）

支持：特定于实现的（使用指定的方法，未指定服务）

支持：特定于实施(RegularExpression)

parents

数组

parents 是与路由关联的父资源（通常是网关）的列表，以及每个父对象的路由的状态。当此路由附加到父路由时，管理父路由的控制器必须在控制器第一次看到路由时向这个列表添加一个条目，并在修改路由或网关时更新条目。

请注意，无法通过此 API 实现解析的父引用不会添加到此列表中。此 API 的实现只能为它们负责的网关/父资源填充 Route 状态。

此列表中最多表示 32 个网关。空列表表示路由尚未附加到任何网关。

parents[]

object

RouteParentStatus 描述了与相关 Parent 相关的路由的状态。

conditions

数组

conditions 描述了与网关相关的路由状态。请注意，路由的可用性也取决于网关自己的状态条件和侦听器状态。

如果 Route 的 ParentRef 指定支持路由路由的现有网关，且网关的控制器有足够的访问权限，那么该网关的控制器必须在 Route 上设置 "Accepted" 条件，以指示网关接受或拒绝该路由，以及原因。

如果网关实施至少一个 Route 规则，则路由必须被视为"接受"。

有些情况下，因为缺少控制器可见性，可能无法设置 "Accepted" 条件，其中包括：

* Route 指的是不存在的父对象。* Route 是控制器不支持的类型。* Route 位于控制器无法访问的命名空间中。

conditions[]

object

condition 包含此 API 资源当前状态的一个方面的详细信息。

controllerName

string

ControllerName 是一个 domain/path 字符串，表示写入此状态的控制器的名称。这与 GatewayClass 上的 controllerName 字段对应。

示例："example.net/gateway-controller"。

此字段的格式是 DOMAIN "/" PATH，其中 DOMAIN 和 PATH 是有效的 Kubernetes 名称(https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names)。

在编写状态时，控制器需要填充此字段。当不再需要时，控制器应确保清理填充其 ControllerName 状态的条目。

parentRef

object

ParentRef 与 spec 中的 ParentRef 对应，这个 RouteParentStatus struct 描述其状态。

lastTransitionTime

字符串

lastTransitionTime 是条件从一个状态转换到另一个状态最后一次的时间。这应该是底层条件变化的时间。如果为未知，则使用 API 字段更改的时间是可以接受的。

message

字符串

Message 是人类可读的消息，指示有关转换的详细信息。这可能是一个空字符串。

observedGeneration

整数

observedGeneration 代表 .metadata.generation，这是条件设置所基于的条件。例如，如果 .metadata.generation 目前为 12，但 .status.conditions[x].observedGeneration 是 9，则代表条件与实例的当前状态已不匹配。

reason

字符串

reason 包含程序标识符，指示条件最后一次转换的原因。特定条件类型的制作者可能会定义预期的值和此字段的含义，以及这些值是否被视为有保证的 API。该值应该是 CamelCase 字符串。此字段可能不是空的。

status

字符串

条件的状态，True, False, Unknown 之一。

type

字符串

CamelCase 或 foo.example.com/CamelCase 中的条件类型。

group

string

组是引用的组。如果未指定，"gateway.networking.k8s.io" 将推断出来。要设置核心 API 组（如 "Service" kind referent），Group 必须明确设置为 "" （空字符串）。

支持：Core

kind

string

kind 是引用的类型。

支持"Core"支持的父资源有两种：

* gateway (Gateway conformance profile)* Service (Mesh conformance profile, only ClusterIP Services)

对其他资源的支持是特定于实施的。

name

string

name 是引用的名称。

支持：Core

namespace

string

namespace 是引用的命名空间。如果未指定，这指的是 Route 的本地命名空间。

请注意，对于跨命名空间边界的 ParentRefs 有特定的规则。只有跨命名空间引用被引用的命名空间中明确允许时才有效。例如： Gateway 具有 AllowedRoutes 字段，ReferenceGrant 提供了一种通用方法来启用其他类型的跨命名空间引用。

支持：Core

port

整数

port 是此 Route 目标的网络端口。它可以根据父资源的类型进行解释。

当父资源是网关时，此目标是在支持此类 Route （并选择此路由）的指定端口上侦听所有的监听程序。不建议设置 Port，除非 Route 中指定的网络行为必须应用到特定端口，而不是可以更改其端口的监听程序。当同时指定了 Port 和 sectionName 时，所选监听器的名称和端口必须与两个指定的值匹配。

实施 MAY 选择支持其他父资源。支持其他类型的父资源的实施必须清楚地记录/如果端口的解释方式。

对于状态，只要父资源接受部分，则附加被视为成功。例如，网关监听程序可以通过 Route kind、namespace 或 hostname 来限制哪些 Routes 可以附加到它们。如果 2 网关监听程序的 1 个接受来自引用路由的附件，则路由必须被视为成功附加。如果没有网关监听程序接受来自此 Route 的附件，则路由必须被视为与网关分离。

支持：扩展

sectionName

string

SectionName 是目标资源中的一个部分的名称。在以下资源中，sectionName 被解释为：

* gateway: Listener 名称。当同时指定了 Port (experimental)和 SectionName 时，所选监听器的名称和端口必须与两个指定的值匹配。* service: 端口名称。当同时指定了 Port (experimental)和 SectionName 时，所选监听器的名称和端口必须与两个指定的值匹配。

实施 MAY 选择支持将路由附加到其他资源。如果是这种情况，它们必须清楚地记录 SectionName 的解释方式。

如果未指定（空字符串），这将引用整个资源。对于状态，如果父资源中的至少一个部分接受它，则附加被视为成功。例如，网关监听程序可以通过 Route kind、namespace 或 hostname 来限制哪些 Routes 可以附加到它们。如果 2 网关监听程序的 1 个接受来自引用路由的附件，则路由必须被视为成功附加。如果没有网关监听程序接受来自此 Route 的附件，则路由必须被视为与网关分离。

支持：Core