oimiragieo/cloud-run

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.