Skip to content

GEP-1619: Refactor SessionPersistence to discriminated union pattern - #4873

Merged
kubernetes-prow[bot] merged 1 commit into
kubernetes-sigs:mainfrom
gcs278:gep1619-discriminated-union
Aug 11, 2026
Merged

kubernetes-prow[bot] merged 1 commit into
kubernetes-sigs:mainfrom
gcs278:gep1619-discriminated-union

Conversation

@gcs278

@gcs278 gcs278 commented May 18, 2026 •

Copy link
Copy Markdown
Contributor

What type of PR is this?

/kind gep

What this PR does / why we need it

What

Refactors the SessionPersistence API to use the discriminated union pattern, split out from #4649 to land independently. This is a breaking change to the experimental API.

  • Remove sessionName field and move naming into type-specific configs (cookie.name / header.name)
  • Rename cookieConfig to cookie to match the union discriminator convention
  • Add HeaderConfig struct with required name field for header-based persistence
  • Change cookie.name support level from Implementation-specific to Extended; header.name is Core and required
  • Reuse the existing HeaderName type (Add shared type HeaderName and use it for GRPCHeaderName, HTTPHeaderName and QueryParamMatchName #1796) for both cookie and header name fields, adding RFC token character validation
  • Add CEL validation enforcing type/field consistency (e.g. cookie type requires cookie field)
  • Add +unionDiscriminator marker on Type field

Why

  • sessionName is misleading. The field name suggests a server-side session identifier, but every implementation uses it as the literal cookie or header name on the wire. cookie.name / header.name makes this clear. Every major dataplane and cloud LB models session naming as separate fields per type.

  • Implementation-specific blocks conformance testing. The current support level means implementations can interpret sessionName however they want, making conformance tests impossible. Changing to Extended enables standardizing cookie sharing semantics and validating cookie name conflicts (Clarify sessionPersistence scoping and conflict resolution across HTTPRoutes and Backends #4268). The original motivation for Implementation-specific was to accommodate cloud LBs that can't control the cookie name, but Extended achieves the same goal (implementations can opt out) while enabling conformance testing.

  • Name belongs to the mechanism, not the concept. You can say "the cookie name is X" or "the header name is X", but not "the session persistence name is X." Pushing the name into type-specific configs groups it with the other attributes of that mechanism.

Which issue(s) this PR fixes:

Fixes # N/A

This addresses concern was raised in #4268 about ambiguities

Does this PR introduce a user-facing change?:

SessionPersistence API: move sessionName to cookie.name (Extended, optional) and header.name (Core, required), rename cookieConfig to cookie, add HeaderConfig

@k8s-ci-robot

Copy link
Copy Markdown
Contributor

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

@k8s-ci-robot k8s-ci-robot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. release-note Denotes a PR that will be considered when it comes time to generate release notes. kind/gep PRs related to Gateway Enhancement Proposal(GEP) size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels May 18, 2026
@k8s-ci-robot

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: gcs278
Once this PR has been reviewed and has the lgtm label, please assign robscott for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

Comment thread apis/v1/shared_types.go Outdated
// Support: Extended
//
// +optional
Name *HeaderName `json:"name,omitempty"`

@mikemorris mikemorris May 20, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some additional documentation for why this can be omitted (cloud load balancer constraints?) and the behavior of implementations if it is omitted would be helpful.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good call - added docs for what happens when the field is omitted from a user perspective (+optional).

From an implementation perspective, this is Extended because some implementations hardcode the cookie name (GKE hardcodes to "GSSA", Contour hardcodes to X-Contour-Session-Affinity). I'll add details to the GEP. Let me know if you think it should also be in the API doc comments.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let me know if you think it should also be in the API doc comments.

I think this would be useful to document mostly for implementations to better understand whether they should support this field, and if they support it but it's omitted how they should handle that situation. Possibly worth using the <gateway:util:excludeFromCRD> tag for any implementer-specific guidance not necessary for users of the API.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mikemorris updated. Sorry for the delay. Originally held off for my GEP housekeeping PR #4870, but realized there's no dependency between them.

Comment thread apis/v1/shared_types.go Outdated
// Support: Extended
//
// +optional
Name *HeaderName `json:"name,omitempty"`

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similar question as Cookie.Name, why is this field optional and what is the expected behavior if omitted?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. I think that header.name should actually be required since the client needs to know the header name to include it in subsequent requests. Unlike cookies, headers aren't automatically handled by the browser. Also, all prior art for header persistence has the header name as required too - so it feels safe.

Updated it to be +required.

@gcs278
gcs278 force-pushed the gep1619-discriminated-union branch 2 times, most recently from 977b30d to f8aa06b Compare May 22, 2026 00:43
@k8s-ci-robot k8s-ci-robot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label May 22, 2026
@gcs278
gcs278 force-pushed the gep1619-discriminated-union branch from f8aa06b to 91c2916 Compare May 22, 2026 00:51
@gcs278
gcs278 force-pushed the gep1619-discriminated-union branch 2 times, most recently from f544ed8 to 32cb398 Compare June 16, 2026 14:53
@gcs278
gcs278 marked this pull request as ready for review June 16, 2026 15:11
@k8s-ci-robot k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Jun 16, 2026
@k8s-ci-robot
k8s-ci-robot requested a review from davidjumani June 16, 2026 15:11
@gcs278

gcs278 commented Jun 16, 2026

Copy link
Copy Markdown
Contributor Author

@mikemorris I'm ready for review again when you get a chance - thanks for the initial review.

@zhaohuabing

zhaohuabing commented Jul 2, 2026 •

Copy link
Copy Markdown
Contributor

Since this PR already reshapes CookieConfig (rename to cookie, add cookie.name), would it make sense to also address the cookie Path concern from #4713 here, or keep it for a follow-up?

The route-level guidance derives Path from the matched route path, which breaks when an upstream proxy rewrites the request (Gateway matches /foo/bar but the client sees /), so the browser stops sending the cookie. #4713 proposes relaxing that (allow Path unset) and/or adding an explicit cookie.path field — which would land naturally alongside cookie.name.

Fine to keep this PR focused; happy to open a follow-up for the Path work. Just want to confirm the direction.

@gcs278

gcs278 commented Jul 3, 2026

Copy link
Copy Markdown
Contributor Author

Since this PR already reshapes CookieConfig (rename to cookie, add cookie.name), would it make sense to also address the cookie Path concern from #4713 here, or keep it for a follow-up?

It's related to these changes, but I vote to keep it as a follow up. I'm trying to keep my PRs limited in size to keep things moving. It seems like we quite low on reviewer bandwidth right now too.

But the good news is with the shift to Backend, we have more time to put path in.

Fine to keep this PR focused; happy to open a follow-up for the Path work. Just want to confirm the direction.

Yea please feel free to help drive this forward and open a follow up PR. I could also use reviews on this PR as well - so feel free to help with that. Sorry I've gotten a bit stuck on other things, but Session Persistence need to start moving again.

Ping @mikemorris @rikatz @youngnick for another review here when you get a chance, thanks!

@zhaohuabing zhaohuabing left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM thanks!

Comment thread apis/v1/shared_types.go Resolved
@youngnick

Copy link
Copy Markdown
Contributor

I think that this looks good overall, but has some things that still need work. I'll approve, and we can iterate and wait for LGTM, then unhold.

/approve

@kubernetes-prow

Copy link
Copy Markdown

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: gcs278, youngnick, zhaohuabing

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubernetes-prow kubernetes-prow Bot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Jul 6, 2026
@gcs278
gcs278 force-pushed the gep1619-discriminated-union branch 2 times, most recently from 35498a7 to 650b0a5 Compare July 9, 2026 01:28
@gcs278

gcs278 commented Jul 9, 2026 •

Copy link
Copy Markdown
Contributor Author

@rikatz @youngnick ready for another review.

I would like to point out that this is a breaking experimental change. There will be churn for 3 implementations (nginx-gateway-fabric, envoy gateway, and kgateway). I get this is unfortunately painful, but the reason experimental exists

The alternative would be to "freeze" the current type definitions and defer all breaking changes to a new struct targeted for Backend, but that's pretty messy.

Comment thread apis/v1/shared_types.go Resolved
@gcs278
gcs278 force-pushed the gep1619-discriminated-union branch from 650b0a5 to 2e3948d Compare July 24, 2026 14:39
@rikatz

rikatz commented Jul 24, 2026

Copy link
Copy Markdown
Member

this one lgtm

@mikemorris @youngnick can we move forward?

Comment thread geps/gep-1619/index.md Resolved
Comment thread geps/gep-1619/index.md Outdated
The cookie name is configured via the `cookie.name` field (Extended support). Not all implementations support
configuring the cookie name. For example, GKE's stateful generated cookie
([GSSA](https://pkg.go.dev/github.com/GoogleCloudPlatform/gke-gateway-api/apis/networking/v1)) uses a fixed cookie
name that cannot be changed by the user. If `cookie.name` is not specified, a unique cookie name will be generated.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
name that cannot be changed by the user. If `cookie.name` is not specified, a unique cookie name will be generated.
name that cannot be changed by the user. If `cookie.name` is not specified, a unique cookie name SHOULD be generated.

It sounds like not all implementations (such as GKE described in the sentence before) may generate a unique cookie name?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point - updated. SHOULD seems right because it's extended and not all implementation support name. Though, I guess we could make it MUST when it's implemented. Made it SHOULD for now.

@mikemorris

mikemorris commented Jul 24, 2026 •

Copy link
Copy Markdown
Contributor

/lgtm

Tiny nit on cookie name language. I do want to ensure #5046 (changing default cookie path and adding explicit cookie.path field) lands in the same release as this to avoid too much churn.

@gcs278
gcs278 force-pushed the gep1619-discriminated-union branch from 2e3948d to db053a4 Compare July 24, 2026 18:31
Move sessionName into type-specific configs (cookie.name / header.name),
rename cookieConfig to cookie, and add HeaderConfig struct. Change session
name support level from Implementation-specific to Extended. This aligns
with the union discriminator pattern and with prior art from dataplanes
and implementations.

NOTE: This is a breaking change to the experimental API.
@gcs278

gcs278 commented Jul 24, 2026

Copy link
Copy Markdown
Contributor Author

@mikemorris fixed your suggestions. Will need re-lgtm.

I will work on getting #5046 in good shape to land soon. BTW - do you mean an official release (1.6.z or 1.7.0)? or a monthly experimental when you say "same release".

@mikemorris

Copy link
Copy Markdown
Contributor

Ah forgot that distinction - mostly concerned that the default path change doesn't land after some other part of this reaches standard, idk if it might make sense to include some mention of the expected upcoming default changes in release notes for implementer awareness, but yea less concerned with monthly experimental releases.

/lgtm

@kubernetes-prow kubernetes-prow Bot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jul 29, 2026
@gcs278

gcs278 commented Aug 11, 2026

Copy link
Copy Markdown
Contributor Author

/unhold

@kubernetes-prow kubernetes-prow Bot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Aug 11, 2026
@kubernetes-prow
kubernetes-prow Bot merged commit 839fd4f into kubernetes-sigs:main Aug 11, 2026
20 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. kind/gep PRs related to Gateway Enhancement Proposal(GEP) lgtm "Looks good to me", indicates that a PR is ready to be merged. release-note Denotes a PR that will be considered when it comes time to generate release notes. size/L Denotes a PR that changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants