Canary Deployments in Cloud Run: Using Traffic Splitting to Roll Out New Revisions

Why Split Traffic in Cloud Run?

When rolling out a new revision of a Cloud Run service you often want to expose only a fraction of users to the new code. Traffic splitting lets you route a specified percentage of requests to one revision while the rest go to another. This is the foundation for canary or blue‑green deployments without manual load‑balancer changes.

What the Feature Actually Does

• Traffic is distributed at the load‑balancer level. Each incoming HTTP request is assigned to a revision based on the configured percentages.
• The distribution is *statistical*; a single request will not necessarily hit the revision that owns its percentage.
• Percentages must add up to 100, and Cloud Run rounds to whole numbers. Any fraction less than 1% becomes 0%.
• If you omit a revision in the update command, Cloud Run automatically assigns the remaining traffic to the latest revision.
• All revisions share the same concurrency and instance limits, so a small traffic split can still hit capacity constraints if the revision is under‑provisioned.

Configuring a Split with gcloud

Below is a step‑by‑step example that splits traffic 30 % to rev-a and 70 % to rev-b for a service named my-service in the us-central1 region.

# Deploy two revisions first (the commands are placeholders).
# gcloud run deploy my-service --image gcr.io/my-project/rev-a --region us-central1 --platform managed
# gcloud run deploy my-service --image gcr.io/my-project/rev-b --region us-central1 --platform managed

# Assign traffic percentages.
# Run as a user with the "roles/run.admin" IAM role.

gcloud run services update-traffic my-service \
  --region us-central1 \
  --to-revision=rev-a=30 \
  --to-revision=rev-b=70

After the command completes, verify the split with:

gcloud run services describe my-service \
  --region us-central1 \
  --format='get(traffic)'

The output will list each revision and the percentage of traffic it receives.

Practical Verification

Traffic splitting is probabilistic. To confirm that the split works as expected:

1. Generate a steady stream of requests to https://my-service-hash.run.app using a tool like ab or wrk.
2. Check Cloud Logging for the serviceName and revisionName fields. Count the number of hits per revision over a period of minutes.
3. Optionally, enable Cloud Monitoring metrics for run.googleapis.com/request_count and filter by revision_id to see the split in real time.

Because the split is rounded, you might see 29 % or 71 % in practice, especially with a low traffic volume.

Limits and Edge Cases

• Percentage Rounding – Cloud Run truncates any fraction less than 1%. If you try to split 0.5 % to a revision, it will receive 0 % traffic.
• Sum Must Equal 100 – If the percentages you provide do not sum to 100, Cloud Run will adjust the last revision to make up the difference, but it will warn you in the output.
• Missing Revision – Omitting a revision in the command will route all remaining traffic to the latest revision. This can unintentionally expose all users to the new code.
• Concurrency & Instance Limits – Each revision shares the service’s concurrency and instance limits. A small traffic slice can still hit a capacity ceiling if the revision’s instances are saturated.
• Cross‑Service Routing – Traffic splitting applies only within a single service. If you need domain‑based routing between services, you must configure a separate load balancer or use Cloud Endpoints.

Common Mistakes

1. Assuming Per‑Request Routing – Expecting that 30 % of requests will hit rev-a in a deterministic way will lead to confusion. Use logging to confirm the statistical distribution.
2. Leaving Out a Revision – Forgetting to include a revision in the split can cause all traffic to jump to the latest revision. Double‑check the output of gcloud run services describe.
3. Ignoring Rounding Effects – When working with very low traffic volumes, a 1 % split might be effectively 0 %. Plan your split percentages accordingly.
4. Not Monitoring Concurrency – A new revision may be under‑provisioned, causing latency spikes even with a small traffic share. Monitor run.googleapis.com/instance_count and run.googleapis.com/concurrency metrics.

Rolling Back a Split

To revert to 100 % traffic on the latest revision, run:

gcloud run services update-traffic my-service \
  --region us-central1 \
  --to-revision=latest=100

Or delete the split configuration entirely by resetting the traffic distribution to the default.

Conclusion

Traffic splitting in Cloud Run is a lightweight, declarative way to perform canary releases. By understanding its rounding behavior, limits, and the need for monitoring, you can safely expose a portion of users to new revisions while keeping the rest on stable code.