WIP: Document hash-based routing #569

b1tamara · 2025-11-04T09:03:50Z

No description provided.

peanball

Some wording, some questions.

hash-based-routing.html.md.erb

peanball · 2025-11-04T09:09:20Z

hash-based-routing.html.md.erb

+
+- **Configurable via Per-Route Options**: Easily set up Hash-Based Routing using application route options
+- **Consistent Hashing**: Implements the Maglev consistent hashing algorithm as outlined in the paper "Maglev: A Fast and Reliable Software Network Load Balancer" (https://storage.googleapis.com/gweb-research2023-media/pubtools/2904.pdf)
+- **Minimal Rehashing**: Uses the Maglev lookup table to map application instances by hash, minimizing the need to recalculate the entire table when instances are added or removed


the recalculation is not the expensive part. The really expensive part is the resulting shift of specific hashes to other instances. This rehashing minimization makes sure that happens as little as possible and keeps the "allocation" of hash values to their instances as stable as possible.

Yes, you are right. I did not like the word recalculation either, I wanted to say the same what you mentioned.
Maybe:

**Minimal Rehashing**: Uses the Maglev lookup table to map application instances by hash, ensuring that hash positions are shifted to other instances as little as possible when application instances are added or removed."

sounds great!

hash-based-routing.html.md.erb

peanball · 2025-11-04T09:12:28Z

hash-based-routing.html.md.erb

+
+Hash-Based Routing implements a clear precedence hierarchy:
+
+1. **Sticky Sessions**: First checks if a sticky session is used and the sticky session endpoint is available


is the sticky session counted towards the balance / in-flight requests or not?

All in-flight requests will be counted (incl. sticky session requests). It happens via {RoundRobin Iterater | HashBased Iterator | LeastConnection Iterator}.PreRequest logic

hash-based-routing.html.md.erb

peanball · 2025-11-04T09:19:00Z

hash-based-routing.html.md.erb

+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.
+
+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 (e.g., `X-Resource-ID` or `Tenant-ID`). 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).
+
+This makes it especially suitable for applications requiring high scalability and performance, such as microservices architectures or multi-tenant applications, when dealing with limited or memory-intensive resources in backend services.


These paragraphs are very wordy and a bit meandering. LLM?

Either way, the main point is:
Session affinity works on session level. Heavy users may end up on the same instance and through session affinity pin to it, thus overloading it. Identifying sessions for web applications is usually done via session cookie and does not pose too much implementation burden. CF only supports a single cookie name however, defaulting to JSESSIONID.

With hash based routing, identifiers other than the session ID can be used, and spill-over to other instances is possible with the balance factor (see next section).

hash-based-routing.html.md.erb

Co-authored-by: Alexander Lais <Alexander.lais@me.com>

hoffmaen

Rephrasing key features

hoffmaen · 2025-11-06T11:11:24Z

hash-based-routing.html.md.erb

+
+## <a id="key-features"></a> Key Features
+
+- **Configurable via Per-Route Options**: Easily set up Hash-Based Routing using application route options


Maybe add a link to per-route-options documentation?

Suggested change

- **Configurable via Per-Route Options**: Easily set up Hash-Based Routing using application route options

- **Configurable via Per-Route Options**: Easily configurable via per-route options

It is the same words twice.
WDYT about
Configurable via Per-Route Options: Hash-Based load-balancing setup through application route options

hoffmaen · 2025-11-06T11:13:52Z

hash-based-routing.html.md.erb

