Envoy xDS 与资源 API 的 Protocol Buffer 定义全解v2 API 包【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy导读本文以api/envoy/api/v2/README.md为骨架系统讲解 Envoy 的 xDSx Discovery Service协议与顶层资源 API 消息在 Protocol Bufferprotobuf层面的定义方式包括//envoy/api/v2:friends包组的可见性约束、CDS/LDS/EDS/RDS/SRDS/VHDS 六大发现服务的 gRPC 接口形态以及DiscoveryRequest/DiscoveryResponse/DeltaDiscoveryRequest/DeltaDiscoveryResponse等通用发现协议消息的字段语义。读完本文你将掌握如何阅读这套 v2 API 的.proto文件、理解 xDS 全量与 Delta 两种订阅模式的差异并能顺着import public链与move_to_package注解追踪到资源类型的定义位置及其 v3 迁移方向。一、v2 API 包的整体定位1.1 一句话定位api/envoy/api/v2/README.md开门见山本目录存放的是xDS 与顶层资源 API 消息的 Protocol Buffer 定义。所谓“顶层资源 API 消息”指的是那些直接由 Envoy 实例向管理面management server订阅的资源类型——集群Cluster、监听器Listener、端点ClusterLoadAssignment、路由RouteConfiguration、作用域路由ScopedRouteConfiguration等以及承载这些资源传输的发现协议消息本身。从实际目录结构看api/envoy/api/v2/下共有 11 个顶层.proto文件文件主题discovery.proto通用发现协议组件Discovery/DeltaDiscovery 消息cds.protoCluster Discovery ServiceCDSlds.protoListener Discovery ServiceLDSeds.protoEndpoint Discovery ServiceEDSrds.protoRoute Discovery ServiceRDS Virtual Host Discovery ServiceVHDSsrds.protoScoped Routes Discovery ServiceSRDScluster.protoCluster 资源消息listener.protoListener 资源消息endpoint.protoClusterLoadAssignment 资源消息route.protoRouteConfiguration 资源消息scoped_route.protoScopedRouteConfiguration 资源消息配套的子包目录还有auth/、cluster/、core/、endpoint/、listener/、route/、ratelimit/其中 core/ 与 auth/ 被整个//envoy/api/v2的各个子包广泛引用。1.2 README 的核心规则//envoy/api/v2:friends包组README 强调了一条对 API 演进至关重要的 Bazel 可见性约束Package group//envoy/api/v2:friends枚举了所有共享 API 消息的消费者。所有共享定义的默认可见性都应设置为//envoy/api/v2:friends。这意味着这些 protobuf 定义并非对仓库内任意目标开放而是通过 Bazel 的visibility机制限定在“友方包组”内。这样做的目的很明确防止其他模块随意依赖内部 API 细节在 API 冻结FROZEN与迁移到 v3 的过程中把依赖面控制在一个可审计的集合内保证 Envoy 主仓库、go-control-plane等生成代码消费方与 API 定义同步演进。此外 README 还点名了envoy.api.v2.core与envoy.api.v2.auth两个子包它们在整个//envoy/api/v2的子包中被广泛消费core 提供 Node、Address、ConfigSource、GrpcService 等通用类型auth 提供 TLS 证书相关的 TransportSocket 配置是共享 API 消息的典型代表。二、通用发现协议discovery.proto 逐字段精读discovery.proto 是理解整个 xDS 协议的基础文件它不定义任何具体资源而是定义“资源是怎么被请求、被分发、被确认”的传输层消息。文件顶部option (udpa.annotations.file_status).package_version_status FROZEN;明确标注该包已冻结不再新增字段且option (udpa.annotations.file_migrate).move_to_package envoy.service.discovery.v3;指示其后续迁移目标为 v3 的 discovery 服务包。2.1 DiscoveryRequest全量SotW模式的订阅请求DiscoveryRequest用于经典的全量状态同步State of the WorldSotW模式字段如下字段类型语义version_infostring最近一次成功处理响应的版本号首次请求为空字符串。收到响应后Envoy 在准备好 ACK/NACK 之前不会发送新请求nodecore.Node发起请求的节点标识resource_namesrepeated string要订阅的资源名列表为空表示订阅该 API 的全部资源。LDS/CDS 允许为空拉取全部监听器/集群进而通过 EDS/RDS 显式列出需要获取的次级资源名type_urlstring请求的资源类型例如type.googleapis.com/envoy.api.v2.ClusterLoadAssignment。在 CDS/LDS 等单例 xDS API 中隐式可知但在 ADS聚合发现服务多路复用场景下必须显式携带response_noncestring被 ACK/NACK 的DiscoveryResponse对应的 nonce。仅在非持久流式 xDS如 HTTP或客户端尚未接受任何更新时可为空error_detailgoogle.rpc.Status当上一次响应未能成功更新配置时填充error_detail.message给出 Envoy 内部异常信息仅供人工调试字符串格式不保证跨版本稳定值得注意的协议语义version_info与每个type_url一一对应、彼此独立ACK 表示客户端已应用新版本配置回传新版本号NACK 表示拒绝新配置回传旧版本号并填充error_detail。2.2 DiscoveryResponse全量模式的分发响应DiscoveryResponse的字段字段类型语义version_infostring响应数据的版本号resourcesrepeated google.protobuf.Any响应资源类型随所调用的 API 而定canarybool标注金丝雀canary配置配合--terminate-on-canary-transition-failure与--dry-run-canary两个命令行标志使用当前标记为[#not-implemented-hide:]type_urlstring资源类型 URL在 ADS 多路复用时用于标识 xDS API须与resources中 Any 的类型一致noncestring供客户端在下一次DiscoveryRequest中显式 ACK 该响应管理面据此忽略携带旧版本 nonce 的迟到请求control_planecore.ControlPlane发送响应的控制面实例标识当前标记为[#not-implemented-hide:]2.3 Delta 模式按资源粒度增量同步DeltaDiscoveryRequest与DeltaDiscoveryResponse用于新的 gRPC delta 端点。与全量模式的核心差异在于delta 响应不需要包含被跟踪资源的完整快照而是相对 xDS 客户端状态的差异diff并且版本号以单个资源为粒度。delta 会话始终处于 gRPC 双向流上下文中服务端可以持续跟踪每个连接客户端的状态。DeltaDiscoveryRequest承担两类相互独立的职责一条消息可以同时具备两种角色订阅变更通知通过resource_names_subscribe加入跟踪列表与resource_names_unsubscribe移出跟踪列表表达客户端对资源的兴趣增减NACK通过携带response_nonce确认之前的资源更新当error_detail存在时即为 NACK。另外断线重连后的每条 gRPC 流的首条消息对某个type_url而言还有第三个角色通过initial_resource_versionsmap键为资源名、值为不透明版本号告知服务端客户端已拥有的资源及其版本从而在流重连后延续同一个逻辑 xDS 会话。该字段的填充规则会话的首条流不填充客户端此时没有任何资源流内首条之后的消息不填充服务端已正确跟踪客户端状态在 ADS 场景下重连流的每个 type_url 的首条消息都会填充各自的initial_resource_versions。一个关键且易踩坑的语义与全量模式不同delta 模式下resource_names_subscribe/resource_names_unsubscribe为空列表仅表示“没有要增删的资源”而不表示订阅全部但服务端必须对所有resource_names_subscribe列出的资源作出响应即使它认为客户端已持有最新版本因为客户端可能在发出 unsubscribe 之前就重新订阅了该资源——proto 注释中明确以测试用例DeltaSubscriptionStateTest.RemoveThenAdd佐证了这一场景。DeltaDiscoveryResponse字段字段类型语义system_version_infostring响应数据版本仅用于调试resourcesrepeated Resource增量资源类型须与type_url一致type_urlstring资源类型 URLADS 多路复用时标识 xDS APIremoved_resourcesrepeated string需要从 xDS 客户端删除的资源名对不存在的资源可忽略noncestring供DeltaDiscoveryRequest唯一引用该响应进行 (N)ACK必填Resource消息则是 delta 模式下的资源包装name资源名用于与其他同类型资源区分aliases该资源的其他别名列表version资源级版本号支持按资源粒度跟踪状态resource被跟踪的资源本体google.protobuf.Any。三、六大发现服务的接口形态envoy/api/v2下的每个服务都遵循相同的三端点模式StreamXxxSotW 双向流、DeltaXxxdelta 双向流、FetchXxx单次 REST 拉取并通过envoy.annotations.resource注解声明其分发的资源类型。下表汇总以仓库内.proto文件为准服务文件资源类型REST 端点ClusterDiscoveryServicecds.protoenvoy.api.v2.Cluster/v2/discovery:clustersListenerDiscoveryServicelds.protoenvoy.api.v2.Listener/v2/discovery:listenersEndpointDiscoveryServiceeds.protoenvoy.api.v2.ClusterLoadAssignment/v2/discovery:endpointsRouteDiscoveryServicerds.protoenvoy.api.v2.RouteConfiguration/v2/discovery:routesVirtualHostDiscoveryServicerds.protoenvoy.api.v2.route.VirtualHost—仅 deltaScopedRoutesDiscoveryServicesrds.protoenvoy.api.v2.ScopedRouteConfiguration/v2/discovery:scoped-routes3.1 CDS集群发现cds.proto 定义了ClusterDiscoveryService其职责注释很简洁“返回此代理将向其负载均衡的集群列表。”三个 RPC 分别是rpc StreamClusters(stream DiscoveryRequest) returns (stream DiscoveryResponse) {} rpc DeltaClusters(stream DeltaDiscoveryRequest) returns (stream DeltaDiscoveryResponse) {} rpc FetchClusters(DiscoveryRequest) returns (DiscoveryResponse) { option (google.api.http).post /v2/discovery:clusters; option (google.api.http).body *; }该文件还通过import public envoy/api/v2/cluster.proto;将Cluster资源定义对外转发这样下游只需 importcds.proto即可同时获得服务与资源类型。文件内另有一个CdsDummy空消息注释说明这是为了绕开 C protobuf 在“仅含服务、不含消息”的文件上的已知 issuegoogle/protobuf#4221属于构建层面的 workaround并非配置项。3.2 LDS监听器发现lds.proto 定义ListenerDiscoveryService。其文档注释交代了监听器的生命周期语义Envoy 启动时发起 RPC 以发现监听器列表更新以流式方式整体下发每次都是一次全量更新对已消失监听器上的既有连接允许排空drain完成。三种 RPC 形态与 CDS 一致DeltaListeners/StreamListeners/FetchListenersREST 端点为/v2/discovery:listeners。3.3 EDS端点发现eds.proto 定义EndpointDiscoveryService分发ClusterLoadAssignment。其关键约定DiscoveryRequest.resource_names字段指定要订阅的集群名列表——即 EDS 是按集群名粒度订阅端点集的。当 CDS 下发了一个eds_cluster_config类型为 EDS 的集群后Envoy 会自动以该集群名为resource_names发起 EDS 请求这正是 xDS 中“CDS 隐含驱动 EDS 请求”的联动机制。3.4 RDS 与 VHDS路由与虚拟主机发现rds.proto 定义了两个服务RouteDiscoveryService分发RouteConfiguration。resource_names字段指定路由配置名从而允许一个包含多个 HTTP 监听器及多个 HTTP 连接管理器过滤器的 Envoy 配置使用不同的路由表每个监听器通过该标识把 HTTP 连接管理器绑定到对应的路由表。VirtualHostDiscoveryServiceVHDS用于动态更新某个RouteConfiguration下的虚拟主机列表。当配置了 VHDS 且一次 HTTP 请求无法解析出路由时会在请求处理过程中触发虚拟主机列表更新。resource_names_subscribe包含要跟踪的虚拟主机名或别名别名即 HTTP 请求的host/authority头内容xDS 服务端依据VirtualHost.domains字段的内容将别名与虚拟主机匹配resource_names_unsubscribe包含已从该路由表退订的虚拟主机名。注意 VHDS只提供 delta 形态的DeltaVirtualHostsRPC。3.5 SRDS作用域路由发现srds.proto 定义ScopedRoutesDiscoveryService分发ScopedRouteConfiguration。每个ScopedRouteConfiguration代表一个“路由作用域routing scope”包含一组映射允许 HTTP 连接管理器按请求动态指派路由表通过RouteConfiguration消息指定。它解决了“多个租户/多个域名共享同一组监听器但需要不同路由”的场景REST 端点为/v2/discovery:scoped-routes。四、资源消息与子包core 与 auth4.1 import public 的资源转发链顶层服务文件均通过import public转发对应的资源定义形成一条清晰的阅读路径cds.proto --import public-- cluster.proto lds.proto --import public-- listener.proto eds.proto --import public-- endpoint.proto rds.proto --import public-- route.proto srds.proto --import public-- scoped_route.proto而 BUILD 文件由tools/proto_format/proto_sync.py生成勿手改进一步展示了//envoy/api/v2:pkg的依赖全景auth/pkg、cluster/pkg、core/pkg、endpoint/pkg、listener/pkg、route/pkg、envoy/config/filter/accesslog/v2:pkg、envoy/config/listener/v2:pkg、envoy/type:pkg以及xds//udpa/annotations:pkg——这正是 README 所述“core 与 auth 被整个 v2 包消费”的构建级印证。4.2 core 子包跨 API 共享的通用类型envoy.api.v2.core是 xDS 消息的“公共底座”其 BUILD 目录 下包含base.proto定义Node、Localityregion/zone/sub_zone、RoutingPriorityDEFAULT/HIGH、RequestMethod、TrafficDirectionINBOUND/OUTBOUND等通用枚举与消息。其中Locality的注释提示若启用发现服务路由且服务端下发了带locality的LocalityLbEndpoints应设置该字段也可通过--service-zone命令行选项指定。config_source.proto定义ConfigSource/ApiConfigSource/AggregatedConfigSource等配置来源类型。ApiConfigSource.ApiType枚举给出了三种取数方式——RESTREST-JSON v2 API按refresh_delay间隔轮询、GRPCgRPC v2 双向流、DELTA_GRPC使用DeltaDiscovery{Request,Response}而非Discovery{Request,Response}服务端只下发增量transport_api_version字段用ApiVersion枚举描述线上传输协议版本AUTO/V2已标记 deprecatedV3 2为现行版本佐证了本仓库处于 v2→v3 迁移期的版本现实set_node_on_first_message_only用于流式 gRPC 配置类型下仅首条消息携带节点标识。其余文件address.proto、backoff.proto、grpc_service.protoGrpcService被ApiConfigSource.grpc_services引用、health_check.proto、protocol.proto、http_uri.proto、socket_option.proto等。4.3 auth 子包TLS 传输套接字配置envoy.api.v2.auth目录 auth/提供UpstreamTlsContext、DownstreamTlsContext、CertificateValidationContext、Secret等 TLS 相关类型供监听器与集群的transport_socket配置复用是 README 点名的另一个跨子包共享依赖。五、版本状态与迁移读懂 FROZEN 与 move_to_package阅读本目录.proto文件时会反复看到两组 udpa 注解它们是理解 v2 API 生命周期的钥匙option (udpa.annotations.file_status).package_version_status FROZEN;——标记文件所属包已冻结语义不再演进、只做 bug 修复新功能一律落在 v3。option (udpa.annotations.file_migrate).move_to_package envoy.service.xxx.v3;——声明迁移目标例如discovery.proto→envoy.service.discovery.v3cds.proto→envoy.service.cluster.v3lds.proto→envoy.service.listener.v3eds.proto→envoy.service.endpoint.v3rds.proto、srds.proto→envoy.service.route.v3core/base.proto→envoy.config.core.v3同时每个文件都声明了多语言生成目标java_package io.envoyproxy.envoy.api.v2、go_package github.com/envoyproxy/go-control-plane/envoy/api/v2;apiv2表明这些定义不仅服务于 Envoy 主仓库也是go-control-plane等管理面 SDK 的契约来源。与之呼应ApiVersion枚举中AUTO与V2均已标记 deprecated、V3是现行值若在线上配置中指定 v2 传输版本需要自行评估与当前 Envoy 版本的兼容性——仓库注释也明确提示“如果客户端不支持 v2例如因弃用这是一个无效值”。六、在仓库中进一步验证从 proto 到实现如果你希望从定义走向实现可以沿以下路径在本仓库中继续探索均为仓库根目录相对路径管理面 SDK 视角go_package指向的go-control-plane是对该契约的独立实现本仓库的 api/examples/service_envoy 提供了基于这些 API 的示例产出物。API 规范化工具本目录 BUILD 文件由 tools/proto_format/proto_sync.py 生成体现 API proto 的自动化同步流程tools/proto_format/ 目录下还有 proto_format 相关的格式检查脚本。迁移与冻结校验udpa 注解的消费逻辑位于xds外部依赖见 bazel/external/ 的依赖管理仓库内 api/versioning/ 与 API_VERSIONING.md 记录了 API 版本化与冻结的整体策略。配置示例configs/ 目录下的 YAML 配置如 ads.yaml展示了如何在真实 bootstrap 中组合使用ConfigSource、ApiConfigSourceapi_type、grpc_services、transport_api_version等字段接入 ADS 或独立 xDS。结语api/envoy/api/v2/README.md用三句话点明了本目录的定位而其背后的 11 个.proto文件则承载了 Envoy 控制面协议最核心的契约//envoy/api/v2:friends的可见性约束保证了共享 API 的演进可控discovery.proto定义了 SotW 与 Delta 两套传输语义六大发现服务以统一的Stream/Delta/Fetch三端点形态覆盖了集群、监听器、端点、路由、作用域路由与虚拟主机的动态下发FROZEN 状态与move_to_package注解则记录着 v2 向 v3 迁移的历史坐标。对任何希望理解 xDS 协议、开发管理面服务或为 Envoy 做二次集成的开发者而言这份 API 契约都是最权威的起点。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
