第 15 章 Gateway [gateway.networking.k8s.io/v1]

addresses

数组

为此网关请求的地址。这是可选的，行为取决于实现。如果在 spec 中设置值并且请求的地址无效或不可用，实施必须指示在 GatewayStatus.Addresses 中的关联条目中指明这一点。

Addresses 字段表示在网关"外面"地址的请求，此网关绑定的流量将使用。这可以是外部负载均衡器或其他网络基础架构的 IP 地址或主机名，或者流量将发送到的一些其他地址。

如果没有指定地址，实施 MAY 以特定于实施的方式调度网关，分配适当的地址集合。

实现 MUST 将所有 Listeners 绑定到分配给网关的每个网关Address，并在 GatewayStatus.Addresses 中添加对应的条目。

支持：扩展

addresses[]

object

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

gatewayClassName

string

用于此网关的 GatewayClassName。这是 GatewayClass 资源的名称。

infrastructure

object

基础架构定义了有关此网关实例的基础架构级属性。

支持：扩展

监听器

数组

与此网关关联的监听器.侦听器定义在这个网关地址上绑定的逻辑端点。至少指定一个 Listener 必须指定。

不同的 Listeners

一组 Listeners （例如在单个网关中）中的每个 Listener 都有所不同，其中流量流需要能够完全分配给一个侦听器。（本节使用 "Listeners" 而不是 "Listeners in a single Gateway"，因为实现 MAY 合并配置从多个网关合并到单个数据平面，在这种情况下也会应用这些规则。

实际上，这意味着集合中的每个监听程序都必须具有 Port, Protocol, 和 if the protocol, Hostname 的唯一组合。

一些端口、协议和 TLS 设置组合被视为核心支持，且实施必须根据它们支持的对象支持：

HTTPRoute

1.HTTPRoute，端口：80，协议：HTTP 2.HTTPRoute, Port: 443, Protocol: HTTPS, TLS Mode: Terminate, TLS keypair provided

TLSRoute

1.TLSRoute, Port: 443, Protocol: TLS, TLS Mode: Passthrough

"distinct" Listeners 具有以下属性：

该实施可以将入站请求与单个不同的 Listener 匹配。

当多个 Listeners 共享字段的值（例如，具有相同 Port 值的两个 Listeners）时，实现只能使用其他 Listener 字段将请求与其中一个 Listeners 匹配。

当多个监听器对于 Protocol 字段的值相同时，每个带有匹配协议值的 Listeners 值都需要为其他字段有不同的值。

Listener 的 MUST 不同字段集合因协议而异。以下规则定义了哪些字段需要被认为 Listeners 的规则与当前在 Gateway API spec 中定义的每个协议不同。

所有共享协议值都必须使用 不同的值 的监听程序集对于 至少其中一个 字段是不同的：

* HTTP, HTTPS, TLS: Port, Hostname * TCP, UDP: Port

调用 的一个重要 规则涉及在实施时发生：

* 支持 TCP 协议 Listeners，以及 HTTP、HTTPS 或 TLS 协议 Listeners，而 * 会看到与 TCP 协议相同的 端口的 HTTP、HTTPS 或 TLS 协议。

在这种情况下，所有与 TCP Listener 共享端口的 Listeners 并不不同，因此不接受它。

如果实现不支持 TCP 协议 Listeners，则不会应用前面的规则，并且不接受 TCP Listeners SHOULD。

请注意，tls 字段不用于确定监听器是否是不同的，因为 仅在 TLS 配置上有所不同的 Listeners 仍会在所有情况下都冲突。

# 监听程序只通过主机名不同

当 Listeners 只根据主机名不同时，入站请求主机名需要与最具体的特定主机名值匹配，以选择正确的 Listener 及其相关路由集合。

在通配符匹配前，需要处理完全匹配，在回退（空主机名值）匹配前，会处理通配符匹配。例如： "foo.example.com" 优先于 "*.example.com"，而 "\*.example.com" 优先于 ""。

