Configure session affinity for Knative services

1. Create a Knative service with session affinity

The following steps demonstrate a configuration that maps each session to a dedicated pod, and the pod is automatically scaled in after 5 minutes of inactivity. This is suitable for short-term stateful tasks, such as API debugging or short-lived inference sessions.

For long-running AI inference sessions, we recommend setting session-timeout to 30m or longer to prevent premature session termination.

1. Log on to the ACS console. In the left navigation pane, click Clusters.

2. On the Clusters page, click the name of the target cluster. In the left navigation pane, choose Applications > Knative.

3. On the Services page, select default for Namespace, click Create from Template, select Custom for Sample Template, and use the following YAML to deploy the service.

   This example uses the recommended default values for the corresponding annotations. To customize the timeout, cookie name, or number of sessions per pod, see Annotation parameters.

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: my-sessions-per-pod
   spec:
     template:
       metadata:
         annotations:
           # Enable session affinity.
           serving.knative.dev/session-affinity: "true"
           # The idle timeout period for a session. The pod is automatically scaled in after the timeout.
           serving.knative.dev/session-timeout: "5m"
           # The name of the cookie used for session identification.
           serving.knative.dev/session-affinity-cookie: "demo"
           # Use the number of sessions as the metric for autoscaling.
           autoscaling.knative.dev/metric: "session"
           # The maximum number of sessions that each pod can handle.
           autoscaling.knative.dev/target: "1"
       spec:
         containers:
           - image: registry-cn-hangzhou-vpc.ack.aliyuncs.com/acs/knative-samples-helloworld-go-session:v1.0-bfdce98

4. After the my-sessions-per-pod deployment is complete, on the Services page, obtain the Gateway address and the service's Default Domain.

5. Verify session routing.

   Requests with different cookie values should be routed to different pods.

   • Accessing with Cookie demo=11 routes the request to Pod A.

     curl -i -H "Host: my-sessions-per-pod.default.example.com" http://47.xx.xx.xx \
       -H "Cookie: demo=11"

     Expected output from pod A:

     HTTP/1.1 200 OK
     Date: Tue, 21 Apr 2026 09:57:44 GMT
     Content-Type: text/plain; charset=utf-8
     Content-Length: 77
     Connection: keep-alive
     
     Hello World!
     
     Cookies:
       Name:  demo
       Value: 11
     
     Raw Cookie Header: demo=11

   • A request with Cookie demo=22 is routed to Pod B.

     curl -i -H "Host: my-sessions-per-pod.default.example.com" http://47.xx.xx.xx \
       -H "Cookie: demo=22"

   • Expected output from pod B:

     HTTP/1.1 200 OK
     Date: Tue, 21 Apr 2026 11:27:15 GMT
     Content-Type: text/plain; charset=utf-8
     Content-Length: 77
     Connection: keep-alive
     
     Hello World!
     
     Cookies:
       Name:  demo
       Value: 22
     
     Raw Cookie Header: demo=22

6. Confirm that pods for both sessions have been created.

   kubectl get pods -l serving.knative.dev/service=my-sessions-per-pod

   The expected output shows two pods in the Running state, handling the sessions for Cookie demo=11 and demo=22. The number of pods matches the number of active sessions, which indicates that session-aware autoscaling has taken effect.

(Optional) 2. Configure Redis storage mode

In a production environment with multiple Activator replicas, you must use Redis storage mode to ensure session consistency. Set the Redis address in the config-defaults ConfigMap in the knative-serving namespace.

For a detailed comparison of the two modes, see Comparison of session storage modes.

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-defaults
  namespace: knative-serving
data:
  # Replace this with the connection address of your Redis instance.
  session-storage-redis-addr: "r-xxxxxxxxxxxx.redis.rds.aliyuncs.com:6379"

Annotation parameters

The following are all the annotations for session affinity. You can configure them as needed in the spec.template.metadata.annotations field of a Knative service.

Comparison of session storage modes

In-memory mode works out of the box and is suitable for development and testing. Redis mode supports multiple Activator replicas and is better suited for production environments.

Choosing between in-memory and Redis modes

Choose the appropriate storage mode based on your deployment scale and reliability requirements.

Troubleshooting session affinity

Check the following:

1. Whether serving.knative.dev/session-affinity: "true" is set in the spec.template.metadata.annotations field of the Revision.

2. Ensure that the request carries a recognizable session key.

3. Determines whether the value of session-affinity-cookie is the same as the request cookie name when you use a custom cookie.

4. View the Activator logs: kubectl -n knative-serving logs -l app=activator -c activator

Can a Knative service simultaneously use session and concurrency metrics?

No. The session, concurrency, and RPS scaling metrics are mutually exclusive. A service can be configured with only one of them.

Session affinity and canary releases

The two features are orthogonal. Traffic is first distributed to different revisions based on the configured percentages. Within each revision, session affinity is maintained independently.