You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/ngf/traffic-management/session-persistence.md
+12-1Lines changed: 12 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -27,7 +27,7 @@ The NGINX directives discussed in this guide are:
27
27
28
28
## Note
29
29
30
-
{{< call-out "important" >}}`SessionPersistence` is only available for [NGINX Plus]({{< ref "/ngf/install/nginx-plus.md" >}}) users, with alternatives provided for NGINX OSS users. It is a Gateway API field from the experimental release channel and is subject to change. {{< /call-out >}}
30
+
{{< call-out "important" >}}Cookie-based `SessionPersistence` is only available for [NGINX Plus]({{< ref "/ngf/install/nginx-plus.md" >}}) users, with alternatives provided for NGINX OSS users. Session Persistence is a Gateway API field from the experimental release channel and is subject to change. {{< /call-out >}}
31
31
32
32
## Before you begin
33
33
@@ -209,6 +209,17 @@ NGINX_POD_NAME=<NGINX Pod>
209
209
210
210
## Session Persistence Methods
211
211
212
+
## Choosing the right session persistence method for your environment
213
+
214
+
The choice between `ip_hash` and cookie-based session persistence depends on your use case.
215
+
216
+
The `ip_hash` load-balancing method provides basic IP-based affinity: as long as NGINX sees the real client IP and not many users share that IP, requests from the same client will usually go to the same upstream Pod. However, there are important limitations:
217
+
218
+
-**Shared IPs:** When there is a load balancer or proxy in front of NGINX that does not preserve the real client IP, or when many users appear to come from a single IP address (for example, corporate NAT or VPNs), `ip_hash` operates on the shared IP rather than on individual users. This means many different users behind the same IP are all routed to the same upstream Pod, so you do not get true per-user stickiness.
219
+
-**Changing IPs:** If a user’s apparent IP changes over time (for example, when a load balancer or NAT pool uses multiple egress addresses), that user can be rehashed to a different upstream Pod and lose stickiness.
220
+
221
+
Cookie-based session persistence with `sticky cookie` provides stronger, per-user stickiness. NGINX issues a session cookie, and all subsequent requests that present that cookie are routed to the same upstream Pod, regardless of changes in client IP or intermediate.
222
+
212
223
### Session Persistence with NGINX OSS
213
224
214
225
In this section, you’ll configure a basic `coffee` HTTPRoute that routes traffic to the `coffee` Service. You’ll then attach an `UpstreamSettingsPolicy` to change the load-balancing method for that upstream to showcase session affinity behavior. NGINX hashes the client IP to select an upstream server, so requests from the same IP are routed to the same upstream as long as it is available. Session affinity quality with `ip_hash` depends on NGINX seeing the real client IP. In environments with external load balancers or proxies, operators must ensure appropriate `real_ip_header/set_real_ip_from` configuration so that `$remote_addr` reflects the end-user address otherwise, stickiness will be determined by the address of the front-end proxy rather than the actual client.
0 commit comments