Canary Deployments on Cloud Run: Splitting Traffic Without Downtime

You just shipped a new container image to a live service, and the health checks look fine. Then error rates climb. With a traditional deployment, the fix is another full rollout—another gamble. Cloud Run traffic splitting removes that gamble by letting you send a small slice of production traffic to a new revision while the majority stays on the known-good version.

The core idea is simple: a revision is an immutable snapshot of your service configuration and container image. Traffic splitting assigns percentages of incoming requests to specific revisions. You can expose 1% of requests to the canary revision and keep 99% on the stable one. If the canary misbehaves, you shift traffic back instantly. No rebuild, no redeploy, no DNS changes.

How revisions and traffic allocation work

When you deploy a new image to Cloud Run, the platform creates a new revision rather than mutating the existing one. By default, the newest revision receives 100% of traffic. To run a canary, you explicitly divide that traffic between two or more revisions. Cloud Run then routes each incoming request according to those percentages.

Because each revision is a separate set of instances, scaling is independent. If your canary revision receives 10% of requests, Cloud Run provisions instances for it based on its own concurrency—the number of requests a single instance can handle at once—and scaling settings. You do not need to duplicate infrastructure manually.

Worked example: shifting 10% of traffic to a canary

Assume you have a service named order-api currently serving revision order-api-00042-abc. You have built a new image tagged v2 and want to expose it to 10% of requests.

First, deploy the new image. This creates a new revision but does not yet send it traffic. Run the following in your local terminal or Cloud Shell, authenticated with an account that has roles/run.admin or equivalent deploy and traffic-update permissions:

gcloud run deploy order-api \
  --image us-central1-docker.pkg.dev/my-project/order-api:v2 \
  --region us-central1 \
  --platform managed \
  --no-traffic

The --no-traffic flag is important: it ensures the new revision is created but receives 0% of requests. After deployment, note the new revision name from the output, for example order-api-00043-xyz.

Next, split the traffic. Replace the revision names with the ones from your project:

gcloud run services update-traffic order-api \
  --region us-central1 \
  --platform managed \
  --to-revisions order-api-00042-abc=90,order-api-00043-xyz=10

To confirm the allocation, describe the service and inspect the traffic field:

gcloud run services describe order-api \
  --region us-central1 \
  --platform managed \
  --format='value(traffic)'

You should see output listing both revisions with their assigned percentages. If the canary looks healthy after a few minutes, you can promote it by sending 100% of traffic to the new revision:

gcloud run services update-traffic order-api \
  --region us-central1 \
  --platform managed \
  --to-latest

If something goes wrong, rollback is a single command that restores the previous allocation. This changes live routing state, so run it only when you intend to divert traffic:

gcloud run services update-traffic order-api \
  --region us-central1 \
  --platform managed \
  --to-revisions order-api-00042-abc=100

Deciding when to promote or roll back

A canary is only useful if you watch the right signals. Cloud Run exports request metrics to Cloud Monitoring. The metric run.googleapis.com/request_count, filtered by revision_name, shows how many requests each revision actually serves. Over a few minutes, the canary should receive roughly its assigned share.

Compare that against latency and error metrics for the same revision. A practical decision rule: if the canary's rate of 5xx server-error responses or its p95 latency—the response time below which 95% of requests complete—is materially worse than the stable revision over a sustained window, roll back. If it is equal or better, increase the canary percentage in steps—say 10%, then 50%, then 100%—and repeat the observation.

You can also verify the split without leaving the terminal by tailing logs for both revisions, though the Monitoring chart in the Cloud Console gives a faster visual confirmation under the service's Metrics tab.

Limitations and trade-offs

Traffic splitting is not a universal safety net. It works best for stateless services. If your application stores session data in process memory or writes to a local disk path that is not shared between revisions, requests routed to the canary may behave differently than those on the stable revision. Design your service to keep state in an external store such as Memorystore, Firestore, or Cloud SQL before relying on a canary.

There is also a floor on the canary size. Cloud Run does not support fractional percentages below 1%. If you need to test with 0.1% of traffic, you will need a different routing layer, such as an API gateway or a service mesh in front of Cloud Run.

Finally, every deployment creates a revision, and a single service can hold at most 100 revisions. If you deploy frequently, you must delete old revisions before you can create new ones. Deleting a revision that still holds traffic requires moving that traffic first.

Actionable checklist

• Deploy the new image with --no-traffic so the revision exists without receiving requests.
• Assign a small percentage, such as 10%, using gcloud run services update-traffic.
• Verify the split with gcloud run services describe and the traffic field.
• Watch run.googleapis.com/request_count and error/latency metrics filtered by revision_name.
• Promote with --to-latest or roll back by restoring 100% to the previous revision.

Canary deployments on Cloud Run do not require a separate orchestrator or complex pipeline. A few gcloud commands and a Monitoring dashboard give you a reversible, production-safe rollout.