Document hash-based routing

custom-per-route-options.html.md.erb

@@ -8,24 +8,26 @@ By default, communication between Gorouter and backends is configured through th
 This topic describes how to specify per-route Gorouter options scoped at the application level.
 This greater granularity lets developers tailor optimal routing behavior for applications' unique load profiles or other requirements.
 
-Gorouter supports the following per-route option, described in the section below:
+Gorouter supports the following per-route options, described in the sections below:
 
 - `loadbalancing`: Configures the load balancing algorithm used by Gorouter for this particular route. <%= vars.per_route_lb_version %>
-   - Settings: `round-robin`, `least-connection`.
+   - Settings: `round-robin`, `least-connection`, `hash`.
+- `hash_header`: Defines the HTTP header used for hash-based routing decisions. Required when `loadbalancing` is set to `hash`. Cannot be used with other load balancing algorithms. <%= vars.hash_routing_version %>
+- `hash_balance`: Sets the float number for the balance factor used by Gorouter to manage load imbalance applying the hash-based routing for this route. Optional when `loadbalancing` is `hash`. Cannot be used with other algorithms. <%= vars.hash_routing_version %>
 
 ## <a id="loadbalancing"></a> Configure Gorouter's Load Balancing Algorithm
 
 <%= vars.per_route_lb_version %>
 
 The per-route option `loadbalancing` allows configuring the load balancing algorithm, which defines how the load is distributed between Gorouters and backends.
 
-This option supports two settings for load balancing:
+This option supports the following settings for load balancing:
 
 - `round-robin` distributes the load evenly across all available backends
 - `least-connection` directs traffic to the backend with the fewest active connections at any given time, optimizing resource utilization
+- `hash` distributes requests based on a specific HTTP header value, ensuring requests with the same header value are consistently directed to the same backend. See [Hash-Based Routing](hash-based-routing.html) for details. <%= vars.hash_routing_version %>
 
-
-### <a id="lb-set-manifest"></a> Configure Load Balancing in an App Manifest
+### <a id="lb-set-manifest"></a> Configure Load Balancing using an App Manifest
 
 To configure per-route load balancing for an application that has not yet been pushed:
 
@@ -49,91 +51,74 @@ To configure per-route load balancing for an application that has not yet been p
     cf push -f manifest.yml
     ```
 
-### <a id="lb-update-route"></a> Change Load Balancing Algorithm of an Existing Route
-
-To change the per-route `loadbalancing` option of an existing route, you can use the cli command, `update-route`.
+### <a id="lb-create-route"></a> Create a Route with a Specific Load Balancing Algorithm Using the CF CLI
 
-For example, to change an app route's algorithm from `least-connection` to `round-robin`, you can run the `update-route` command:
+To create a route with a per-route `loadbalancing` option, you can use the CLI command `create-route`.
+For example:
 
 ```console
-cf update-route EXAMPLE.COM --hostname MY-HOST --option loadbalancing=round-robin
+cf create-route EXAMPLE.COM --hostname MY-HOST --option loadbalancing=round-robin
 ```
 
-Alternatively, it is also possible to update the per-route load balancing option via the `/v3/routes` API.
+### <a id="lb-map-route"></a> Map a Route to an Existing App with a Specific Load Balancing Algorithm Using the CF CLI
 
-Run the `PATCH` request to the targeted API endpoint:
+To create and map a new route to an existing application with the per-route `loadbalancing` option, you can use the CLI command `map-route`.
+
+For example:
 
 ```console
-cf curl /v3/routes/GUID -X PATCH -H "Content-type: application/json" \
-  -d '{
-    "options": {
-      "loadbalancing": "round-robin"
-    }
-  }'
+cf map-route MY-APP EXAMPLE.COM --hostname MY-HOST --option loadbalancing=round-robin
 ```
-Where `GUID` is the unique identifier for the route.
 
-### <a id="lb-create-route"></a> Create a Route with a specific Load Balancing Algorithm
+<p class="note">
+The command <code>map-route</code> supports the <code>--option</code> flag only for new routes.
+To update an existing route, use the command <code>update-route</code> described below.</p>
 
-To create a route with a per-route `loadbalancing` option, you can use the cli command `create-route`.
-For example:
+
+### <a id="lb-update-route"></a> Update the Load Balancing Algorithm of an Existing Route Using the CF CLI
+
+To change the per-route `loadbalancing` option of an existing route, you can use the CLI command `update-route`.
+
+For example, to change an app route's algorithm from `least-connection` to `round-robin`, you can run the `update-route` command:
 
 ```console
