Design Session Persistence - Part 1

[salonichf5]

Proposed changes

Write a clear and concise description that helps reviewers understand the purpose and impact of your changes. Use the
following format:

Problem: Need to get consensus on goals and non-goals for session persistence.

Solution: Create a proposal doc to outline goals and non goals of the feature

Testing: N/A

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 #ISSUE

Checklist

Before creating a PR, run through this checklist and mark each as complete.

• I have read the CONTRIBUTING doc
• I have added tests that prove my fix is effective or that my feature works
• I have checked that all unit tests pass after adding my changes
• I have updated necessary documentation
• I have rebased my branch onto main
• I will ensure my PR is targeting the main branch and pulling from my branch from my own fork

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.

NONE

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.01%. Comparing base (fe604d9) to head (509a526).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4158   +/-   ##
=======================================
  Coverage   86.00%   86.01%           
=======================================
  Files         131      131           
  Lines       14111    14111           
  Branches       35       35           
=======================================
+ Hits        12136    12137    +1     
+ Misses       1773     1771    -2     
- Partials      202      203    +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[bjee19]

lgtm

[sjberman]

This can be merged into main, doesn't need to be targeting the feature branch necessarily.

[sjberman]

The GEP I linked in the comment above should also be deeply read and understood, because it includes a lot more implications about where and how SessionPersistence is applied to a route. The BackendLBPolicy mentioned in there is now called BackendTrafficPolicy, and is a part of the apisx section of the repo. I think this policy was intended to include something relating to load balancing methods at some point too, probably needs clarification from the community.

We need to investigate and consider all of these things.

[salonichf5]

@sjberman I’ve gone through all your comments and recommendations — thank you for the detailed feedback. I agree that aligning with the Gateway API spec is ideal.

I’ve also reached out
to the community regarding potential modifications to the existing SessionPersistence spec under the route rule, or alternatively, moving the GEP-1619 forward. That said, I think we need to find a balance between progressing community discussions and delivering on the feature commitments for NGF. As you know, community work tends to move at a slower pace.

I’ve reached out to @mkingst as well for clarification on the importance of some of these directives, given they’re PLUS features — I’d assume users paying for PLUS would want full capability, or at least this helps incentivize upgrades.

Once I have more clarity, I’ll share some concrete suggestions on how we can move forward and we can adjust as needed.

Thanks for all the suggestions, it helped me get a broader viewpoint.

[salonichf5]

This can be merged into main, doesn't need to be targeting the feature branch necessarily.

I want to learn to work with feature branches and rebases so this is only for my own need.

[sjberman]

@salonichf5 Totally agree that things move slow and sometimes we can't wait. But the benefit of this particular situation is that there is a basic API in place that may cover the use cases we need for now, and allow us to get that solution implemented, while we wait and push forward with more advanced directives for the future. As the saying goes "don't let perfect be the enemy of good".

[salonichf5]

@salonichf5 Totally agree that things move slow and sometimes we can't wait. But the benefit of this particular situation is that there is a basic API in place that may cover the use cases we need for now, and allow us to get that solution implemented, while we wait and push forward with more advanced directives for the future. As the saying goes "don't let perfect be the enemy of good".

Definitely. I am also aiming towards being as Gateway API conformant as possible once I have more answers. I'll update you here when that happens

[salonichf5]

@sjberman @ciarams87 @bjee19 I have update the goals and non-goals for Session persistence design. Some key changes are:

• support loadbalancing method ip_hash for basic session persistence by extending Upstream Settings Policy API.
• translation of the Gateway API sessionPersistence specification (when defined at the route level) into NGINX Plus cookie-based session persistence directives.
• secure and httpOnly directives will be enabled by default due to current limitations in the community specification.
• The sameSite directive is excluded from this design for now for the same reason.

In parallel, I plan to contribute to help include these three directives (secure, httpOnly, and sameSite) in the official Gateway API sessionPersistence specification.

Additionally, I will merge the doc proposal to main and do implementation in feature branch for my own learning.