屬性

屬性是指 Envoy 在請求和連線處理期間提供的上下文屬性。它們由點分隔的路徑命名（例如 request.path），具有固定的類型（例如 string 或 int），並且可能根據上下文而存在或不存在。屬性透過 get_property ABI 方法暴露給 RBAC 過濾器中的 CEL 執行階段以及 Wasm 擴充功能。

屬性值類型僅限於

  • string 用於 UTF-8 字串

  • bytes 用於位元組緩衝區

  • int 用於 64 位元帶正負號整數

  • uint 用於 64 位元不帶正負號整數

  • bool 用於布林值

  • list 用於數值清單

  • map 用於具有字串鍵的關聯陣列

  • timestamp 用於 Timestamp 指定的時間戳記

  • duration 用於 Duration 指定的持續時間

  • Protocol buffer 訊息類型

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 的 scheme 部分，例如「http」

request.method

string

請求方法，例如「GET」

request.headers

map<string, string>

所有請求標頭，依據小寫標頭名稱編製索引

request.referer

string

Referer 請求標頭

request.useragent

string

User agent 請求標頭

request.time

timestamp

接收到第一個位元組的時間

request.id

string

對應於 x-request-id 標頭值的請求 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

路徑表達式

路徑表達式允許透過屬性名稱後接一連串的欄位名稱、映射和列表索引，來存取結構化屬性中的內部欄位。例如，Wasm ABI 中的 get_property({"node", "id"}) 會提取 node 訊息屬性中 id 欄位的值，而 get_property({"request", "headers", "my-header"}) 則是指特定請求標頭的逗號連接值。