-cf create-route EXAMPLE.COM --hostname MY-HOST --option loadbalancing=round-robin
+cf update-route EXAMPLE.COM --hostname MY-HOST --option loadbalancing=round-robin
 ```
 
-Alternatively, it is also possible to create a route with a per-route load balancing option via the `/v3/routes` API:
+### <a id="lb-remove-route-option"></a> Remove the Specific Load Balancing Algorithm Using the CF CLI
+
+To remove the `loadbalancing` option from an existing route, run:
 
 ```console
-cf curl /v3/routes -X POST -H "Content-type: application/json" \
-  -d '{
-    "host": "MY-HOST",
-    "path": "MY-PATH",
-    ...
-    "options": {
-      "loadbalancing": "round-robin"
-    }
-  }'
+cf update-route EXAMPLE.COM --hostname MY-HOST -r loadbalancing
 ```
 
-### <a id="lb-map-route"></a> Map a Route to an Existing App with specific Load Balancing Algorithm
+## <a id="hash-based-routing"></a> Configure Hash-Based Routing
 
-To create and map a new route to an existing application with the per-route `loadbalancing` option, you can use the cli command `map-route`.
+<%= vars.hash_routing_version %>
 
-For example:
+Hash-Based Routing is a load-balancing method that routes incoming requests to application instances based on a specific HTTP header value. This ensures consistent routing, so requests with the same header value are always routed to the same instance.
 
-```console
-cf map-route MY-APP EXAMPLE.COM --hostname MY-HOST --option loadbalancing=round-robin
-```
+For details on Hash-Based Routing concepts, features, and how it compares to Session Affinity, see [Hash-Based Routing](hash-based-routing.html).
 
-<p class="note">
-The command <code>map-route</code> supports the <code>--option</code> flag only for new routes.
-To update an existing route, the command <code>update-route</code> must be used as described before.</p>
+For instructions on configuring hash-based routing using the app manifest or the CF CLI, see [Configure Hash-Based Routing](hash-based-routing.html#configure).
 
-### <a id="lb-retrieve-route-options"></a> Retrieve Route Options
+## <a id="lb-retrieve-route-options"></a> Retrieve Route Options
 
-To read route options, you can query the route using the `route` command:
+To view route options, you can query the route using the `route` command:
 
 ```console
 cf route EXAMPLE.COM --hostname MY-HOST
 ```
 
-  The response lists the chosen `loadbalancing` algorithm option, e.g. `least-connection`:
+The response lists the chosen `loadbalancing` algorithm option, e.g. `least-connection`:
 
 ```console
 options: {loadbalancing=least-connection}
 ```
 
-  Alternatively, you can query the `routes` API endpoint for a route:
+Or `hash` with its related options:
 
 ```console
-cf curl /v3/routes/?hosts=MY-HOST
+options:    {hash_balance=1.2, hash_header=HASH-HEADER-NAME, loadbalancing=hash}
 ```
-
-Where `MY-HOST` is the host attribute of the route. The response lists the chosen `loadbalancing` algorithm option as well:
-
-```console
-    "options": {"loadbalancing": "least-connection"}
-```
-
-To retrieve all the routes with the corresponding options in a space of an organization, you can use the `routes` command.

deploy-apps/manifest-attributes.html.md.erb

@@ -583,7 +583,9 @@ Under each route, you can optionally include an `options` attribute to configure
 
 Available options are:
 
-- `loadbalancing` - defines how Gorouter distributes requests across the application backends. Valid values are `round-robin` and `least-connection`.
+- `loadbalancing` - defines how Gorouter distributes requests across the application backends. Valid values are `round-robin`, `least-connection` and `hash`.
+- `hash_header` - defines the HTTP header used for hash-based routing decisions. Required when `loadbalancing` is set to `hash`.
+- `hash_balance` - defines the balance factor used to manage load imbalance for hash-based routing. Optional when `loadbalancing` is set to `hash`. Values in the 1.1-2.0 range provide the best balance of even distribution and performance. Omitting `hash_balance` or setting it explicitly to 0 indicates that the load situation will not be considered.
 
 For example:
 
@@ -597,6 +599,11 @@ For example:
   - route: example2.com
     options:
       loadbalancing: least-connection
+  - route: example3.com
+    options:
+      loadbalancing: hash
+      hash_header: Hash-Relevant-Header
+      hash_balance: 1.25
 ```
 
 #### <a id='manifest-attibutes-2'></a> Manifest attributes

hash-based-routing.html.md.erb

