Hash-Based Routing

Page last updated:

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.

Prerequisites

To use Hash-Based Routing, ensure that

• your Cloud Foundry deployment meets the minimum version requirements. Available from cf-deployment v55.2.0, together with cf CLI 8.10.0 and later.
• platform operators activate the feature so that the CF feature flag hash_based_routing is set to true. See Feature Flags for more details.

Key Features

• Consistent Hashing: Uses the Maglev Algorithm to determine instance assignments (see Maglev: A Fast and Reliable Software Network Load Balancer 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
• 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

Configure Hash-Based Routing

Available from cf-deployment v55.2.0, together with cf CLI 8.10.0 and later.

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.

Configure Hash-Based Routing with an App Manifest

To configure Hash-Based Routing with an app manifest, use the following steps:

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 for this particular route.

   ---
   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.

2. Push the app with the manifest:

   cf push -f manifest.yml
   

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:

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:

cf create-route EXAMPLE.COM --hostname MY-HOST -o loadbalancing=hash -o hash_header=HASH-HEADER-NAME

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:

cf map-route MY-APP EXAMPLE.COM --hostname MY-HOST -o loadbalancing=hash -o hash_header=HASH-HEADER-NAME -o hash_balance=1.2

The command map-route supports the --option flag only for new routes. To update an existing route, see the instructions for update-route below.

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:

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:

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:

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.

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:

cf update-route EXAMPLE.COM --hostname MY-HOST -r loadbalancing

Retrieve Hash-Based Route Options

To view route options, you can query the route using the route command:

cf route EXAMPLE.COM --hostname MY-HOST

The response lists the chosen options, for example:

options:    {hash_balance=1.2, hash_header=HASH-HEADER-NAME, loadbalancing=hash}

Hash-Based Routing vs. Session Affinity

Session Affinity works at the session level and relies on session cookies (see 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). Unlike Session Affinity, Hash-Based Routing requires no code changes to the application.

Handling imbalanced loads

Imbalanced loads 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.

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.

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.