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.

Session affinity is enabled or disabled at the revision level. Note that if you enable session affinity on a Cloud Run revision and also use traffic splitting, there is no guarantee of affinity for the revision. That is, with a traffic split, a client will not necessarily connect to the same revision, and therefore not to the same instance.

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.

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, connections, 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 configuration 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.