GCP Cloud Run Skill

A Claude Code skill for deploying containerized applications on Google Cloud Run — covering service configuration, automatic scaling, custom domains, Cloud SQL connections, and CI/CD integration.

When to Use This Skill

Choose this skill when:

• Deploying containerized web applications or APIs on Google Cloud
• Setting up auto-scaling serverless containers
• Connecting Cloud Run services to Cloud SQL, Memorystore, or Pub/Sub
• Configuring custom domains and SSL for Cloud Run services
• Setting up CI/CD with Cloud Build for automatic deployments
• Managing environment variables and secrets in Cloud Run

Consider alternatives when:

• You need long-running background processing over 60 minutes (use GKE or Compute Engine)
• You need WebSocket connections beyond 60 minutes (use GKE)
• You need GPU compute (use Vertex AI or Compute Engine with GPUs)

Quick Start

Copy
# Authenticate with Google Cloud
gcloud auth login
gcloud config set project my-project-id

# Build and deploy to Cloud Run
gcloud run deploy my-service \
  --source . \
  --region us-central1 \
  --allow-unauthenticated

Copy
# Dockerfile for Cloud Run
FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/package.json ./

# Cloud Run provides PORT environment variable
ENV PORT=8080
EXPOSE 8080
CMD ["node", "dist/index.js"]

Core Concepts

Cloud Run Configuration

Setting	Default	Recommended	Description
CPU	1	1-2	vCPU per instance
Memory	512Mi	512Mi-2Gi	RAM per instance
Min Instances	0	0 (dev), 1 (prod)	Minimum running instances
Max Instances	100	10-100	Maximum scaling limit
Concurrency	80	80-250	Requests per instance
Timeout	300s	60-300s	Request timeout
CPU Allocation	Request-based	Always (for background work)	CPU availability

Service Configuration

Copy
# service.yaml - Cloud Run service definition
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: my-api
spec:
  template:
    metadata:
      annotations:
        autoscaling.knative.dev/minScale: "1"
        autoscaling.knative.dev/maxScale: "50"
        run.googleapis.com/cloudsql-instances: "project:region:instance"
    spec:
      containerConcurrency: 100
      timeoutSeconds: 300
      containers:
        - image: gcr.io/my-project/my-api:latest
          ports:
            - containerPort: 8080
          resources:
            limits:
              memory: "1Gi"
              cpu: "2"
          env:
            - name: NODE_ENV
              value: "production"
            - name: DB_PASSWORD
              valueFrom:
                secretKeyRef:
                  key: latest
                  name: db-password

Cloud SQL Connection

Copy
// Connect to Cloud SQL from Cloud Run
import { Pool } from 'pg';

const pool = new Pool({
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
  // Cloud Run uses Unix sockets for Cloud SQL
  host: `/cloudsql/${process.env.CLOUD_SQL_CONNECTION_NAME}`,
});

Configuration

Parameter	Type	Default	Description
region	string	"us-central1"	GCP region for deployment
memory	string	"512Mi"	Memory allocation per instance
cpu	string	"1"	CPU allocation per instance
min_instances	number	0	Minimum instances (0 for scale-to-zero)
max_instances	number	100	Maximum instances for auto-scaling
concurrency	number	80	Max concurrent requests per instance
timeout	number	300	Request timeout in seconds
allow_unauthenticated	boolean	false	Allow public access without auth

Best Practices

1. Set min-instances: 1 for production services — cold starts add 2-10 seconds of latency for the first request; keeping one instance warm eliminates this for user-facing services.

2. Use Cloud SQL Auth Proxy via Unix sockets — connect to Cloud SQL through the built-in socket path rather than public IP; this is faster, more secure, and doesn't require IP whitelisting.

3. Store secrets in Secret Manager, not environment variables — use gcloud secrets and reference them in service config; environment variables are visible in the Cloud Console to anyone with service access.

4. Set concurrency based on your application's resource usage — Node.js apps handle 80-250 concurrent requests well; CPU-intensive apps should lower this to 1-10 to prevent resource contention.

5. Use --source . for simple deployments — Cloud Run can build from source using Buildpacks, eliminating the need to manage Dockerfiles for standard Node.js, Python, and Go applications.

Common Issues

Cold start latency is too high — Set min-instances: 1 and reduce container image size. Alpine-based images start faster than Debian. Minimize initialization work (lazy-load heavy dependencies, defer database connections until first request).

Cloud SQL connection limit exceeded — Each Cloud Run instance opens its own connection pool. Set max in your connection pool to 2-5 per instance, and increase Cloud SQL's max_connections if needed. Use connection pooling (PgBouncer) for high-scale services.

Service runs out of memory — Node.js apps with large payloads or in-memory processing may exceed the default 512Mi. Increase memory allocation or stream large responses instead of buffering them in memory.