Revisions & traffic splitting
Every deploy - a new image or just a config change - creates a new immutable revision. What makes revision a first-class resource is that you control which revision(s) serve traffic and in what proportion: split for canary/blue-green, pin for rollback, and tag for testing before any traffic flows.
Deploying a revision
Before Cloud Run can run your container, the image must live in a repository Cloud Run can reach - normally a Docker repository in Artifact Registry. You push the image there; Cloud Run pulls it at deploy time.
Deploy with the console, the gcloud CLI, a YAML config file, or Terraform. You hand Cloud Run a container image URL; it records that in a service configuration and produces a service plus a new revision.
The first deploy creates the service and its first revision; every later deploy to that service automatically creates a new revision.
- A service has exactly one container image at a time - each revision points at one image URL.
- Changing any service configuration setting creates a new revision too, even with no change to the image. Subsequent revisions inherit the previous config unless you explicitly override it.
It is not only a new image that produces a revision. Editing env vars, memory/CPU limits, concurrency, scaling bounds, the service account, or any other setting deploys a new revision. Roll back by shifting traffic to an older revision - the old config is still there, frozen.
To deploy, you need Owner, Editor, or both the Cloud Run Admin (roles/run.admin) and Service Account User (roles/iam.serviceAccountUser) roles - or a custom role with the equivalent permissions. Cloud Run Admin alone is not enough; you also need Service Account User to let the revision run as its service account.
A revision is immutable
Each time you change the service resource, Cloud Run makes an immutable copy of it - the revision. "Immutable" means you can never edit a revision in place; you only ever add new revisions. A revision bundles the container image with its service configuration.
Updating a service
The service resource holds the configuration that describes how Cloud Run runs your application. When you deploy a change to it, Cloud Run watches for the change and rolls out a new revision of your app.
- Send all traffic to the new revision as soon as it is healthy, or
- perform a gradual rollout by controlling the percentage of requests sent to the new revision.
Rolling out a new revision
Cloud Run does not cut traffic over the instant a revision is created. It scales up the new revision first and waits for it to be ready, while the current revision keeps serving:
Once the new instances are healthy, Cloud Run routes traffic to the new revision. Both revisions then autoscale independently: the previous revision stops receiving requests, goes idle, and eventually scales to zero; the new revision adds instances as demand requires.
For a controlled rollout, deploy with --no-traffic so the new revision receives 0% initially, then raise its percentage incrementally once you have vetted it.
Splitting traffic
Assign each revision a percentage of requests. This is how you roll back, gradually roll out, or run two revisions side by side.
- Configure percentages in the console,
gcloud, a YAML file, or Terraform. - Traffic changes are not instantaneous: when you change the split, in-flight requests run to completion and are never dropped - during the transition a request may land on either the new or the previous revision.
By default, requests from the same client can hit different container instances. Enabling session affinity makes Cloud Run try (best-effort, not guaranteed) to route a client to the same revision's instance. If you split traffic with session affinity on, the effective split can skew - see the docs on session affinity and traffic splitting.
Pinning traffic
Pinning sends 100% of traffic to one specific revision instead of the latest. It decouples deploying a revision from migrating traffic to it: add a new revision and Cloud Run will not automatically send it any traffic.
Pin when you want to roll back to a known-good revision, or test a new revision before moving production traffic to it.
Tagging revisions
A tag gives a revision its own URL - the tag name added as a prefix to the service URL (e.g. tag green on service hello becomes https://green---hello-xyz-uc.a.run.app) - without serving it any production traffic.
- Reach the tagged revision directly to test and vet it; when it is confirmed good, start migrating traffic to it (console,
gcloud, YAML, or Terraform). - A useful pattern: tag a revision with the commit ID used to build it.
Recap
The settings captured in a revision (changing any one deploys a new revision):
- Container image URL
- Container entrypoint and arguments
- Secrets and environment variables
- Request timeout
- Concurrency (max concurrent requests per instance)
- CPU / memory limits
- Scaling boundaries (min / max instances)
- Google Cloud config (service account, connectors)