Envoy Network External Processing 连接属性(CEL)评估支持深度解析
Envoy Network External Processing 连接属性(CEL)评估支持深度解析
导读
本文围绕 Envoy 网络外部处理过滤器(envoy.filters.network.ext_proc)新增的一项能力展开:通过 connection_attributes 配置项,在 L4 网络外部处理器中评估 CEL(Common 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 流(Process RPC)灵活地处理原始 TCP/UDP 流量。与 HTTP 层的外部处理过滤器不同,它工作在 L4 传输层,可以:
- 双向检查流量(客户端 → 服务端、服务端 → 客户端);
- 修改网络数据负载;
- 控制连接生命周期(继续、优雅关闭或立即重置)。
过滤器通过 NetworkExternalProcessor 消息配置,外部服务需要实现 NetworkExternalProcessor 服务契约 中定义的 Process RPC。典型场景包括自定义协议检查与改写、高级流量操纵、安全扫描过滤和动态连接管理等。
新特性核心:连接属性评估与下发
本次新增的能力可以概括为两句话:
支持在网络外部处理器中评估 CEL 连接属性(connection attributes)与过滤器状态(filter state); 通过
connection_attributes配置项指定要评估的属性,评估结果随ProcessingRequest.attributes发送给外部处理服务。
具体而言,这包含两个协议层面的配合:
- 配置侧:
NetworkExternalProcessor.connection_attributes(repeated string,字段号 7),用于列出需要评估的数据平面属性名; - 数据侧:
ProcessingRequest.attributes(map<string, google.protobuf.Struct>,字段号 4),用于承载被选中属性的求值结果。
数据平面提供了丰富的标准属性(即官方文档中的 arch_overview_attributes 属性集)用于表达策略。配置中列出的每个属性名都会基于连接上下文与过滤器状态进行求值,然后填充到 ProcessingRequest.attributes 字段中。
配置方式与完整配置示例
以下是一份完整的过滤器配置示例,展示了 connection_attributes 与其它关键配置项的组合用法(YAML 结构对应 envoy.extensions.filters.network.ext_proc.v3.NetworkExternalProcessor):
network_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_service |
GrpcService |
处理网络流量的外部 gRPC 服务,必须实现 NetworkExternalProcessor 服务中的 Process RPC |
failure_mode_allow |
bool |
默认为 false。为 true 时,若 gRPC 流无法建立或提前异常关闭,处理将继续而不报错;为 false 时过滤器失败并关闭连接 |
processing_mode |
ProcessingMode |
控制数据方向处理:process_read/process_write 可设为 STREAMED(默认)或 SKIP。两者都设为 SKIP 会被配置拒绝 |
message_timeout |
Duration |
同步模式下每条消息的超时时间,默认 200ms,范围 0~3600 秒 |
stat_prefix |
string |
统计前缀,必填(最小长度 1) |
metadata_options |
MetadataOptions |
动态元数据转发/接收命名空间配置(untyped 与 typed 两类) |
connection_attributes |
repeated string |
本次新增:要评估的数据平面属性名列表 |
协议语义:ProcessingRequest.attributes
外部处理服务在双向流中收到的是 ProcessingRequest,其完整结构见 network_external_processor.proto:
read_data(字段 1):请求路径上拦截到的数据(客户端 → 服务端);write_data(字段 2):响应路径上拦截到的数据(服务端 → 客户端);metadata(字段 3):与请求关联的元数据(连接属性、过滤器配置等上下文信息),注意它不会自动从请求传播到响应,外部处理器需要时须自行在响应中包含;attributes(字段 4):由配置中connection_attributes列表选定的属性值,其中每一项都来自数据平面支持的标准属性集。
attributes 是一个 map<string, 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为InvalidArgumentError("Unable 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::Value:kBool→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.proto(
NetworkExternalProcessor.connection_attributes) - 服务协议定义:network_external_processor.proto(
ProcessingRequest.attributes) - 过滤器实现:ext_proc.cc(
Config构造与addAttributes) - CEL 表达式管理:matching_utils.h、matching_utils.cc(表达式编译与求值)