Design for session persistence - Part II #4221
Conversation
github-actions
bot
added
the
documentation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #4221 +/- ##
==========================================
- Coverage 86.08% 86.07% -0.02%
==========================================
Files 131 131
Lines 14167 14171 +4
Branches 35 35
==========================================
+ Hits 12196 12198 +2
+ Misses 1770 1769 -1
- Partials 201 204 +3 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
| For **HTTPRoutes**, we do not set the `domain` attribute. Deriving a broader domain (for example, a common suffix across hostnames or a parent domain) would widen the cookie scope to sibling subdomains and increase the risk of cross-host leakage. Since users cannot explicitly configure this field, inferring a shared domain would also be vulnerable to abuse. Leaving domain unset ensures each cookie is scoped to the exact host that issued it. | ||
|
|
||
| To determine the cookie `path` for HTTPRoutes, we handle the simple case where there is a single path match as follows: | ||
|
|
||
| | 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. | | ||
|
|
||
| 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. |
There was a problem hiding this comment.
I think this is a reasonable first approach for HTTPRoute path handling, but if it’s viewed as over derived then, I’m also comfortable simplifying it to rely on the default cookie path behavior (i.e., not computing a path on the NGF side at all).
sjberman
left a comment
sjberman
left a comment
There was a problem hiding this comment.
Be sure to fill out the security/testing/use case sections as provided in the proposal template.
salonichf5
force-pushed
the
docs/session-persistence
branch
from
d9cd13c to
462e832
Compare
|
|
||
| ### Edge Cases | ||
|
|
||
| - If both Kubernetes Service-level session affinity and Gateway API sessionPersistence are configured for the same traffic, the route MUST be rejected, with a status condition explaining that the two mechanisms are incompatible. |
There was a problem hiding this comment.
What is nginx's behavior if both are set? Is it really incompatible?
There was a problem hiding this comment.
I haven’t tested this myself yet, but based on the docs, setting sessionAffinity: ClientIP on a Kubernetes Service makes kube-proxy apply stickiness at the L4 (transport) layer. Because that decision happens before traffic reaches NGINX at L7, it can effectively “pin” certain client IPs to specific NGINX Pods. In a deployment with multiple NGINX gateway replicas, that can skew traffic and override NGINX’s own session stickiness or load-balancing strategy.
By default, sessionAffinity is None, so kube-proxy doesn’t do any of this.
This aligns with the recommendation in the Gateway API GEP on session persistence, so I added it here since it seemed consistent with that direction.
There was a problem hiding this comment.
And this would specifically relate to the NGINX Service, not the backend service, because nginx routes directly to the pods, not through the Service, so kube-proxy plays no role in the nginx -> backend traffic.
Proposed changes
Write a clear and concise description that helps reviewers understand the purpose and impact of your changes. Use the
following format:
Problem: Users want sessionPersistence for their server communication
Solution: Add a detailed approach on how to support sessionPersistence for NGF while being community conformant.
Testing: Did a couple of manual checks
Please focus on (optional): If you any specific areas where you would like reviewers to focus their attention or provide
specific feedback, add them here.
Closes #4051
Checklist
Before creating a PR, run through this checklist and mark each as complete.
Release notes
If this PR introduces a change that affects users and needs to be mentioned in the release notes,
please add a brief note that summarizes the change.