xds: sync Envoy proto to commit fd28e42f31730f5ed6f13f52999692a4885dd312 (2020-09-15)

xds/src/main/java/io/grpc/xds/EnvoyProtoData.java

@@ -226,6 +226,7 @@ static final class Builder {
       private Map<String, ?> metadata;
       @Nullable
       private Locality locality;
+      // TODO(sanjaypujare): eliminate usage of listening_addresses field.
       private final List<Address> listeningAddresses = new ArrayList<>();
       private String buildVersion = "";
       private String userAgentName = "";
@@ -326,6 +327,7 @@ List<Address> getListeningAddresses() {
       return listeningAddresses;
     }
 
+    @SuppressWarnings("deprecation")
     @VisibleForTesting
     public io.envoyproxy.envoy.config.core.v3.Node toEnvoyProtoNode() {
       io.envoyproxy.envoy.config.core.v3.Node.Builder builder =

xds/src/main/java/io/grpc/xds/XdsClientImpl.java

@@ -462,6 +462,7 @@ private void updateNodeMetadataForListenerRequest(int port) {
       newMetadata.putAll(node.getMetadata());
     }
     newMetadata.put("TRAFFICDIRECTOR_PROXYLESS", "1");
+    // TODO(sanjaypujare): eliminate usage of listening_addresses.
     EnvoyProtoData.Address listeningAddress =
         new EnvoyProtoData.Address("0.0.0.0", port);
     node =

xds/src/test/java/io/grpc/xds/EnvoyProtoDataTest.java

@@ -96,6 +96,7 @@ public void locality_equal() {
         .testEquals();
   }
 
+  @SuppressWarnings("deprecation")
   @Test
   public void convertNode() {
     Node node = Node.newBuilder()

xds/third_party/envoy/import.sh

@@ -18,7 +18,7 @@
 set -e
 BRANCH=master
 # import VERSION from one of the google internal CLs
-VERSION=3dedf1693f45239c670c5ba7598db44ff2e32c2f
+VERSION=fd28e42f31730f5ed6f13f52999692a4885dd312
 GIT_REPO="https://github.com/envoyproxy/envoy.git"
 GIT_BASE_DIR=envoy
 SOURCE_PROTO_BASE_DIR=envoy/api
@@ -130,8 +130,11 @@ envoy/type/matcher/metadata.proto
 envoy/type/matcher/path.proto
 envoy/type/matcher/value.proto
 envoy/type/matcher/number.proto
+envoy/type/matcher/v3/metadata.proto
+envoy/type/matcher/v3/number.proto
 envoy/type/matcher/v3/regex.proto
 envoy/type/matcher/v3/string.proto
+envoy/type/matcher/v3/value.proto
 envoy/type/metadata/v2/metadata.proto
 envoy/type/metadata/v3/metadata.proto
 envoy/type/percent.proto

xds/third_party/envoy/src/main/proto/envoy/api/v2/cluster.proto

@@ -448,7 +448,7 @@ message Cluster {
     // connections to upstream hosts whenever hosts are added or removed from the cluster.
     bool close_connections_on_host_set_change = 6;
 
-    //Common Configuration for all consistent hashing load balancers (MaglevLb, RingHashLb, etc.)
+    // Common Configuration for all consistent hashing load balancers (MaglevLb, RingHashLb, etc.)
     ConsistentHashingLbConfig consistent_hashing_lb_config = 7;
   }
 

xds/third_party/envoy/src/main/proto/envoy/api/v2/route/route_components.proto

@@ -436,7 +436,7 @@ message RouteMatch {
     type.matcher.RegexMatcher safe_regex = 10 [(validate.rules).message = {required: true}];
   }
 
-  // Indicates that prefix/path matching should be case insensitive. The default
+  // Indicates that prefix/path matching should be case sensitive. The default
   // is true.
   google.protobuf.BoolValue case_sensitive = 4;
 

xds/third_party/envoy/src/main/proto/envoy/config/accesslog/v3/accesslog.proto

@@ -4,10 +4,12 @@ package envoy.config.accesslog.v3;
 
 import "envoy/config/core/v3/base.proto";
 import "envoy/config/route/v3/route_components.proto";
+import "envoy/type/matcher/v3/metadata.proto";
 import "envoy/type/v3/percent.proto";
 
 import "google/protobuf/any.proto";
 import "google/protobuf/struct.proto";
+import "google/protobuf/wrappers.proto";
 
 import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
@@ -39,8 +41,8 @@ message AccessLog {
   // Filter which is used to determine if the access log needs to be written.
   AccessLogFilter filter = 2;
 
-  // Custom configuration that depends on the access log being instantiated. Built-in
-  // configurations include:
+  // Custom configuration that depends on the access log being instantiated.
+  // Built-in configurations include:
   //
   // #. "envoy.access_loggers.file": :ref:`FileAccessLog
   //    <envoy_api_msg_extensions.access_loggers.file.v3.FileAccessLog>`
@@ -53,7 +55,7 @@ message AccessLog {
   }
 }
 
-// [#next-free-field: 12]
+// [#next-free-field: 13]
 message AccessLogFilter {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.config.filter.accesslog.v2.AccessLogFilter";
@@ -93,6 +95,9 @@ message AccessLogFilter {
 
     // Extension filter.
     ExtensionFilter extension_filter = 11;
+
+    // Metadata Filter
+    MetadataFilter metadata_filter = 12;
   }
 }
 
@@ -156,25 +161,30 @@ message RuntimeFilter {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.config.filter.accesslog.v2.RuntimeFilter";
 
-  // Runtime key to get an optional overridden numerator for use in the *percent_sampled* field.
-  // If found in runtime, this value will replace the default numerator.
+  // Runtime key to get an optional overridden numerator for use in the
+  // *percent_sampled* field. If found in runtime, this value will replace the
+  // default numerator.
   string runtime_key = 1 [(validate.rules).string = {min_bytes: 1}];
 
-  // The default sampling percentage. If not specified, defaults to 0% with denominator of 100.
+  // The default sampling percentage. If not specified, defaults to 0% with
+  // denominator of 100.
   type.v3.FractionalPercent percent_sampled = 2;
 
   // By default, sampling pivots on the header
-  // :ref:`x-request-id<config_http_conn_man_headers_x-request-id>` being present. If
-  // :ref:`x-request-id<config_http_conn_man_headers_x-request-id>` is present, the filter will
-  // consistently sample across multiple hosts based on the runtime key value and the value
-  // extracted from :ref:`x-request-id<config_http_conn_man_headers_x-request-id>`. If it is
-  // missing, or *use_independent_randomness* is set to true, the filter will randomly sample based
-  // on the runtime key value alone. *use_independent_randomness* can be used for logging kill
-  // switches within complex nested :ref:`AndFilter
+  // :ref:`x-request-id<config_http_conn_man_headers_x-request-id>` being
+  // present. If :ref:`x-request-id<config_http_conn_man_headers_x-request-id>`
+  // is present, the filter will consistently sample across multiple hosts based
+  // on the runtime key value and the value extracted from
+  // :ref:`x-request-id<config_http_conn_man_headers_x-request-id>`. If it is
+  // missing, or *use_independent_randomness* is set to true, the filter will
+  // randomly sample based on the runtime key value alone.
+  // *use_independent_randomness* can be used for logging kill switches within
+  // complex nested :ref:`AndFilter
   // <envoy_api_msg_config.accesslog.v3.AndFilter>` and :ref:`OrFilter
-  // <envoy_api_msg_config.accesslog.v3.OrFilter>` blocks that are easier to reason about
-  // from a probability perspective (i.e., setting to true will cause the filter to behave like
-  // an independent random variable when composed within logical operator filters).
+  // <envoy_api_msg_config.accesslog.v3.OrFilter>` blocks that are easier to
+  // reason about from a probability perspective (i.e., setting to true will
+  // cause the filter to behave like an independent random variable when
+  // composed within logical operator filters).
   bool use_independent_randomness = 3;
 }
 
@@ -203,21 +213,22 @@ message HeaderFilter {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.config.filter.accesslog.v2.HeaderFilter";
 
-  // Only requests with a header which matches the specified HeaderMatcher will pass the filter
-  // check.
+  // Only requests with a header which matches the specified HeaderMatcher will
+  // pass the filter check.
   route.v3.HeaderMatcher header = 1 [(validate.rules).message = {required: true}];
 }
 
 // Filters requests that received responses with an Envoy response flag set.
 // A list of the response flags can be found
-// in the access log formatter :ref:`documentation<config_access_log_format_response_flags>`.
+// in the access log formatter
+// :ref:`documentation<config_access_log_format_response_flags>`.
 message ResponseFlagFilter {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.config.filter.accesslog.v2.ResponseFlagFilter";
 
-  // Only responses with the any of the flags listed in this field will be logged.
-  // This field is optional. If it is not specified, then any response flag will pass
-  // the filter check.
+  // Only responses with the any of the flags listed in this field will be
+  // logged. This field is optional. If it is not specified, then any response
+  // flag will pass the filter check.
   repeated string flags = 1 [(validate.rules).repeated = {
     items {
       string {
@@ -248,8 +259,8 @@ message ResponseFlagFilter {
   }];
 }
 
-// Filters gRPC requests based on their response status. If a gRPC status is not provided, the
-// filter will infer the status from the HTTP status code.
+// Filters gRPC requests based on their response status. If a gRPC status is not
+// provided, the filter will infer the status from the HTTP status code.
 message GrpcStatusFilter {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.config.filter.accesslog.v2.GrpcStatusFilter";
@@ -277,11 +288,32 @@ message GrpcStatusFilter {
   // Logs only responses that have any one of the gRPC statuses in this field.
   repeated Status statuses = 1 [(validate.rules).repeated = {items {enum {defined_only: true}}}];
 
-  // If included and set to true, the filter will instead block all responses with a gRPC status or
-  // inferred gRPC status enumerated in statuses, and allow all other responses.
+  // If included and set to true, the filter will instead block all responses
+  // with a gRPC status or inferred gRPC status enumerated in statuses, and
+  // allow all other responses.
   bool exclude = 2;
 }
 
+// Filters based on matching dynamic metadata.
+// If the matcher path and key correspond to an existing key in dynamic
+// metadata, the request is logged only if the matcher value is equal to the
+// metadata value. If the matcher path and key *do not* correspond to an
+// existing key in dynamic metadata, the request is logged only if
+// match_if_key_not_found is "true" or unset.
+message MetadataFilter {
+  option (udpa.annotations.versioning).previous_message_type =
+      "envoy.config.filter.accesslog.v2.MetadataFilter";
+
+  // Matcher to check metadata for specified value. For example, to match on the
+  // access_log_hint metadata, set the filter to "envoy.common" and the path to
+  // "access_log_hint", and the value to "true".
+  type.matcher.v3.MetadataMatcher matcher = 1;
+
+  // Default result if the key does not exist in dynamic metadata: if unset or
+  // true, then log; if false, then don't log.
+  google.protobuf.BoolValue match_if_key_not_found = 2;
+}
+
 // Extension filter is statically registered at runtime.
 message ExtensionFilter {
   option (udpa.annotations.versioning).previous_message_type =

xds/third_party/envoy/src/main/proto/envoy/config/cluster/v3/cluster.proto

@@ -43,7 +43,7 @@ message ClusterCollection {
 }
 
 // Configuration for a single upstream cluster.
-// [#next-free-field: 50]
+// [#next-free-field: 53]
 message Cluster {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Cluster";
 
@@ -246,6 +246,20 @@ message Cluster {
       // List of keys to match with the weighted cluster metadata.
       repeated string keys = 1;
 
+      // Selects a mode of operation in which each subset has only one host. This mode uses the same rules for
+      // choosing a host, but updating hosts is faster, especially for large numbers of hosts.
+      //
+      // If a match is found to a host, that host will be used regardless of priority levels, unless the host is unhealthy.
+      //
+      // Currently, this mode is only supported if `subset_selectors` has only one entry, and `keys` contains
+      // only one entry.
+      //
+      // When this mode is enabled, configurations that contain more than one host with the same metadata value for the single key in `keys`
+      // will use only one of the hosts with the given key; no requests will be routed to the others. The cluster gauge
+      // :ref:`lb_subsets_single_host_per_subset_duplicate<config_cluster_manager_cluster_stats_subset_lb>` indicates how many duplicates are
+      // present in the current configuration.
+      bool single_host_per_subset = 4;
+
       // The behavior used when no endpoint subset matches the selected route's
       // metadata.
       LbSubsetSelectorFallbackPolicy fallback_policy = 2
@@ -396,6 +410,16 @@ message Cluster {
     google.protobuf.UInt64Value maximum_ring_size = 4 [(validate.rules).uint64 = {lte: 8388608}];
   }
 
+  // Specific configuration for the :ref:`Maglev<arch_overview_load_balancing_types_maglev>`
+  // load balancing policy.
+  message MaglevLbConfig {
+    // The table size for Maglev hashing. The Maglev aims for ‘minimal disruption’ rather than an absolute guarantee.
+    // Minimal disruption means that when the set of upstreams changes, a connection will likely be sent to the same
+    // upstream as it was before. Increasing the table size reduces the amount of disruption.
+    // The table size must be prime number. If it is not specified, the default is 65537.
+    google.protobuf.UInt64Value table_size = 1;
+  }
+
   // Specific configuration for the
   // :ref:`Original Destination <arch_overview_load_balancing_types_original_destination>`
   // load balancing policy.
@@ -462,6 +486,26 @@ message Cluster {
       // If set to `true`, the cluster will use hostname instead of the resolved
       // address as the key to consistently hash to an upstream host. Only valid for StrictDNS clusters with hostnames which resolve to a single IP address.
       bool use_hostname_for_hashing = 1;
+
+      // Configures percentage of average cluster load to bound per upstream host. For example, with a value of 150
+      // no upstream host will get a load more than 1.5 times the average load of all the hosts in the cluster.
+      // If not specified, the load is not bounded for any upstream host. Typical value for this parameter is between 120 and 200.
+      // Minimum is 100.
+      //
+      // Applies to both Ring Hash and Maglev load balancers.
+      //
+      // This is implemented based on the method described in the paper https://arxiv.org/abs/1608.01350. For the specified
+      // `hash_balance_factor`, requests to any upstream host are capped at `hash_balance_factor/100` times the average number of requests
+      // across the cluster. When a request arrives for an upstream host that is currently serving at its max capacity, linear probing
+      // is used to identify an eligible host. Further, the linear probe is implemented using a random jump in hosts ring/table to identify
+      // the eligible host (this technique is as described in the paper https://arxiv.org/abs/1908.08762 - the random jump avoids the
+      // cascading overflow effect when choosing the next host in the ring/table).
+      //
+      // If weights are specified on the hosts, they are respected.
+      //
+      // This is an O(N) algorithm, unlike other load balancers. Using a lower `hash_balance_factor` results in more hosts
+      // being probed, so use a higher value if you require better performance.
+      google.protobuf.UInt32Value hash_balance_factor = 2 [(validate.rules).uint32 = {gte: 100}];
     }
 
     // Configures the :ref:`healthy panic threshold <arch_overview_load_balancing_panic_threshold>`.
@@ -519,7 +563,7 @@ message Cluster {
     // connections to upstream hosts whenever hosts are added or removed from the cluster.
     bool close_connections_on_host_set_change = 6;
 
-    //Common Configuration for all consistent hashing load balancers (MaglevLb, RingHashLb, etc.)
+    // Common Configuration for all consistent hashing load balancers (MaglevLb, RingHashLb, etc.)
     ConsistentHashingLbConfig consistent_hashing_lb_config = 7;
   }
 
@@ -541,6 +585,36 @@ message Cluster {
     google.protobuf.Duration max_interval = 2 [(validate.rules).duration = {gt {nanos: 1000000}}];
   }
 
+  // [#not-implemented-hide:]
+  message PrefetchPolicy {
+    // Indicates how many streams (rounded up) can be anticipated per-upstream for each
+    // incoming stream. This is useful for high-QPS or latency-sensitive services. Prefetching
+    // will only be done if the upstream is healthy.
+    //
+    // For example if this is 2, for an incoming HTTP/1.1 stream, 2 connections will be
+    // established, one for the new incoming stream, and one for a presumed follow-up stream. For
+    // HTTP/2, only one connection would be established by default as one connection can
+    // serve both the original and presumed follow-up stream.
+    //
+    // In steady state for non-multiplexed connections a value of 1.5 would mean if there were 100
+    // active streams, there would be 100 connections in use, and 50 connections prefetched.
+    // This might be a useful value for something like short lived single-use connections,
+    // for example proxying HTTP/1.1 if keep-alive were false and each stream resulted in connection
+    // termination. It would likely be overkill for long lived connections, such as TCP proxying SMTP
+    // or regular HTTP/1.1 with keep-alive. For long lived traffic, a value of 1.05 would be more
+    // reasonable, where for every 100 connections, 5 prefetched connections would be in the queue
+    // in case of unexpected disconnects where the connection could not be reused.
+    //
+    // If this value is not set, or set explicitly to one, Envoy will fetch as many connections
+    // as needed to serve streams in flight. This means in steady state if a connection is torn down,
+    // a subsequent streams will pay an upstream-rtt latency penalty waiting for streams to be
+    // prefetched.
+    //
+    // This is limited somewhat arbitrarily to 3 because prefetching connections too aggressively can
+    // harm latency more than the prefetching helps.
+    google.protobuf.DoubleValue prefetch_ratio = 1 [(validate.rules).double = {lte: 3.0 gte: 1.0}];
+  }
+
   reserved 12, 15, 7, 11, 35;
 
   reserved "hosts", "tls_context", "extension_protocol_options";
@@ -766,15 +840,19 @@ message Cluster {
 
   // Optional configuration for the load balancing algorithm selected by
   // LbPolicy. Currently only
-  // :ref:`RING_HASH<envoy_api_enum_value_config.cluster.v3.Cluster.LbPolicy.RING_HASH>` and
+  // :ref:`RING_HASH<envoy_api_enum_value_config.cluster.v3.Cluster.LbPolicy.RING_HASH>`,
+  // :ref:`MAGLEV<envoy_api_enum_value_config.cluster.v3.Cluster.LbPolicy.MAGLEV>` and
   // :ref:`LEAST_REQUEST<envoy_api_enum_value_config.cluster.v3.Cluster.LbPolicy.LEAST_REQUEST>`
   // has additional configuration options.
-  // Specifying ring_hash_lb_config or least_request_lb_config without setting the corresponding
+  // Specifying ring_hash_lb_config or maglev_lb_config or least_request_lb_config without setting the corresponding
   // LbPolicy will generate an error at runtime.
   oneof lb_config {
     // Optional configuration for the Ring Hash load balancing policy.
     RingHashLbConfig ring_hash_lb_config = 23;
 
+    // Optional configuration for the Maglev load balancing policy.
+    MaglevLbConfig maglev_lb_config = 52;
+
     // Optional configuration for the Original Destination load balancing policy.
     OriginalDstLbConfig original_dst_lb_config = 34;
 
@@ -884,6 +962,14 @@ message Cluster {
 
   // Configuration to track optional cluster stats.
   TrackClusterStats track_cluster_stats = 49;
+
+  // [#not-implemented-hide:]
+  // Prefetch configuration for this cluster.
+  PrefetchPolicy prefetch_policy = 50;
+
+  // If `connection_pool_per_downstream_connection` is true, the cluster will use a separate
+  // connection pool for every downstream connection
+  bool connection_pool_per_downstream_connection = 51;
 }
 
 // [#not-implemented-hide:] Extensible load balancing policy configuration.