Cloud Run Traffic Splitting: Route Requests to New Revisions Safely

The problem: all-or-nothing deployments

When you deploy a new revision to Cloud Run, the default behavior sends 100% of traffic to the latest revision. If that revision contains a bug, every user request fails until you roll back. Traffic splitting removes that cliff by letting you route a controlled percentage of requests to a new revision while the majority stays on the known-good one.

Approach	User exposure	Recovery action
Immediate promotion	100% of requests	Redeploy previous revision or update traffic
Traffic split	Configured percentage	Single update-traffic call to 100% stable

Desired outcome

Route a specific percentage of incoming requests to a candidate revision while the remaining traffic continues to hit the current stable revision. This lets you observe real-world behavior—latency, error rates, and downstream effects—before promoting the candidate to full production traffic.

Prerequisites

• An existing Cloud Run service with at least two deployed revisions: the current stable revision and the candidate you want to test.
• The Google Cloud CLI (gcloud) installed locally or access to Cloud Shell. These commands assume a recent version of the CLI.
• IAM permissions to update and read the service, typically roles/run.admin or the narrower run.services.update and run.services.get permissions.
• The candidate revision must be deployed and healthy. Cloud Run does not block traffic to an unhealthy revision, but sending requests to one will increase error rates.

Procedure: split traffic between revisions

Run the following command from your terminal or Cloud Shell. Replace the placeholders with your actual values:

gcloud run services update-traffic SERVICE_NAME \
  --region=REGION \
  --platform=managed \
  --to-revisions=REVISION_CURRENT=90,REVISION_CANDIDATE=10

Replace SERVICE_NAME with your Cloud Run service name, REGION with the region where the service runs (for example, us-central1), and the two revision names with the exact revision identifiers. The numbers after each revision name are percentage weights; they must total 100.

If you omit --platform=managed, the command targets Cloud Run for Anthos. For most users, --platform=managed is correct.

The command changes state immediately, but propagation can take a few seconds. During that window, some requests may still hit the previous routing configuration.

Expected checks

Confirm the split took effect and that traffic is flowing as intended.

Verify the routing configuration

Describe the service and inspect the traffic block:

gcloud run services describe SERVICE_NAME \
  --region=REGION \
  --platform=managed \
  --format='value(traffic)'

The output lists each revision and its assigned percentage. Verify that the candidate revision shows the expected weight.

Observe real request distribution

Send a series of requests to the service URL and check which revision served each one. If your application emits a revision identifier in a response header or log field, use that to confirm the split. For example, with curl:

for i in $(seq 1 20); do
  curl -s -o /dev/null -w "%{header_json}\n" https://SERVICE_URL/
done

Inspect the headers or response body for the revision name. With only 20 requests, a 90/10 split may not appear exact; treat small samples as directional rather than precise.

Check Cloud Monitoring metrics

In the Google Cloud console, open Cloud Monitoring and filter for your Cloud Run service. Look at request count broken down by revision. The observed percentages should align with the configured split within a reasonable tolerance, roughly ±5% for a meaningful sample size. If the candidate revision receives zero requests, the split likely did not apply.

Filter Cloud Logging

Use Cloud Logging to see which revision handled each request. Filter with:

resource.type="cloud_run_revision"
logName="projects/PROJECT_ID/logs/run.googleapis.com%2Frequests"

Examine the revision_name field in the log entries to confirm distribution across both revisions.

Recovery options

If the candidate revision causes errors or unexpected behavior, shift traffic back immediately.

Roll back to the stable revision

Send 100% of traffic to the known-good revision:

gcloud run services update-traffic SERVICE_NAME \
  --region=REGION \
  --platform=managed \
  --to-revisions=REVISION_CURRENT=100

This is the fastest recovery path because it does not require redeploying anything.

Remove the candidate revision

If you want to clean up the failed candidate entirely, delete the revision after traffic has been moved away:

gcloud run revisions delete REVISION_CANDIDATE \
  --region=REGION \
  --platform=managed

You cannot delete a revision that still receives traffic. Ensure the candidate is at 0% before deleting it.

Limitations and practical considerations

• Same service only: Traffic splitting works between revisions of a single Cloud Run service. You cannot split traffic across different services using this command; that requires an external load balancer.
• Propagation delay: Routing changes are not instantaneous. Expect a brief window where requests may follow the old configuration.
• Health checks: Cloud Run does not automatically withhold traffic from a revision that fails startup or readiness probes. If the candidate is unhealthy, the split will route errors to it.
• No built-in canary automation: The update-traffic command sets a static split. It does not automatically promote or roll back based on error rates. You must monitor and adjust manually or build automation on top.

Summary of the workflow

Deploy the candidate revision, split traffic with gcloud run services update-traffic, verify the distribution through service description, logs, and metrics, then either promote the candidate by moving it to 100% or roll back by restoring the stable revision. The same command handles both directions, so recovery is a single CLI call.