Google Cloud Run deploy loop
The unit of a deploy is a revision: an immutable snapshot of image + config. You never mutate a revision — you create a new one and shift traffic to it. That single fact drives both the deploy flow and the rollback flow below.
Set these once so every command is copy-pasteable:
PROJECT=my-project
REGION=us-central1
REPO=app # Artifact Registry repo
SERVICE=api
IMAGE="$REGION-docker.pkg.dev/$PROJECT/$REPO/$SERVICE"
1. Build & push (Artifact Registry)
Cloud Run has one hard runtime contract: the container must listen on
0.0.0.0:$PORT. Cloud Run injects PORT (default 8080); it is reserved, so
you cannot set it with --set-env-vars. Bind to it or the revision never becomes
ready ("failed to start and listen on the port defined by the PORT variable").
Multi-stage Dockerfile — small final image, honours $PORT:
# ---- build ----
FROM node:20-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build && npm prune --production
# ---- runtime ----
FROM node:20-slim
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
# Listen on $PORT (Cloud Run sets it; default 8080). Do NOT hardcode a port.
CMD ["node", "dist/server.js"]
Create the registry once, then build & push. Prefer Cloud Build (builds in GCP, no local Docker daemon, layer cache in the cloud):
# One-time: create the Docker repo
gcloud artifacts repositories create "$REPO" \
--repository-format=docker --location="$REGION" --project="$PROJECT"
# Build + push in one step, tagged with the commit for traceability
gcloud builds submit --tag "$IMAGE:$(git rev-parse --short HEAD)" --project="$PROJECT"
Local Docker alternative (authenticate the daemon to Artifact Registry first):
gcloud auth configure-docker "$REGION-docker.pkg.dev"
docker build -t "$IMAGE:$(git rev-parse --short HEAD)" .
docker push "$IMAGE:$(git rev-parse --short HEAD)"
Cloud Build trigger (CI on push). cloudbuild.yaml uses substitution
variables — built-ins like $PROJECT_ID, $SHORT_SHA, $COMMIT_SHA, and custom
ones that MUST start with _:
# cloudbuild.yaml
substitutions:
_REGION: us-central1
_SERVICE: api
steps:
- name: gcr.io/cloud-builders/docker
args: ['build', '-t', '${_REGION}-docker.pkg.dev/$PROJECT_ID/app/${_SERVICE}:$SHORT_SHA', '.']
- name: gcr.io/cloud-builders/docker
args: ['push', '${_REGION}-docker.pkg.dev/$PROJECT_ID/app/${_SERVICE}:$SHORT_SHA']
- name: gcr.io/google.com/cloudsdktool/cloud-sdk
entrypoint: gcloud
args: ['run', 'deploy', '${_SERVICE}', '--image',
'${_REGION}-docker.pkg.dev/$PROJECT_ID/app/${_SERVICE}:$SHORT_SHA',
'--region', '${_REGION}']
images: ['${_REGION}-docker.pkg.dev/$PROJECT_ID/app/${_SERVICE}:$SHORT_SHA']
options:
logging: CLOUD_LOGGING_ONLY
gcloud builds triggers create github \
--name="$SERVICE-main" --repo-name=my-repo --repo-owner=my-org \
--branch-pattern='^main$' --build-config=cloudbuild.yaml --project="$PROJECT"
2. Deploy
gcloud run deploy "$SERVICE" \
--image="$IMAGE:$(git rev-parse --short HEAD)" \
--region="$REGION" --project="$PROJECT" \
--service-account="$SERVICE@$PROJECT.iam.gserviceaccount.com" \
--cpu=1 --memory=512Mi --concurrency=80 \
--min-instances=0 --max-instances=10 \
--timeout=300 --port=8080
Auth — pick exactly one model:
- Public:
--allow-unauthenticated(grantsroles/run.invokertoallUsers). - IAM-gated:
--no-allow-unauthenticated, then grant specific callers:gcloud run services add-iam-policy-binding "$SERVICE" --region="$REGION" \ --member="serviceAccount:caller@$PROJECT.iam.gserviceaccount.com" \ --role="roles/run.invoker"
Config — plain config vs secrets:
--set-env-vars=KEY=val,KEY2=val2for non-sensitive config.--set-env-varsreplaces the whole set;--update-env-varsmerges;--remove-env-varsdrops.--set-secrets=API_KEY=my-secret:latestreferences Secret Manager — the value is never baked into the revision spec or image. Mount as a file with--set-secrets=/secrets/key=my-secret:latest. The runtime service account needsroles/secretmanager.secretAccessoron the secret. Never put a credential in--set-env-vars.
Sizing — see the gotchas below for the reasoning; the knobs are --cpu,
--memory, --concurrency, --min-instances, --max-instances, --timeout,
--cpu-boost (faster cold starts), --no-cpu-throttling (CPU always allocated,
for background work after the response).
Startup / liveness probes are set via the service YAML, not a deploy flag —
export, add the probe, and replace:
# service.yaml (excerpt)
spec:
template:
spec:
containers:
- image: REGION-docker.pkg.dev/PROJECT/app/api:SHA
startupProbe: # gates readiness; failures block the new revision
httpGet: { path: /healthz }
periodSeconds: 3
failureThreshold: 3
livenessProbe: # restarts a wedged container mid-serving
httpGet: { path: /healthz }
gcloud run services replace service.yaml --region="$REGION"
Canary / blue-green — deploy with no traffic and a tag, verify the tagged URL, then split traffic:
gcloud run deploy "$SERVICE" --image="$IMAGE:$SHA" --region="$REGION" \
--no-traffic --tag=canary # reachable at canary---<svc>.run.app
gcloud run services update-traffic "$SERVICE" --region="$REGION" \
--to-tags=canary=10 # 10% to canary
gcloud run services update-traffic "$SERVICE" --region="$REGION" --to-latest
3. Verify — read the traffic state, don't trust the exit code
gcloud run deploy exiting 0 means the API accepted the request; it does not
prove the new revision is healthy AND serving traffic. Read the artifact — the
served revision — before declaring the deploy done (see
../../rules/evidence-discipline.md):
# Which revision(s) actually receive traffic, and at what percent?
gcloud run services describe "$SERVICE" --region="$REGION" \
--format='value(status.traffic)'
# Latest revision's readiness — must be True
gcloud run revisions list --service="$SERVICE" --region="$REGION" \
--format='table(metadata.name, status.conditions[0].status, spec.containerConcurrency)' \
--limit=5
# Smoke the live URL
URL=$(gcloud run services describe "$SERVICE" --region="$REGION" --format='value(status.url)')
curl -fsS "$URL/healthz"
A deploy is done when the new revision name appears in status.traffic at the
percent you intended AND its Ready condition is True. A revision stuck
Ready=False while an OLD revision still serves 100% is the common silent failure:
the deploy "succeeded" and none of your code is live.
4. Rollback — shift traffic, never mutate
Revisions are immutable, so rollback is a traffic move to a known-good revision. No rebuild, no redeploy:
# Find the last-known-good revision
gcloud run revisions list --service="$SERVICE" --region="$REGION" --format='table(metadata.name, metadata.creationTimestamp)'
# Send 100% back to it
gcloud run services update-traffic "$SERVICE" --region="$REGION" \
--to-revisions=api-00042-abc=100
# Re-verify with the step-3 describe — confirm the good revision now owns 100%
Pin traffic to explicit revisions (not --to-latest) in production so a stray
gcloud run deploy cannot silently take 100% before you have verified it.
Config gotchas
- PORT is a contract, not a setting. Listen on
$PORT; never hardcode3000. You may change the port Cloud Run sends with--port, but the container must read the env var either way. - Env var vs Secret Manager. Config →
--set-env-vars. Anything secret →--set-secrets(Secret Manager), so it stays out of the revision spec, out ofdescribeoutput, and out of the image.--set-env-varsreplaces the whole map; reach for--update-env-varswhen you mean "add one". - Concurrency vs CPU.
--concurrencyis requests-per-instance (default 80, max 1000). A request-bound / I/O-bound service (mostly waiting on a DB or upstream) wants high concurrency + modest CPU — one instance serves many requests cheaply. A CPU-bound service (rendering, crypto, ML) wants low concurrency (even 1) + more--cpu, so requests don't starve each other. Setting both high is how you get tail-latency blowups. - Cold starts cost money to kill.
--min-instances=1+keeps warm instances but you pay for idle.--cpu-boostspeeds the cold start itself without a standing cost. See diagnostics for the full trade. - Request timeout has a ceiling.
--timeoutdefault is 300s, max 3600s (60 min). A long request that exceeds it returns 504 — distinct from a client timeout. Don't raise it to paper over a slow dependency.
Time budget
Every step here must finish inside a bounded wait — a deploy that "hangs" is
usually a revision failing its startup probe, not a slow API. Do not sit on an
unbounded gcloud run deploy; if it does not settle, poll revisions list for the
Ready condition and read the logs (see diagnostics). Keep any scripted wait
bounded and polled, per ../../rules/timeouts.md.
References
- references/terraform.md —
google_cloud_run_v2_service, IAM invoker binding, service-account wiring, Serverless VPC connector, multi-environment state. - references/diagnostics.md — cold starts, OOM, request-timeout debugging, log-based alerting.