docs: make WeightedCluster.total_weight visible (#434)

Update documentation to match implementation in envoyproxy/envoy#2440.

Makes the WeightedCluster.total_weight field visible in documentation. Update ClusterWeight.weight and traffic shaping document to match.

Signed-off-by: Stephan Zuercher <stephan@turbinelabs.io>

docs/root/configuration/http_conn_man/traffic_splitting.rst

@@ -135,6 +135,10 @@ to each upstream cluster.
       }
     }
 
+By default, the weights must sum to exactly 100. In the V2 API, the
+:ref:`total weight <envoy_api_field_route.WeightedCluster.total_weight>` defaults to 100, but can
+be modified to allow finer granularity.
+
 The weights assigned to each cluster can be dynamically adjusted using the
 following runtime variables: ``routing.traffic_split.helloworld.helloworld_v1``,
 ``routing.traffic_split.helloworld.helloworld_v2`` and

envoy/api/v2/route/route.proto

@@ -198,9 +198,10 @@ message WeightedCluster {
     // :ref:`cluster manager configuration <config_cluster_manager>`.
     string name = 1 [(validate.rules).string.min_bytes = 1];
 
-    // An integer between 0-100. When a request matches the route, the choice of
+    // An integer between 0 and :ref:`total_weight
-    // an upstream cluster is determined by its weight. The sum of weights
+    // <envoy_api_field_route.WeightedCluster.total_weight>`. When a request matches the route,
-    // across all entries in the clusters array must add up to 100.
+    // the choice of an upstream cluster is determined by its weight. The sum of weights across all
+    // entries in the clusters array must add up to the total_weight, which defaults to 100.
     google.protobuf.UInt32Value weight = 2;
 
     // Optional endpoint metadata match criteria. Only endpoints in the upstream
@@ -212,9 +213,8 @@ message WeightedCluster {
   // Specifies one or more upstream clusters associated with the route.
   repeated ClusterWeight clusters = 1 [(validate.rules).repeated .min_items = 1];
 
-  // [#not-implemented-hide:] Specifies the total weight across all clusters. The sum of all
+  // Specifies the total weight across all clusters. The sum of all cluster weights must equal this
-  // cluster weights must equal this value, which must be greater than 0. Defaults to 100.
+  // value, which must be greater than 0. Defaults to 100.
-  // [#comment:TODO(zuercher): when visible update ClusterWeight.weight and traffic splitting.
   google.protobuf.UInt32Value total_weight = 3 [(validate.rules).uint32.gte = 1];
 
   // Specifies the runtime key prefix that should be used to construct the