属性

属性是指 Envoy 在处理请求和连接过程中提供的上下文属性。它们由点分隔路径命名（例如 request.path），具有固定类型（例如 string 或 int），并且可能根据上下文存在或不存在。属性在 CEL 运行时中公开 RBAC 过滤器，以及通过 get_property ABI 方法公开给 Wasm 扩展。

属性值类型仅限于

  • string 用于 UTF-8 字符串

  • bytes 用于字节缓冲区

  • int 用于 64 位有符号整数

  • uint 用于 64 位无符号整数

  • bool 用于布尔值

  • list 用于值列表

  • map 用于具有字符串键的关联数组

  • timestamp 用于时间戳，如 Timestamp 所指定

  • duration 用于持续时间，如 Duration 所指定

  • 协议缓冲区消息类型

CEL 为操作抽象类型（如 getMonth 用于 timestamp 值）提供了标准辅助函数。请注意，整数字面量（例如 7）的类型为 int，这不同于 uint（例如 7u），并且算术转换不是自动的（使用 uint(7) 进行显式转换）。

Wasm 扩展根据属性的类型接收属性值作为序列化缓冲区。字符串和字节按原样传递，整数直接作为 64 位传递，时间戳和持续时间近似为纳秒，结构化值递归地转换为一对序列。

请求属性

以下请求属性通常在初始请求处理时可用，这使得它们适合 RBAC 策略。

request.* 属性仅在 http 过滤器中可用。

属性

类型

描述

request.path

string

URL 的路径部分

request.url_path

string

URL 的路径部分，不包括查询字符串

request.host

string

URL 的主机部分

request.scheme

string

URL 的方案部分，例如“http”

request.method

string

请求方法，例如“GET”

request.headers

map<string, string>

所有请求标头，按小写标头名称索引

request.referer

string

Referer 请求标头

request.useragent

string

用户代理请求标头

request.time

timestamp

接收第一个字节的时间

request.id

string

请求 ID，对应于 x-request-id 标头值

request.protocol

string

请求协议（“HTTP/1.0”、“HTTP/1.1”、“HTTP/2”或“HTTP/3”）

request.query

string

URL 的查询部分，格式为“name1=value1&name2=value2”。

如果 request.headers 关联数组中的标头值有多个，则它们会以逗号连接起来。

请求完成后，会提供其他属性

属性

类型

描述

request.duration

duration

请求的总持续时间

request.size

int

请求正文的大小。如果可用，将使用 Content length 标头。

request.total_size

int

请求的总大小，包括标头的近似未压缩大小

响应属性

响应属性仅在请求完成后可用。

response.* 属性仅在 http 过滤器中可用。

属性

类型

描述

response.code

int

响应 HTTP 状态码

response.code_details

string

内部响应代码详细信息（可能会更改）

response.flags

int

响应的附加详细信息，超出了标准响应代码，以位向量形式编码

response.grpc_status

int

响应 gRPC 状态码

response.headers

map<string, string>

所有响应标头，按小写标头名称索引

response.trailers

map<string, string>

所有响应尾部，按小写尾部名称索引

response.size

int

响应正文的大小

response.total_size

int

响应的总大小，包括标头和尾部的近似未压缩大小

response.backend_latency

duration

从发送第一个字节到上游后端到接收最后一个字节之间的持续时间

连接属性

以下属性在建立下游连接后可用（这也适用于 HTTP 请求，这使得它们适合 RBAC）

属性

类型

描述

source.address

string

下游连接远程地址

source.port

int

下游连接远程端口

destination.address

string

下游连接本地地址

destination.port

int

下游连接本地端口

connection.id

uint

下游连接 ID

connection.mtls

bool

指示是否将 TLS 应用于下游连接，以及是否提供了对等证书

connection.requested_server_name

string

下游 TLS 连接中的请求服务器名称

connection.tls_version

string

下游 TLS 连接的 TLS 版本

connection.subject_local_certificate

string

下游 TLS 连接中本地证书的主题字段

