router: complete the new matcher based cluster specifier (#39816)

Commit Message: router: complete the new matcher based cluster specifier
Additional Description:

Now we can specifiy multiple clusters in single route and select
different cluster based on the request attributes.

This is an independent new feature but also is pre PR of
[#38859](envoyproxy/envoy#38859).

Risk Level: low, new extension.
Testing: unit.
Docs Changes: added.
Release Notes: added.

---------

Signed-off-by: wangbaiping(wbpcode) <[email protected]>
Signed-off-by: code <[email protected]>
Co-authored-by: Rohit Agrawal <[email protected]>

Mirrored from https://github.com/envoyproxy/envoy @ f19cadd4ead6166cc22b5d225d4719e25e50be45

Author: update-envoy[bot]

envoy/extensions/router/cluster_specifiers/matcher/v3/matcher.proto

@@ -15,11 +15,61 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
 // [#protodoc-title: Matcher Based Cluster Specifier]
 // [#extension: envoy.router.cluster_specifier_plugin.matcher]
-// [#not-implemented-hide:]
+
+message ClusterAction {
+  // Indicates the upstream cluster to which the request should be routed
+  // to.
+  string cluster = 1 [(validate.rules).string = {min_len: 1}];
+}
 
 message MatcherClusterSpecifier {
   // The matcher for cluster selection after the route has been selected. This is used when the
   // route has multiple clusters (like multiple clusters for different users) and the matcher
   // is used to select the cluster to use for the request.
+  //
+  // The match tree to use for grouping incoming requests into buckets.
+  //
+  // Example:
+  //
+  // .. validated-code-block:: yaml
+  //   :type-name: xds.type.matcher.v3.Matcher
+  //
+  //   matcher_list:
+  //     matchers:
+  //     - predicate:
+  //         single_predicate:
+  //           input:
+  //             typed_config:
+  //               '@type': type.googleapis.com/envoy.type.matcher.v3.HttpRequestHeaderMatchInput
+  //               header_name: env
+  //           value_match:
+  //             exact: staging
+  //       on_match:
+  //         action:
+  //           typed_config:
+  //             '@type': type.googleapis.com/envoy.extensions.router.cluster_specifiers.matcher.v3.ClusterAction
+  //             cluster: "staging-cluster"
+  //
+  //     - predicate:
+  //         single_predicate:
+  //           input:
+  //             typed_config:
+  //               '@type': type.googleapis.com/envoy.type.matcher.v3.HttpRequestHeaderMatchInput
+  //               header_name: env
+  //           value_match:
+  //             exact: prod
+  //       on_match:
+  //         action:
+  //           typed_config:
+  //             '@type': type.googleapis.com/envoy.extensions.router.cluster_specifiers.matcher.v3.ClusterAction
+  //             cluster: "prod-cluster"
+  //
+  //   # Catch-all with a default cluster.
+  //   on_no_match:
+  //     action:
+  //       typed_config:
+  //         '@type': type.googleapis.com/envoy.extensions.router.cluster_specifiers.matcher.v3.ClusterAction
+  //         cluster: "default-cluster"
+  //
   xds.type.matcher.v3.Matcher cluster_matcher = 1 [(validate.rules).message = {required: true}];
 }