Metadata in XDS resources

Overview

In Envoy, static metadata can be configured on various resources: listener, virtual host, route and cluster.

Static metadata can be used for various purposes:

  • Observability: enrichment of access logs and traces with metadata formatters and custom tags.
  • Processing: provide configuration context to filters in a certain scope (e.g. vhost, route, etc.).

This document describes how Envoy Gateway manages static metadata for various XDS resource such as listeners, virtual hosts, routes, clusters and endpoints.

Configuration

Envoy Gateway propagates certain attributes of Gateway-API resources to XDS resources. Attributes include:

  • Metadata: Kind, Group/Version, Name, Namespace and Annotations (belonging to the metadata.gateway.envoyproxy.io namespace)
  • Spec: SectionName (Listener Name, RouteRule Name, Port Name), in-spec annotations (e.g. Gateway Annotations)

Future enhancements may include:

  • Additional attribute propagation
  • Supporting section-specific metadata, e.g. HTTPRoute Metadata annotations that are propagated only to a specific route rule XDS metadata.
  • Supporting additional XDS resource, e.g. endpoints and filter chains.

Translation

Envoy Gateway uses the following namespace for envoy resource metadata: io.envoyproxy.gateway.metadata. For example, an envoy route resource may have the following metadata structure:

name: httproute/gateway-conformance-infra/myroute/rule/0/match/0/*
match:
  path_separated_prefix: "/mypath"
route:
  cluster: httproute/gateway-conformance-infra/myroute/rule/0
metadata:
  filter_metadata:
    envoy-gateway:
      resources:
        - namespace: gateway-conformance-infra
          groupVersion: gateway.networking.k8s.io/v1
          kind: HTTPRoute
          annotations:
            foo: bar
          name: myroute

Envoy Gateway translates Gateway-API in the following manner:

Usage

Users can consume metadata in various ways:

  • Adding metadata to access logs using the metadata operator, e.g. %METADATA(ROUTE:envoy-gateway:resources)
  • Accessing metadata in CEL expressions through the xds.*_metadata attribute