+## <a id="key-features"></a> Key Features
+
+- **Configurable via Per-Route Options**: Easily set up Hash-Based Routing using application route options
+- **Consistent Hashing**: Implements the Maglev consistent hashing algorithm as outlined in the paper "Maglev: A Fast and Reliable Software Network Load Balancer" (https://storage.googleapis.com/gweb-research2023-media/pubtools/2904.pdf)


Suggested change

- **Consistent Hashing**: Implements the Maglev consistent hashing algorithm as outlined in the paper "Maglev: A Fast and Reliable Software Network Load Balancer" (https://storage.googleapis.com/gweb-research2023-media/pubtools/2904.pdf)

- **Consistent Hashing**: Consistent hashing via 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)

hoffmaen · 2025-11-06T11:15:27Z

hash-based-routing.html.md.erb

+
+- **Configurable via Per-Route Options**: Easily set up Hash-Based Routing using application route options
+- **Consistent Hashing**: Implements the Maglev consistent hashing algorithm as outlined in the paper "Maglev: A Fast and Reliable Software Network Load Balancer" (https://storage.googleapis.com/gweb-research2023-media/pubtools/2904.pdf)
+- **Minimal Rehashing**: Uses the Maglev lookup table to map application instances by hash, minimizing changes to hash assignments when application instances are added or removed


Suggested change

- **Minimal Rehashing**: Uses the Maglev lookup table to map application instances by hash, minimizing changes to hash assignments when application instances are added or removed

- **Minimal Rehashing**: The Maglev Algorithm minimizes changes to the mapping table (header->instance), when application instances are added or removed

I would remove the (header->instance) bit, or at least change it to (hash -> instance).

hash-based-routing.html.md.erb

hoffmaen · 2025-11-06T11:19:57Z

hash-based-routing.html.md.erb

+- **Minimal Rehashing**: Uses the Maglev lookup table to map application instances by hash, minimizing changes to hash assignments when application instances are added or removed
+- **Configurable Hash Header**: Allows specifying which HTTP header to use for hashing via the `hash_header` property
+- **Session Affinity Precedence**: Prioritizes session affinity, or sticky sessions, over hash-based routing when available
+- **Handling imbalanced loads**: Implements detection and mitigation of higher request loads on single instances due to different usage patterns for specific hashes. This avoids overloading a single instance while keeping instances for a particular hash at a minimum.


Suggested change

- **Handling imbalanced loads**: Implements detection and mitigation of higher request loads on single instances due to different usage patterns for specific hashes. This avoids overloading a single instance while keeping instances for a particular hash at a minimum.

- **Handling imbalanced loads**: Imbalanced load on a subset of instances is avoided. This avoids overloading a single instance while keeping instances for a particular hash at a minimum.

"is avoided" is passive voice and that should be avoided ;-)

hash-based-routing.html.md.erb

Co-authored-by: Clemens Hoffmann <clemens.hoffmann@sap.com>

anita-flegg · 2025-11-10T17:09:21Z

@ameowlia , is this something we also need to add to the TPCF commercial docs?

anita-flegg · 2025-11-11T18:28:40Z

Note to myself -- CF OSS docs only.

WIP: Document hash-based routing

69b33d0

peanball reviewed Nov 4, 2025

View reviewed changes

b1tamara and others added 2 commits November 4, 2025 11:02

Apply suggestions from code review

2681f4b

Co-authored-by: Alexander Lais <Alexander.lais@me.com>

Apply review feedback

58cd0d5

hoffmaen reviewed Nov 6, 2025

View reviewed changes

hoffmaen reviewed Nov 7, 2025

View reviewed changes

b1tamara and others added 2 commits November 7, 2025 09:12

Apply suggestions from code review

73de4a8

Co-authored-by: Clemens Hoffmann <clemens.hoffmann@sap.com>

Rephrase

6d7a71c

b1tamara mentioned this pull request Nov 12, 2025

Implement hash-based routing as a per-route load balancing Algorithm in gorouter cloudfoundry/routing-release#505

Open


		Hash-Based Routing implements a clear precedence hierarchy:

		1. Sticky Sessions: First checks if a sticky session is used and the sticky session endpoint is available


		## <a id="key-features"></a> Key Features

		- Configurable via Per-Route Options: Easily set up Hash-Based Routing using application route options

	- Consistent Hashing: Implements the Maglev consistent hashing algorithm as outlined in the paper "Maglev: A Fast and Reliable Software Network Load Balancer" (https://storage.googleapis.com/gweb-research2023-media/pubtools/2904.pdf)
	- Consistent Hashing: Consistent hashing via 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: Uses the Maglev lookup table to map application instances by hash, minimizing changes to hash assignments when application instances are added or removed
	- Minimal Rehashing: The Maglev Algorithm minimizes changes to the mapping table (header->instance), when application instances are added or removed

	- Handling imbalanced loads: Implements detection and mitigation of higher request loads on single instances due to different usage patterns for specific hashes. This avoids overloading a single instance while keeping instances for a particular hash at a minimum.
	- Handling imbalanced loads: Imbalanced load on a subset of instances is avoided. This avoids overloading a single instance while keeping instances for a particular hash at a minimum.

WIP: Document hash-based routing #569

Are you sure you want to change the base?

WIP: Document hash-based routing #569

Uh oh!

Conversation

b1tamara commented Nov 4, 2025

Uh oh!

peanball left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

b1tamara Nov 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

hoffmaen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hoffmaen Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

anita-flegg commented Nov 10, 2025

Uh oh!

anita-flegg commented Nov 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

b1tamara Nov 4, 2025 •

edited

Loading

hoffmaen Nov 6, 2025 •

edited

Loading