此外，如果有多个通配符条目，必须在较少的特定通配符条目之前处理更具体的通配符条目。例如： "*.foo.example.com" 优先于 "\*.example.com "。

这里的精确定义是通配符字符右侧的点数越高，优先级越高。

通配符字符会将任意数量的字符和 点 与左侧匹配，因此 "*.example.com" 将同时与 "foo.bar.example.com" 和 "bar.example.com" 匹配。

处理不一致的 Listeners

如果一组 Listeners 包含不不同的 Listeners，则这些 Listeners 为冲突，并且实施 MUST 将 Listener 状态中的 " Conflicted " 条件设置为 "True"。

对于本文档的目的，单词 "indistinct" 和 "conflicted" 被视为等效的内容。

实现 MAY 只有在只接受不包含冲突的 Listeners 的部分 Listener 集时，才选择接受带有某些冲突的 Listeners 的网关。

具体来说，实施 MAY 接受部分 Listener 设置，具体取决于以下规则：

* 实施必须选择一个有冲突的 Listener 作为主办者。不接受 ALL indistinct Listeners 进行处理。* 至少有一个不同的 Listener 必须存在，否则网关有效地包含 Listeners，且必须拒绝整个处理。

当网关包含冲突的 Listenered Listeners 是否接受网关时，在网关状态上设置 "ListenersNotValid" 条件。该条件 SHOULD 明确表示消息中哪些 Listeners 被冲突，哪些被接受。另外，这些监听器 SHOULD 的 Listener 状态表示哪些 Listeners 被冲突且没有接受。

常规 Listener 行为

请注意，对于所有不同的 Listener，请求 SHOULD 匹配最多一个 Listener。例如，如果为 "foo.example.com" 和 "*.example.com" 定义 Listeners，则对 "foo.example.com" SHOULD 的请求只使用附加到 "foo.example.com" Listener 的路由。

这个概念被称为 "Listener Isolation"，它是网关 API 的扩展功能。不支持 Listener 隔离功能的实现有明确记录，但必须声明支持 GatewayHTTPListenerIsolation 功能。

支持 Listener 隔离 SHOULD 声明对扩展 网关HTTPListener 隔离功能的 实现，并传递相关的一致性测试。

兼容 Listeners

如果出现以下情况，网关的 Listeners 被视为 兼容 ：

1.它们与众不同。2.该实施可以满足所有所分配的地址上可用的地址要求。

扩展支持中的兼容组合因实施而异。与一个实现兼容的组合可能与另一个实现不兼容。

例如，一个不能在同一地址上提供 TCP 和 UDP 侦听器的实现，或者无法混合 HTTPS 和通用 TLS 侦听同一端口，也不会考虑兼容这些情况，即使它们不同。

如果所有网关中的所有 Listeners 都兼容，则实施 MAY 将单独的网关合并到一组地址上。

在以后的发行版本中，MinItems=1 要求被丢弃。

支持：Core

listeners[]

object

侦听器传播网关接受网络连接的逻辑端点的概念。

type

string

地址的类型。

value

string

地址值。值的有效性取决于控制器的类型和支持。

示例：1.2. 3.4,128::1,my-ip-address.

annotations

对象（字符串）

将 SHOULD 应用到响应此网关创建的任何资源的注解。

对于创建其他 Kubernetes 对象的实现，这应该是对资源的 metadata.annotations 字段。对于其他实现，这指的是任何相关的（特定于实现特定）概念。

实施可能会选择添加其他特定于实施的注解，因为它们认为适合。

支持：扩展

labels

对象（字符串）

SHOULD 应用于响应此网关创建的任何资源的标签。

对于创建其他 Kubernetes 对象的实现，这应该是资源上的 metadata.labels 字段。对于其他实施，这指的是任何相关的（特定于实施的）"标签"概念。

