.. _arch_overview_attributes: 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 :ref:`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. .. _arch_overview_request_attributes: 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. .. csv-table:: :header: Attribute, Type, Description :escape: ' :widths: 1, 1, 4 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", 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'")" Header values in ``request.headers`` associative array are comma-concatenated in case of multiple values. Additional attributes are available once the request completes: .. csv-table:: :header: Attribute, Type, Description :widths: 1, 1, 4 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. .. csv-table:: :header: Attribute, Type, Description :widths: 1, 1, 4 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", All response headers indexed by the lower-cased header name response.trailers, "map", 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 Connection attributes --------------------- The following attributes are available once the downstream connection is established (which also applies to HTTP requests making them suitable for RBAC): .. csv-table:: :header: Attribute, Type, Description :widths: 1, 1, 4 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 The following additional attributes are available upon the downstream connection termination: .. csv-table:: :header: Attribute, Type, Description :widths: 1, 1, 4 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: .. csv-table:: :header: Attribute, Type, Description :widths: 1, 1, 4 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.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: .. csv-table:: :header: Attribute, Type, Description :widths: 1, 1, 4 metadata, :ref:`Metadata`, Dynamic request metadata filter_state, "map", Mapping from a filter state name to its serialized string value Note that these attributes may change during the life of a request as the data can be updated by filters at any point. Wasm attributes --------------- In addition to all above, the following extra attributes are available to Wasm extensions: .. csv-table:: :header: Attribute, Type, Description :widths: 1, 1, 4 plugin_name, string, Plugin name plugin_root_id, string, Plugin root ID plugin_vm_id, string, Plugin VM ID node, :ref:`Node`, Local node description cluster_name, string, Upstream cluster name cluster_metadata, :ref:`Metadata`, Upstream cluster metadata listener_direction, int, Enumeration value of the :ref:`listener traffic direction` listener_metadata, :ref:`Metadata`, Listener metadata route_name, string, Route name route_metadata, :ref:`Metadata`, Route metadata upstream_host_metadata, :ref:`Metadata`, Upstream host metadata 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.