Envoy Network External Processing 连接属性CEL评估支持深度解析【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy导读本文围绕 Envoy 网络外部处理过滤器envoy.filters.network.ext_proc新增的一项能力展开通过connection_attributes配置项在 L4 网络外部处理器中评估 CELCommon Expression Language连接属性与过滤器状态filter state并将评估结果通过ProcessingRequest.attributes字段随 gRPC 双向流发送给外部处理服务。读完本文你将掌握该特性的配置方法、协议字段语义、源码级实现原理以及实际接入外部处理服务时的注意事项。该能力对应的官方变更记录为 changelogs/current/new_features/network_ext_proc__connection-attributes.rst正文将结合协议定义与实现源码逐层展开。背景Network External Processing 过滤器Envoy 的 Network External Processing 过滤器允许外部服务通过双向 gRPC 流ProcessRPC灵活地处理原始 TCP/UDP 流量。与 HTTP 层的外部处理过滤器不同它工作在 L4 传输层可以双向检查流量客户端 → 服务端、服务端 → 客户端修改网络数据负载控制连接生命周期继续、优雅关闭或立即重置。过滤器通过 NetworkExternalProcessor 消息配置外部服务需要实现 NetworkExternalProcessor 服务契约 中定义的ProcessRPC。典型场景包括自定义协议检查与改写、高级流量操纵、安全扫描过滤和动态连接管理等。新特性核心连接属性评估与下发本次新增的能力可以概括为两句话支持在网络外部处理器中评估CEL 连接属性connection attributes与过滤器状态filter state 通过connection_attributes配置项指定要评估的属性评估结果随ProcessingRequest.attributes发送给外部处理服务。具体而言这包含两个协议层面的配合配置侧NetworkExternalProcessor.connection_attributesrepeated string字段号 7用于列出需要评估的数据平面属性名数据侧ProcessingRequest.attributesmapstring, google.protobuf.Struct字段号 4用于承载被选中属性的求值结果。数据平面提供了丰富的标准属性即官方文档中的arch_overview_attributes属性集用于表达策略。配置中列出的每个属性名都会基于连接上下文与过滤器状态进行求值然后填充到ProcessingRequest.attributes字段中。配置方式与完整配置示例以下是一份完整的过滤器配置示例展示了connection_attributes与其它关键配置项的组合用法YAML 结构对应envoy.extensions.filters.network.ext_proc.v3.NetworkExternalProcessornetwork_filters: - name: envoy.filters.network.ext_proc typed_config: type: type.googleapis.com/envoy.extensions.filters.network.ext_proc.v3.NetworkExternalProcessor stat_prefix: network_ext_proc grpc_service: envoy_grpc: cluster_name: ext_proc_server failure_mode_allow: true processing_mode: process_read: STREAMED process_write: STREAMED message_timeout: 0.200s metadata_options: forwarding_namespaces: untyped: - my.metadata.namespace connection_attributes: - connection.remote_address - connection.local_address - source.address - xds.route_metadata其中与连接属性直接相关的字段为connection_attributes其余字段说明如下均可在 ext_proc.proto 中找到权威定义字段类型说明grpc_serviceGrpcService处理网络流量的外部 gRPC 服务必须实现NetworkExternalProcessor服务中的ProcessRPCfailure_mode_allowbool默认为 false。为 true 时若 gRPC 流无法建立或提前异常关闭处理将继续而不报错为 false 时过滤器失败并关闭连接processing_modeProcessingMode控制数据方向处理process_read/process_write可设为STREAMED默认或SKIP。两者都设为SKIP会被配置拒绝message_timeoutDuration同步模式下每条消息的超时时间默认 200ms范围 03600 秒stat_prefixstring统计前缀必填最小长度 1metadata_optionsMetadataOptions动态元数据转发/接收命名空间配置untyped 与 typed 两类connection_attributesrepeated string本次新增要评估的数据平面属性名列表协议语义ProcessingRequest.attributes外部处理服务在双向流中收到的是ProcessingRequest其完整结构见 network_external_processor.protoread_data字段 1请求路径上拦截到的数据客户端 → 服务端write_data字段 2响应路径上拦截到的数据服务端 → 客户端metadata字段 3与请求关联的元数据连接属性、过滤器配置等上下文信息注意它不会自动从请求传播到响应外部处理器需要时须自行在响应中包含attributes字段 4由配置中connection_attributes列表选定的属性值其中每一项都来自数据平面支持的标准属性集。attributes是一个mapstring, google.protobuf.Struct每个 key 对应一个被选中的属性名value 是求值结果以Struct形式承载任意类型值。从实现上看该 map 以 Envoy 内部的NetworkExternalProcessor过滤器命名空间作为整体 key将全部求值结果作为一个Struct放入其中详见下文源码分析。源码级实现原理1. 配置解析构建 CEL 表达式管理器在 ext_proc.cc 的Config构造函数中connection_attributes被直接传递给ExpressionManager完成初始化expression_manager_(builder, local_info, config.connection_attributes(), creation_status)ExpressionManager定义于 matching_utils.h负责将属性名编译为 CEL 表达式并保存主要职责包括hasConnectionExpr()判断是否配置了连接属性表达式evaluateConnectionAttributes(activation)基于给定的激活上下文Activation对全部表达式求值initExpressions()逐个解析并编译属性表达式。2. CEL 表达式编译过程matching_utils.cc 中的initExpressions展示了完整的编译链路对每个属性名调用 CEL parser 的google::api::expr::parser::Parse()解析为ParsedExpr解析失败时设置creation_status为InvalidArgumentErrorUnable to parse descriptor expression过滤器创建失败通过Extensions::Filters::Common::Expr::CompiledExpression::Create()编译表达式失败同样报错并终止编译成功的表达式以属性名为 key 存入absl::flat_hash_map重复属性自动去重。需要特别说明的是整个编译过程受USE_CEL_PARSER编译开关保护。若构建环境中未启用 CEL parser配置了connection_attributes时会打印 warning 日志且表达式不会被解析这一点在部署自定义构建版本时需要注意。3. 求值与类型映射evaluateAttributes对每个编译后的表达式在给定 Activation 上执行求值求值出错返回 Error时跳过该属性并记录 trace 级日志结果值按类型映射到Protobuf::ValuekBool→bool_valuekInt64/kUint64→number_value其它类型 → 通过print()转为string_value也就是说属性求值结果最终以google.protobuf.Struct形式呈现外部服务可用通用 JSON 语义解析。4. 发送时机仅连接建立后发送一次在 ext_proc.cc 的addAttributes(ProcessingRequest req)方法中体现了发送时机逻辑void NetworkExtProcFilter::addAttributes(ProcessingRequest req) { if (attributes_sent_ || !config_-expressionManager().hasConnectionExpr()) { return; } auto activation_ptr Filters::Common::Expr::createActivation( config_-expressionManager().localInfo(), read_callbacks_-connection().streamInfo(), nullptr, nullptr, nullptr); auto attributes config_-expressionManager().evaluateConnectionAttributes(*activation_ptr); attributes_sent_ true; (*req.mutable_attributes())[NetworkFilterNames::get().NetworkExternalProcessor] std::move(attributes); }关键点只发送一次attributes_sent_标志确保连接属性仅在首个ProcessingRequest中携带后续数据请求不再重复评估与发送求值上下文通过createActivation()将LocalInfo与连接的StreamInfo注入 Activation因此connection_attributes中既可以引用连接级属性如远端/本地地址也可以引用存储于StreamInfo的过滤器状态filter state这与 changelog 中“evaluating CEL connection attributes and filter state”的描述一致命名空间 key结果以NetworkExternalProcessor过滤器命名空间为 key 放入attributesmap外部服务可按固定命名空间读取整组属性。实践注意事项属性名必须合法 CEL 表达式connection_attributes中的每一项都会被当作 CEL 表达式解析拼写错误或语法非法将导致过滤器配置加载失败InvalidArgumentError需参照数据平面标准属性集arch_overview_attributes书写属性名。求值结果的一次性语义属性在连接生命周期内只随首个请求发送一次。若外部服务后续需要属性应自行在本地缓存这也意味着连接中途变化的属性不会重复推送。与 metadata 的关系attributes与metadata动态元数据是两条独立通道。动态元数据需要通过metadata_options.forwarding_namespaces显式声明转发命名空间而连接属性只需在connection_attributes中列出即可。构建开关若自定义构建未启用USE_CEL_PARSER连接属性功能将静默不可用仅 warning 日志请确认发行版/自建二进制支持 CEL parser。与 HTTP ext_proc 的对照HTTP 层的外部处理过滤器早已支持属性传递ProcessingRequest.attributes与DynamicMetadata本次变更将同等能力下沉到 L4 网络过滤器使原始 TCP/UDP 流量处理也能基于连接属性做精细化决策。关键参考文件变更记录network_ext_proc__connection-attributes.rst过滤器配置定义ext_proc.protoNetworkExternalProcessor.connection_attributes服务协议定义network_external_processor.protoProcessingRequest.attributes过滤器实现ext_proc.ccConfig构造与addAttributesCEL 表达式管理matching_utils.h、matching_utils.cc表达式编译与求值【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Envoy Network External Processing 连接属性（CEL）评估支持深度解析
Envoy Network External Processing 连接属性CEL评估支持深度解析【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy导读本文围绕 Envoy 网络外部处理过滤器envoy.filters.network.ext_proc新增的一项能力展开通过connection_attributes配置项在 L4 网络外部处理器中评估 CELCommon Expression Language连接属性与过滤器状态filter state并将评估结果通过ProcessingRequest.attributes字段随 gRPC 双向流发送给外部处理服务。读完本文你将掌握该特性的配置方法、协议字段语义、源码级实现原理以及实际接入外部处理服务时的注意事项。该能力对应的官方变更记录为 changelogs/current/new_features/network_ext_proc__connection-attributes.rst正文将结合协议定义与实现源码逐层展开。背景Network External Processing 过滤器Envoy 的 Network External Processing 过滤器允许外部服务通过双向 gRPC 流ProcessRPC灵活地处理原始 TCP/UDP 流量。与 HTTP 层的外部处理过滤器不同它工作在 L4 传输层可以双向检查流量客户端 → 服务端、服务端 → 客户端修改网络数据负载控制连接生命周期继续、优雅关闭或立即重置。过滤器通过 NetworkExternalProcessor 消息配置外部服务需要实现 NetworkExternalProcessor 服务契约 中定义的ProcessRPC。典型场景包括自定义协议检查与改写、高级流量操纵、安全扫描过滤和动态连接管理等。新特性核心连接属性评估与下发本次新增的能力可以概括为两句话支持在网络外部处理器中评估CEL 连接属性connection attributes与过滤器状态filter state 通过connection_attributes配置项指定要评估的属性评估结果随ProcessingRequest.attributes发送给外部处理服务。具体而言这包含两个协议层面的配合配置侧NetworkExternalProcessor.connection_attributesrepeated string字段号 7用于列出需要评估的数据平面属性名数据侧ProcessingRequest.attributesmapstring, google.protobuf.Struct字段号 4用于承载被选中属性的求值结果。数据平面提供了丰富的标准属性即官方文档中的arch_overview_attributes属性集用于表达策略。配置中列出的每个属性名都会基于连接上下文与过滤器状态进行求值然后填充到ProcessingRequest.attributes字段中。配置方式与完整配置示例以下是一份完整的过滤器配置示例展示了connection_attributes与其它关键配置项的组合用法YAML 结构对应envoy.extensions.filters.network.ext_proc.v3.NetworkExternalProcessornetwork_filters: - name: envoy.filters.network.ext_proc typed_config: type: type.googleapis.com/envoy.extensions.filters.network.ext_proc.v3.NetworkExternalProcessor stat_prefix: network_ext_proc grpc_service: envoy_grpc: cluster_name: ext_proc_server failure_mode_allow: true processing_mode: process_read: STREAMED process_write: STREAMED message_timeout: 0.200s metadata_options: forwarding_namespaces: untyped: - my.metadata.namespace connection_attributes: - connection.remote_address - connection.local_address - source.address - xds.route_metadata其中与连接属性直接相关的字段为connection_attributes其余字段说明如下均可在 ext_proc.proto 中找到权威定义字段类型说明grpc_serviceGrpcService处理网络流量的外部 gRPC 服务必须实现NetworkExternalProcessor服务中的ProcessRPCfailure_mode_allowbool默认为 false。为 true 时若 gRPC 流无法建立或提前异常关闭处理将继续而不报错为 false 时过滤器失败并关闭连接processing_modeProcessingMode控制数据方向处理process_read/process_write可设为STREAMED默认或SKIP。两者都设为SKIP会被配置拒绝message_timeoutDuration同步模式下每条消息的超时时间默认 200ms范围 03600 秒stat_prefixstring统计前缀必填最小长度 1metadata_optionsMetadataOptions动态元数据转发/接收命名空间配置untyped 与 typed 两类connection_attributesrepeated string本次新增要评估的数据平面属性名列表协议语义ProcessingRequest.attributes外部处理服务在双向流中收到的是ProcessingRequest其完整结构见 network_external_processor.protoread_data字段 1请求路径上拦截到的数据客户端 → 服务端write_data字段 2响应路径上拦截到的数据服务端 → 客户端metadata字段 3与请求关联的元数据连接属性、过滤器配置等上下文信息注意它不会自动从请求传播到响应外部处理器需要时须自行在响应中包含attributes字段 4由配置中connection_attributes列表选定的属性值其中每一项都来自数据平面支持的标准属性集。attributes是一个mapstring, google.protobuf.Struct每个 key 对应一个被选中的属性名value 是求值结果以Struct形式承载任意类型值。从实现上看该 map 以 Envoy 内部的NetworkExternalProcessor过滤器命名空间作为整体 key将全部求值结果作为一个Struct放入其中详见下文源码分析。源码级实现原理1. 配置解析构建 CEL 表达式管理器在 ext_proc.cc 的Config构造函数中connection_attributes被直接传递给ExpressionManager完成初始化expression_manager_(builder, local_info, config.connection_attributes(), creation_status)ExpressionManager定义于 matching_utils.h负责将属性名编译为 CEL 表达式并保存主要职责包括hasConnectionExpr()判断是否配置了连接属性表达式evaluateConnectionAttributes(activation)基于给定的激活上下文Activation对全部表达式求值initExpressions()逐个解析并编译属性表达式。2. CEL 表达式编译过程matching_utils.cc 中的initExpressions展示了完整的编译链路对每个属性名调用 CEL parser 的google::api::expr::parser::Parse()解析为ParsedExpr解析失败时设置creation_status为InvalidArgumentErrorUnable to parse descriptor expression过滤器创建失败通过Extensions::Filters::Common::Expr::CompiledExpression::Create()编译表达式失败同样报错并终止编译成功的表达式以属性名为 key 存入absl::flat_hash_map重复属性自动去重。需要特别说明的是整个编译过程受USE_CEL_PARSER编译开关保护。若构建环境中未启用 CEL parser配置了connection_attributes时会打印 warning 日志且表达式不会被解析这一点在部署自定义构建版本时需要注意。3. 求值与类型映射evaluateAttributes对每个编译后的表达式在给定 Activation 上执行求值求值出错返回 Error时跳过该属性并记录 trace 级日志结果值按类型映射到Protobuf::ValuekBool→bool_valuekInt64/kUint64→number_value其它类型 → 通过print()转为string_value也就是说属性求值结果最终以google.protobuf.Struct形式呈现外部服务可用通用 JSON 语义解析。4. 发送时机仅连接建立后发送一次在 ext_proc.cc 的addAttributes(ProcessingRequest req)方法中体现了发送时机逻辑void NetworkExtProcFilter::addAttributes(ProcessingRequest req) { if (attributes_sent_ || !config_-expressionManager().hasConnectionExpr()) { return; } auto activation_ptr Filters::Common::Expr::createActivation( config_-expressionManager().localInfo(), read_callbacks_-connection().streamInfo(), nullptr, nullptr, nullptr); auto attributes config_-expressionManager().evaluateConnectionAttributes(*activation_ptr); attributes_sent_ true; (*req.mutable_attributes())[NetworkFilterNames::get().NetworkExternalProcessor] std::move(attributes); }关键点只发送一次attributes_sent_标志确保连接属性仅在首个ProcessingRequest中携带后续数据请求不再重复评估与发送求值上下文通过createActivation()将LocalInfo与连接的StreamInfo注入 Activation因此connection_attributes中既可以引用连接级属性如远端/本地地址也可以引用存储于StreamInfo的过滤器状态filter state这与 changelog 中“evaluating CEL connection attributes and filter state”的描述一致命名空间 key结果以NetworkExternalProcessor过滤器命名空间为 key 放入attributesmap外部服务可按固定命名空间读取整组属性。实践注意事项属性名必须合法 CEL 表达式connection_attributes中的每一项都会被当作 CEL 表达式解析拼写错误或语法非法将导致过滤器配置加载失败InvalidArgumentError需参照数据平面标准属性集arch_overview_attributes书写属性名。求值结果的一次性语义属性在连接生命周期内只随首个请求发送一次。若外部服务后续需要属性应自行在本地缓存这也意味着连接中途变化的属性不会重复推送。与 metadata 的关系attributes与metadata动态元数据是两条独立通道。动态元数据需要通过metadata_options.forwarding_namespaces显式声明转发命名空间而连接属性只需在connection_attributes中列出即可。构建开关若自定义构建未启用USE_CEL_PARSER连接属性功能将静默不可用仅 warning 日志请确认发行版/自建二进制支持 CEL parser。与 HTTP ext_proc 的对照HTTP 层的外部处理过滤器早已支持属性传递ProcessingRequest.attributes与DynamicMetadata本次变更将同等能力下沉到 L4 网络过滤器使原始 TCP/UDP 流量处理也能基于连接属性做精细化决策。关键参考文件变更记录network_ext_proc__connection-attributes.rst过滤器配置定义ext_proc.protoNetworkExternalProcessor.connection_attributes服务协议定义network_external_processor.protoProcessingRequest.attributes过滤器实现ext_proc.ccConfig构造与addAttributesCEL 表达式管理matching_utils.h、matching_utils.cc表达式编译与求值【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考