@@ -0,0 +1,160 @@
+---
+title: Hash-Based Routing
+owner: CF for VMs Networking
+---
+
+## <a id="purpose"></a> Purpose
+
+Hash-Based Routing is a load-balancing algorithm that distributes incoming requests to application instances based on the value of a configured HTTP header. Typically, this is a header that identifies a user, resource, or tenant, such as `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 meets the minimum version requirements. <%= vars.hash_routing_version %>
+- 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
+
+- **Consistent Hashing**: Uses the Maglev Algorithm to determine instance assignments (see [Maglev: A Fast and Reliable Software Network Load Balancer](https://storage.googleapis.com/gweb-research2023-media/pubtools/2904.pdf) for details)
+- **Minimal Rehashing**: The Maglev Algorithm ensures that the mapping of header values to application instances remains as consistent as possible when instances are added or removed
+- **Configurable Hash Header**: The HTTP header used for Hash-Based Routing is configurable for each route
+- **Configurable via Per-Route Options**: Hash-Based load balancing is set up through [per-route options](custom-per-route-options.html)
+- **Handling imbalanced loads**: Detection and mitigation of imbalanced load on single instances prevents overloading while keeping the number of instances for a particular hash at a minimum
+- **Session Affinity Precedence**: Session Affinity (sticky sessions) is prioritized over Hash-Based Routing
+- **No availability zone preference**: The global properties `locallyOptimistic` and `localAvailabilityZone` are ignored when using Hash-Based Routing
+
+Hash-Based Routing implements the following precedence hierarchy:
+
+1. **Session Affinity**: If a sticky session cookie is present and the target instance is available, the request is routed to that instance
+2. **Hash-Based Routing**: If a hash header is configured for the route and present in the request, Gorouter routes to the instance determined by the header value's hash
+3. **Default Load Balancing**: If the hash header is absent from the request, Gorouter falls back to the platform's default load balancing algorithm
+
+## <a id="configure"></a> Configure Hash-Based Routing
+
+<%= vars.hash_routing_version %>
+
+The per-route hash options offer detailed control over hash-based load balancing for individual routes. For a full list of per-route options, see [Configuring per-route options](custom-per-route-options.html).
+
+### <a id="options-hash-set-manifest"></a> Configure Hash-Based Routing with an App Manifest
+
+1. In the application manifest, include a `route` definition with the following `options` attributes:
+   - `loadbalancing` set to `hash`
+   - `hash_header` set to the HTTP header name used for routing decisions
+   - optionally, `hash_balance` set to a float number for the balance factor used by Gorouter to [manage load imbalance](#handling-imbalance-loads) for this particular route.
+
+   	```yaml
+   	---
+   	applications:
+   	- name: MY-APP
+   	  routes:
+   	    - route: MY-HOST.EXAMPLE.COM
+   	      options:
+   	        loadbalancing: hash
+   	        hash_header: HASH-HEADER-NAME
+   	        hash_balance: 1.2
+   	```
+
+    Where `MY-APP` is the name of your app, `MY-HOST.EXAMPLE.COM` is the route you want to map to your app and `HASH-HEADER-NAME` is the HTTP header name.
+
+1. Push the app with the manifest:
+
+    ```console
+    cf push -f manifest.yml
+    ```
+
+### <a id="options-hash-create-route"></a> Create a Route with Hash-Based Options Using the CF CLI
+
+To create a route with hash-specific options, you can use the CLI command `create-route`. For example:
+
+```console
+cf create-route EXAMPLE.COM --hostname MY-HOST --option loadbalancing=hash --option hash_header=HASH-HEADER-NAME --option hash_balance=1.2
+```
+
+Alternatively, you can use the shorthand `-o` for `--option`. Since `hash_balance` is optional, you can omit it:
+
+```console
+cf create-route EXAMPLE.COM --hostname MY-HOST -o loadbalancing=hash -o hash_header=HASH-HEADER-NAME
+```
+
+### <a id="options-hash-map-route"></a> Map a Route with Hash Options to an Existing App Using the CF CLI
+
+To create a new route suitable for hash-based routing and map it to an existing application, you can use the CLI command `map-route`.
+
+For example:
+
+```console
+cf map-route MY-APP EXAMPLE.COM --hostname MY-HOST -o loadbalancing=hash -o hash_header=HASH-HEADER-NAME -o hash_balance=1.2
+```
+
+<p class="note">
+The command <code>map-route</code> supports the <code>--option</code> flag only for new routes.
+To update an existing route, see the instructions for <code>update-route</code> below.</p>
+
+### <a id="options-hash-update-route"></a> Update an Existing Route with Hash Options Using the CF CLI
+
+You can change an existing route that uses the default load balancing algorithm to the hash load balancing algorithm.
+
+For example, to change an app route's algorithm from default `round-robin` to `hash` and set `hash_header` to HASH-HEADER-NAME without a balance factor, you can run the `update-route` command:
+
+```console
+cf update-route EXAMPLE.COM --hostname MY-HOST -o loadbalancing=hash -o hash_header=HASH-HEADER-NAME
+```
+
+To add a balance factor along with the previous settings, you can later run the `update-route` command, for example, with the `hash_balance` option set to `1.5`:
+
+```console
+cf update-route EXAMPLE.COM --hostname MY-HOST -o hash_balance=1.5
+```
+
+To remove the balance factor, run the `update-route` command with the `-r` flag:
+
+```console
+cf update-route EXAMPLE.COM --hostname MY-HOST -r hash_balance
+```
+
+Removing the balance factor indicates to Gorouter that load imbalance is accepted and all requests for a particular hash should be routed to the same instance as long as it is healthy, without redirecting to other predetermined instances.
+
+### <a id="options-hash-revert"></a> Revert Hash Options Using the CF CLI
+
+Running the `update-route` command with the `-r` flag for the option `loadbalancing` removes all hash options from the route, returning to the default load balancing algorithm:
+
+```console
+cf update-route EXAMPLE.COM --hostname MY-HOST -r loadbalancing
+```
+
+### <a id="options-hash-retrieve"></a> Retrieve Hash-Based Route Options
+
+To view route options, you can query the route using the `route` command:
+
+```console
+cf route EXAMPLE.COM --hostname MY-HOST
+```
+
+The response lists the chosen options, for example:
+
+```console
+options:    {hash_balance=1.2, hash_header=HASH-HEADER-NAME, loadbalancing=hash}
+```
+
+## <a id="hash-based-vs-session-affinity"></a> Hash-Based Routing vs. Session Affinity
+
+Session Affinity works at the session level and relies on session cookies (see [Session Affinity](https://docs.cloudfoundry.org/concepts/http-routing.html#-session-affinity) for details). Heavy users can be pinned to a single instance, leading to uneven load distribution. Implementing Session Affinity in web applications requires handling session cookies.
+
+Hash-Based Routing provides a more scalable approach by consistently routing requests based on any configurable HTTP header value, not just session identifiers. This allows distribution based on tenant IDs, resource IDs, or other business-relevant identifiers. When a single instance receives disproportionate load, requests can spill over to other predetermined instances (see [Handling imbalanced loads](#handling-imbalance-loads)). Unlike Session Affinity, Hash-Based Routing requires no code changes to the application.
+
+## <a id="handling-imbalance-loads"></a> Handling imbalanced loads
+
+Imbalanced load can occur when certain header values receive disproportionately more traffic. For example, a particular tenant may generate a large number of requests, resulting in heavier use of the instance assigned to that tenant's hash. Additionally, multiple high-traffic header values might map 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` route option. This factor determines whether an instance is handling more traffic than its fair share compared to 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 Gorouter. When this threshold is exceeded, the router redirects subsequent requests to other predetermined, less-loaded instances.
+
+Values in the 1.1–2.0 range offer a good balance between even distribution and performance. Optimal values depend on the application's traffic patterns. Omitting `hash_balance` or setting it to 0 means load imbalance is accepted and all requests for a particular hash are routed to the same instance as long as it is healthy.
+
+## <a id="minimal-rehashing"></a> Minimal Rehashing
+
+The Maglev algorithm used in Hash-Based Routing minimizes rehashing when application instances are added or removed. When a new instance is added, only a small subset of hashes is remapped to it, while most continue to route to their original instances. Similarly, when an instance is removed, only the hashes mapped to that instance are reassigned. This design minimizes disruption and maintains consistent routing behavior as the application scales up or down.
+
+## <a id="retries-in-hash-based"></a> Retries in Hash-Based Routing
+
+For idempotent requests, Hash-Based Routing supports a retry mechanism. When a request fails due to a network error or a 5xx response from the application instance, the router retries the request with a different, predetermined application instance. The next entry in the Maglev lookup table determines this instance — the same approach used for handling imbalanced loads. This ensures that retries adhere to the principles of Hash-Based Routing while providing resilience against temporary failures such as instance restarts or network interruptions.

routing-index.html.md.erb

@@ -9,6 +9,8 @@ These topics contain information about configuring routes and domains:
 
 * [Configuring per-route options](custom-per-route-options.html)
 
+* [Hash-Based Routing](hash-based-routing.html)
+
 * [Configuring <%= vars.app_runtime_abbr %> to route traffic to apps on custom ports](custom-ports.html)
 
 * [Routing HTTP/2 and gRPC traffic to apps](http2-protocol.html)