Cloud Run — Health Check Triggered Cascading 503 Failures

Every developer eventually hits the same wall: the app works perfectly on your laptop, but getting it into production means provisioning servers, configuring load balancers, managing autoscaling groups, and babysitting infrastructure at 2am. For teams that just want their code to run reliably at scale, that overhead is expensive, slow, and frankly soul-crushing. Cloud Run was built to eliminate exactly that gap between 'it works on my machine' and 'it's live in production'.

Cloud Run is Google's fully managed serverless container platform. Unlike AWS Lambda, which forces you into specific runtimes and tiny deployment packages, Cloud Run runs any container that listens on a port and responds to HTTP. That one constraint — your app must be stateless and HTTP-driven — unlocks everything else: automatic scaling from zero to thousands of concurrent requests, per-100ms billing, global deployment, and zero server management. It bridges the gap between rigid Function-as-a-Service platforms and the full complexity of Kubernetes.

By the end of this article you'll understand exactly how Cloud Run's request-driven execution model works, how to containerize a real Node.js API and deploy it with a single command, how to wire up environment variables and secrets the right way, and how to avoid the three mistakes that burn developers on their first production deployment. You'll also walk away knowing how to answer the Cloud Run questions that actually come up in DevOps and platform engineering interviews.

How Cloud Run's Request-Driven Model Actually Works

Before writing a single line of code, you need to understand Cloud Run's mental model — because it changes how you architect your app.

When no requests are hitting your service, Cloud Run scales it to zero. There are literally no running instances. The moment a request arrives, Cloud Run starts a container instance, routes the request to it, and keeps that instance alive to handle more requests for a short idle period. If traffic spikes, it starts more instances in parallel. This is called request-driven scaling, and it's the core reason Cloud Run is cheap for low-traffic services and effortless to scale for high-traffic ones.

The critical implication: your container must be stateless. Don't store session data in memory between requests, don't write to local disk expecting it to persist, and don't open background threads that do work outside of a request lifecycle. Any state must live in an external system — Cloud SQL, Firestore, Redis, or Cloud Storage.

Cold starts are the one real trade-off. When Cloud Run starts a fresh instance, there's a brief delay (typically 200ms–2s depending on your image size and runtime) before it can serve traffic. For latency-sensitive APIs, you can set a minimum instance count of 1 to keep a warm instance always running — at the cost of paying for that idle time. For batch jobs or internal tools, cold starts usually don't matter at all.

#!/bin/bash
# ─────────────────────────────────────────────────────────────
# GOAL: Build a Docker image, push it to Artifact Registry,
#       and deploy it as a Cloud Run service in one script.
#
# PREREQUISITES:
#   - gcloud CLI installed and authenticated
#   - Docker installed and running
#   - A GCP project with billing enabled
# ─────────────────────────────────────────────────────────────

# Replace these with your actual values
GCP_PROJECT_ID="my-production-project"
GCP_REGION="us-central1"
SERVICE_NAME="product-api"
IMAGE_NAME="us-central1-docker.pkg.dev/${GCP_PROJECT_ID}/cloud-run-services/${SERVICE_NAME}"

# Step 1: Authenticate Docker to push to Artifact Registry
# gcloud configures Docker credentials automatically — no manual login needed
gcloud auth configure-docker us-central1-docker.pkg.dev --quiet

# Step 2: Build the Docker image and tag it for Artifact Registry
# The tag format must match your Artifact Registry repository path exactly
docker build \
  --tag "${IMAGE_NAME}:latest" \
  --platform linux/amd64 \
  . # <── build context is the current directory (where Dockerfile lives)

# Step 3: Push the image to Artifact Registry
# Cloud Run pulls from here at deploy time — it never touches Docker Hub by default
docker push "${IMAGE_NAME}:latest"

# Step 4: Deploy to Cloud Run
gcloud run deploy "${SERVICE_NAME}" \
  --image "${IMAGE_NAME}:latest" \
  --platform managed \
  --region "${GCP_REGION}" \
  --allow-unauthenticated \
  --port 8080 \
  --memory 512Mi \
  --cpu 1 \
  --min-instances 0 \
  --max-instances 100 \
  --concurrency 80
  # --allow-unauthenticated: makes the service publicly accessible
  # --concurrency 80: each instance handles up to 80 simultaneous requests
  # --min-instances 0: scale to zero when idle (cheapest option)
  # --max-instances 100: hard cap to prevent runaway billing

Building a Real Containerized API That Cloud Run Will Love

Cloud Run's only requirement is that your container listens on the port defined by the PORT environment variable. That's it. Cloud Run injects PORT at runtime — you don't hardcode it. This one detail trips up a lot of developers who hardcode 3000 or 8080 in their app and then wonder why health checks fail.

Here's a real-world pattern: a lightweight Node.js product API. Notice how the app reads PORT from the environment, handles a health check endpoint (which Cloud Run hits to confirm your container started successfully), and does clean shutdown on SIGTERM (Cloud Run sends SIGTERM before killing an instance during scale-down, giving you a chance to finish in-flight requests).

