Mastering Nginx Session Affinity: How ip_hash Ensures Sticky Sessions

Background

A common requirement is that all requests from the same client be sent 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 requests from the same client to the same backend server, typically using the client’s IP address or a cookie.

Client‑to‑server interaction:

Implementation Approach

Nginx can hash the client IP to select an upstream server, ensuring that the same IP always maps to the same backend.

ip_hash Directive

The

ip_hash

directive tells Nginx to use the client IP address as the hashing key.

<code>Syntax: ip_hash;</code>

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 this server is unavailable.

From version 1.3.2 (and 1.2.2) IPv6 is supported. The

down

parameter can temporarily mark a server as unavailable.

Usage Example

<code>upstream backend {    ip_hash;    server backend1.example.com;    server backend2.example.com;    server backend3.example.com down;    server backend4.example.com;}</code>

ip_hash

: Uses the client IP to route all requests from that IP to the same backend.

server

: Lists the backend servers in the

upstream

block.

backend3.example.com down

: Marks this server as temporarily disabled, so it will not receive new connections.

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

GitHub Issue Example

An issue on GitHub asked whether a client IP would be reassigned to another server when the original server is marked

down

and then restored. The test results were:

When server A is marked

down

, the IP 192.168.1.10 is routed to server B.

After removing

down

from server 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, potentially overloading one server.

Limited load‑balancing capabilities; it ignores server health and performance, unlike algorithms such as

least_conn

or the full

ngx_http_upstream_module

.

May cause resource waste if a high‑frequency client monopolizes a single backend.

Unsuitable for clients with dynamic IPs, as IP changes break session stickiness.

Maintaining session state adds system complexity, making it less ideal for stateless architectures.

Conclusion

The

ip_hash

method is effective for achieving session affinity, but it has drawbacks such as load imbalance and limited flexibility.