Skip to content

Commit 80200b8

Browse files
arihantgk8s-ci-robot
arihantg
authored and
k8s-ci-robot
committed
Adding GEP-3798 client ip based session persistence
1 parent 9d59dd8 commit 80200b8

File tree

2 files changed

+170
-0
lines changed

2 files changed

+170
-0
lines changed

‎geps/gep-3798/index.md

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# GEP-3798: Client IP-Based Session Persistence
2+
3+
* Issue: [#3798](https://github.com/kubernetes-sigs/gateway-api/issues/3798)
4+
* Status: Provisional
5+
6+
(See [status definitions](../overview.md#gep-states).)
7+
8+
## TLDR
9+
10+
### What
11+
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 per the nomenclature established in [#1619](https://gateway-api.sigs.k8s.io/geps/gep-1619), this feature is being referred as Session Affinity .
12+
13+
14+
## Goals
15+
16+
* Define an API extension within Gateway API to enable client IP-based session persistence.
17+
18+
* Allow configuration of a session duration for which a client IP should stick to a backend.
19+
20+
* 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.
21+
22+
* Ensure the solution is generic enough to be implemented by various Gateway API controllers.
23+
24+
* Improve portability of applications requiring client IP persistence across different Gateway API implementations.
25+
26+
## Non-Goals
27+
28+
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).
29+
30+
## Introduction
31+
32+
### Why: The Problem This Solves
33+
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:
34+
35+
* Lack of Portability: 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.
36+
37+
* Inconsistent User Experience: Users have to learn different methods for configuring the same logical feature depending on their chosen Gateway API implementation.
38+
39+
* Limited API Expressiveness: Important traffic management capabilities are not directly exposed or controlled through the Gateway API, making it less comprehensive for certain application requirements.
40+
41+
* 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.
42+
43+
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.
44+
45+
### Who: Beneficiaries
46+
* 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.
47+
48+
* 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.
49+
50+
* Gateway API Implementers: Receive a clear specification for implementing client IP-based session persistence, fostering interoperability and reducing divergent approaches.
51+
52+
* Users with Stateful Applications: Applications that rely on client IP affinity (e.g., certain legacy applications, gaming servers, or applications with in-memory session stores) will directly benefit from a reliable and configurable persistence mechanism.
53+
54+
## API
55+
56+
As mentioned in the [GEP-1619](https://gateway-api.sigs.k8s.io/geps/gep-1619/#api), `SessionPersistence` can be applied via `BackendLBPolicy` and `RouteRule` API .Similar [edge case behaviour](https://gateway-api.sigs.k8s.io/geps/gep-1619/#edge-case-behavior) and [API Granularity](https://gateway-api.sigs.k8s.io/geps/gep-1619/#api-granularity) for ClientIP Persistence type should be applicable as well.
57+
58+
Requirement is to introduce a new `SessionPersistenceType` called `ClientIP`
59+
60+
Example (illustrative, exact field names and structure are subject to review):
61+
62+
```
63+
# Existing SessionPersistence (simplified for example)
64+
# apiVersion: gateway.networking.k8s.io/v1beta1
65+
# kind: HTTPRoute
66+
67+
spec:
68+
rules:
69+
- backendRefs:
70+
- name: my-service
71+
port: 80
72+
sessionPersistence:
73+
# New field for client IP based persistence
74+
type: "ClientIP"
75+
absoluteTimeout: "5m"
76+
ipMask: 24 # Optional: IP mask for subnet persistence (e.g., "24" for /24 subnet)
77+
```
78+
```
79+
type SessionPersistence struct {
80+
...
81+
82+
// IPMask defines the IP mask to be applied on client this may be
83+
// used to persist clients from a same subnet to stick to same session
84+
//
85+
// Support: Implementation-specific
86+
//
87+
// +optional
88+
// +kubebuilder:validation:Minimum=0
89+
// +kubebuilder:validation:Maximum=128
90+
IPMask *uint32 `json:"ipMask,omitempty"`
91+
92+
}
93+
94+
type SessionPersistenceType string
95+
96+
const (
97+
// CookieBasedSessionPersistence specifies cookie-based session
98+
// persistence.
99+
//
100+
// Support: Core
101+
CookieBasedSessionPersistence SessionPersistenceType = "Cookie"
102+
103+
// HeaderBasedSessionPersistence specifies header-based session
104+
// persistence.
105+
//
106+
// Support: Extended
107+
HeaderBasedSessionPersistence SessionPersistenceType = "Header"
108+
109+
// ClientIPBasedSessionPersistence specifies Client IP based session
110+
// persistence.
111+
//
112+
// Support: Implementation-specific
113+
ClientIPBasedSessionPersistence SessionPersistenceType = "ClientIP"
114+
)
115+
```
116+
117+
### Conformance tests
118+
119+
NA
120+
121+
## Alternatives
122+
123+
Yet to do
124+
125+
## References
126+
127+
Below are references showing how ClientIP persistence is currently supported across some implementations:
128+
129+
* [AVI](https://techdocs.broadcom.com/us/en/vmware-security-load-balancing/avi-load-balancer/avi-load-balancer/30-2/load-balancing-overview/persistence.html)
130+
* [Envoy](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-msg-config-route-v3-routeaction-hashpolicy-connectionproperties) (the connection property hash policy can be used with Ring Hash load balancing to ensure session persistence for a particular source IP)
131+
* [Nginx](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#ip_hash)
132+
* [Native k8s](https://kubernetes.io/docs/reference/networking/virtual-ips/#session-affinity)
133+

‎geps/gep-3798/metadata.yaml

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
apiVersion: internal.gateway.networking.k8s.io/v1alpha1
2+
kind: GEPDetails
3+
number: 3798
4+
name: Client IP-Based Session Persistence
5+
status: Provisional
6+
# Any authors who contribute to the GEP in any way should be listed here using
7+
# their GitHub handle.
8+
authors:
9+
- arihantg
10+
relationships:
11+
# obsoletes indicates that a GEP makes the linked GEP obsolete, and completely
12+
# replaces that GEP. The obsoleted GEP MUST have its obsoletedBy field
13+
# set back to this GEP, and MUST be moved to Declined.
14+
obsoletes: {}
15+
obsoletedBy: {}
16+
# extends indicates that a GEP extends the linked GEP, adding more detail
17+
# or additional implementation. The extended GEP MUST have its extendedBy
18+
# field set back to this GEP.
19+
extends: {}
20+
extendedBy: {}
21+
# seeAlso indicates other GEPs that are relevant in some way without being
22+
# covered by an existing relationship.
23+
seeAlso:
24+
- number: 1619
25+
name: Session Persistence
26+
description: Session Persistence via BackendLBPolicy
27+
28+
# references is a list of hyperlinks to relevant external references.
29+
# It's intended to be used for storing GitHub discussions, Google docs, etc.
30+
references: {}
31+
# featureNames is a list of the feature names introduced by the GEP, if there
32+
# are any. This will allow us to track which feature was introduced by which GEP.
33+
# This is the value added to supportedFeatures and the conformance tests, in string form.
34+
featureNames: {}
35+
# changelog is a list of hyperlinks to PRs that make changes to the GEP, in
36+
# ascending date order.
37+
changelog: {}

0 commit comments

Comments
 (0)