通用发现 API 组件 (proto)

service.discovery.v3.ResourceLocator

[service.discovery.v3.ResourceLocator proto]

指定要订阅的资源。

{
  "name": ...,
  "dynamic_parameters": {...}
}

name: (string) 要订阅的资源名称。

dynamic_parameters: (repeated map<string, string>) 用于与资源上的动态参数约束匹配的一组动态参数。这允许客户端在同一资源的多个变体之间进行选择。

service.discovery.v3.ResourceName

[service.discovery.v3.ResourceName proto]

指定具体的资源名称。

{
  "name": ...,
  "dynamic_parameter_constraints": {...}
}

name: (string) 资源的名称。

dynamic_parameter_constraints: (service.discovery.v3.DynamicParameterConstraints) 与该资源关联的动态参数约束。在匹配订阅的资源定位器时，由客户端缓存（包括 xDS 代理）使用。

service.discovery.v3.DiscoveryRequest

[service.discovery.v3.DiscoveryRequest proto]

DiscoveryRequest 请求在某些 API 上针对给定 Envoy 节点的相同类型的版本化资源集。

{
  "version_info": ...,
  "node": {...},
  "resource_names": [],
  "type_url": ...,
  "response_nonce": ...,
  "error_detail": {...}
}

version_info: (string) 请求消息中提供的 version_info 将是使用最近成功处理的响应接收到的 version_info，或者在第一次请求时为空。预期在收到响应后不会发送新的请求，直到 Envoy 实例准备 ACK/NACK 新配置。ACK/NACK 分别通过返回应用的新 API 配置版本或之前的 API 配置版本来进行。每个 type_url（见下文）都有一个与其关联的独立版本。

node: (config.core.v3.Node) 发出请求的节点。

resource_names: (repeated string) 要订阅的资源列表，例如集群名称列表或路由配置名称。如果为空，则返回 API 的所有资源。LDS/CDS 可能有空的 resource_names，这将导致返回 Envoy 实例的所有资源。然后，LDS 和 CDS 响应将暗示需要通过 EDS/RDS 获取的资源数量，这些资源将在 resource_names 中显式枚举。

type_url: (string) 所请求资源的类型，例如“type.googleapis.com/envoy.api.v2.ClusterLoadAssignment”。这在通过单例 xDS API（例如 CDS、LDS 等）发出的请求中是隐式的，但在 ADS 中是必需的。

response_nonce: (string) 与正在 ACK/NACK 的 DiscoveryResponse 对应的 nonce。请参阅上面关于 version_info 和 DiscoveryResponse nonce 注释的讨论。这可能为空，仅当 1) 这是非持久流 xDS，例如 HTTP，或者 2) 客户端尚未在该 xDS 流中接受更新（与 delta 不同，它仅在新的显式 ACK 时填充）。

error_detail: (Status) 当之前的 DiscoveryResponse 无法更新配置时，将填充此值。 message 字段位于 error_details 中，提供了与故障相关的 Envoy 内部异常。它仅用于手动调试，提供的字符串不能保证在 Envoy 版本之间保持稳定。

service.discovery.v3.DiscoveryResponse

[service.discovery.v3.DiscoveryResponse proto]

{
  "version_info": ...,
  "resources": [],
  "type_url": ...,
  "nonce": ...,
  "control_plane": {...}
}

version_info: (string) 响应数据的版本。

resources: (repeated Any) 响应资源。这些资源是类型化的，并且取决于所调用的 API。

type_url: (string) 资源的类型 URL。在 ADS 上复用时标识 xDS API。必须与“资源”重复的 Any（如果非空）中的 type_url 保持一致。

nonce: (string) 对于基于 gRPC 的订阅，nonce 提供了一种方法来在后续的 DiscoveryRequest 中显式确认特定的 DiscoveryResponse。在该 DiscoveryResponse 发送时，可能已通过 Envoy 向管理服务器发送了有关先前版本的其他消息，这些消息在响应发送时未处理。nonce 允许管理服务器忽略对先前版本的任何进一步的 DiscoveryRequest，直到收到带有 nonce 的 DiscoveryRequest 为止。nonce 是可选的，对于非流式 xDS 实现来说不是必需的。

control_plane: (config.core.v3.ControlPlane) 发送响应的控制平面实例。

service.discovery.v3.DeltaDiscoveryRequest

[service.discovery.v3.DeltaDiscoveryRequest proto]

