Extension configuration

Each configuration resource in Envoy has a type URL in the typed_config. This type corresponds to a versioned schema. If the type URL uniquely identifies an extension capable of interpreting the configuration, then the extension is selected regardless of the name field. In this case the name field becomes optional and can be used as an identifier or as an annotation for the particular instance of the extension configuration. For example, the following filter configuration snippet is permitted:

  1. name: front-http-proxy
  2. typed_config:
  3.   "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
  4.   stat_prefix: ingress_http
  5.   codec_type: AUTO
  6.   rds:
  7.     route_config_name: local_route
  8.     config_source:
  9.       resource_api_version: V3
  10.       api_config_source:
  11.         api_type: GRPC
  12.         transport_api_version: V3
  13.         grpc_services:
  14.           envoy_grpc:
  15.             cluster_name: xds_cluster
  16.   http_filters:
  17.   - name: front-router
  18.     typed_config:
  19.       "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
  20.       dynamic_stats: true

In case the control plane lacks the schema definitions for an extension, xds.type.v3.TypedStruct should be used as a generic container. The type URL inside it is then used by a client to convert the contents to a typed configuration resource. For example, the above example could be written as follows:

  1. name: front-http-proxy
  2. typed_config:
  3.   "@type": type.googleapis.com/xds.type.v3.TypedStruct
  4.   type_url: type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
  5.   value:
  6.     stat_prefix: ingress_http
  7.     codec_type: AUTO
  8.     rds:
  9.       route_config_name: local_route
  10.       resource_api_version: V3
  11.       config_source:
  12.         api_config_source:
  13.           api_type: GRPC
  14.           transport_api_version: V3
  15.           grpc_services:
  16.             envoy_grpc:
  17.               cluster_name: xds_cluster
  18.     http_filters:
  19.     - name: front-router
  20.       typed_config:
  21.         "@type": type.googleapis.com/xds.type.v3.TypedStruct
  22.         type_url: type.googleapis.com/envoy.extensions.filters.http.router.v3Router

Discovery service

Extension configuration can be supplied dynamically from an xDS management server using ExtensionConfiguration discovery service. The name field in the extension configuration acts as the resource identifier. For example, HTTP connection manager supports dynamic filter re-configuration for HTTP filters.

Extension config discovery service has a statistics tree rooted at <stat_prefix>.extension_config_discovery.<extension_config_name>. In addition to the common subscription statistics, it also provides the following:

Name

Type

Description

config_reload

Counter

Total number of successful configuration updates

config_fail

Counter

Total number of failed configuration updates

config_conflict

Counter

Total number of conflicting applications of configuration updates; this may happen when a new listener cannot reuse a subscribed extension configuration due to an invalid type URL.