Envoy xDS API 版本化机制详解transport 与 resource 双版本体系的原理与实践【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy导读本文以 Envoy 官方文档 versioning.rst 为核心结合仓库中 api/API_VERSIONING.md 版本化规范、config_source.proto 配置定义与 utility.h 源码实现系统讲解 Envoy xDS API 的版本化方案。你将理解传输版本transport API version与资源版本resource API version两个核心概念的区别掌握 v3 API 的包命名规则、向后兼容策略、废弃deprecation生命周期以及如何在真实 bootstrap 配置中设置ApiVersion字段。为什么需要版本化xDS 生态的稳定性基石Envoy 的数据面 APIData Plane API不仅仅驱动 Envoy 自身还被其他代理、管理服务器management server和配置生成器共同消费是一套通用数据面 APIuniversal data plane API参见 api/README.md。因此API 的稳定性直接决定了整个控制面/数据面生态的可持续性。版本化正是为了保障管理服务器与 Envoy 客户端之间线上传输协议wire protocol长期兼容已生成的语言绑定protobuf 编译产物不因升级而失效YAML/JSON 配置、文本 proto 等一等公民输入可持续加载。版本化的两个维度transport API version 与 resource API version官方文档 versioning.rst 明确指出Envoy 的 xDS API 版本分为两个独立维度二者都遵循 API_VERSIONING.md 中定义的支持与废弃策略维度英文名称作用范围对应配置字段传输版本transport API versionxDS 传输协议gRPC/REST 端点、[Delta]DiscoveryRequest/Response线上消息ApiConfigSource.transport_api_version字段号 8、SelfConfigSource.transport_api_version字段号 1资源版本resource API version资源本身的类型 URL 与消息结构决定客户端请求/期望收到的资源类型ConfigSource.resource_api_version字段号 6在 proto 定义config_source.proto中二者共用同一个枚举// xDS API and non-xDS services version. This is used to describe both resource and transport // protocol versions (in distinct configuration fields). enum ApiVersion { // When not specified, we assume v3; it is the only supported version. AUTO 0; // Use xDS v2 API. This is no longer supported. V2 1 [deprecated true, (envoy.annotations.deprecated_at_minor_version_enum) 3.0]; // Use xDS v3 API. V3 2; }要点解读AUTO 0是默认值未显式指定时按 v3 处理且 v3 是当前唯一受支持的版本V2 1已被标记废弃deprecated_at_minor_version_enum 3.0v2 主版本已移除、不再受支持字段注释给出了两版本的精确定义transport_api_version描述线上使用的 xDS gRPC/REST 端点及[Delta]DiscoveryRequest/Response的版本resource_api_version决定客户端将请求的资源类型 URL 以及期望收到的资源类型。从源码看transport_api_version出现在 ApiConfigSource 与 SelfConfigSource 中resource_api_version出现在 ConfigSource 中。所有字段都带有(validate.rules).enum {defined_only: true}校验即配置值必须是枚举已定义值否则配置加载失败。源码级佐证transport 版本校验在 source/common/config/utility.h 中checkTransportVersion模板函数展示了 Envoy 对传输版本的运行时校验逻辑template class Proto static absl::Status checkTransportVersion(const Proto api_config_source) { const auto transport_api_version api_config_source.transport_api_version(); ASSERT_IS_MAIN_OR_TEST_THREAD(); if (transport_api_version ! envoy::config::core::v3::ApiVersion::AUTO transport_api_version ! envoy::config::core::v3::ApiVersion::V3) { const std::string warning fmt::format( V2 xDS transport protocol version is deprecated in {}. The v2 xDS major version has been removed and is no longer supported. See the advice in https://www.envoyproxy.io/docs/envoy/latest/faq/api/envoy_v3., api_config_source.DebugString()); ENVOY_LOG_MISC(warn, warning); return absl::InvalidArgumentError(warning); } return absl::OkStatus(); }可以推断除AUTO默认按 v3与V3之外的任何传输版本取值即V2都会产生警告日志并返回InvalidArgumentError配置被拒绝。这从实现层面印证了文档v3 是唯一受支持版本的结论。语义化版本包即版本package-as-versionEnvoy API 由一组相互独立的包package家族构成每个包采用基于 protobuf 的语义化版本方案参考 Google Cloud API 设计指南的 versioning 规则主版本号直接编码在包名与目录结构中追踪 API 第 3 版包名envoy.service.trace.v3对应 proto 位于api/envoy/service/trace/v3/管理 API 的 alpha 版包名如envoy.admin.v3alpha每个 protobuf 必须直接位于带版本号的包命名空间下不允许envoy.service.trace.v3.somethingelse这类子包。vN xDS API 的真实含义日常讨论与 GitHub label 中常说的v2、v3、vNAPI 有精确的技术含义。任意一条 Envoy API 消息例如envoy.config.bootstrap.v3.Bootstrap会传递引用若干其他包这些包可能处于vN、v(N-1)等不同版本——Envoy API 本质上是版本化包命名空间的 DAG有向无环图。所谓vN xDS API指的是根配置资源如 bootstrap、Cluster等 xDS 资源所属的N值例如 v3 API 的 bootstrap 配置即envoy.config.bootstrap.v3.Bootstrap。向后兼容策略哪些改动被禁止在某个包的主版本内部Envoy 不允许任何破坏性变更。指导原则是线上格式与 protobuf 编译器生成的语言绑定都不能出现向后兼容的破坏。具体包括字段不得重新编号或改变类型——标准 proto 开发流程字段名与包命名空间不得重命名理由包括字段重命名虽不破坏二进制线上格式但会破坏 YAML/JSON 与文本 proto 的加载Envoy 视 YAML/JSON 为一等公民输入对 service 定义而言gRPC 端点 URL 由包命名空间推导重命名将破坏客户端/服务端通信对嵌入Any的消息如DiscoveryResponse中的顶层Cluster、Listener等资源类型 URL 包含包命名空间可能被 Envoy 或其他消费方用于类型解析消费方代码将被破坏需要源码级改动其他在普通 protobuf 场景通常被认为安全、但对 Envoy API 属于破坏性的改动将单值字段升级为 repeated如uint32 foo 1;改为repeated uint32 foo 1;这会改变 JSON 线上表示用oneof包裹已有字段虽无 proto/JSON/YAML 线上影响但会破坏 Go 等语言的消费方 stub制造不必要的 churn提高protoc-gen-validate注解的严格程度除非新约束只是把文档或结构上已隐含的行为显式建模。例外情形以下场景可不受上述策略约束新字段/消息引入后14 天内的修改前提是该字段/消息尚未进入任何 Envoy 发布版vNalpha版本alpha 主版本内允许任意破坏性变更带(udpa.annotations.file_status).work_in_progress、(xds.annotations.v3.file_status).work_in_progress、(xds.annotations.v3.message_status).work_in_progress或(xds.annotations.v3.field_status).work_in_progress注解的 proto。另外需注意google.protobuf.UInt32Value等包装类型的默认值变化不受上述策略约束因此需要跨 Envoy API 或实现保持主版本内稳定的管理服务器应对此类字段显式设置值不要依赖默认值。API 生命周期v3 是最终主版本文档 API_VERSIONING.md 明确了重要结论Envoy 曾计划周期性推出 xDS API 新主版本以清理技术债但由于 Envoy 与更大的 xDS 生态gRPC 等已广泛采用版本跳升不再现实。v3 API 是最终主版本将永远被支持。这带来两个实践推论废弃deprecation仍然存在它只是向最终用户提示某个功能存在更优配置方式任何字段永不会被删除Envoy 也永不会移除任何已废弃字段的实现。对客户端实现的补充说明客户端如各语言 SDK可以就字段继续使用输出额外警告例如字段继续使用被视为重大安全风险也可以自行停止支持某些字段但Envoy Proxy 作为 xDS 客户端承诺永不停止支持已废弃字段。新增 API 特性扩展与稳定并重新包、新消息、新枚举、新字段与新枚举值可以在保持向后兼容的前提下安全加入 API。新增特性应只加入当前稳定主版本理由如下特性可立即被消费当前稳定主版本的用户使用若放入vNalpha则无法做到vNalpha可由vN机械生成开发者无需在两个位置维护新特性鼓励用户从旧主版本迁移到当前稳定主版本以消费新功能。客户端能力协商client features 的补充机制并非所有客户端都支持某个主版本内的全部字段与特性。常规场景下优先用 protobuf 语义处理忽略某字段内容即可表示客户端不支持该能力在希望兼容一段范围的客户端时同时设置废弃字段与新表达方式在开销可接受的前提下。但 protobuf 语义并非总是足够例如路由匹配器route matcher的合取条件不应因客户端缺少匹配实现能力而被忽略否则可能导致路由策略绕过security 问题客户端可能期望服务器以特定格式/编码返回响应例如Struct-in-Any的 JSON 编码不透明扩展配置。为此Envoy 提供了专门的client features机制见 docs 中 client_features 文档 对应规范用于显式声明客户端能力弥补纯 protobuf 语义的不足。实战在配置中指定 API 版本在真实 bootstrap 配置中ApiVersion通常不需要显式设置AUTO默认按 v3。以下给出结合 xds_api.rst 与 config_source.proto 的典型用法。1. gRPC 流式 xDStransport 默认 v3在dynamic_resources中使用 ADS 或独立 gRPC 订阅api_type: GRPCSotW或DELTA_GRPCdeltadynamic_resources: ads_config: api_type: GRPC # 或 DELTA_GRPCdelta 变体仅 gRPC transport_api_version: V3 # 可省略AUTO 默认即 v3 grpc_services: - envoy_grpc: cluster_name: some_xds_cluster cds_config: {ads: {}} lds_config: {ads: {}}2. REST 轮询 xDSREST 为 SotWstate of the world语义适用于资源量小、变更稀疏的场景cds_config: api_config_source: api_type: REST cluster_names: [some_xds_cluster] refresh_delay: 30s # REST 轮询间隔 request_timeout: 1s # 默认 1s3. 资源版本与传输版本的区分示例当通过ApiConfigSource走 gRPC 时transport_api_version决定线协议而ConfigSource.resource_api_version决定资源类型 URL。实践中二者都保持默认v3即可显式设置时务必都取V3或省略因为V2已不被支持配置会被 checkTransportVersion 拒绝。ApiConfigSource中其余字段的补充说明来自 config_source.protocluster_names仅用于 REST配置多个集群时任一失败将循环切换集群必须静态定义且类型不能是 EDSgrpc_services用于 GRPC多个服务在失败时循环切换refresh_delayREST API 两次轮询之间的间隔request_timeoutREST 请求超时默认 1srate_limit_settings对 discovery 请求做限流默认max_tokens100、fill_rate10/s最小填充率一年一次set_node_on_first_message_only流式 gRPC 下仅首条 discovery 请求携带 node 标识config_validators收到更新时执行的配置校验器envoy.config.validators扩展类别校验失败则拒绝配置并发送 NACK。仓库中的版本化体系全景规范文档api/API_VERSIONING.md语义化版本、向后兼容、生命周期、新增特性、客户端能力概述文档docs/root/configuration/overview/versioning.rstxDS 端点与 ADS/delta/TTL 细节docs/root/configuration/overview/xds_api.rst配置源与ApiVersion枚举定义api/envoy/config/core/v3/config_source.proto传输版本运行时校验实现source/common/config/utility.hAPI 风格规范api/STYLE.md。小结Envoy 的版本化方案以包即版本为核心通过 transport 与 resource 两个正交维度分别约束线协议与资源结构在 v3 成为最终主版本后向后兼容与只废弃、不删除成为长期承诺。理解这套机制是正确配置 xDS 管理服务器、编写 bootstrap 动态资源、评估 API 变更影响面的前提。当前仓库版本VERSION.txt 显示为 1.40.0-dev中v3 是唯一受支持的 xDS API 版本。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Envoy xDS API 版本化机制详解：transport 与 resource 双版本体系的原理与实践
Envoy xDS API 版本化机制详解transport 与 resource 双版本体系的原理与实践【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy导读本文以 Envoy 官方文档 versioning.rst 为核心结合仓库中 api/API_VERSIONING.md 版本化规范、config_source.proto 配置定义与 utility.h 源码实现系统讲解 Envoy xDS API 的版本化方案。你将理解传输版本transport API version与资源版本resource API version两个核心概念的区别掌握 v3 API 的包命名规则、向后兼容策略、废弃deprecation生命周期以及如何在真实 bootstrap 配置中设置ApiVersion字段。为什么需要版本化xDS 生态的稳定性基石Envoy 的数据面 APIData Plane API不仅仅驱动 Envoy 自身还被其他代理、管理服务器management server和配置生成器共同消费是一套通用数据面 APIuniversal data plane API参见 api/README.md。因此API 的稳定性直接决定了整个控制面/数据面生态的可持续性。版本化正是为了保障管理服务器与 Envoy 客户端之间线上传输协议wire protocol长期兼容已生成的语言绑定protobuf 编译产物不因升级而失效YAML/JSON 配置、文本 proto 等一等公民输入可持续加载。版本化的两个维度transport API version 与 resource API version官方文档 versioning.rst 明确指出Envoy 的 xDS API 版本分为两个独立维度二者都遵循 API_VERSIONING.md 中定义的支持与废弃策略维度英文名称作用范围对应配置字段传输版本transport API versionxDS 传输协议gRPC/REST 端点、[Delta]DiscoveryRequest/Response线上消息ApiConfigSource.transport_api_version字段号 8、SelfConfigSource.transport_api_version字段号 1资源版本resource API version资源本身的类型 URL 与消息结构决定客户端请求/期望收到的资源类型ConfigSource.resource_api_version字段号 6在 proto 定义config_source.proto中二者共用同一个枚举// xDS API and non-xDS services version. This is used to describe both resource and transport // protocol versions (in distinct configuration fields). enum ApiVersion { // When not specified, we assume v3; it is the only supported version. AUTO 0; // Use xDS v2 API. This is no longer supported. V2 1 [deprecated true, (envoy.annotations.deprecated_at_minor_version_enum) 3.0]; // Use xDS v3 API. V3 2; }要点解读AUTO 0是默认值未显式指定时按 v3 处理且 v3 是当前唯一受支持的版本V2 1已被标记废弃deprecated_at_minor_version_enum 3.0v2 主版本已移除、不再受支持字段注释给出了两版本的精确定义transport_api_version描述线上使用的 xDS gRPC/REST 端点及[Delta]DiscoveryRequest/Response的版本resource_api_version决定客户端将请求的资源类型 URL 以及期望收到的资源类型。从源码看transport_api_version出现在 ApiConfigSource 与 SelfConfigSource 中resource_api_version出现在 ConfigSource 中。所有字段都带有(validate.rules).enum {defined_only: true}校验即配置值必须是枚举已定义值否则配置加载失败。源码级佐证transport 版本校验在 source/common/config/utility.h 中checkTransportVersion模板函数展示了 Envoy 对传输版本的运行时校验逻辑template class Proto static absl::Status checkTransportVersion(const Proto api_config_source) { const auto transport_api_version api_config_source.transport_api_version(); ASSERT_IS_MAIN_OR_TEST_THREAD(); if (transport_api_version ! envoy::config::core::v3::ApiVersion::AUTO transport_api_version ! envoy::config::core::v3::ApiVersion::V3) { const std::string warning fmt::format( V2 xDS transport protocol version is deprecated in {}. The v2 xDS major version has been removed and is no longer supported. See the advice in https://www.envoyproxy.io/docs/envoy/latest/faq/api/envoy_v3., api_config_source.DebugString()); ENVOY_LOG_MISC(warn, warning); return absl::InvalidArgumentError(warning); } return absl::OkStatus(); }可以推断除AUTO默认按 v3与V3之外的任何传输版本取值即V2都会产生警告日志并返回InvalidArgumentError配置被拒绝。这从实现层面印证了文档v3 是唯一受支持版本的结论。语义化版本包即版本package-as-versionEnvoy API 由一组相互独立的包package家族构成每个包采用基于 protobuf 的语义化版本方案参考 Google Cloud API 设计指南的 versioning 规则主版本号直接编码在包名与目录结构中追踪 API 第 3 版包名envoy.service.trace.v3对应 proto 位于api/envoy/service/trace/v3/管理 API 的 alpha 版包名如envoy.admin.v3alpha每个 protobuf 必须直接位于带版本号的包命名空间下不允许envoy.service.trace.v3.somethingelse这类子包。vN xDS API 的真实含义日常讨论与 GitHub label 中常说的v2、v3、vNAPI 有精确的技术含义。任意一条 Envoy API 消息例如envoy.config.bootstrap.v3.Bootstrap会传递引用若干其他包这些包可能处于vN、v(N-1)等不同版本——Envoy API 本质上是版本化包命名空间的 DAG有向无环图。所谓vN xDS API指的是根配置资源如 bootstrap、Cluster等 xDS 资源所属的N值例如 v3 API 的 bootstrap 配置即envoy.config.bootstrap.v3.Bootstrap。向后兼容策略哪些改动被禁止在某个包的主版本内部Envoy 不允许任何破坏性变更。指导原则是线上格式与 protobuf 编译器生成的语言绑定都不能出现向后兼容的破坏。具体包括字段不得重新编号或改变类型——标准 proto 开发流程字段名与包命名空间不得重命名理由包括字段重命名虽不破坏二进制线上格式但会破坏 YAML/JSON 与文本 proto 的加载Envoy 视 YAML/JSON 为一等公民输入对 service 定义而言gRPC 端点 URL 由包命名空间推导重命名将破坏客户端/服务端通信对嵌入Any的消息如DiscoveryResponse中的顶层Cluster、Listener等资源类型 URL 包含包命名空间可能被 Envoy 或其他消费方用于类型解析消费方代码将被破坏需要源码级改动其他在普通 protobuf 场景通常被认为安全、但对 Envoy API 属于破坏性的改动将单值字段升级为 repeated如uint32 foo 1;改为repeated uint32 foo 1;这会改变 JSON 线上表示用oneof包裹已有字段虽无 proto/JSON/YAML 线上影响但会破坏 Go 等语言的消费方 stub制造不必要的 churn提高protoc-gen-validate注解的严格程度除非新约束只是把文档或结构上已隐含的行为显式建模。例外情形以下场景可不受上述策略约束新字段/消息引入后14 天内的修改前提是该字段/消息尚未进入任何 Envoy 发布版vNalpha版本alpha 主版本内允许任意破坏性变更带(udpa.annotations.file_status).work_in_progress、(xds.annotations.v3.file_status).work_in_progress、(xds.annotations.v3.message_status).work_in_progress或(xds.annotations.v3.field_status).work_in_progress注解的 proto。另外需注意google.protobuf.UInt32Value等包装类型的默认值变化不受上述策略约束因此需要跨 Envoy API 或实现保持主版本内稳定的管理服务器应对此类字段显式设置值不要依赖默认值。API 生命周期v3 是最终主版本文档 API_VERSIONING.md 明确了重要结论Envoy 曾计划周期性推出 xDS API 新主版本以清理技术债但由于 Envoy 与更大的 xDS 生态gRPC 等已广泛采用版本跳升不再现实。v3 API 是最终主版本将永远被支持。这带来两个实践推论废弃deprecation仍然存在它只是向最终用户提示某个功能存在更优配置方式任何字段永不会被删除Envoy 也永不会移除任何已废弃字段的实现。对客户端实现的补充说明客户端如各语言 SDK可以就字段继续使用输出额外警告例如字段继续使用被视为重大安全风险也可以自行停止支持某些字段但Envoy Proxy 作为 xDS 客户端承诺永不停止支持已废弃字段。新增 API 特性扩展与稳定并重新包、新消息、新枚举、新字段与新枚举值可以在保持向后兼容的前提下安全加入 API。新增特性应只加入当前稳定主版本理由如下特性可立即被消费当前稳定主版本的用户使用若放入vNalpha则无法做到vNalpha可由vN机械生成开发者无需在两个位置维护新特性鼓励用户从旧主版本迁移到当前稳定主版本以消费新功能。客户端能力协商client features 的补充机制并非所有客户端都支持某个主版本内的全部字段与特性。常规场景下优先用 protobuf 语义处理忽略某字段内容即可表示客户端不支持该能力在希望兼容一段范围的客户端时同时设置废弃字段与新表达方式在开销可接受的前提下。但 protobuf 语义并非总是足够例如路由匹配器route matcher的合取条件不应因客户端缺少匹配实现能力而被忽略否则可能导致路由策略绕过security 问题客户端可能期望服务器以特定格式/编码返回响应例如Struct-in-Any的 JSON 编码不透明扩展配置。为此Envoy 提供了专门的client features机制见 docs 中 client_features 文档 对应规范用于显式声明客户端能力弥补纯 protobuf 语义的不足。实战在配置中指定 API 版本在真实 bootstrap 配置中ApiVersion通常不需要显式设置AUTO默认按 v3。以下给出结合 xds_api.rst 与 config_source.proto 的典型用法。1. gRPC 流式 xDStransport 默认 v3在dynamic_resources中使用 ADS 或独立 gRPC 订阅api_type: GRPCSotW或DELTA_GRPCdeltadynamic_resources: ads_config: api_type: GRPC # 或 DELTA_GRPCdelta 变体仅 gRPC transport_api_version: V3 # 可省略AUTO 默认即 v3 grpc_services: - envoy_grpc: cluster_name: some_xds_cluster cds_config: {ads: {}} lds_config: {ads: {}}2. REST 轮询 xDSREST 为 SotWstate of the world语义适用于资源量小、变更稀疏的场景cds_config: api_config_source: api_type: REST cluster_names: [some_xds_cluster] refresh_delay: 30s # REST 轮询间隔 request_timeout: 1s # 默认 1s3. 资源版本与传输版本的区分示例当通过ApiConfigSource走 gRPC 时transport_api_version决定线协议而ConfigSource.resource_api_version决定资源类型 URL。实践中二者都保持默认v3即可显式设置时务必都取V3或省略因为V2已不被支持配置会被 checkTransportVersion 拒绝。ApiConfigSource中其余字段的补充说明来自 config_source.protocluster_names仅用于 REST配置多个集群时任一失败将循环切换集群必须静态定义且类型不能是 EDSgrpc_services用于 GRPC多个服务在失败时循环切换refresh_delayREST API 两次轮询之间的间隔request_timeoutREST 请求超时默认 1srate_limit_settings对 discovery 请求做限流默认max_tokens100、fill_rate10/s最小填充率一年一次set_node_on_first_message_only流式 gRPC 下仅首条 discovery 请求携带 node 标识config_validators收到更新时执行的配置校验器envoy.config.validators扩展类别校验失败则拒绝配置并发送 NACK。仓库中的版本化体系全景规范文档api/API_VERSIONING.md语义化版本、向后兼容、生命周期、新增特性、客户端能力概述文档docs/root/configuration/overview/versioning.rstxDS 端点与 ADS/delta/TTL 细节docs/root/configuration/overview/xds_api.rst配置源与ApiVersion枚举定义api/envoy/config/core/v3/config_source.proto传输版本运行时校验实现source/common/config/utility.hAPI 风格规范api/STYLE.md。小结Envoy 的版本化方案以包即版本为核心通过 transport 与 resource 两个正交维度分别约束线协议与资源结构在 v3 成为最终主版本后向后兼容与只废弃、不删除成为长期承诺。理解这套机制是正确配置 xDS 管理服务器、编写 bootstrap 动态资源、评估 API 变更影响面的前提。当前仓库版本VERSION.txt 显示为 1.40.0-dev中v3 是唯一受支持的 xDS API 版本。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
