Skip to content

GEP-3798: Client IP-Based Session Persistence

  • Issue: #3798
  • Status: Provisional

(See status definitions.)

Notes and Disclaimers

  • This is currently targeting release as Experimental in v1.4.0. However there was notable concern in PR#3844 that it may be difficult to get multiple implementations who will be ready to implement this and move it forward. As such, the primary focus at this point should be finding representatives of implementations who may be interested in implementing this. Otherwise, this GEP may need to be Deferred and revisited as part of a later release.

TLDR

What

This GEP proposes the addition of Client IP-based session persistence to the Gateway API. This feature will allow Gateway API implementations to ensure that requests originating from a specific client IP address (or a subnet defined by an IP mask) are consistently routed to the same backend endpoint for a configurable duration. This aims to provide a standardized and centralized mechanism for client IP persistence across various Gateway API implementations.

As mentioned in the GEP-1619, SessionPersistence can be applied via BackendLBPolicy and RouteRule API. Similar edge case behaviour and API Granularity for ClientIP Persistence type should be applicable as well.

An important addition/difference compared to GEP-1619 is that the identity of the backend assigned to a client (or a group of clients in the same subnet) is stored on the server (load balancer / gateway) side as opposed to the client side.

Goals

  • Define an API extension within Gateway API to enable client IP-based session persistence.

  • Allow configuration of a session duration for which a client IP should stick to a backend.

  • Provide an optional mechanism to specify an IP mask for subnet-based persistence, allowing multiple clients from the same subnet to be routed to the same backend.

  • Improve portability of applications requiring client IP persistence across different Gateway API implementations.

Non-Goals

This GEP does not dictate the specific algorithm or implementation details for how an individual Gateway controller maintains the client IP-to-backend mapping (e.g., in-memory, distributed cache).

Introduction

Why: The Problem This Solves

Currently, achieving client IP-based session persistence within Kubernetes Gateway API environments often requires vendor-specific annotations or out-of-band configurations on the underlying load balancer or ingress controller. This approach has several drawbacks:

  • Inconsistent User Experience: Users have to learn different methods for configuring the same logical feature depending on their chosen Gateway API implementation. Configurations are not easily transferable between different Gateway API implementations, leading to vendor lock-in and increased operational overhead when migrating or using multiple controllers.

  • Reduced Visibility: The desired session persistence behavior is not explicitly declared within the Gateway API resources, making it harder to audit, manage, and understand the routing logic from a single source of truth.

This GEP addresses these issues by providing a first-class API mechanism for client IP-based session persistence, enhancing the Gateway API's capabilities and promoting consistency and portability.

Who: Beneficiaries

  • Application Developers: Can define session persistence requirements directly in their Gateway API configurations, ensuring consistent behavior regardless of the underlying Gateway implementation. This simplifies application deployment and management for stateful workloads.

  • Platform Operators/Administrators: Gain a standardized way to configure and manage client IP-based session persistence across their clusters, reducing the need for custom scripts or deep knowledge of individual controller implementations. This improves operational efficiency and consistency.

  • Gateway API Implementers: Receive a clear specification for implementing client IP-based session persistence, fostering interoperability and reducing divergent approaches.

  • Users with Stateful/Legacy Applications: Applications that rely on client IP Persistence (e.g., certain legacy applications, gaming servers, or applications with in-memory session stores) will directly benefit from a reliable and configurable persistence mechanism.

API

TODO: when we get to the implementation iterations, we need to consider whether we can implement this using functionality established in GEP-1619.

Conformance tests

NA

Alternatives

Yet to do

References

Below are references showing how ClientIP persistence is currently supported across some implementations:

Below are some implementations of ClientIP persistence which allows configuring subnet Mask