Rework hash-based routing page

Author: b1tamara

hash-based-routing.html.md.erb

@@ -7,15 +7,22 @@ owner: CF for VMs Networking
 
 Hash-Based Routing is a load-balancing algorithm that distributes incoming requests to application instances based on a hash of a specific HTTP header value,  e.g., `X-Resource-ID` or `Tenant-ID`. This ensures consistent routing behavior where requests containing the same header value are always directed to the same instance.
 
+## <a id="prerequisites"></a> Prerequisites
+
+To use Hash-Based Routing, ensure that
+
+- your <%= vars.app_runtime_abbr %> deployment is running version <%= vars.hash_routing_version %> or later.
+- platform operators activate the feature so that the CF feature flag `hash_based_routing` is set to `true`. See [Feature Flags](https://docs.cloudfoundry.org/adminguide/listing-feature-flags.html#flags) for more details.
+
 ## <a id="key-features"></a> Key Features
 
 - **Configurable via Per-Route Options**: Hash-Based load-balancing setup through application route options
 - **Configurable Hash Header**: The HTTP header to consider for Hash-Based Routing is configurable for each route
 - **Session Affinity Precedence**: Session affinity (sticky sessions) is prioritized over Hash-Based Routing
 - **No availability zones preference**: The global properties `locallyOptimistic` and `localAvailabilityZone` are ignored when using Hash-Based Routing
 - **Consistent Hashing**: Implementation of the Maglev Algorithm (see [Maglev: A Fast and Reliable Software Network Load Balancer](https://storage.googleapis.com/gweb-research2023-media/pubtools/2904.pdf) for details)
-- **Minimal Rehashing**: Usage of the Maglev lookup table to map application instances by hash ensures that hash positions are shifted to other instances as little as possible when application instances are added or removed
-- **Handling imbalanced loads**: Detection and mitigation of higher request loads on individual instances prevents overloading while keeping instances for a particular hash at a minimum.
+- **Minimal Rehashing**: Usage of the Maglev Algorithm to map application instances by hash ensures that hash positions are shifted to other instances as little as possible when application instances are added or removed
+- **Handling imbalanced loads**: Detection and mitigation of imbalanced load on single instances prevents overloading while keeping instances for a particular hash at a minimum
 
 Hash-Based Routing implements a clear precedence hierarchy:
 
@@ -26,20 +33,18 @@ Hash-Based Routing implements a clear precedence hierarchy:
 
 ## <a id="hash-based-vs-session-affinity"></a> Hash-Based Routing vs. Session Affinity
 
-Using Session Affinity, requests from a particular client are always routed to the same app instance. This allows apps to store session data specific to a user session (see more details in the [Session Affinity](https://docs.cloudfoundry.org/concepts/http-routing.html#-session-affinity) documentation).
-
-While Session Affinity offers a solution for maintaining session consistency, it poses scalability challenges, as Session Affinity is confined to a single instance. It increases the risk that large customers could be routed to the same instance by chance. On the other hand, enabling Session Affinity requires additional implementation effort on the application side to return a sticky session cookie in responses.
+While Session Affinity provides a way to keep session consistency, it works at the session level and can cause scalability issues. Heavy users might be routed to the same instance and stay pinned to it through session affinity, which could lead to overload. Session Affinity usually depends on session cookies (see more details in the [Session Affinity](https://docs.cloudfoundry.org/concepts/http-routing.html#-session-affinity) documentation), which requires implementation effort for web applications.
 
-In contrast, Hash-Based Routing provides a more scalable and balanced approach by consistently distributing requests based on a hash of a specific HTTP header value. This hash value determines the appropriate application instance for each request, ensuring that requests with the same hash are consistently routed to the same instance, but might be routed to another predetermined instance when the current one is saturated (find more about Handling imbalanced loads below). In contrast to Session Affinity, no code change is required.
+In contrast, Hash-Based Routing offers a more scalable and flexible approach by consistently distributing requests based on a hash of any configurable HTTP header value, not just session identifiers. This allows for load distribution based on tenant IDs, resource IDs, or other business-relevant identifiers. Configurable load imbalance handling enables spillover to other instances (see [Handling imbalanced loads](#handling-imbalance-loads)).
 
-This makes Hash-Based Routing particularly suitable for applications that demand high scalability and performance, such as microservices architectures or multi-tenant applications, especially when dealing with limited or memory-intensive backend resources.
+Unlike Session Affinity, Hash-Based Routing requires no code changes to the application.
 
 ## <a id="handling-imbalance-loads"></a> Handling imbalanced loads
 
 Hash-Based Routing includes mechanisms to detect imbalanced load across application instances. An imbalanced load occurs when certain hashes receive more traffic, such as when a specific tenant generates many requests, resulting in heavier use of their mapped instances than others’. Additionally, multiple high-traffic targets might be assigned to the same instance.
 
 To prevent overloading specific instances while others remain underutilized, the acceptable threshold for load imbalance can be configured using the `hash_balance` property.
-This factor determines whether an instance is handling more traffic than its fair share based on the average load across all instances, measured by the number of in-flight requests. For example, with a balance factor of 1.25, no single instance should handle more than 125% of the average number of in-flight requests across all instances managed by the current router. When this threshold is exceeded, the router redirects subsequent requests to other, less-loaded instances.
+This setting determines whether an instance is handling more traffic than its fair share based on the average load across all instances, measured by the number of in-flight requests. For example, with a balance factor of 1.25, no single instance should handle more than 125% of the average number of in-flight requests across all instances managed by the current router. When this threshold is exceeded, the router redirects subsequent requests to other, less-loaded instances.
 Values of the balance factor in the 1.1-2.0 range offer a good balance between even distribution and performance. However, optimal values depend on the application's traffic patterns and load characteristics.
 
 This approach ensures that a minimum number of instances process requests for a particular hash while preventing any single instance from becoming overloaded.