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

1. ALWAYS specify --region for all gcloud run commands — omitting region causes interactive prompts that break automation.
2. NEVER use --allow-unauthenticated for internal services — use IAM-based authentication for service-to-service communication.
3. ALWAYS set memory and CPU limits explicitly — default limits may be too low for production workloads.
4. NEVER store secrets in environment variables directly — use Secret Manager with --set-secrets flag.
5. 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.