DeltaDiscoveryRequest 和 DeltaDiscoveryResponse 用于 Delta xDS 的新 gRPC 端点。

使用 Delta xDS，DeltaDiscoveryResponse 不需要包含跟踪资源的完整快照。相反，DeltaDiscoveryResponse 是对 xDS 客户端状态的差异。在 Delta XDS 中，有每个资源的版本，这允许在资源粒度跟踪状态。xDS Delta 会话始终处于 gRPC 双向流的上下文中。这允许 xDS 服务器跟踪连接到它的 xDS 客户端的状态。

在 Delta xDS 中，nonce 字段是必需的，用于将 DeltaDiscoveryResponse 与 DeltaDiscoveryRequest ACK 或 NACK 配对。可选地，消息级 system_version_info 存在于响应消息中，仅用于调试目的。

DeltaDiscoveryRequest 扮演两个独立的角色。任何 DeltaDiscoveryRequest 都可以是以下任一或两者：[1] 通知服务器客户端获得了哪些资源或失去了对哪些资源的兴趣（使用 resource_names_subscribe 和 resource_names_unsubscribe），或者 [2]（N）ACK 服务器的早期资源更新（使用 response_nonce，error_detail 的存在使其成为 NACK）。此外，重新连接的 gRPC 流的第一个消息（对于给定的 type_url）具有第三个作用：使用 initial_resource_versions 字段通知服务器客户端已经拥有的资源（及其版本）。

与世界状态一样，当多个资源类型复用（ADS）时，所有请求/确认/更新在逻辑上都由 type_url 隔离：Cluster ACK 存在于与先前 Route NACK 完全不同的世界中。特别是，在每个 gRPC 流的“开始”发送的 initial_resource_versions 实际上包含每个 type_url 的消息，每个消息都有自己的 initial_resource_versions。

{
  "node": {...},
  "type_url": ...,
  "resource_names_subscribe": [],
  "resource_names_unsubscribe": [],
  "initial_resource_versions": {...},
  "response_nonce": ...,
  "error_detail": {...}
}

node: (config.core.v3.Node) 发出请求的节点。

type_url: (string) 所请求资源的类型，例如 type.googleapis.com/envoy.api.v2.ClusterLoadAssignment。如果资源仅通过 xds_resource_subscribe 和 xds_resources_unsubscribe 引用，则不需要设置此值。

resource_names_unsubscribe: (repeated string) 要从跟踪资源列表中删除的资源名称列表。

initial_resource_versions: (重复 map<字符串, 字符串>) 通知服务器 xDS 客户端已知资源的版本，使客户端即使在 gRPC 流重新连接的情况下也能继续相同的逻辑 xDS 会话。它不会被填充：[1] 在会话的第一个流中，因为客户端还没有任何资源，[2] 在流中（对于给定的 type_url）的第一个消息之后的任何消息中，因为服务器已经正确跟踪客户端的状态。（在 ADS 中，重新连接的流的每个 type_url 的第一条消息会填充此映射。）映射的键是 xDS 客户端已知的 xDS 资源的名称。映射的值是不透明的资源版本。

response_nonce: (字符串) 当 DeltaDiscoveryRequest 是对之前 DeltaDiscoveryResponse 的 ACK 或 NACK 消息时，response_nonce 必须是 DeltaDiscoveryResponse 中的 nonce。否则（与 DiscoveryRequest 不同），response_nonce 必须省略。

error_detail: (状态) 这是在之前的 DiscoveryResponse 无法更新配置时填充的。 message 字段在 error_details 中提供与失败相关的 Envoy 内部异常。

service.discovery.v3.DeltaDiscoveryResponse

[service.discovery.v3.DeltaDiscoveryResponse 原型]

{
  "system_version_info": ...,
  "resources": [],
  "type_url": ...,
  "removed_resources": [],
  "removed_resource_names": [],
  "nonce": ...
}

system_version_info: (字符串) 响应数据的版本（用于调试）。

resources: (重复 service.discovery.v3.Resource) 响应资源。这些是类型化的资源，其类型必须与 type_url 字段匹配。

type_url: (字符串) 资源的类型 URL。在通过 ADS 多路复用时识别 xDS API。如果“资源”不为空，则必须与“资源”中 Any 内的 type_url 保持一致。

removed_resources: (重复字符串) 已删除并要从 xDS 客户端中删除的资源的资源名称。可以忽略缺少资源的已删除资源。

