Extension configuration

Each configuration resource in Envoy has a type URL in the typed_config. This type corresponds to a versioned schema. The type URL uniquely identifies an extension capable of interpreting the configuration. The name field is 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:

extensions-demo.yaml
14      - name: front-http-proxy
15        typed_config:
16          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
17          stat_prefix: ingress_http
18          codec_type: AUTO
19          rds:
20            route_config_name: local_route
21            config_source:
22              api_config_source:
23                api_type: GRPC
24                grpc_services:
25                - envoy_grpc:
26                    cluster_name: xds_cluster
27          http_filters:
28          - name: front-router
29            typed_config:
30              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
31              dynamic_stats: true
32  clusters:
33  - type: STRICT_DNS

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:

extensions-demo-with-type-url.yaml
14      - name: front-http-proxy
15        typed_config:
16          "@type": type.googleapis.com/xds.type.v3.TypedStruct
17          type_url: type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
18          value:
19            stat_prefix: ingress_http
20            codec_type: AUTO
21            rds:
22              route_config_name: local_route
23              config_source:
24                api_config_source:
25                  api_type: GRPC
26                  grpc_services:
27                  - envoy_grpc:
28                      cluster_name: xds_cluster
29            http_filters:
30            - name: front-router
31              typed_config:
32                "@type": type.googleapis.com/xds.type.v3.TypedStruct
33                type_url: type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
34                value:
35                  dynamic_stats: true
36  clusters:
37  - type: STRICT_DNS

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.

Listener filters

For Listener filters, the discovery service configuration is: dynamic listener filter re-configuration. The dynamic listener filter config is only supported in TCP listeners. If the dynamic configuration is missing, the connection will be rejected until a valid config is updated.

Network filters

For downstream network filters, the discovery service configuration is: dynamic filter re-configuration. If the dynamic configuration is missing, the connection will be rejected until a valid config is updated. When a filter configuration updates, the new configuration will only apply to new connections, existing connections will keep using the older filter configuration.

HTTP filters

For HTTP filters, HTTP connection manager supports dynamic filter re-configuration. If the configuration is missing a local HTTP response with ‘500’ status code will be returned.

Statistics

In addition to the statistics supported for xDS subscriptions, the following statistics are supported for listener filters, downstream network filters, and HTTP filters, rooted at extension_config_discovery.<stat_prefix>.<extension_config_name>.

  • For TCP listener filters, the value of <stat_prefix> is tcp_listener_filter.

  • For downstream network filters, the value of <stat_prefix> is network_filter.

  • For upstream network filters, the value of <stat_prefix> is upstream_network_filter.

  • For downstream HTTP filters, the value of <stat_prefix> is http_filter.

  • For upstream HTTP filters, the value of <stat_prefix> is upstream_http_filter.

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.

Additionally, the following statistics are supported to indicate that a connection was closed due to a missing configuration, rooted at listener.<address> (or listener.<stat_prefix>. if stat_prefix is non-empty).

Name

Type

Description

extension_config_missing

Counter

Total connections closed due to missing listener filter extension configuration

network_extension_config_missing

Counter

Total connections closed due to missing network filter extension configuration