connection.subject_peer_certificate

string

下游 TLS 连接中对等证书的主题字段

connection.dns_san_local_certificate

string

下游 TLS 连接中本地证书 SAN 字段中的第一个 DNS 条目

connection.dns_san_peer_certificate

string

下游 TLS 连接中对等证书 SAN 字段中的第一个 DNS 条目

connection.uri_san_local_certificate

string

下游 TLS 连接中本地证书 SAN 字段中的第一个 URI 条目

connection.uri_san_peer_certificate

string

下游 TLS 连接中对等证书 SAN 字段中的第一个 URI 条目

connection.sha256_peer_certificate_digest

string

如果存在，则在下游 TLS 连接中对等证书的 SHA256 摘要

connection.transport_failure_reason

string

传输失败原因，例如证书验证失败

下游连接终止后，会提供以下附加属性

属性

类型

描述

connection.termination_details

string

连接的内部终止详细信息（可能会更改）

上游属性

以下属性在上游连接建立后可用

属性

类型

描述

upstream.address

string

上游连接远程地址

upstream.port

int

上游连接远程端口

upstream.tls_version

string

上游 TLS 连接的 TLS 版本

upstream.subject_local_certificate

string

上游 TLS 连接中本地证书的主题字段

upstream.subject_peer_certificate

string

上游 TLS 连接中对等证书的主题字段

upstream.dns_san_local_certificate

string

上游 TLS 连接中本地证书 SAN 字段中的第一个 DNS 条目

upstream.dns_san_peer_certificate

string

上游 TLS 连接中对等证书 SAN 字段中的第一个 DNS 条目

upstream.uri_san_local_certificate

string

上游 TLS 连接中本地证书 SAN 字段中的第一个 URI 条目

upstream.uri_san_peer_certificate

string

上游 TLS 连接中对等证书 SAN 字段中的第一个 URI 条目

upstream.sha256_peer_certificate_digest

string

如果存在，则在上游 TLS 连接中对等证书的 SHA256 摘要

upstream.local_address

string

上游连接的本地地址

upstream.transport_failure_reason

string

上游传输失败原因，例如证书验证失败

元数据和过滤器状态

在过滤器之间交换的数据作为以下属性提供

属性

类型

描述

metadata

元数据

动态请求元数据

filter_state

map<string, Value>

从过滤器状态名称到对象值的映射

upstream_filter_state

map<string, Value>

从上游过滤器状态名称到对象值的映射

过滤器状态值表示形式根据过滤器状态声明中的以下顺序确定

  • 如果值表示为动态 CelValue 包装器，则按原样返回 CelValue。

  • 如果键是众所周知的并且启用了字段反射，则将其返回为从字段名称到字段值的映射。

  • 否则，值将作为序列化字节返回。

请注意，这些属性在请求的生命周期内可能会发生变化，因为过滤器可以在任何时候更新数据。

配置属性

与处理请求或连接相关的配置标识符和元数据作为以下属性提供

属性

类型

描述

xds.node

节点

本地节点描述

xds.cluster_name

string

上游集群名称

xds.cluster_metadata

元数据

上游集群元数据

xds.listener_direction

int

的枚举值 监听器流量方向

xds.listener_metadata

元数据

监听器元数据

xds.route_name

string

路由名称

xds.route_metadata

元数据

路由元数据

xds.upstream_host_metadata

元数据

上游主机元数据

xds.filter_chain_name

string

监听器过滤器链名称

Wasm 属性

除了上述所有内容之外，Wasm 扩展还可以使用以下额外的属性

属性

类型

描述

plugin_name

string

插件名称

plugin_root_id

string

插件根 ID

plugin_vm_id

string

插件 VM ID

路径表达式

路径表达式允许通过一系列字段名称、映射和列表索引，在结构化属性中访问内部字段。例如，get_property({"node", "id"}) 在 Wasm ABI 中提取了 node 消息属性中 id 字段的值，而 get_property({"request", "headers", "my-header"}) 指的是特定请求头中以逗号连接的值。