Cloud Run Deployment Patterns

Stateless, scalable, cost-effective serverless containers on Google Cloud Run.

Core Constraints

Quick Reference

Port Binding

import os
import uvicorn

port = int(os.environ.get("PORT", 8080))
uvicorn.run(app, host="0.0.0.0", port=port)

Health Checks

Environment Variables

Common Anti-Patterns

Pydantic Settings and Cloud Run Deployment

Pydantic validates env vars at container startup (import time). A placeholder like "PLACEHOLDER_SET_BY_DEPLOY_SCRIPT" in an HttpUrl field crashes the container before any deploy script runs. Solution: deploy dependency services first, capture URLs, inject real values via sed/envsubst, then deploy. For self-referential WS_URL: deploy with placeholder, capture URL, update with gcloud run services update --set-env-vars. See reference.md § Pydantic Settings — Pre-Deployment Injection.

Pre-Deployment Validation Checklist

Run BEFORE building/pushing Docker images (saves 5-10 min):

• Code quality: just validate-branch (format, lint, type-check, tests)
• Dockerfile lint: hadolint/hadolint-action@v3.1.0
• YAML validation: python -c "import yaml; yaml.safe_load(open('.cloudrun/staging.yaml'))"
• Secrets verification: gcloud secrets describe <secret-name> --project=PROJECT_ID
• Connection pool capacity: max_instances × (pool_size + pool_overflow) ≤ database_max_connections. Tier limits: db-f1-micro = 25, db-g1-small = 100, db-standard-1 = 200+.

Docker Multi-Stage Build Pattern

3-stage Dockerfile with uv + BuildKit caching: fetch uv → install deps in builder → copy .venv + src into a minimal runtime image with a non-root user. Yields 50-70% faster rebuilds and ~200MB runtime image (vs 1GB+ with build tools). See reference.md § Docker Multi-Stage Build (uv) for the full Dockerfile.

Service Account Verification for CI/CD

CI/CD secrets (e.g., GCP_SA_KEY) may contain a different service account than expected, causing silent permission failures. Debug by extracting the SA email from the key JSON (jq -r .client_email key.json), then confirm its IAM bindings on the target resource (gcloud run services get-iam-policy <svc> / gcloud projects get-iam-policy <project>) match what the deploy expects before assuming a code fault.

VPC Egress Configuration

Entrypoint Shell Injection Prevention

Interpolating env vars into JSON via heredoc in entrypoint.sh is vulnerable to shell injection. jq provides safe JSON construction:

# BAD — shell injection via env var value
cat <<EOF > /app/config.json
{"apiUrl": "$API_URL"}
EOF

# GOOD — jq escapes values safely
jq -n --arg url "$API_URL" '{"apiUrl": $url}' > /app/config.json

Runtime config pipeline for Angular SPAs: runtime-config.model.ts → config.service.ts → config.initializer.ts → entrypoint.sh → .cloudrun/staging.yaml

See reference.md for connection pool settings, Redis configuration, and graceful shutdown patterns. See examples.md for thread-safe caching and complete health check implementations.