consistent hash: add warnings (#2574)

I have helped on >10 issues from these confusion, so hoping to clear
things up.

Co-authored-by: John Howard <howardjohn@google.com>

networking/v1alpha3/destination_rule.pb.go

@@ -1998,6 +1998,17 @@ func (x *TrafficPolicy_TunnelSettings) GetTargetPort() uint32 {
 // properties. The affinity to a particular destination host may be
 // lost when one or more hosts are added/removed from the destination
 // service.
+//
+// Note: consistent hashing is less reliable at maintaining affinity than common
+// "sticky sessions" implementations, which often encode a specific destination in
+// a cookie, ensuring affinity is maintained as long as the backend remains.
+// With consistent hash, the guarantees are weaker; any host addition or removal can
+// break affinity for `1/backends` requests.
+//
+// Warning: consistent hashing depends on each proxy having a consistent view of endpoints.
+// This is not the case when locality load balancing is enabled. Locality load balancing
+// and consistent hash will only work together when all proxies are in the same locality,
+// or a high level load balancer handles locality affinity.
 type LoadBalancerSettings_ConsistentHashLB struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache

networking/v1alpha3/destination_rule.pb.html

@@ -1409,6 +1409,15 @@ session affinity based on HTTP headers, cookies or other
 properties. The affinity to a particular destination host may be
 lost when one or more hosts are added/removed from the destination
 service.</p>
+<p>Note: consistent hashing is less reliable at maintaining affinity than common
+&ldquo;sticky sessions&rdquo; implementations, which often encode a specific destination in
+a cookie, ensuring affinity is maintained as long as the backend remains.
+With consistent hash, the guarantees are weaker; any host addition or removal can
+break affinity for <code>1/backends</code> requests.</p>
+<p>Warning: consistent hashing depends on each proxy having a consistent view of endpoints.
+This is not the case when locality load balancing is enabled. Locality load balancing
+and consistent hash will only work together when all proxies are in the same locality,
+or a high level load balancer handles locality affinity.</p>
 
 <table class="message-fields">
 <thead>

networking/v1alpha3/destination_rule.proto

@@ -562,6 +562,17 @@ message LoadBalancerSettings {
   // properties. The affinity to a particular destination host may be
   // lost when one or more hosts are added/removed from the destination
   // service.
+  //
+  // Note: consistent hashing is less reliable at maintaining affinity than common
+  // "sticky sessions" implementations, which often encode a specific destination in
+  // a cookie, ensuring affinity is maintained as long as the backend remains.
+  // With consistent hash, the guarantees are weaker; any host addition or removal can
+  // break affinity for `1/backends` requests.
+  //
+  // Warning: consistent hashing depends on each proxy having a consistent view of endpoints.
+  // This is not the case when locality load balancing is enabled. Locality load balancing
+  // and consistent hash will only work together when all proxies are in the same locality,
+  // or a high level load balancer handles locality affinity.
   message ConsistentHashLB {
 
     message RingHash {

networking/v1beta1/destination_rule.pb.go

@@ -1947,6 +1947,17 @@ func (x *TrafficPolicy_TunnelSettings) GetTargetPort() uint32 {
 // properties. The affinity to a particular destination host may be
 // lost when one or more hosts are added/removed from the destination
 // service.
+//
+// Note: consistent hashing is less reliable at maintaining affinity than common
+// "sticky sessions" implementations, which often encode a specific destination in
+// a cookie, ensuring affinity is maintained as long as the backend remains.
+// With consistent hash, the guarantees are weaker; any host addition or removal can
+// break affinity for `1/backends` requests.
+//
+// Warning: consistent hashing depends on each proxy having a consistent view of endpoints.
+// This is not the case when locality load balancing is enabled. Locality load balancing
+// and consistent hash will only work together when all proxies are in the same locality,
+// or a high level load balancer handles locality affinity.
 type LoadBalancerSettings_ConsistentHashLB struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache

networking/v1beta1/destination_rule.proto

@@ -511,6 +511,17 @@ message LoadBalancerSettings {
   // properties. The affinity to a particular destination host may be
   // lost when one or more hosts are added/removed from the destination
   // service.
+  //
+  // Note: consistent hashing is less reliable at maintaining affinity than common
+  // "sticky sessions" implementations, which often encode a specific destination in
+  // a cookie, ensuring affinity is maintained as long as the backend remains.
+  // With consistent hash, the guarantees are weaker; any host addition or removal can
+  // break affinity for `1/backends` requests.
+  //
+  // Warning: consistent hashing depends on each proxy having a consistent view of endpoints.
+  // This is not the case when locality load balancing is enabled. Locality load balancing
+  // and consistent hash will only work together when all proxies are in the same locality,
+  // or a high level load balancer handles locality affinity.
   message ConsistentHashLB {
 
     message RingHash {