Support for transport socket matching on locality metadata (#34598)

This patch adds a metadata field to the [LocalityLbEndpoints](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/endpoint/v3/endpoint_components.proto#config-endpoint-v3-localitylbendpoints) configuration. The new field can be used to perform transport socket matching for all endpoints in a locality:

```
  load_assignment:
    cluster_name: example_cluster
    endpoints:
    - metadata: # <----- This is new.
        filter_metadata:
          envoy.transport_socket_match:
            network.id: vpc-1
      lb_endpoints:
      - endpoint:
          address:
            socket_address:
              address: 10.1.1.1
              port_value: 11337
      - endpoint:
          address:
            socket_address:
              address: 10.1.1.2
              port_value: 11337
```

Notice the ability to add metadata alongside the collection of endpoints. The transport socket matcher will still check the `envoy.transport_socket_match` metadata for an endpoint, but now if there is no match it will look at that field in its locality's metadata. This essentially allows one to set a transport socket match for groups of endpoints with a single metadata field, which can significantly improve scalability for deployments with many endpoints as shown in https://github.com/envoyproxy/envoy/issues/34530.

Signed-off-by: Tony Allen <txallen@google.com>

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

envoy/config/cluster/v3/cluster.proto

@@ -168,7 +168,7 @@ message Cluster {
     // The name of the match, used in stats generation.
     string name = 1 [(validate.rules).string = {min_len: 1}];
 
-    // Optional endpoint metadata match criteria.
+    // Optional metadata match criteria.
     // The connection to the endpoint with metadata matching what is set in this field
     // will use the transport socket configuration specified here.
     // The endpoint's metadata entry in ``envoy.transport_socket_match`` is used to match
@@ -754,12 +754,14 @@ message Cluster {
 
   reserved "hosts", "tls_context", "extension_protocol_options";
 
-  // Configuration to use different transport sockets for different endpoints.
-  // The entry of ``envoy.transport_socket_match`` in the
-  // :ref:`LbEndpoint.Metadata <envoy_v3_api_field_config.endpoint.v3.LbEndpoint.metadata>`
-  // is used to match against the transport sockets as they appear in the list. The first
-  // :ref:`match <envoy_v3_api_msg_config.cluster.v3.Cluster.TransportSocketMatch>` is used.
-  // For example, with the following match
+  // Configuration to use different transport sockets for different endpoints.  The entry of
+  // ``envoy.transport_socket_match`` in the :ref:`LbEndpoint.Metadata
+  // <envoy_v3_api_field_config.endpoint.v3.LbEndpoint.metadata>` is used to match against the
+  // transport sockets as they appear in the list. If a match is not found, the search continues in
+  // :ref:`LocalityLbEndpoints.Metadata
+  // <envoy_v3_api_field_config.endpoint.v3.LocalityLbEndpoints.metadata>`.  The first :ref:`match
+  // <envoy_v3_api_msg_config.cluster.v3.Cluster.TransportSocketMatch>` is used.  For example, with
+  // the following match
   //
   // .. code-block:: yaml
   //
@@ -783,8 +785,9 @@ message Cluster {
   // socket match in case above.
   //
   // If an endpoint metadata's value under ``envoy.transport_socket_match`` does not match any
-  // ``TransportSocketMatch``, socket configuration fallbacks to use the ``tls_context`` or
-  // ``transport_socket`` specified in this cluster.
+  // ``TransportSocketMatch``, the locality metadata is then checked for a match. Barring any
+  // matches in the endpoint or locality metadata, the socket configuration fallbacks to use the
+  // ``tls_context`` or ``transport_socket`` specified in this cluster.
   //
   // This field allows gradual and flexible transport socket configuration changes.
   //

envoy/config/endpoint/v3/endpoint_components.proto

@@ -147,7 +147,7 @@ message LedsClusterLocalityConfig {
 // A group of endpoints belonging to a Locality.
 // One can have multiple LocalityLbEndpoints for a locality, but only if
 // they have different priorities.
-// [#next-free-field: 9]
+// [#next-free-field: 10]
 message LocalityLbEndpoints {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.api.v2.endpoint.LocalityLbEndpoints";
@@ -161,6 +161,9 @@ message LocalityLbEndpoints {
   // Identifies location of where the upstream hosts run.
   core.v3.Locality locality = 1;
 
+  // Metadata to provide additional information about the locality endpoints in aggregate.
+  core.v3.Metadata metadata = 9;
+
   // The group of endpoints belonging to the locality specified.
   // [#comment:TODO(adisuissa): Once LEDS is implemented this field needs to be
   // deprecated and replaced by ``load_balancer_endpoints``.]