Update ring hash lb docs (#277)

Signed-off-by: Daniel Hochman <danielhochman@users.noreply.github.com>

api/cds.proto

@@ -299,9 +299,11 @@ message Cluster {
     google.protobuf.UInt64Value minimum_ring_size = 1;
 
     message DeprecatedV1 {
-      // Envoy uses xxHash by default in v2. Previously std::hash was used
-      // which can vary based on platform. This field exists for migration
-      // purposes.
+      // Defaults to true, meaning that std::hash is used to hash hosts onto
+      // the ketama ring. std::hash can vary by platform. For this reason,
+      // Envoy will eventually use xxHash by default. This field exists for
+      // migration purposes and will eventually be deprecated. Set it to false
+      // to use xxHash now.
       google.protobuf.BoolValue use_std_hash = 1;
     }
     DeprecatedV1 deprecated_v1 = 2;

docs/root/configuration/cluster_manager/cluster.rst

@@ -11,6 +11,7 @@ Cluster
     "connect_timeout_ms": "...",
     "per_connection_buffer_limit_bytes": "...",
     "lb_type": "...",
+    "ring_hash_lb_config": "{...}",
     "hosts": [],
     "service_name": "...",
     "health_check": "{...}",
@@ -61,6 +62,10 @@ lb_type
   :ref:`*original_dst* <arch_overview_service_discovery_types_original_destination>`, and may not be
   used with any other cluster type.
 
+:ref:`ring_hash_lb_config <config_cluster_manager_cluster_ring_hash_lb_config>`
+  *(optional, object)* Optional configuration for the ring hash load balancer, used when *lb_type*
+  is set to *ring_hash*.
+
 hosts
   *(sometimes required, array)* If the service discovery type is *static*, *strict_dns*, or
   *logical_dns* the hosts array is required. Hosts array is not allowed with cluster type
@@ -199,3 +204,4 @@ dns_resolvers
   cluster_stats
   cluster_runtime
   cluster_outlier_detection
+  cluster_ring_hash_lb_config

docs/root/configuration/cluster_manager/cluster_ring_hash_lb_config.rst

@@ -0,0 +1,26 @@
+.. _config_cluster_manager_cluster_ring_hash_lb_config:
+
+Ring hash load balancer configuration
+=====================================
+
+Ring hash load balancing settings are used when the *lb_type* is set to *ring_hash* in the
+:ref:`cluster manager <config_cluster_manager_cluster_lb_type>`.
+
+.. code-block:: json
+
+  {
+    "minimum_ring_size": "...",
+    "use_std_hash": "..."
+  }
+
+minimum_ring_size
+  *(optional, integer)* Minimum hash ring size, i.e. total virtual nodes. A larger size will provide
+  better request distribution since each host in the cluster will have more virtual nodes. Defaults
+  to 1024. In the case that total number of hosts is greater than the minimum, each host will be
+  allocated a single virtual node.
+
+use_std_hash
+  *(optional, boolean)* Defaults to true, meaning that std::hash is used to hash hosts onto the
+  ketama ring. std::hash can vary by platform. For this reason, Envoy will eventually use
+  `xxHash <https://github.com/Cyan4973/xxHash>`_ by default. This field exists for migration
+  purposes and will eventually be deprecated. Set it to false to use xxHash now.

docs/root/configuration/cluster_manager/cluster_runtime.rst

@@ -104,13 +104,6 @@ upstream.weight_enabled
 
 .. _config_cluster_manager_cluster_runtime_ring_hash:
 
-Ring hash load balancing
-------------------------
-
-upstream.ring_hash.min_ring_size
-  The minimum size of the hash ring for the :ref:`ring hash load balancer
-  <arch_overview_load_balancing_types>`. The default is 1024.
-
 .. _config_cluster_manager_cluster_runtime_zone_routing:
 
 Zone aware load balancing