OCI Native Ingress Controller now supports cookie-based session persistence for OCI load balancers. OKE also now supports cookie-based session persistence for OCI load balancers provisioned for Kubernetes Services of type LoadBalancer, giving teams two ways to enable sticky sessions depending on how they expose application traffic. In both cases, you can choose between application cookie persistence and load balancer cookie persistence.

Applications running on Kubernetes are often designed to be stateless, but that is not always the case in practice. Some workloads still depend on session continuity between requests. Examples include traditional web applications that keep session state in memory on backend instances, authenticated user flows such as sign-in or checkout, and applications being migrated to Kubernetes before session handling has been fully externalized.

For these types of applications, routing requests from the same client to the same backend can help preserve session continuity and reduce the amount of session-handling logic required in the application layer. With this release, teams running on OKE can now enable that behavior whether they expose workloads directly through a Service of type LoadBalancer or through OCI Native Ingress Controller.

cookier persistence example with load balancers

Two persistence models

OKE load balancers configured through either Services of type LoadBalancer or OCI Native Ingress Controller support two cookie-based persistence models with K8s versions 1.32 and above.

With application cookie persistence, the backend application sets and manages the cookie. This is a good fit when your application already issues its own session cookie and you want session affinity to follow that existing behavior. In this mode, stickiness begins when the backend returns a matching Set-Cookie header with the configured cookie name.

With load balancer cookie persistence, the load balancer sets and manages the persistence cookie on your behalf. This can be a simpler option when you want sticky sessions without changing application behavior, or when you prefer to manage session affinity at the infrastructure layer.

Two ways to use cookie-based session persistence in OKE

Both of the above persistence models can be used with both Kubernetes Services of type LoadBalancer and OCI Native Ingress Controller. That gives teams a choice between configuring sticky sessions directly on a service or through ingress, depending on how application traffic is exposed.

Use a Service of type LoadBalancer when you want to expose a Kubernetes service directly and configure the OCI load balancer through Service annotations. This is a good fit for simpler external exposure patterns where ingress-specific routing is not required.

Use OCI Native Ingress Controller when you want ingress-based traffic management, such as host- and path-based routing, and want to configure session persistence through Ingress annotations. NIC creates and manages an OCI flexible load balancer from Kubernetes ingress resources, and now supports the same cookie-based persistence capability there as well.

A quick configuration example

If you are exposing an application through a Service of type LoadBalancer, you can configure cookie-based session persistence with Service annotations on the Kubernetes manifest. Services support both application cookie persistence and load balancer cookie persistence through Service annotations. The example below shows load balancer cookie persistence:

apiVersion: v1
kind: Service
metadata:
  name: my-app-svc
  annotations:
    oci.oraclecloud.com/load-balancer-type: "lb"
    oci-load-balancer.oraclecloud.com/lb-cookie-session-persistence-config: |
      {
        "cookieName": "X-Oracle-OCI-Route",
        "disableFallback": true,
        "path": "/",
        "isHttpOnly": true
      }
spec:
  type: LoadBalancer
  selector:
    app: my-app
  ports:
    - name: http
      port: 80
      targetPort: 8080

If you are using OCI Native Ingress Controller, you can configure cookie-based session persistence with Ingress annotations. NIC also supports both persistence models through Ingress annotations. The example below shows application cookie persistence: 

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-cookie-ingress
  annotations:
    oci-native-ingress.oraclecloud.com/session-persistence-config: |
      {
        "cookieName": "APPSESS"
      }
spec:
  ingressClassName: oci-native-ingress
  rules:
    - http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: app-service
                port:
                  number: 8080

Taken together, these two paths cover the full feature set: Services of type LoadBalancer and OCI Native Ingress Controller both support application cookie persistence and load balancer cookie persistence, with the difference being whether you configure the feature on a Service or on an Ingress resource.

A few things to keep in mind

  • Configure only one persistence mode at a time for a backend set. If both persistence annotations are specified in a given configuration path, reconciliation fails.
  • Make sure the annotation value is valid JSON. Malformed JSON causes configuration failure.
  • In application cookie mode, persistence starts only after the backend returns the expected cookie in a Set-Cookie header.
  • In load balancer cookie mode, you can optionally configure fields such as cookieName, disableFallback, domain, path, maxAgeInSeconds, isSecure, and isHttpOnly, depending on the configuration path you are using.
  • If isSecure is set to true, use HTTPS or TLS listeners. Secure cookies are not accepted on HTTP-only listeners.

Learn more

To go deeper, start with