Understand the usptream_ketama_hash module in Nginx, setup, directives, and how consistent hashing works for reliable load balancing. Our Live Support Team is always here to help you.

Understanding the usptream_ketama_hash module in Nginx

In high-traffic environments, keeping request distribution predictable is essential. The usptream_ketama_hash module ensures exactly that. This load-balancing method uses a consistent hashing algorithm to distribute requests across backend servers in a stable, predictable way, even when nodes go offline or new ones join.

Ketama consistent hashing (often just called consistent hashing) is widely used in caching systems and distributed platforms. Instead of reassigning all requests when a server changes, it remaps only the minimum necessary keys, which makes the process efficient and stable.

How it Works

The usptream_ketama_hash module creates a hash ring. Each server maps to multiple virtual peers (defined by server weight). These peers spread evenly across the ring. When a request arrives, the module calculates a hash key using a specified Nginx variable and locates the closest matching peer on the ring.

If a backend server goes down, the module reroutes requests to the next available server without disrupting the entire mapping.

Basic Configuration Example

upstream backend {

...

ketama_hash    $uri;

}

Then here, $uri is used to determine the hash key, keeping the mapping consistent for the same request URI.

Server Parameters You Can Control

• server id field:

The id field acts as a server flag. If it’s not set, the IP address and port are used as identifiers. Setting an id ensures that even if a server’s IP or port changes, it will still be recognized as the same node. This helps reduce unnecessary remapping.

• server weight field:

This defines how many virtual peers a server will have on the hash ring. More weight means more virtual peers, influencing request distribution.

Supported Consistent Hash Options

The module allows mapping requests based on different Nginx variables:

• consistent_hash $remote_addr; – maps via client IP address.
• consistent_hash $request_uri; – maps via the request URI.
• consistent_hash $args; – maps via the URL query string.

Directives

Syntax:

consistent_hash variable_name

Default: none

Context: upstream

Therefore, this directive sets how requests are distributed among upstream servers using the consistent hashing algorithm. The variable specified will be the input to the hash function.

Installation and Compilation

The usptream_ketama_hash module is built by default in Nginx but can be disabled with:

--without-http_upstream_consistent_hash_module

To install manually:

$ ./configure

$ make

$ make install

[If needed, Our team is available 24/7 for additional assistance.]

Conclusion

Furthermore, in environments where request stability and cache efficiency are critical, the usptream_ketama_hash module offers a straightforward yet powerful solution. By using consistent hashing, it minimizes disruptions when back-end servers change and keeps traffic distribution steady.