remove sequential route blocks from traffic splitting (envoyproxy#445)

docs/configuration/http_conn_man/route_config/route.rst

@@ -49,7 +49,7 @@ cluster
   *path_redirect* is not specified), one of *cluster* or *weighted_clusters* must be specified.
   With the *weighted_clusters* option, multiple upstream clusters can be specified for a given route.
   The request is forwarded to one of the upstream clusters based on weights assigned
-  to each cluster. See :ref:`traffic splitting <config_http_conn_man_route_table_traffic_splitting_split_percentages>`
+  to each cluster. See :ref:`traffic splitting <config_http_conn_man_route_table_traffic_splitting_split>`
   for additional documentation.
 
 .. _config_http_conn_man_route_table_route_host_redirect:

docs/configuration/http_conn_man/route_config/traffic_splitting.rst

@@ -92,18 +92,15 @@ accomplish the task.
 Traffic splitting across multiple upstreams
 -------------------------------------------
 
-Consider the ``helloworld`` example again with three versions (v1, v2 and
-v3). Envoy provides two ways to split traffic evenly across the three
-versions (i.e., ``33%, 33%, 34%``):
-
-.. _config_http_conn_man_route_table_traffic_splitting_split_percentages:
-
-(a) Weight-based cluster selection
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The first option is to use a **single** :ref:`route <config_http_conn_man_route_table_route>` with
-:ref:`weighted_clusters <config_http_conn_man_route_table_route_weighted_clusters>`,
-where multiple upstream cluster targets are specified for a single route,
+Consider the ``helloworld`` example again, now with three versions (v1, v2 and
+v3) instead of two. To split traffic evenly across the three versions
+(i.e., ``33%, 33%, 34%``), the ``weighted_clusters`` option can be used to
+specify the weight for each upstream cluster.
+
+Unlike the previous example, a **single** :ref:`route
+<config_http_conn_man_route_table_route>` entry is sufficient. The
+:ref:`weighted_clusters <config_http_conn_man_route_table_route_weighted_clusters>`
+configuration block in a route can be used to specify multiple upstream clusters
 along with weights that indicate the **percentage** of traffic to be sent
 to each upstream cluster.
 
@@ -137,61 +134,3 @@ 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
 ``routing.traffic_split.helloworld.helloworld_v3``.
-
-.. _config_http_conn_man_route_table_traffic_splitting_split_probabilities:
-
-(b) Probabilistic route selection
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The second option is to use **multiple** :ref:`routes <config_http_conn_man_route_table_route>`
-as shown in the traffic shifting example, with :ref:`runtimes <config_http_conn_man_route_table_route_runtime>`
-that specify the **probability** of selecting a route.
-Since Envoy matches routes with a :ref:`first match <config_http_conn_man_route_table_route_matching>`
-policy, the related routes (one for each upstream cluster) must be placed back-to-back,
-along with a runtime in all but the last route.
-
-.. code-block:: json
-
-    {
-      "route_config": {
-        "virtual_hosts": [
-          {
-            "name": "helloworld",
-            "domains": ["*"],
-            "routes": [
-              {
-                "prefix": "/",
-                "cluster": "helloworld_v1",
-                "runtime": {
-                  "key": "routing.traffic_split.helloworld.helloworld_v1",
-                  "default": 33
-                }
-              },
-              {
-                "prefix": "/",
-                "cluster": "helloworld_v2",
-                "runtime": {
-                  "key": "routing.traffic_split.helloworld.helloworld_v2",
-                  "default": 50
-                }
-              },
-              {
-                "prefix": "/",
-                "cluster": "helloworld_v3",
-              }
-            ]
-          }
-        ]
-      }
-    }
-
-In the configuration above,
-
-1. ``routing.traffic_split.helloworld.helloworld_v1`` is set to ``33``, so that there is a
-   *33\% probability* that the v1 route will be selected by Envoy.
-2. ``routing.traffic_split.helloworld.helloworld_v2`` is set to ``50``, so that if the v1 route
-   is not selected, between v2 and v3, there is a *50\% probability* that the v2 route will
-   be selected by Envoy. If v2 is not selected the traffic falls through to the v3 route.
-
-This distribution of probabilities ensures that the traffic will be split evenly across
-all three routes (i.e. ``33%, 33%, 34%``).

docs/intro/arch_overview/http_routing.rst

@@ -27,10 +27,10 @@ request. The router filter supports the following features:
 * Request timeout specified either via :ref:`HTTP
   header <config_http_filters_router_headers>` or via :ref:`route configuration
   <config_http_conn_man_route_table_route_timeout>`.
-* Probability-based route selection via :ref:`runtime values <config_http_conn_man_route_table_route_runtime>`
-  (see :ref:`traffic shifting/shifting <config_http_conn_man_route_table_traffic_splitting>`).
-* :ref:`Weight/percentage-based <config_http_conn_man_route_table_route_weighted_clusters>` upstream cluster selection
-  for a given route (see :ref:`traffic shifting/splitting <config_http_conn_man_route_table_traffic_splitting_split>`).
+* Traffic shifting from one upstream cluster to another via :ref:`runtime values <config_http_conn_man_route_table_route_runtime>`
+  (see :ref:`traffic shifting/splitting <config_http_conn_man_route_table_traffic_splitting>`).
+* Traffic splitting across multiple upstream clusters using :ref:`weight/percentage-based routing<config_http_conn_man_route_table_route_weighted_clusters>`
+  (see :ref:`traffic shifting/splitting <config_http_conn_man_route_table_traffic_splitting_split>`).
 * Arbitrary headers :ref:`routing rules <config_http_conn_man_route_table_route_headers>`.
 * Virtual cluster specifications. A virtual cluster is specified at the virtual host level and is
   used by Envoy to generate additional statistics on top of the standard cluster level ones. Virtual