Gradual Rollouts with Cloud Run Traffic Splitting: A Practical Guide

The problem: you need to update a Cloud Run service without risking a sudden surge of errors

When you push a new version of a Cloud Run service, all incoming traffic switches to that revision at once. If the new revision contains a breaking change or a performance regression, every user sees the issue immediately. You want a way to shift traffic gradually, watch key metrics, and roll back instantly if something goes wrong—without touching DNS or load‑balancer settings.

What Cloud Run traffic splitting does

Traffic splitting lets you assign a percentage of incoming requests to each revision of a single Cloud Run service. The percentages must total 100 %. The platform routes requests based on the configured split, so you can run a canary release, an A/B test, or a gradual rollout while keeping the same service URL.

Setting up a gradual rollout

1. Deploy the first revision (v1)

   Run this command in Cloud Shell or a local machine with the gcloud CLI installed. You need the IAM role roles/run.admin (or roles/run.serviceAdmin) on the project.

   gcloud run deploy helloservice \
     --image=gcr.io/cloudrun/hello \
     --tag=v1 \
     --platform=managed \
     --region=$REGION \
     --allow-unauthenticated
   

   Replace $REGION with your chosen region (e.g., us-central1). The service name is helloservice; the revision will be named something like helloservice-v1-xxxx.

2. Deploy the second revision (v2)

   Deploy a new image under the same service name. This creates a second revision.

   gcloud run deploy helloservice \
     --image=gcr.io/cloudrun/hello:v2 \
     --tag=v2 \
     --platform=managed \
     --region=$REGION \
     --allow-unauthenticated
   

3. Update the traffic split

   Start with a small canary, for example 10 % to v2 and 90 % to v1.

   gcloud run services update-traffic helloservice \
     --to-revisions=helloservice-v1-xxxx=90,helloservice-v2-yyyy=10 \
     --platform=managed \
     --region=$REGION
   

   You can find the exact revision names with gcloud run services describe helloservice --platform=managed --region=$REGION --format='value(spec.template.metadata.name)'.

4. Increase the split gradually

   After monitoring, raise the v2 share (e.g., to 50 %).

   gcloud run services update-traffic helloservice \
     --to-revisions=helloservice-v1-xxxx=50,helloservice-v2-yyyy=50 \
     --platform=managed \
     --region=$REGION
   

Verifying the split works

After each traffic‑update, wait a few seconds for the change to propagate globally. Then:

• Manual check: Send a few requests with curl (or your client) and note the response. If v1 returns "Hello v1" and v2 returns "Hello v2", you should see roughly the expected ratio.
• Observability check: In Cloud Monitoring, open the Cloud Run > Request count metric, filter by resource.labels.service_name = "helloservice" and resource.labels.revision_name. The chart should show the traffic distribution matching the percentages you set.

If you see a sudden spike in error latency or error rate for the new revision, you can roll back instantly by moving traffic back to the previous revision:

gcloud run services update-traffic helloservice \
  --to-revisions=helloservice-v1-xxxx=100,helloservice-v2-yyyy=0 \
  --platform=managed \
  --region=$REGION

Trade‑offs and limitations

• Scope: Splitting works only within a single Cloud Run service and region. You cannot split traffic across different services or across regions.
• Backward compatibility required**: The new revision must accept the same environment variables, secrets, and API contract as the old one. Breaking changes will affect the portion of traffic sent to the new revision.
• No per‑request routing: You cannot route based on headers, user ID, or other attributes. If you need that granularity, implement it in your application or place a service mesh/API gateway in front of Cloud Run.
• Cold‑start latency unaffected**: Each revision’s instances still experience cold starts independently; the split does not reduce latency for individual instances.

Actionable closing

Start small: expose 5‑10 % of traffic to the new revision, monitor error rate and latency in Cloud Monitoring, then increase the share in steps of 10‑20 % until you reach 100 %. If anything looks off, roll back with a single gcloud run services update-traffic command. This approach gives you zero‑downtime deployments, observable canary validation, and an instant safety net—all without changing your service’s public URL.