Implementing Session Affinity with Nginx ip_hash Directive

Background

A project requires that all requests from the same client be routed to the same backend server to keep session data consistent.

Session Affinity

Session affinity (also called session persistence or stickiness) is a load‑balancing strategy that routes all requests from a single client to the same backend server, typically using the client’s IP address or a cookie.

The interaction between client and server is illustrated in the diagram below.

Implementation Approach

Nginx can hash the client’s IP address and map it to a specific upstream server, ensuring that subsequent requests from the same IP reach the same server.

Three clients with different fixed IPs are hashed by Nginx to select one of the upstream servers. The server also generates a session ID with an expiration time and returns it to the client; subsequent requests carry this session ID, allowing the same server to validate the session.

ip_hash Directive

The ip_hash directive enables IP‑based hashing.

Syntax: ip_hash;
Default:
Context: upstream

Official description (translated):

Specifies that a group should use a load‑balancing method where requests are distributed between servers based on client IP addresses. The first three octets of the client IPv4 address, or the entire IPv6 address, are used as a hashing key. The method ensures that requests from the same client will always be passed to the same server except when that server is unavailable.

Notes:

IPv6 support starts from version 1.3.2/1.2.2.

To temporarily remove a server, use the down parameter.

Before versions 1.3.1/1.2.2, ip_hash cannot be combined with weight configuration.

Usage Example

Below is a typical ip_hash configuration:

upstream backend {
    ip_hash;

    server backend1.example.com;
    server backend2.example.com;
    server backend3.example.com down;
    server backend4.example.com;
}

Explanation of the configuration:

ip_hash : tells Nginx to use the client’s IP address to decide which backend server will handle the request, ensuring all requests from the same IP go to the same server.

server : lists the backend servers within the upstream backend block (four servers in this example).

backend3.example.com down : marks this server as temporarily unavailable, so it will not accept new connections.

With this setup, Nginx routes requests based on client IP, keeping session data consistent.

Interesting Github Issue

An issue on Github asked whether an IP that was hashed to server A would be reassigned to server B when A is marked down , and whether it would switch back when A recovers. The test results were:

When server A is marked down , the IP (e.g., 192.168.1.10) is routed to server B.

After removing the down flag from A, the same IP is routed back to server A.

Pitfalls of ip_hash

Not suitable for uneven load: It does not consider server load, which may cause some servers to be overloaded while others are idle.

Limited load‑balancing capability: It only uses client IP and ignores server health or performance; more advanced modules like least_conn or the full ngx_http_upstream_module may be needed.

Potential resource waste: A high‑frequency client IP can concentrate traffic on a single server, leading to imbalance.

Dynamic IP issues: Clients with frequently changing IPs (e.g., DHCP) may lose session affinity.

Session state maintenance: Using ip_hash often requires additional session state handling, adding system complexity.

Conclusion

The ip_hash directive is effective for scenarios requiring session affinity, but it brings challenges such as load imbalance and limited flexibility, so it should be used with awareness of its constraints.