github.com/nginxinc/kubernetes-ingress@v1.12.5/examples/session-persistence/README.md (about)

     1  # Session Persistence
     2  
     3  It is often required that the requests from a client are always passed to the same backend container. You can enable such behavior with [Session Persistence](https://www.nginx.com/products/session-persistence/), available in the NGINX Plus Ingress controller.
     4  
     5  NGINX Plus supports *the sticky cookie* method. With this method, NGINX Plus adds a session cookie to the first response from the backend container, identifying the container that sent the response. When a client issues the next request, it will send the cookie value and NGINX Plus will route the request to the same container.  
     6  
     7  ## Syntax
     8  
     9  To enable session persistence for one or multiple services, add the **nginx.com/sticky-cookie-services** annotation to your Ingress resource definition. The annotation specifies services that should have session persistence enabled as well as various attributes of the cookie. The annotation syntax is as follows:
    10  ```
    11  nginx.com/sticky-cookie-services: "service1[;service2;...]"
    12  ```
    13  Here each service follows the following syntactic rule:
    14  ```
    15  serviceName=serviceName cookieName [expires=time] [domain=domain] [httponly] [secure] [path=path]
    16  ```
    17  The syntax of the *cookieName*, *expires*, *domain*, *httponly*, *secure* and *path* parameters is the same as for the [sticky directive](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#sticky) in the NGINX Plus configuration.
    18  
    19  ## Example
    20  
    21  In the following example we enable session persistence for two services -- the *tea-svc* service and the *coffee-svc* service:
    22  ```yaml
    23  apiVersion: networking.k8s.io/v1beta1
    24  kind: Ingress
    25  metadata:
    26    name: cafe-ingress-with-session-persistence
    27    annotations:
    28      nginx.com/sticky-cookie-services: "serviceName=coffee-svc srv_id expires=1h path=/coffee;serviceName=tea-svc srv_id expires=2h path=/tea"
    29  spec:
    30    rules:
    31    - host: cafe.example.com
    32      http:
    33        paths:
    34        - path: /tea
    35          backend:
    36            serviceName: tea-svc
    37            servicePort: 80
    38        - path: /coffee
    39          backend:
    40            serviceName: coffee-svc
    41            servicePort: 80
    42  ```
    43  For both services, the sticky cookie has the same *srv_id* name. However, we specify the different values of expiration time and  a path.
    44  
    45  ## Notes
    46  
    47  Session persistence **works** even in the case where you have more than one replicas of the NGINX Plus Ingress controller running.
    48  
    49  ## Advanced Session Persistence
    50  
    51  The NGINX Plus Ingress controller supports only one of the three session persistence methods available in NGINX Plus. Visit [this page](https://www.nginx.com/products/session-persistence/) to learn about all of the methods. If your session persistence requirements are more complex than the ones in the example above, you will have to use a different approach to deploying and configuring NGINX Plus without the Ingress controller. You can read the [Load Balancing Kubernetes Services with NGINX Plus](https://www.nginx.com/blog/load-balancing-kubernetes-services-nginx-plus/) blog post to find out more.