Skip to content

Commit 946cf7f

Browse files
committed
update based on reviews
1 parent a595e2e commit 946cf7f

File tree

2 files changed

+19
-10
lines changed

2 files changed

+19
-10
lines changed

content/ngf/overview/gateway-api-compatibility.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -176,7 +176,7 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command
176176
- `name`: Not supported.
177177
- `timeouts`: Not supported.
178178
- `retry`: Not supported.
179-
- `sessionPersistence`: Supported.
179+
- `sessionPersistence`: Supported (NGINX Plus).
180180
- `status`
181181
- `parents`
182182
- `parentRef`: Supported.
@@ -226,7 +226,7 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command
226226
- `extensionRef`: Supported for SnippetsFilters.
227227
- `backendRefs`: Partially supported. Backend ref `filters` are not supported.
228228
- `name`: Not supported.
229-
- `sessionPersistence`: Supported.
229+
- `sessionPersistence`: Supported (NGINX Plus).
230230
- `status`
231231
- `parents`
232232
- `parentRef`: Supported.

content/ngf/traffic-management/session-persistence.md

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,11 @@ Learn how to configure session persistence using NGINX Gateway Fabric.
1111

1212
## Overview
1313

14-
In this guide, you’ll learn how to configure session persistence for your application. Session persistence ensures that multiple requests from the same client are consistently routed to the same backend Pod. This is useful when your application maintains in-memory state (for example, shopping carts or user sessions). NGINX Gateway Fabric supports configuring session persistence via `UpstreamSettingsPolicy` resource or directly on `HTTPRoute` and `GRPCRoute` resources. For NGINX OSS users, using the `ip_hash` load-balancing method provides basic session affinity by routing requests from the same client IP to the same backend Pod. For NGINX Plus users, the `sticky cookie` directive can be used to provide true session persistence based on a generated session cookie.
14+
In this guide, you’ll learn how to configure session persistence for your application. Session persistence ensures that multiple requests from the same client are consistently routed to the same backend Pod. This is useful when your application maintains in-memory state (for example, shopping carts or user sessions). NGINX Gateway Fabric supports configuring session persistence via `UpstreamSettingsPolicy` resource or directly on `HTTPRoute` and `GRPCRoute` resources. For NGINX OSS users, using the `ip_hash` load-balancing method provides basic session affinity by routing requests from the same client IP to the same backend Pod. For NGINX Plus users, cookie-based session persistence can be configured using the `sessionPersistence` field in a Route.
1515
In this guide, you will deploy three applications:
1616

1717
- An application configured with `ip_hash` load-balancing method.
18-
- An application configured with cookie–based session persistence.
18+
- An application configured with cookie–based session persistence (if you have access to NGINX Plus).
1919
- A regular application with default load-balancing.
2020

2121
These applications will showcase the benefits of session persistence for stateful workloads.
@@ -152,15 +152,13 @@ kubectl get all -o wide -n default
152152
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
153153
pod/coffee-5b9c74f9d9-2zlqq 1/1 Running 0 3h19m 10.244.0.95 kind-control-plane <none> <none>
154154
pod/coffee-5b9c74f9d9-7gfwn 1/1 Running 0 3h19m 10.244.0.94 kind-control-plane <none> <none>
155-
pod/gateway-nginx-5c9f576669-tc258 1/1 Running 0 3h19m 10.244.0.99 kind-control-plane <none> <none>
156155
pod/latte-d5f64f67f-9t2j5 1/1 Running 0 3h19m 10.244.0.96 kind-control-plane <none> <none>
157156
pod/latte-d5f64f67f-drwc6 1/1 Running 0 3h19m 10.244.0.98 kind-control-plane <none> <none>
158157
pod/tea-859766c68c-cnb8n 1/1 Running 0 3h19m 10.244.0.93 kind-control-plane <none> <none>
159158
pod/tea-859766c68c-kttkb 1/1 Running 0 3h19m 10.244.0.97 kind-control-plane <none> <none>
160159
161160
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE SELECTOR
162161
service/coffee ClusterIP 10.96.169.1 <none> 80/TCP 3h19m app=coffee
163-
service/gateway-nginx ClusterIP 10.96.15.149 <none> 80/TCP 3h19m app.kubernetes.io/instance=nginx-gateway,app.kubernetes.io/managed-by=nginx-gateway-nginx,app.kubernetes.io/name=gateway-nginx,gateway.networking.k8s.io/gateway-name=gateway
164162
service/latte ClusterIP 10.96.42.39 <none> 80/TCP 3h19m app=latte
165163
service/tea ClusterIP 10.96.81.103 <none> 80/TCP 3h19m app=tea
166164
```
@@ -183,7 +181,18 @@ spec:
183181
EOF
184182
```
185183

186-
After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. Save the public IP address and port of the NGINX Service into shell variables:
184+
After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. Verify the gateway is created:
185+
186+
```bash
187+
kubectl get gateways.gateway.networking.k8s.io gateway
188+
```
189+
190+
```text
191+
NAME CLASS ADDRESS PROGRAMMED AGE
192+
gateway nginx 10.96.15.149 True 23h
193+
```
194+
195+
Save the public IP address and port of the NGINX Service into shell variables:
187196

188197
```text
189198
GW_IP=XXX.YYY.ZZZ.III
@@ -202,7 +211,7 @@ NGINX_POD_NAME=<NGINX Pod>
202211

203212
### Session Persistence with NGINX OSS
204213

205-
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. Refer to this [guide]({{< ref "/ngf/how-to/data-plane-configuration/#configure-proxy-protocol-and-rewriteclientip-settings" >}}) for more information on configuring these fields.
214+
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.
206215

207216
To create an HTTPRoute for the `coffee` service, copy and paste the following into your terminal:
208217

@@ -250,7 +259,7 @@ Status:
250259
Controller Name: gateway.nginx.org/nginx-gateway-controller
251260
```
252261

253-
Now, let’s create an `UpstreamSettingsPolicy` targeting the `coffee` Service to change the load-balancing method for its upstreams:
262+
Now, let’s create an `UpstreamSettingsPolicy` targeting the `coffee` Service to change the load-balancing method for its upstream:
254263

255264
```yaml
256265
kubectl apply -f - <<EOF
@@ -293,7 +302,7 @@ Next, verify that the policy has been applied to the `coffee` upstream by inspec
293302
kubectl exec -it -n <NGINX-pod-namespace> $NGINX_POD_NAME -- nginx -T
294303
```
295304

296-
You should see the `ip_hash` directive on the `coffee` upstreams:
305+
You should see the `ip_hash` directive on the `coffee` upstream:
297306

298307
```text
299308
upstream default_coffee_80 {

0 commit comments

Comments
 (0)