Setting session affinity (services)

This page shows how to enable session affinity for your Cloud Run service revision.

By default, session affinity is not enabled, so requests from the same client might be handled by different container instances, as shown here:

If you enable session affinity, Cloud Run routes sequential requests for a given client to the same revision container instance. Cloud Run uses a session affinity cookie with a TTL of 30 days, and inspects its value to identify multiple requests by the same client and directs all these requests to the same instance, as shown here:

Key behaviors to be aware of

As shown in the diagram above, with session affinity enabled, a client will reach the same container instance. However, note that the container instance can receive requests from different clients. Session affinity does not mean that the container instance is dedicated only to one client.

Due to the autoscaling behavior of Cloud Run, session affinity is best effort affinity. If the instance is restarted, terminated, overloaded or becomes unavailable as a result of the number of instances scaling in, session affinity is broken and further requests are routed to a different instance.

Although you can cache client session data in memory of container instances, you cannot assume that a client will always reconnect to the same instance, even when session affinity is enabled.

If you use Cloud Load Balancing, the session affinity of the Cloud Run service can be coupled to the session affinity of Global and Internal Load Balancers.

Session affinity and traffic splitting

You enable or disable session affinity at the revision level. If you enable session affinity on a Cloud Run revision and also use traffic splitting, session affinity takes precedence over any traffic splitting. In extreme cases, if a single client using session affinity is responsible for a vast majority of all requests, all of those requests can be routed to a given revision regardless of the traffic splitting configuration.

If you enable traffic splitting for revisions where some of the revisions have session affinity enabled and some do not, the result is that requests are gradually shifted towards revisions that have session affinity enabled, even though you do not explicitly change the traffic split configuration. The reason for this is that every request that doesn't have a session affinity cookie attached is subject to a random split, where some will eventually be assigned to a revision with session affinity and subsequently those requests will stay with that particular revision.

When updating the traffic splitting configuration for a Cloud Run service, subsequent requests with session affinity cookies attached might be assigned to a different revision. Cloud Run minimizes the number of clients that are redirected to a new revision.

For example, if a service was splitting traffic at 90%/10%, and the traffic split is updated to 80%/20%, then 10% of the traffic will be redirected to the revision that is now serving 20% of the traffic.

Set session affinity

Any configuration change leads to the creation of a new revision. Subsequent revisions will also automatically get this configuration setting unless you make explicit updates to change it.

You can set session affinity using the Google Cloud console, the gcloud command line, or using a .yaml file when you create a new service or deploy a new revision:

Console

Go to Cloud Run
Click Create Service if you are configuring a new service you are deploying to. If you are configuring an existing service, click on the service, then click Edit and Deploy New Revision.
If you are configuring a new service, fill out the initial service settings page as desired, then click Container, Networking, Security to expand the service configuration page.
Click the Connections tab.
Click the Session affinity text box.
Click Create or Deploy.

Command line

To specify session affinity, use the following command:

gcloud beta run services update SERVICE --session-affinity

Replace

SERVICE with the name of the service you are updating.

To remove session affinity, use the command

gcloud beta run services update SERVICE --no-session-affinity

YAML

You can download and view existing service configurations using the gcloud run services describe --format export command, which yields cleaned results in YAML format. You can then modify the fields described below and upload the modified YAML using the gcloud run services replace command. Make sure you only modify fields as documented.

To view and download the configuration:

gcloud run services describe SERVICE --format export > service.yaml

Add the run.googleapis.com/sessionAffinity: annotation:
```
spec:
 template:
   metadata:
     annotations:
       run.googleapis.com/sessionAffinity: 'BOOL'
```
Replace
- 'BOOL' with value 'true' to set session affinity, or 'false' to remove session affinity.
Replace the service with its new configuration using the following command:
```
gcloud run services replace service.yaml
```

View session affinity settings

To view the current session affinity settings for your Cloud Run service:

Console

Go to Cloud Run
Click the service you are interested in to open the Service details page.
Click the Revisions tab.
In the details panel at the right, the session affinity setting is listed under the Connections tab.

Command line

Use the following command:
```
gcloud run services describe SERVICE
```
Locate the session affinity setting in the returned configuration.