The Dockerfile matters as much as the code. Keep your image small — every extra MB adds cold start latency. Use multi-stage builds to separate build dependencies from the runtime image, use Alpine-based base images, and always run as a non-root user. Cloud Run doesn't require root, and running as root is a security smell that will get flagged in any serious security audit.

# ── Stage 1: Install dependencies ──────────────────────────────
# We use a full Node image here because we need npm to install packages
FROM node:20-alpine AS dependency-installer
WORKDIR /build

# Copy package files first — Docker layer caching means if these
# haven't changed, npm install is skipped entirely on rebuild
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
# npm ci is stricter than npm install — it respects package-lock.json exactly
# --omit=dev drops devDependencies so they don't bloat the final image

# ── Stage 2: Runtime image ──────────────────────────────────────
# Start fresh from a minimal Alpine image — no build tools, no npm cache
FROM node:20-alpine AS runtime
WORKDIR /app

# Create a non-root user — Cloud Run doesn't need root and neither does your app
RUN addgroup --system api-group && adduser --system --ingroup api-group api-user

# Copy only what we need: the installed node_modules and the app source
COPY --from=dependency-installer /build/node_modules ./node_modules
COPY src/ ./src/
COPY package.json ./

# Switch to non-root user before the app starts
USER api-user

# Cloud Run injects PORT at runtime — we expose 8080 as a documentation hint
# but the app itself must read process.env.PORT, not hardcode this number
EXPOSE 8080

CMD ["node", "src/server.js"]

Wiring Up Secrets, Environment Variables, and Service Accounts Correctly

This is where most tutorials stop, and where real production deployments begin. Your app almost certainly needs secrets — database passwords, API keys, JWT signing keys. Hardcoding them into environment variables in your Cloud Run service definition means they show up in plaintext in your deployment history and in anyone's gcloud run describe output. That's a compliance and security problem.

The right pattern is to store secrets in Google Secret Manager and grant your Cloud Run service's service account permission to read them. Cloud Run can then mount secrets as environment variables or as files at startup — they're injected at runtime, never baked into the image or visible in the service config.

Service accounts are equally important. By default, Cloud Run uses the Compute Engine default service account, which has editor-level access to your entire project. That's far too permissive. Create a dedicated service account for each Cloud Run service, grant it only the specific IAM roles it needs (like roles/secretmanager.secretAccessor and roles/cloudsql.client), and attach it at deploy time. This is the principle of least privilege, and it's not optional in production.

#!/bin/bash
# ─────────────────────────────────────────────────────────────
# GOAL: Create a dedicated service account for the product-api,
#       store secrets in Secret Manager, and deploy Cloud Run
#       with proper IAM bindings — no plaintext secrets anywhere.
# ─────────────────────────────────────────────────────────────

GCP_PROJECT_ID="my-production-project"
GCP_REGION="us-central1"
SERVICE_NAME="product-api"
SERVICE_ACCOUNT_NAME="product-api-runner"
SERVICE_ACCOUNT_EMAIL="${SERVICE_ACCOUNT_NAME}@${GCP_PROJECT_ID}.iam.gserviceaccount.com"
IMAGE_NAME="us-central1-docker.pkg.dev/${GCP_PROJECT_ID}/cloud-run-services/${SERVICE_NAME}:latest"

# Step 1: Create a dedicated service account for this Cloud Run service
# Never use the default Compute SA — it has far too many permissions
gcloud iam service-accounts create "${SERVICE_ACCOUNT_NAME}" \
  --display-name "Service Account for product-api Cloud Run service" \
  --project "${GCP_PROJECT_ID}"

# Step 2: Store the database password in Secret Manager
# Read the secret from stdin so it never appears in your shell history
echo -n "super-secret-db-password" | \
  gcloud secrets create DB_PASSWORD \
    --data-file=- \
    --replication-policy="automatic" \
    --project "${GCP_PROJECT_ID}"
# The -n flag on echo prevents a trailing newline — important for passwords!

# Step 3: Grant the service account permission to READ this specific secret
# Note: secretAccessor only allows reading — not creating or deleting secrets
gcloud secrets add-iam-policy-binding DB_PASSWORD \
  --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}" \
  --role="roles/secretmanager.secretAccessor" \
  --project "${GCP_PROJECT_ID}"

# Step 4: Deploy Cloud Run with the dedicated service account
# and mount the secret as an environment variable at runtime
gcloud run deploy "${SERVICE_NAME}" \
  --image "${IMAGE_NAME}" \
  --platform managed \
  --region "${GCP_REGION}" \
  --service-account "${SERVICE_ACCOUNT_EMAIL}" \
  --update-secrets="DB_PASSWORD=DB_PASSWORD:latest" \
  # ↑ Format: ENV_VAR_NAME=SECRET_NAME:VERSION
  # Cloud Run fetches the secret at startup and injects it as an env var
  # Your app reads it with: process.env.DB_PASSWORD — same as any env var
  --set-env-vars="NODE_ENV=production,DB_HOST=10.0.0.5,DB_NAME=products_db" \
  --allow-unauthenticated