实施可能会选择添加其他特定于实施的标签，因为它们认为适合。

如果实现将这些标签映射到 Pod，或者在标签更改时重新创建任何其他资源，则 SHOULD 会明确警告文档中此行为。

支持：扩展

parametersRef

object

ParametersRef 是对包含与网关对应的配置参数的资源的引用。如果控制器不需要任何其他配置，则这是可选的。

这与 GatewayClass 的 parameter Ref 的参数 相同，但基于每个Gateway

网关的 GatewayClass 可以提供自己的 参数Ref。当两者都被指定时，合并行为是特定于实现的。通常建议 GatewayClass 提供可由网关覆盖的默认值。

如果无法找到引用，请参阅不支持的类型，或者当该资源中的数据格式时，网关 SHOULD 将被拒绝，并将 "Accepted" 状态条件设置为 "False"，以及 "InvalidParameters" 原因。

支持：特定于实施

group

string

组是引用的组。

kind

string

kind 是引用的类型。

name

string

name 是引用的名称。

allowedRoutes

object

allowedRoutes 定义 MAY 附加到 Listener 和存在这些 Route 资源的可信命名空间的路由类型。

虽然客户端请求可能与多个路由规则匹配，但只有一条规则最终可能会收到请求。匹配优先级必须按以下条件顺序决定：

* 根据 Route 类型定义的最具体匹配。* 基于创建时间戳的最旧的路由。例如，创建时间戳为 "2020-09-08 01:02:03" 的路由优先于创建时间戳为 "2020-09-08 01:02:04"。* 如果其它内容都等同，则路由应以字母顺序（命名空间/名称）首先显示。例如，foo/bar 优先于 foo/baz。

应实施附加到此 Listener 的 Route 中的所有有效规则。可以忽略无效的 Route 规则（有时意味着完整的路由）。如果 Route 规则从 valid 转换为无效，则应该丢弃对该 Route 规则的支持以确保一致性。例如，即使 Route 规则指定的过滤器无效，该路由中的其余规则应该仍然被支持。

支持：Core

hostname

string

hostname 指定与定义此概念的协议类型匹配的虚拟主机名。如果未指定，则所有主机名都匹配。对于不需要基于主机名的匹配的协议，会忽略此字段。

实现必须针对以下每个协议正确应用主机名匹配：

* TLS：Listener Hostname 必须与 SNI 匹配。* HTTP: Listener Hostname 必须与请求的 Host 标头匹配。* HTTPS：Listener Hostname SHOULD 与 SNI 和 Host 标头匹配。请注意，这不需要 SNI 和 Host 标头相同。下面更详细地描述了这种情况的语义。

为确保安全性，RFC-6066 的第 11.1 节强调了依赖 SNI 主机名匹配的服务器实施，也会验证应用程序协议中的主机名。

RFC-7540 章节 9.1.2 提供了通过响应 HTTP 421 Misdirected Request status 代码来拒绝重复使用连接的机制。这表示原始服务器已拒绝请求，因为它似乎被错误直接。

要检测错误直接的请求，Gateways SHOULD 与在同一端口和协议上的所有 SNI 主机名中配置的请求授权匹配：

* 如果另一个 Listener 具有完全匹配或更具体的通配符条目，则网关 SHOULD 会返回 421。* 如果当前 Listener （在 ClientHello 期间由 SNI 匹配）与 Host: * 不匹配，如果另一个 Listener 与主机匹配，则网关 SHOULD 返回 421。* 如果没有其他 Listener 匹配主机，则网关必须返回一个 404。

对于 HTTPRoute 和 TLSRoute 资源，有与 spec.hostnames 数组的交互。当监听程序和路由都指定主机名时，接受 Route 的值之间需要有一个交集。如需更多信息，请参阅特定于路由的主机名文档。

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

支持：Core

name

string

name 是 Listener 的名称。此名称必须在网关内唯一。

支持：Core

port

整数

