route match: Add runtime_fraction field for more granular routing

api/envoy/api/v2/route/BUILD

@@ -9,6 +9,7 @@ api_proto_library_internal(
     deps = [
         "//envoy/api/v2/core:base",
         "//envoy/type:range",
+        "//envoy/type:runtime_percent",
     ],
 )
 
@@ -18,5 +19,6 @@ api_go_proto_library(
     deps = [
         "//envoy/api/v2/core:base_go_proto",
         "//envoy/type:range_go_proto",
+        "//envoy/type:runtime_percent",
     ],
 )

api/envoy/api/v2/route/route.proto

@@ -6,6 +6,7 @@ option java_generic_services = true;
 
 import "envoy/api/v2/core/base.proto";
 import "envoy/type/range.proto";
+import "envoy/type/runtime_percent.proto";
 
 import "google/protobuf/duration.proto";
 import "google/protobuf/struct.proto";
@@ -283,7 +284,14 @@ message RouteMatch {
   // 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;
+  //
+  // .. attention::
+  //
+  //   **This field is deprecated**. Set the
+  //   :ref:`runtime_fraction<envoy_api_field_route.RouteMatch.runtime_fraction>` field instead.
+  //   This field is ignored if
+  //   :ref:`runtime_fraction<envoy_api_field_route.RouteMatch.runtime_fraction>` is set.
+  core.RuntimeUInt32 runtime = 5 [deprecated = true];
 
   // 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
@@ -298,6 +306,16 @@ message RouteMatch {
   // query parameters is nonzero, they all must match the *path* header's
   // query string for a match to occur.
   repeated QueryParameterMatcher query_parameters = 7;
+
+  // 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.
+  envoy.type.RuntimeFractionalPercent runtime_fraction = 8;
 }
 
 // [#comment:next free field: 9]

api/envoy/type/BUILD

@@ -13,6 +13,18 @@ api_go_proto_library(
     proto = ":http_status",
 )
 
+api_proto_library_internal(
+    name = "runtime_percent",
+    srcs = ["runtime_percent.proto"],
+    visibility = ["//visibility:public"],
+    deps = [":percent"],
+)
+
+api_go_proto_library(
+    name = "runtime_percent",
+    proto = ":runtime_percent",
+)
+
 api_proto_library_internal(
     name = "percent",
     srcs = ["percent.proto"],

api/envoy/type/runtime_percent.proto

@@ -0,0 +1,27 @@
+syntax = "proto3";
+
+package envoy.type;
+
+import "validate/validate.proto";
+import "gogoproto/gogo.proto";
+
+import "envoy/type/percent.proto";
+
+option (gogoproto.equal_all) = true;
+
+// [#protodoc-title: RuntimePercent]
+
+// 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 to get numerator value for comparison. This value is used if defined.
+  string numerator_key = 2;
+
+  // Runtime key to get denominator type for comparison. This value is used if defined. Valid field
+  // value strings must match valid :ref:`denominator
+  // types<envoy_api_enum_type.FractionalPercent.DenominatorType>`.
+  string denominator_key = 3;
+}

docs/build.sh

@@ -114,6 +114,7 @@ PROTO_RST="
   /envoy/service/auth/v2alpha/external_auth/envoy/service/auth/v2alpha/external_auth.proto.rst
   /envoy/type/http_status/envoy/type/http_status.proto.rst
   /envoy/type/percent/envoy/type/percent.proto.rst
+  /envoy/type/runtime_percent/envoy/type/runtime_percent.proto.rst
   /envoy/type/range/envoy/type/range.proto.rst
   /envoy/type/matcher/metadata/envoy/type/matcher/metadata.proto.rst
   /envoy/type/matcher/value/envoy/type/matcher/value.proto.rst

docs/root/api-v2/types/types.rst

@@ -7,6 +7,7 @@ Types
 
   ../type/http_status.proto
   ../type/percent.proto
+  ../type/runtime_percent.proto
   ../type/range.proto
   ../type/matcher/metadata.proto
   ../type/matcher/number.proto

source/common/access_log/access_log_impl.cc

@@ -113,14 +113,15 @@ bool RuntimeFilter::evaluate(const RequestInfo::RequestInfo&,
   const Http::HeaderEntry* uuid = request_header.RequestId();
   uint64_t random_value;
   if (use_independent_randomness_ || uuid == nullptr ||
-      !UuidUtils::uuidModBy(uuid->value().c_str(), random_value,
-                            ProtobufPercentHelper::fractionalPercentDenominatorToInt(percent_))) {
+      !UuidUtils::uuidModBy(
+          uuid->value().c_str(), random_value,
+          ProtobufPercentHelper::fractionalPercentDenominatorToInt(percent_.denominator()))) {
     random_value = random_.random();
   }
 
   return runtime_.snapshot().featureEnabled(
       runtime_key_, percent_.numerator(), random_value,
-      ProtobufPercentHelper::fractionalPercentDenominatorToInt(percent_));
+      ProtobufPercentHelper::fractionalPercentDenominatorToInt(percent_.denominator()));
 }
 
 OperatorFilter::OperatorFilter(const Protobuf::RepeatedPtrField<

source/common/protobuf/utility.cc

@@ -20,8 +20,9 @@ uint64_t convertPercent(double percent, uint64_t max_value) {
   return max_value * (percent / 100.0);
 }
 
-uint64_t fractionalPercentDenominatorToInt(const envoy::type::FractionalPercent& percent) {
-  switch (percent.denominator()) {
+uint64_t fractionalPercentDenominatorToInt(
+    const envoy::type::FractionalPercent::DenominatorType& denominator) {
+  switch (denominator) {
   case envoy::type::FractionalPercent::HUNDRED:
     return 100;
   case envoy::type::FractionalPercent::TEN_THOUSAND:

source/common/protobuf/utility.h

@@ -68,10 +68,11 @@ uint64_t convertPercent(double percent, uint64_t max_value);
 
 /**
  * Convert a fractional percent denominator enum into an integer.
- * @param percent supplies percent to convert.
+ * @param denominator supplies denominator to convert.
  * @return the converted denominator.
  */
-uint64_t fractionalPercentDenominatorToInt(const envoy::type::FractionalPercent& percent);
+uint64_t fractionalPercentDenominatorToInt(
+    const envoy::type::FractionalPercent::DenominatorType& denominator);
 
 } // namespace ProtobufPercentHelper
 } // namespace Envoy

source/common/router/config_impl.cc

@@ -260,7 +260,7 @@ RouteEntryImplBase::RouteEntryImplBase(const VirtualHostImpl& vhost,
       timeout_(PROTOBUF_GET_MS_OR_DEFAULT(route.route(), timeout, DEFAULT_ROUTE_TIMEOUT_MS)),
       idle_timeout_(PROTOBUF_GET_OPTIONAL_MS(route.route(), idle_timeout)),
       max_grpc_timeout_(PROTOBUF_GET_OPTIONAL_MS(route.route(), max_grpc_timeout)),
-      runtime_(loadRuntimeData(route.match())), loader_(factory_context.runtime()),
+      loader_(factory_context.runtime()), runtime_(loadRuntimeData(route.match())),
       host_redirect_(route.redirect().host_redirect()),
       path_redirect_(route.redirect().path_redirect()),
       https_redirect_(route.redirect().https_redirect()),
@@ -345,8 +345,9 @@ bool RouteEntryImplBase::matchRoute(const Http::HeaderMap& headers, uint64_t ran
   bool matches = true;
 
   if (runtime_) {
-    matches &= loader_.snapshot().featureEnabled(runtime_.value().key_, runtime_.value().default_,
-                                                 random_value);
+    matches &= loader_.snapshot().featureEnabled(runtime_.value().numerator_key_,
+                                                 runtime_.value().numerator_default_, random_value,
+                                                 runtime_.value().denominator_val_);
   }
 
   matches &= Http::HeaderUtility::matchHeaders(headers, config_headers_);
@@ -404,14 +405,33 @@ void RouteEntryImplBase::finalizeResponseHeaders(
 absl::optional<RouteEntryImplBase::RuntimeData>
 RouteEntryImplBase::loadRuntimeData(const envoy::api::v2::route::RouteMatch& route_match) {
   absl::optional<RuntimeData> runtime;
-  if (route_match.has_runtime()) {
-    RuntimeData data;
-    data.key_ = route_match.runtime().runtime_key();
-    data.default_ = route_match.runtime().default_value();
-    runtime = data;
+  RuntimeData data;
+
+  if (route_match.has_runtime_fraction()) {
+    data.numerator_key_ = route_match.runtime_fraction().numerator_key();
+    data.numerator_default_ = route_match.runtime_fraction().default_value().numerator();
+
+    const std::string& denominator_key = route_match.runtime_fraction().denominator_key();
+    const std::string& denominator_data = loader_.snapshot().get(denominator_key);
+    using FractionalPercent = envoy::type::FractionalPercent;
+    FractionalPercent::DenominatorType denominator_type;
+    if (!FractionalPercent::DenominatorType_Parse(denominator_data, &denominator_type)) {
+      denominator_type = route_match.runtime_fraction().default_value().denominator();
+    }
+    data.denominator_val_ =
+        ProtobufPercentHelper::fractionalPercentDenominatorToInt(std::move(denominator_type));
+  } else if (route_match.has_runtime()) {
+    // For backwards compatibility, the deprecated 'runtime' field must be converted to a
+    // RuntimeData format with a variable denominator type. This field assumes a percentage (0-100),
+    // so the hard-coded denominator value reflects this.
+    data.numerator_key_ = route_match.runtime().runtime_key();
+    data.numerator_default_ = route_match.runtime().default_value();
+    data.denominator_val_ = 100;
+  } else {
+    return runtime;
   }
 
-  return runtime;
+  return data;
 }
 
 void RouteEntryImplBase::finalizePathHeader(Http::HeaderMap& headers,

source/common/router/config_impl.h

@@ -362,8 +362,9 @@ class RouteEntryImplBase : public RouteEntry,
 
 private:
   struct RuntimeData {
-    std::string key_{};
-    uint64_t default_{};
+    std::string numerator_key_{};
+    uint64_t numerator_default_{};
+    uint64_t denominator_val_{};
   };
 
   class DynamicRouteEntry : public RouteEntry, public Route {
@@ -494,8 +495,7 @@ class RouteEntryImplBase : public RouteEntry,
 
   typedef std::shared_ptr<WeightedClusterEntry> WeightedClusterEntrySharedPtr;
 
-  static absl::optional<RuntimeData>
-  loadRuntimeData(const envoy::api::v2::route::RouteMatch& route);
+  absl::optional<RuntimeData> loadRuntimeData(const envoy::api::v2::route::RouteMatch& route);
 
   static std::multimap<std::string, std::string>
   parseOpaqueConfig(const envoy::api::v2::route::Route& route);
@@ -516,8 +516,8 @@ class RouteEntryImplBase : public RouteEntry,
   const std::chrono::milliseconds timeout_;
   const absl::optional<std::chrono::milliseconds> idle_timeout_;
   const absl::optional<std::chrono::milliseconds> max_grpc_timeout_;
-  const absl::optional<RuntimeData> runtime_;
   Runtime::Loader& loader_;
+  const absl::optional<RuntimeData> runtime_;
   const std::string host_redirect_;
   const std::string path_redirect_;
   const bool https_redirect_;

source/extensions/filters/http/fault/fault_filter.cc

@@ -134,13 +134,14 @@ bool FaultFilter::isDelayEnabled() {
   bool enabled = config_->runtime().snapshot().featureEnabled(
       DELAY_PERCENT_KEY, fault_settings_->delayPercentage().numerator(),
       config_->randomGenerator().random(),
-      ProtobufPercentHelper::fractionalPercentDenominatorToInt(fault_settings_->delayPercentage()));
+      ProtobufPercentHelper::fractionalPercentDenominatorToInt(
+          fault_settings_->delayPercentage().denominator()));
   if (!downstream_cluster_delay_percent_key_.empty()) {
     enabled |= config_->runtime().snapshot().featureEnabled(
         downstream_cluster_delay_percent_key_, fault_settings_->delayPercentage().numerator(),
         config_->randomGenerator().random(),
         ProtobufPercentHelper::fractionalPercentDenominatorToInt(
-            fault_settings_->delayPercentage()));
+            fault_settings_->delayPercentage().denominator()));
   }
   return enabled;
 }
@@ -149,13 +150,14 @@ bool FaultFilter::isAbortEnabled() {
   bool enabled = config_->runtime().snapshot().featureEnabled(
       ABORT_PERCENT_KEY, fault_settings_->abortPercentage().numerator(),
       config_->randomGenerator().random(),
-      ProtobufPercentHelper::fractionalPercentDenominatorToInt(fault_settings_->abortPercentage()));
+      ProtobufPercentHelper::fractionalPercentDenominatorToInt(
+          fault_settings_->abortPercentage().denominator()));
   if (!downstream_cluster_abort_percent_key_.empty()) {
     enabled |= config_->runtime().snapshot().featureEnabled(
         downstream_cluster_abort_percent_key_, fault_settings_->abortPercentage().numerator(),
         config_->randomGenerator().random(),
         ProtobufPercentHelper::fractionalPercentDenominatorToInt(
-            fault_settings_->abortPercentage()));
+            fault_settings_->abortPercentage().denominator()));
   }
   return enabled;
 }

source/extensions/filters/network/mongo_proxy/proxy.cc

@@ -325,7 +325,7 @@ absl::optional<uint64_t> ProxyFilter::delayDuration() {
                                           fault_config_->delayPercentage().numerator(),
                                           generator_.random(),
                                           ProtobufPercentHelper::fractionalPercentDenominatorToInt(
-                                              fault_config_->delayPercentage()))) {
+                                              fault_config_->delayPercentage().denominator()))) {
     return result;
   }