Composite Filter

Attention

The composite filter is in alpha and is currently under active development. Capabilities will be expanded over time and the configuration structures are likely to change.

The composite filter allows delegating filter actions to a filter specified by a match result. The purpose of this is to allow different filters or filter configurations to be selected based on the incoming request, allowing for more dynamic configuration that could become prohibitive when making use of per route configurations (e.g. because the cardinality would cause a route table explosion).

The filter does not do any kind of buffering, and as a result it must be able to instantiate the filter it will delegate to before it receives any callbacks that it needs to delegate. Because of this, in order to delegate all the data to the specified filter, the decision must be made based on just the request headers.

Delegation can fail if the filter factory attempted to use a callback not supported by the composite filter. In either case, the <stat_prefix>.composite.delegation_error stat will be incremented.

Sample Envoy configuration

Here’s a sample Envoy configuration that makes use of the composite filter to inject a different latency via the fault filter. It uses the header x-fault-category to determine which fault configuration to use: if the header is equal to the string huge fault, a 10s latency is injected while if the header contains tiny string a 1s latency is injected. If the header is absent or contains a different value, no filter is instantiated.

  1. admin:
  2. address:
  3. socket_address: {address: 0.0.0.0, port_value: 9901}
  4. static_resources:
  5. listeners:
  6. - name: listener1
  7. address:
  8. socket_address: {address: 0.0.0.0, port_value: 51051}
  9. filter_chains:
  10. - filters:
  11. - name: envoy.filters.network.http_connection_manager
  12. typed_config:
  13. "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
  14. stat_prefix: grpc_json
  15. codec_type: AUTO
  16. route_config:
  17. name: local_route
  18. virtual_hosts:
  19. - name: local_service
  20. domains: ["*"]
  21. routes:
  22. # NOTE: by default, matching happens based on the gRPC route, and not on the incoming request path.
  23. # Reference: https://www.envoyproxy.io/docs/envoy/latest/configuration/http_filters/grpc_json_transcoder_filter#route-configs-for-transcoded-requests
  24. - match: {prefix: "/helloworld.Greeter"}
  25. route: {cluster: grpc, timeout: 60s}
  26. http_filters:
  27. - name: composite
  28. typed_config:
  29. "@type": type.googleapis.com/envoy.extensions.common.matching.v3.ExtensionWithMatcher
  30. extension_config:
  31. name: composite
  32. typed_config:
  33. "@type": type.googleapis.com/envoy.extensions.filters.http.composite.v3.Composite
  34. xds_matcher:
  35. matcher_tree:
  36. input:
  37. name: request-headers
  38. typed_config:
  39. "@type": type.googleapis.com/envoy.type.matcher.v3.HttpRequestHeaderMatchInput
  40. header_name: x-fault-category
  41. exact_match_map:
  42. map:
  43. "huge fault": # inject 10s latency into all requests
  44. action:
  45. name: composite-action
  46. typed_config:
  47. "@type": type.googleapis.com/envoy.extensions.filters.http.composite.v3.ExecuteFilterAction
  48. typed_config:
  49. name: http-fault
  50. typed_config:
  51. "@type": type.googleapis.com/envoy.extensions.filters.http.fault.v3.HTTPFault
  52. delay:
  53. fixed_delay: 10s
  54. percentage:
  55. numerator: 100
  56. denominator: HUNDRED
  57. "tiny fault": # inject 1s latency into all requests
  58. action:
  59. name: composite-action
  60. typed_config:
  61. "@type": type.googleapis.com/envoy.extensions.filters.http.composite.v3.ExecuteFilterAction
  62. typed_config:
  63. name: http-fault
  64. typed_config:
  65. "@type": type.googleapis.com/envoy.extensions.filters.http.fault.v3.HTTPFault
  66. delay:
  67. fixed_delay: 1s
  68. percentage:
  69. numerator: 100
  70. denominator: HUNDRED
  71. - name: envoy.filters.http.router
  72. clusters:
  73. - name: grpc
  74. type: LOGICAL_DNS
  75. lb_policy: ROUND_ROBIN
  76. dns_lookup_family: V4_ONLY
  77. typed_extension_protocol_options:
  78. envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
  79. "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
  80. explicit_http_config:
  81. http2_protocol_options: {}
  82. load_assignment:
  83. cluster_name: grpc
  84. endpoints:
  85. - lb_endpoints:
  86. - endpoint:
  87. address:
  88. socket_address:
  89. address: 127.0.0.1
  90. port_value: 50051
  91. layered_runtime:
  92. layers:
  93. - name: static-layer
  94. static_layer:
  95. envoy:
  96. reloadable_features:
  97. experimental_matching_api: true

Statistics

The composite filter outputs statistics in the <stat_prefix>.composite.* namespace.

Name

Type

Description

delegation_success

Counter

Number of requests that successfully created a delegated filter

delegation_error

Counter

Number of requests that attempted to create a delegated filter but failed