Virtual cluster

A virtual cluster is a way of specifying a regex matching rule against certain important endpoints such that statistics are generated explicitly for the matched requests. The reason this is useful is that when doing prefix/path matching Envoy does not always know what the application considers to be an endpoint. Thus, it’s impossible for Envoy to generically emit per endpoint statistics. However, often systems have highly critical endpoints that they wish to get “perfect” statistics on. Virtual cluster statistics are perfect in the sense that they are emitted on the downstream side such that they include network level failures.


Virtual clusters are a useful tool, but we do not recommend setting up a virtual cluster for every application endpoint. This is both not easily maintainable as well as the matching and statistics output are not free.

  "pattern": "...",
  "name": "...",
  "method": "..."
(required, string) Specifies a regex pattern to use for matching requests. The entire path of the request must match the regex. The regex grammar used is defined here.
(required, string) Specifies the name of the virtual cluster. The virtual cluster name as well as the virtual host name are used when emitting statistics. The statistics are emitted by the router filter and are documented here.

(optional, string) Optionally specifies the HTTP method to match on. For example GET, PUT, etc.


  • The regex /rides/d+ matches the path /rides/0
  • The regex /rides/d+ matches the path /rides/123
  • The regex /rides/d+ does not match the path /rides/123/456

Documentation for virtual cluster statistics.