port 是网络端口。多个监听器可能会使用相同的端口，受 Listener 兼容性规则。

支持：Core

protocol

string

protocol 指定此监听器希望接收的网络协议。

支持：Core

tls

object

TLS 是 Listener 的 TLS 配置。如果 Protocol 字段是 "HTTPS" 或 "TLS"，则需要此字段。如果 Protocol 字段是 "HTTP", "TCP", 或 "UDP"，则设置此字段无效。

GatewayTLSConfig 中定义的 SNI 与 GatewayTLSConfig 中定义的证书根据此监听程序的 Hostname 字段定义。

GatewayClass MUST 对任何 TLS 握手使用与所有可用证书匹配的最长 SNI。

支持：Core

kind

数组

kind 指定允许绑定到此网关 Listener 的组和路由类型。如果未指定或为空，则使用 Listener 协议决定选择的路由类型。

RouteGroupKind MUST 与 Listener 协议 字段中指定的应用程序协议兼容的路由类型对应。如果实现不支持或识别此资源类型，则必须将这个 Listener 的 "ResolvedRefs" 条件设置为 False，原因为 "InvalidRouteKinds"。

支持：Core

kinds[]

object

RouteGroupKind 表示组和 Route 资源的类型。

命名空间

object

命名空间表示可以从哪个路由附加到此 Listener 的命名空间。默认情况下，这仅限于此网关的命名空间。

支持：Core

group

string

group 是 Route 的组。

kind

string

kind 是 Route 的种类。

from

string

from 表示为这个网关选择 Routes 的位置。可能的值有：

：此网关都可以使用所有命名空间中的 all: 路由。* selector: 由选择器选择的命名空间中的路由可以被此网关使用。* 相同：只有同一命名空间中的路由可以被这个网关使用。

支持：Core

selector

object

当 From 设置为 "Selector" 时，必须指定选择器。在这种情况下，只有与这个 Selector 匹配的命名空间中的 Routes 才会被这个网关选择。对于"From"的其他值，会忽略此字段。

支持：Core

matchExpressions

array

matchExpressions 是标签选择器要求列表。要求的逻辑关系是 AND。

matchExpressions[]

对象

标签选择器要求是一个选择器，其中包含与键和值相关的值、键和值。

matchLabels

对象（字符串）

matchLabels 是 {key,value} 对的映射。MatchLabels 映射中的单个 {key,value} 等同于 matchExpressions 的一个元素，其 key 字段是 "key"，运算符是 "In"，值数组仅包含 "value"。要求的逻辑关系是 AND。

key

字符串

key 是选择器应用到的标签键。

operator

字符串

运算符代表一个键与一组值的关系。有效的运算符是 In、NotIn、Exists 和 DoesNotExist。

值

数组（字符串）

值是字符串值的数组。如果运算符是 In 或 NotIn，则值数组必须是非空的。如果运算符是 Exists 或 DoesNotExist，则值数组必须为空。这个数组会在策略性合并补丁中被替换。

certificateRefs

数组

CertificateRefs 包含一系列对包含 TLS 证书和私钥的 Kubernetes 对象的引用。这些证书用于为与关联监听程序的主机名匹配的请求建立 TLS 握手。

对 Kubernetes Secret 的单个 CertificateRef 具有 "Core" 支持。实现 MAY 选择支持将多个证书附加到 Listener，但此行为是特定于实现的。

对不同命名空间中的资源的引用是无效的 UNLESS，目标命名空间中有一个参考Grant，允许附加证书。如果 ReferenceGrant 不允许此引用，则此监听器的 "ResolvedRefs" 条件必须为 False，原因为 "RefNotPermitted"。

当模式被设置为 "Terminate" （默认），且是可选的时，需要至少有一个元素。

CertificateRefs 可以引用标准 Kubernetes 资源，如 Secret 或特定于实现的自定义资源。

Support: Core - 对类型为 kubernetes.io/tls 的 Kubernetes Secret 的单一引用

