Cloud Run

Deploy and manage containerized applications on Google Cloud Run. Covers service deployment, revision management, traffic splitting, and log inspection.

When to Use

Deploying containerized web applications or APIs to Google Cloud
Managing Cloud Run services (scaling, traffic, revisions)
Setting up serverless container deployments
Inspecting Cloud Run service logs and metrics
Configuring environment variables and secrets for Cloud Run services

Prerequisites

Google Cloud SDK (gcloud) installed and authenticated
Docker or Cloud Build for container image building
A GCP project with Cloud Run API enabled

Core Commands

Deploy a Service

# Deploy from source (Cloud Build auto-builds)
gcloud run deploy SERVICE_NAME \
  --source . \
  --region us-central1 \
  --allow-unauthenticated

# Deploy from container image
gcloud run deploy SERVICE_NAME \
  --image gcr.io/PROJECT_ID/IMAGE:TAG \
  --region us-central1 \
  --memory 512Mi \
  --cpu 1 \
  --min-instances 0 \
  --max-instances 10

List Services

gcloud run services list --region us-central1 --format json

Get Service Details

gcloud run services describe SERVICE_NAME \
  --region us-central1 \
  --format json

View Logs

gcloud run services logs read SERVICE_NAME \
  --region us-central1 \
  --limit 100

# Tail logs in real-time
gcloud run services logs tail SERVICE_NAME \
  --region us-central1

Traffic Splitting

# Route 50% to latest, 50% to previous revision
gcloud run services update-traffic SERVICE_NAME \
  --region us-central1 \
  --to-revisions LATEST=50,REVISION_NAME=50

# Route all traffic to latest
gcloud run services update-traffic SERVICE_NAME \
  --region us-central1 \
  --to-latest

Environment Variables and Secrets

# Set env vars
gcloud run services update SERVICE_NAME \
  --region us-central1 \
  --set-env-vars KEY1=VALUE1,KEY2=VALUE2

# Mount secret as env var
gcloud run services update SERVICE_NAME \
  --region us-central1 \
  --set-secrets ENV_NAME=SECRET_NAME:latest

Delete a Service

gcloud run services delete SERVICE_NAME \
  --region us-central1 \
  --quiet

Workflow

Step 1: Prepare Container

Either use a Dockerfile or let Cloud Build auto-detect:

# Option A: Build and push manually
docker build -t gcr.io/PROJECT_ID/SERVICE_NAME:latest .
docker push gcr.io/PROJECT_ID/SERVICE_NAME:latest

# Option B: Deploy from source (Cloud Build handles it)
gcloud run deploy SERVICE_NAME --source .

Step 2: Deploy

gcloud run deploy SERVICE_NAME \
  --image gcr.io/PROJECT_ID/SERVICE_NAME:latest \
  --region us-central1 \
  --port 8080 \
  --memory 512Mi \
  --cpu 1

Step 3: Verify

# Get service URL
gcloud run services describe SERVICE_NAME \
  --region us-central1 \
  --format "value(status.url)"

# Test the endpoint
curl $(gcloud run services describe SERVICE_NAME \
  --region us-central1 \
  --format "value(status.url)")

Step 4: Monitor

gcloud run services logs read SERVICE_NAME --region us-central1 --limit 20

Iron Laws

ALWAYS specify --region for all gcloud run commands — omitting region causes interactive prompts that break automation.
NEVER use --allow-unauthenticated for internal services — use IAM-based authentication for service-to-service communication.
ALWAYS set memory and CPU limits explicitly — default limits may be too low for production workloads.
NEVER store secrets in environment variables directly — use Secret Manager with --set-secrets flag.
ALWAYS test deployments with traffic splitting before routing 100% to a new revision.

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
Missing --region flag	Interactive prompt breaks CI/CD	Always specify region explicitly
Public endpoints for internal APIs	Security exposure	Use IAM auth + Cloud Run invoker role
Hardcoded secrets in env vars	Secrets visible in service config	Use Secret Manager integration
No min-instances for latency-critical	Cold start adds 2-10s latency	Set --min-instances 1+ for critical paths
Single revision (no traffic split)	No rollback path	Always keep previous revision, split traffic gradually

MCP Tool Reference (cloud-run-mcp)

When the cloud-run-mcp MCP server is configured, these tools are available:

Tool	Description	Key Params
`deploy-file-contents`	Deploy code directly from file content	service_name, region, source_files
`list-services`	List all Cloud Run services	project_id, region
`get-service`	Get service details + URL	service_name, project_id, region
`get-service-log`	Fetch recent logs	service_name, project_id, limit
`deploy-local-folder`	Deploy from local directory	folder_path, service_name, region
`list-projects`	List GCP projects	—
`create-project`	Create new GCP project	project_id, project_name

MCP setup: npx @google-cloud/cloud-run-mcp or configure in Claude Desktop settings.json Auth: Application Default Credentials (gcloud auth application-default login) When to use MCP vs CLI: Use MCP tools when user asks "deploy this code" or "what services are running"; use gcloud CLI for advanced operations (IAM, VPC, secrets).

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

New pattern -> .claude/context/memory/learnings.md
Issue found -> .claude/context/memory/issues.md
Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.