NGINX Plus: Session Persistence

[mpstefan]

As an application developer using NGF, I want to route all requests in a given session to the same upstream server, so that requests do not get sent to other upstreams and sessions are lost.

Goals

• The requirements are two fold, and can be configured in the UpstreamSettingsPolicy:
• In NGINX Plus: Full-fledged session persistence using the SessionCookie extension.
• In NGINX Open Source: Basic session persistence using ip_hash for upstream server selection.
• NGF users are able to configure session persistence in NGF using one of the methods documented in NGINX Plus documentation (NIC use the the sticky cookie method): https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/#session-persistence
• For OSS, use ip_hash for basic session persistence in the UpstreamSettings Policy.
• For NGINX Plus, provide users with the ability to configure advanced cookie settings such as httpOnly, secure, and samesite attributes to meet modern security and compliance standards.
• Integrate session persistence into NGF workflows via HTTPRoute and Gateway API constructs, ensuring simplicity and adherence to Kubernetes-native practices.

See here to learn how NGINX Ingress Controller managed this with a custom Policy: https://docs.nginx.com/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/

• path: Specifies the path for which the cookie is valid. Default should be /.
• expires: Defines the cookie's expiration time, supporting both time-based (e.g., 1h) and max for long-lived cookies.
• domain: Allows setting a domain for the cookie.
• httpOnly: Configures the HttpOnly attribute for enhanced security. Defaults to false.
• secure: Configures the Secure attribute; must default to false.
• samesite: Allows configuration of the SameSite attribute with support for strict, lax, and none.

Definition of Done

• Support cookie-based session persistence for NGINX Plus using the sticky cookie directive.
• Provide basic IP-based session stickiness for NGINX Open Source using the load balancing method: ip_hash
• Expose configuration fields consistently via the Gateway API for both implementation types.
• The extension integrates seamlessly with HTTPRoute and Gateways adheres to Gateway API standards.
• All configurations are validated, and invalid entries are rejected with clear error messages.
• Complete user documentation with examples is provided, including configuration fields, usage, and troubleshooting.

[nginx-bot[bot]]

Hi @mpstefan!

Thanks for opening this issue! Be sure to check out our Contributing Guidelines and the Issue Lifecycle while you wait for someone on the team to take a look at this.

[mattmichal]

Should/can a separate issue be opened to support this for non-NGINX Plus users? I'm looking to replicate cookie affinity available in ingress-nginx.

[sjberman]

@mattmichal When we get closer to refining this work, we'll decide if it makes sense for two separate tickets or if the work can be combined into this single one.

I see that ingress-nginx uses lua to implement this (among many other features), which is something we will not support, so we will have to come up with a different solution.

[sjberman]

At an initial glance, in order to implement the configuration defined in an HTTPRoute, the sticky cookie directive in NGINX Plus seem to be the only way.

For OSS, ip_hash can't be defined using this spec, so we would need to add a way to configure load balancing methods in upstreams. This could be through the UpstreamSettingsPolicy, or a future spec as defined by the Gateway API. Either way, this is likely out of scope for this ticket.