支持：特定于实施的（而不是一个参考或其他资源类型）

certificateRefs[]

object

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

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

对具有无效 Group 和 Kind 的对象的引用无效，且必须由实施被拒绝，并在包含对象上设置适当的 Conditions。

模式

string

mode 定义客户端启动的 TLS 会话的 TLS 行为。有两种可能模式：

- 终止：下游客户端和网关之间的 TLS 会话在网关终止。此模式需要以某种方式指定证书，如填充 certificateRefs 字段。- Passthrough：TLS 会话不会由网关终止。这意味着网关无法解码 TLS 流，但 TLS 协议的 ClientHello 消息除外。这个模式中会忽略 certificateRefs 字段。

支持：Core

options

对象（字符串）

选项是键/值对列表，用于为每个实现启用扩展 TLS 配置。例如，配置最小 TLS 版本或支持的密码套件。

API 将定义一组通用密钥 MAY。为了避免任何模糊的实现特定实施定义，需要使用域前缀名称，如 example.com/my-custom-option。未前缀的名称为网关 API 定义的密钥名称保留。

支持：特定于实施

group

string

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

kind

string

kind 是引用的类型。例如 "Secret"。

name

string

name 是引用的名称。

namespace

string

namespace 是引用对象的命名空间。如果未指定，本地命名空间将被推断出来。

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

支持：Core

addresses

数组

addresses 列出已绑定到网关的网络地址。

这个列表可能与某些条件下 spec 中提供的地址不同：

* 没有指定地址，所有地址都会被动态分配为指定地址的组合，并分配动态地址的 * 一个指定的地址不可用（例如已在使用中）

addresses[]

object

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

conditions

数组

条件描述了网关的当前条件。

实现应该更喜欢使用 GatewayConditionType 和 GatewayConditionReason 常量来表达网关条件，以便操作员和工具可以聚合到通用 vocabulary 来描述网关状态。

已知条件类型是：

* "accepted" * "Programmed" * "Ready"

conditions[]

object

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

监听器

数组

监听器为 Spec 中定义的每个唯一监听程序端口提供状态。

listeners[]

object

ListenerStatus 是与 Listener 关联的状态。

type

string

地址的类型。

value

string

地址值。值的有效性取决于控制器的类型和支持。

示例：1.2. 3.4,128::1,my-ip-address.

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 中的条件类型。

attachedRoutes

整数

AttachedRoutes 代表已成功附加到此 Listener 的路由总数。

成功将路由附加到 Listener 只会基于相应 Listener 和 Route 的 ParentRefs 字段上的 AllowedRoutes 字段的组合。当一个 Route 被 Listener 的 AllowedRoutes 字段选择，并且 Route 有一个有效的 ParentRef 选择整个网关资源，或一个特定的 Listener 作为父资源（可在各种 Route 类型 ParentRefs 字段的文档中找到它）。监听器或 Route 状态不会影响成功附加，即对于带有 condition Accepted: false 和 MUST 计数的 Listeners 设置 AttachedRoutes 字段数。

此字段使用包括对 Route 附加进行故障排除，并测量对 Listener 的更改的影响。

conditions

数组

条件描述了此侦听器的当前条件。

conditions[]

object

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

name

string

name 是此状态对应的 Listener 的名称。

supportedKinds

数组

SupportedKinds 是指示此监听程序支持的 Kinds 的列表。这必须代表支持该 Listener 配置的实施。

如果在不支持的 Spec 中指定类型，它们必须不会出现在此列表中，并且实施必须将 "ResolvedRefs" 条件设置为 "False"，并带有 "InvalidRouteKinds" 原因。如果同时指定了有效和无效的 Route 类型，实现必须引用指定的有效 Route 类型。

supportedKinds[]

object

RouteGroupKind 表示组和 Route 资源的类型。

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

group 是 Route 的组。

kind

string

kind 是 Route 的种类。