route match: Add runtime_fraction field for more granular routing (#4560)

This patch reintroduces PR #4217.

Signed-off-by: Tony Allen <tallen@lyft.com>

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

envoy/api/v2/core/BUILD

@@ -37,11 +37,15 @@ api_proto_library_internal(
     visibility = [
         ":friends",
     ],
+    deps = [
+        "//envoy/type:percent",
+    ],
 )
 
 api_go_proto_library(
     name = "base",
     proto = ":base",
+    deps = ["//envoy/type:percent_go_proto"],
 )
 
 api_proto_library_internal(

envoy/api/v2/core/base.proto

@@ -9,6 +9,8 @@ import "google/protobuf/wrappers.proto";
 import "validate/validate.proto";
 import "gogoproto/gogo.proto";
 
+import "envoy/type/percent.proto";
+
 option (gogoproto.equal_all) = true;
 
 // [#protodoc-title: Common types]
@@ -216,3 +218,13 @@ message SocketOption {
   SocketState state = 6
       [(validate.rules).message.required = true, (validate.rules).enum.defined_only = true];
 }
+
+// Runtime derived FractionalPercent with defaults for when the numerator or denominator is not
+// specified via a runtime key.
+message RuntimeFractionalPercent {
+  // Default value if the runtime value's for the numerator/denominator keys are not available.
+  envoy.type.FractionalPercent default_value = 1 [(validate.rules).message.required = true];
+
+  // Runtime key for a YAML representation of a FractionalPercent.
+  string runtime_key = 2;
+}

envoy/api/v2/route/route.proto

@@ -291,16 +291,33 @@ message RouteMatch {
   // is true.
   google.protobuf.BoolValue case_sensitive = 4;
 
-  // Indicates that the route should additionally match on a runtime key. An
-  // integer between 0-100. Every time the route is considered for a match, a
-  // random number between 0-99 is selected. If the number is <= the value found
-  // in the key (checked first) or, if the key is not present, the default
-  // value, the route is a match (assuming everything also about the route
-  // matches). A runtime route configuration can be used to roll out route changes in a
-  // gradual manner without full code/config deploys. Refer to the
-  // :ref:`traffic shifting <config_http_conn_man_route_table_traffic_splitting_shift>` docs
-  // for additional documentation.
-  core.RuntimeUInt32 runtime = 5;
+  oneof runtime_specifier {
+    // Indicates that the route should additionally match on a runtime key. An integer between
+    // 0-100. Every time the route is considered for a match, a random number between 0-99 is
+    // selected. If the number is <= the value found in the key (checked first) or, if the key is
+    // not present, the default value, the route is a match (assuming everything also about the
+    // route matches). A runtime route configuration can be used to roll out route changes in a
+    // gradual manner without full code/config deploys. Refer to the :ref:`traffic shifting
+    // <config_http_conn_man_route_table_traffic_splitting_shift>` docs for additional
+    // documentation.
+    //
+    // .. attention::
+    //
+    //   **This field is deprecated**. Set the
+    //   :ref:`runtime_fraction<envoy_api_field_route.RouteMatch.runtime_fraction>` field instead.
+    core.RuntimeUInt32 runtime = 5 [deprecated = true];
+
+    // Indicates that the route should additionally match on a runtime key. Every time the route
+    // is considered for a match, it must also fall under the percentage of matches indicated by
+    // this field. For some fraction N/D, a random number in the range [0,D) is selected. If the
+    // number is <= the value of the numberator N, or if the key is not present, the default
+    // value, the router continues to evaluate the remaining match criteria. A runtime_fraction
+    // route configuration can be used to roll out route changes in a gradual manner (with more
+    // granularity than the deprecated runtime field) without full code/config deploys. Refer to
+    // the :ref:`traffic shifting <config_http_conn_man_route_table_traffic_splitting_shift>` docs
+    // for additional documentation.
+    core.RuntimeFractionalPercent runtime_fraction = 9;
+  }
 
   // Specifies a set of headers that the route should match on. The router will
   // check the request’s headers against all the specified headers in the route