Skip to content

Update session persistence design #4314

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 21, 2025
+4 −3
Merged

Update session persistence design #4314

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9c358b6
update session persistence design
salonichf5 Nov 19, 2025
142008d
update the design based on discussions
salonichf5 Nov 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions docs/proposals/session-persistence.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,9 +150,9 @@ To determine the cookie `path` for HTTPRoutes, we handle the simple case where t

| Path Value | Path Match Type | Cookie `Path` Value | Cookie Match Expectations |
|-------------------------------------|-----------------|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
| `/hello-exact` | Exact | `/hello-exact` | Cookie header is sent for `/hello-exact` path only. |
| `/hello-prefix` | Prefix | `/hello-prefix` | Cookie header is sent for `/hello-prefix` and any subpath starting with `/hello-prefix` (e.g. `/hello-prefix/foo`). |
| `/hello-regex/[a-zA-Z0-9_-]+$` | Regex | `/hello-regex` | Cookie header is sent for any request whose path starts with `/hello-regex` and matches the regex in the location block (e.g. `/hello-regex/a`, `/hello-regex/abc123`). The regex still determines which requests match the route on the server side. |
| `/hello-exact` | Exact | `/hello-exact` | Cookie header is sent for `/hello-exact` path only. |
| `/hello-prefix` | Prefix | `/hello-prefix` | Cookie header is sent for `/hello-prefix` and any subpath starting with `/hello-prefix` (e.g. `/hello-prefix/foo`). |
| `/hello-regex/[a-zA-Z0-9_-]+$` | Regex | `/hello-regex` | No `path` attribute is set for pathType `RegularExpression` |

When there are multiple path matches that share the same sessionPersistence configuration, we derive a single cookie path by computing the longest common prefix that ends on a path-segment boundary `/`. If no non-empty common prefix on a segment boundary exists, we fall back to `/` which is allowing all paths.

Expand All @@ -177,6 +177,7 @@ The main security concern is how far session cookies reach. This design keeps co

- If an implementation routes through Service IPs, any Gateway-level session persistence must be rejected when Service-level session affinity is enabled. In our case, the data plane routes directly to pod IPs, so Service affinity does not interfere with session persistence between the gateway and backends.
- For traffic-splitting configurations, if cookie-based session persistence is enabled, sessions must remain pinned consistently across the split backends.
- When multiple HTTPRoute rules reference the same backend but define different (or no) sessionPersistence settings, session persistence is treated as rule-scoped rather than backend-scoped. For each unique combination of backendRef and session persistence configuration, the controller generates a dedicated NGINX upstream and wires that rule’s internal location to it.

### Future work

Expand Down
Loading