removed_resource_names: (重复 service.discovery.v3.ResourceName) removed_resources 的替代方法，允许指定要删除的资源的哪个变体。此变体必须用于任何已向客户端发送动态参数约束的资源。

nonce: (字符串) nonce 提供了一种方法，使 DeltaDiscoveryRequests 在 (N)ACK 时能够唯一地引用 DeltaDiscoveryResponse。nonce 是必需的。

service.discovery.v3.DynamicParameterConstraints

[service.discovery.v3.DynamicParameterConstraints 原型]

与单个 xDS 资源的变体相关联的一组动态参数约束。这些约束决定资源是否根据订阅中的动态参数集匹配订阅，如 ResourceLocator.dynamic_parameters 字段中所指定。这允许 xDS 实现（客户端、服务器和缓存代理）确定哪个资源变体适合给定客户端。

{
  "constraint": {...},
  "or_constraints": {...},
  "and_constraints": {...},
  "not_constraints": {...}
}

constraint

(service.discovery.v3.DynamicParameterConstraints.SingleConstraint) 要评估的单个约束。

仅 constraint、or_constraints、and_constraints、not_constraints 可以设置。

or_constraints

(service.discovery.v3.DynamicParameterConstraints.ConstraintList) 如果列表中的任何一个约束匹配，则匹配的约束列表。

仅 constraint、or_constraints、and_constraints、not_constraints 可以设置。

and_constraints

(service.discovery.v3.DynamicParameterConstraints.ConstraintList) 必须全部匹配的约束列表。

仅 constraint、or_constraints、and_constraints、not_constraints 可以设置。

not_constraints

(service.discovery.v3.DynamicParameterConstraints) 一组约束的逆（非）。

仅 constraint、or_constraints、and_constraints、not_constraints 可以设置。

service.discovery.v3.DynamicParameterConstraints.SingleConstraint

[service.discovery.v3.DynamicParameterConstraints.SingleConstraint 原型]

给定键的单个约束。

{
  "key": ...,
  "value": ...,
  "exists": {...}
}

key: (字符串) 要匹配的键。

value

(字符串) 匹配此确切值。

仅 value、exists 可以设置。

exists

(service.discovery.v3.DynamicParameterConstraints.SingleConstraint.Exists) 键存在（匹配任何值，除了键不存在）。这允许为不发送任何键的客户端设置默认约束，而其他客户端可能需要基于该键的特殊配置。

仅 value、exists 可以设置。

service.discovery.v3.DynamicParameterConstraints.SingleConstraint.Exists

[service.discovery.v3.DynamicParameterConstraints.SingleConstraint.Exists 原型]

service.discovery.v3.DynamicParameterConstraints.ConstraintList

[service.discovery.v3.DynamicParameterConstraints.ConstraintList 原型]

{
  "constraints": []
}

constraints: (重复 service.discovery.v3.DynamicParameterConstraints)

service.discovery.v3.Resource

[service.discovery.v3.Resource 原型]

{
  "name": ...,
  "resource_name": {...},
  "aliases": [],
  "version": ...,
  "resource": {...},
  "ttl": {...},
  "metadata": {...}
}

name: (字符串) 资源的名称，用于将其与相同类型资源的其他资源区分开来。仅 name 或 resource_name 可以设置。

resource_name: (service.discovery.v3.ResourceName) name 字段的替代方法，用于在服务器支持由动态参数约束区分的命名资源的多个变体时使用。仅 name 或 resource_name 可以设置。

aliases: (重复字符串) 别名是此资源可以使用的其他名称列表。

version: (字符串) 资源级别版本。它允许 xDS 跟踪各个资源的状态。

resource: (任何) 被跟踪的资源。

ttl

(持续时间) 资源的生存时间值。对于每个资源，都会启动一个计时器。每次收到具有新 TTL 的资源时，计时器都会重置。如果收到没有设置 TTL 的资源，则会为该资源删除计时器。计时器到期后，将删除该资源的配置。

TTL 可以通过发送不更改资源版本的响应来刷新或更改。在这种情况下，resource 字段不需要填充，这允许进行轻量级“心跳”更新以使具有 TTL 的资源保持活动状态。

TTL 功能旨在支持在管理服务器出现故障时应删除的配置。例如，该功能可用于故障注入测试，其中故障注入应在 Envoy 失去与管理服务器的联系时终止。

metadata: (config.core.v3.Metadata) Metadata 字段可用于为资源提供其他信息。例如，用于调试的跟踪数据。