Attributes

Attributes refer to contextual properties provided by Envoy during request and connection processing. They are named by a dot-separated path (e.g. request.path), have a fixed type (e.g. string or int), and may be absent or present depending on the context. Attributes are exposed to CEL runtime in RBAC filter, as well as Wasm extensions via get_property ABI method.

Attribute value types are limited to:

  • string for UTF-8 strings

  • bytes for byte buffers

  • int for 64-bit signed integers

  • uint for 64-bit unsigned integers

  • bool for booleans

  • list for lists of values

  • map for associative arrays with string keys

  • timestamp for timestamps as specified by Timestamp

  • duration for durations as specified by Duration

  • Protocol buffer message types

CEL provides standard helper functions for operating on abstract types such as getMonth for timestamp values. Note that integer literals (e.g. 7) are of type int, which is distinct from uint (e.g. 7u), and the arithmetic conversion is not automatic (use uint(7) for explicit conversion).

Wasm extensions receive the attribute values as a serialized buffer according to the type of the attribute. Strings and bytes are passed as-is, integers are passed as 64 bits directly, timestamps and durations are approximated to nano-seconds, and structured values are converted to a sequence of pairs recursively.

Request attributes

The following request attributes are generally available upon initial request processing, which makes them suitable for RBAC policies.

request.* attributes are only available in http filters.

Attribute

Type

Description

request.path

string

The path portion of the URL

request.url_path

string

The path portion of the URL without the query string

request.host

string

The host portion of the URL

request.scheme

string

The scheme portion of the URL e.g. “http”

request.method

string

Request method e.g. “GET”

request.headers

map<string, string>

All request headers indexed by the lower-cased header name

request.referer

string

Referer request header

request.useragent

string

User agent request header

request.time

timestamp

Time of the first byte received

request.id

string

Request ID corresponding to x-request-id header value

request.protocol

string

Request protocol (“HTTP/1.0”, “HTTP/1.1”, “HTTP/2”, or “HTTP/3”)

request.query

string

The query portion of the URL in the format of “name1=value1&name2=value2”.

Header values in request.headers associative array are comma-concatenated in case of multiple values.

Additional attributes are available once the request completes:

Attribute

Type

Description

request.duration

duration

Total duration of the request

request.size

int

Size of the request body. Content length header is used if available.

request.total_size

int

Total size of the request including the approximate uncompressed size of the headers

Response attributes

Response attributes are only available after the request completes.

response.* attributes are only available in http filters.

Attribute

Type

Description

response.code

int

Response HTTP status code

response.code_details

string

Internal response code details (subject to change)

response.flags

int

Additional details about the response beyond the standard response code encoded as a bit-vector

response.grpc_status

int

Response gRPC status code

response.headers

map<string, string>

All response headers indexed by the lower-cased header name

response.trailers

map<string, string>

All response trailers indexed by the lower-cased trailer name

response.size

int

Size of the response body

response.total_size

int

Total size of the response including the approximate uncompressed size of the headers and the trailers

response.backend_latency

duration

Duration between the first byte sent to and the last byte received from the upstream backend

Connection attributes

The following attributes are available once the downstream connection is established (which also applies to HTTP requests making them suitable for RBAC):

Attribute

Type

Description

source.address

string

Downstream connection remote address

source.port

int

Downstream connection remote port

destination.address

string

Downstream connection local address

destination.port

int

Downstream connection local port

connection.id

uint

Downstream connection ID

connection.mtls

bool

Indicates whether TLS is applied to the downstream connection and the peer ceritificate is presented

connection.requested_server_name

string

Requested server name in the downstream TLS connection

connection.tls_version

string

TLS version of the downstream TLS connection

connection.subject_local_certificate

string

The subject field of the local certificate in the downstream TLS connection

connection.subject_peer_certificate

string

The subject field of the peer certificate in the downstream TLS connection

connection.dns_san_local_certificate

string

The first DNS entry in the SAN field of the local certificate in the downstream TLS connection

connection.dns_san_peer_certificate

string

The first DNS entry in the SAN field of the peer certificate in the downstream TLS connection

connection.uri_san_local_certificate

string

The first URI entry in the SAN field of the local certificate in the downstream TLS connection

connection.uri_san_peer_certificate

string

The first URI entry in the SAN field of the peer certificate in the downstream TLS connection

connection.sha256_peer_certificate_digest

string

SHA256 digest of the peer certificate in the downstream TLS connection if present

connection.transport_failure_reason

string

The transport failure reason e.g. certificate validation failed

The following additional attributes are available upon the downstream connection termination:

Attribute

Type

Description

connection.termination_details

string

Internal termination details of the connection (subject to change)

Upstream attributes

The following attributes are available once the upstream connection is established:

Attribute

Type

Description

upstream.address

string

Upstream connection remote address

upstream.port

int

Upstream connection remote port

upstream.tls_version

string

TLS version of the upstream TLS connection

upstream.subject_local_certificate

string

The subject field of the local certificate in the upstream TLS connection

upstream.subject_peer_certificate

string

The subject field of the peer certificate in the upstream TLS connection

upstream.dns_san_local_certificate

string

The first DNS entry in the SAN field of the local certificate in the upstream TLS connection

upstream.dns_san_peer_certificate

string

The first DNS entry in the SAN field of the peer certificate in the upstream TLS connection

upstream.uri_san_local_certificate

string

The first URI entry in the SAN field of the local certificate in the upstream TLS connection

upstream.uri_san_peer_certificate

string

The first URI entry in the SAN field of the peer certificate in the upstream TLS connection

upstream.sha256_peer_certificate_digest

string

SHA256 digest of the peer certificate in the upstream TLS connection if present

upstream.local_address

string

The local address of the upstream connection

upstream.transport_failure_reason

string

The upstream transport failure reason e.g. certificate validation failed

Metadata and filter state

Data exchanged between filters is available as the following attributes:

Attribute

Type

Description

metadata

Metadata

Dynamic request metadata

filter_state

map<string, Value>

Mapping from the filter state name to the object value

upstream_filter_state

map<string, Value>

Mapping from the upstream filter state name to the object value

Filter state value representation is determined based on the filter state declaration in the following order:

  • If the value is represented as a dynamic CelValue wrapper, CelValue is returned verbatim.

  • If the key is well-known and has a field reflection enabled, then it is returned as a map from the field names to the field values.

  • Otherwise, the value is returned as the serialized bytes.

Note that these attributes may change during the life of a request as the data can be updated by filters at any point.

Configuration attributes

Configuration identifiers and metadata related to the handling of the request or the connection is available as the following attributes:

Attribute

Type

Description

xds.node

Node

Local node description

xds.cluster_name

string

Upstream cluster name

xds.cluster_metadata

Metadata

Upstream cluster metadata

xds.listener_direction

int

Enumeration value of the listener traffic direction

xds.listener_metadata

Metadata

Listener metadata

xds.route_name

string

Route name

xds.route_metadata

Metadata

Route metadata

xds.upstream_host_metadata

Metadata

Upstream host metadata

xds.filter_chain_name

string

Listener filter chain name

Wasm attributes

In addition to all above, the following extra attributes are available to Wasm extensions:

Attribute

Type

Description

plugin_name

string

Plugin name

plugin_root_id

string

Plugin root ID

plugin_vm_id

string

Plugin VM ID

Path expressions

Path expressions allow access to inner fields in structured attributes via a sequence of field names, map, and list indexes following an attribute name. For example, get_property({"node", "id"}) in Wasm ABI extracts the value of id field in node message attribute, while get_property({"request", "headers", "my-header"}) refers to the comma-concatenated value of a particular request header.