# Step 5: Verify the deployment and check the service account is correct
gcloud run services describe "${SERVICE_NAME}" \
  --region "${GCP_REGION}" \
  --format="value(spec.template.spec.serviceAccountName)"

Deploying and Monitoring: From First Deploy to Production Observability

Deploying your container is just the beginning. Once it's live, you need to monitor health, latency, and errors. Cloud Run integrates directly with Cloud Monitoring and Logging, but you need to know what to look for.

First, set up a health check endpoint that validates your app's critical dependencies — database connectivity, cache status, external API reachability. Cloud Run uses this for startup probes and eventually for traffic routing. A failing health check means the revision won't receive traffic.

Second, enable Cloud Logging and set log-based alerts. The most common production issues are 5xx errors, latency spikes, and concurrency limit hits. Cloud Run logs every request with status code, latency, and instance id. You can create metrics from these logs.

Third, understand concurrency. By default, each instance handles up to 80 concurrent requests. If your app is I/O-bound (calling a database or external API), increase concurrency to 250+. If it's CPU-bound, lower it. Monitor the container instance count metric — if it's constantly maxing out, reduce concurrency or increase max-instances.

Finally, set up notifications for revision failures and cost anomalies. Cloud Run bills per 100ms, so a runaway instance can cause unexpected bills. Set a budget alert in Google Cloud Billing.

#!/bin/bash
# ─────────────────────────────────────────────────────────────
# GOAL: Create a log-based metric for 5xx errors, set up a
#       Cloud Monitoring alert, and view recent logs.
# ─────────────────────────────────────────────────────────────

# Create a log-based counter metric for HTTP 5xx responses
gcloud logging metrics create product-api-5xx \
  --description "Count of 5xx responses for product-api" \
  --log-filter='resource.type="cloud_run_revision" AND resource.labels.service_name="product-api" AND http_request.status >= 500'

# Create an alert policy (simplified — actually done via Monitoring UI or Terraform)
# This command just outlines the concept
# gcloud alpha monitoring policies create ...

# View recent 5xx logs directly
gcloud logging read 'resource.type="cloud_run_revision" AND resource.labels.service_name="product-api" AND http_request.status >= 500' \
  --limit 10 \
  --format="table(timestamp, http_request.status, http_request.latency)"

Advanced: VPC Connectors, Custom Domains, and Traffic Splitting

Once you're comfortable with basic deployments, you'll hit the advanced scenarios: connecting to private resources (like Cloud SQL with private IP), using a custom domain with SSL, and rolling out canary revisions.

VPC Connector: To reach resources inside your VPC (e.g., a private Cloud SQL instance), you need a Serverless VPC Access connector. Create it in your VPC, then attach it to your Cloud Run service with --vpc-connector. Without it, your container can access the internet but not your private resources. This is a common cause of 'connection refused' that's hard to debug.

Custom domains: By default, you get a .run.app URL. For production, map a custom domain using gcloud beta run domain-mappings create. Cloud Run auto-provisions an SSL certificate via Google-managed certificates. The gotcha: DNS propagation can take 10–30 minutes, and the domain must be verified (you need access to manage DNS records).

Traffic splitting: You can send a percentage of traffic to a specific revision. This powers canary deployments and A/B testing. Use gcloud run services update-traffic to split e.g., 95% to stable, 5% to new-revision. Rollback is instant: set 100% back to the old revision.

All three features require the managed platform (not Cloud Run on GKE).

#!/bin/bash
# ─────────────────────────────────────────────────────────────
# GOAL: Set up VPC connector, map custom domain, split traffic.
# ─────────────────────────────────────────────────────────────

VPC_CONNECTOR_NAME="my-connector"
VPC_NETWORK="default"
REGION="us-central1"

# Step 1: Create a Serverless VPC Access connector (requires VPC Access API)
# Note: this takes about 2-3 minutes to provision
gcloud compute networks vpc-access connectors create ${VPC_CONNECTOR_NAME} \
  --region ${REGION} \
  --network ${VPC_NETWORK} \
  --range 10.8.0.0/28

# Step 2: Deploy with VPC connector (and no egress settings)
gcloud run deploy product-api \
  --vpc-connector ${VPC_CONNECTOR_NAME} \
  --vpc-egress=private-ranges-only  # only route RFC1918 traffic through connector

# Step 3: Map custom domain
# First verify ownership: create a TXT record as instructed by the command
# gcloud beta run domain-mappings create --service product-api --domain api.mycompany.com

# Step 4: Traffic splitting – 5% canary
gcloud run services update-traffic product-api \
  --to-revisions=product-api-00001-wib=95,product-api-00002-xyz=5

# Rollback: send all traffic back to the old revision
gcloud run services update-traffic product-api \
  --to-revisions=product-api-00001-wib=100