opencode-skills-collection 4.0.52 → 4.0.54

package/bundled-skills/gcp-cloud-run/references/detailed-guide.md

@@ -0,0 +1,1350 @@
+# GCP Cloud Run - Detailed Guide
+
+> This file contains the detailed procedure and reference material extracted from `SKILL.md` for focused loading. The root skill defines activation, examples, safety constraints, and limitations.
+
+## Principles
+
+- Cloud Run for containers, Functions for simple event handlers
+- Optimize for cold starts with startup CPU boost and min instances
+- Set concurrency based on workload (start with 8, adjust)
+- Memory includes /tmp filesystem - plan accordingly
+- Use VPC Connector only when needed (adds latency)
+- Containers should start fast and be stateless
+- Handle signals gracefully for clean shutdown
+
+
+## Patterns
+
+### Cloud Run Service Pattern
+
+Containerized web service on Cloud Run
+
+**When to use**: Web applications and APIs,Need any runtime or library,Complex services with multiple endpoints,Stateless containerized workloads
+
+```dockerfile
+# Dockerfile - Multi-stage build for smaller image
+FROM node:20-slim AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+
+FROM node:20-slim
+WORKDIR /app
+
+# Copy only production dependencies
+COPY --from=builder /app/node_modules ./node_modules
+COPY src ./src
+COPY package.json ./
+
+# Cloud Run uses PORT env variable
+ENV PORT=8080
+EXPOSE 8080
+
+# Run as non-root user
+USER node
+
+CMD ["node", "src/index.js"]
+```
+
+```javascript
+// src/index.js
+const express = require('express');
+const app = express();
+
+app.use(express.json());
+
+// Health check endpoint
+app.get('/health', (req, res) => {
+  res.status(200).send('OK');
+});
+
+// API routes
+app.get('/api/items/:id', async (req, res) => {
+  try {
+    const item = await getItem(req.params.id);
+    res.json(item);
+  } catch (error) {
+    console.error('Error:', error);
+    res.status(500).json({ error: 'Internal server error' });
+  }
+});
+
+// Graceful shutdown
+process.on('SIGTERM', () => {
+  console.log('SIGTERM received, shutting down gracefully');
+  server.close(() => {
+    console.log('Server closed');
+    process.exit(0);
+  });
+});
+
+const PORT = process.env.PORT || 8080;
+const server = app.listen(PORT, () => {
+  console.log(`Server listening on port ${PORT}`);
+});
+```
+
+```yaml
+# cloudbuild.yaml
+steps:
+  # Build the container image
+  - name: 'gcr.io/cloud-builders/docker'
+    args: ['build', '-t', 'gcr.io/$PROJECT_ID/my-service:$COMMIT_SHA', '.']
+
+  # Push the container image
+  - name: 'gcr.io/cloud-builders/docker'
+    args: ['push', 'gcr.io/$PROJECT_ID/my-service:$COMMIT_SHA']
+
+  # Deploy to Cloud Run
+  - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
+    entrypoint: gcloud
+    args:
+      - 'run'
+      - 'deploy'
+      - 'my-service'
+      - '--image=gcr.io/$PROJECT_ID/my-service:$COMMIT_SHA'
+      - '--region=us-central1'
+      - '--platform=managed'
+      - '--allow-unauthenticated'
+      - '--memory=512Mi'
+      - '--cpu=1'
+      - '--min-instances=1'
+      - '--max-instances=100'
+      - '--concurrency=80'
+      - '--cpu-boost'
+
+images:
+  - 'gcr.io/$PROJECT_ID/my-service:$COMMIT_SHA'
+```
+
+### Structure
+
+project/
+├── Dockerfile
+├── .dockerignore
+├── src/
+│   ├── index.js
+│   └── routes/
+├── package.json
+└── cloudbuild.yaml
+
+### Gcloud_deploy
+
+# Direct gcloud deployment
+gcloud run deploy my-service \
+  --source . \
+  --region us-central1 \
+  --allow-unauthenticated \
+  --memory 512Mi \
+  --cpu 1 \
+  --min-instances 1 \
+  --max-instances 100 \
+  --concurrency 80 \
+  --cpu-boost
+
+### Cloud Run Functions Pattern
+
+Event-driven functions (formerly Cloud Functions)
+
+**When to use**: Simple event handlers,Pub/Sub message processing,Cloud Storage triggers,HTTP webhooks
+
+```javascript
+// HTTP Function
+// index.js
+const functions = require('@google-cloud/functions-framework');
+
+functions.http('helloHttp', (req, res) => {
+  const name = req.query.name || req.body.name || 'World';
+  res.send(`Hello, ${name}!`);
+});
+```
+
+```javascript
+// Pub/Sub Function
+const functions = require('@google-cloud/functions-framework');
+
+functions.cloudEvent('processPubSub', (cloudEvent) => {
+  // Decode Pub/Sub message
+  const message = cloudEvent.data.message;
+  const data = message.data
+    ? JSON.parse(Buffer.from(message.data, 'base64').toString())
+    : {};
+
+  console.log('Received message:', data);
+
+  // Process message
+  processMessage(data);
+});
+```
+
+```javascript
+// Cloud Storage Function
+const functions = require('@google-cloud/functions-framework');
+
+functions.cloudEvent('processStorageEvent', async (cloudEvent) => {
+  const file = cloudEvent.data;
+
+  console.log(`Event: ${cloudEvent.type}`);
+  console.log(`Bucket: ${file.bucket}`);
+  console.log(`File: ${file.name}`);
+
+  if (cloudEvent.type === 'google.cloud.storage.object.v1.finalized') {
+    await processUploadedFile(file.bucket, file.name);
+  }
+});
+```
+
+```bash
+# Deploy HTTP function
+gcloud functions deploy hello-http \
+  --gen2 \
+  --runtime nodejs20 \
+  --trigger-http \
+  --allow-unauthenticated \
+  --region us-central1
+
+# Deploy Pub/Sub function
+gcloud functions deploy process-messages \
+  --gen2 \
+  --runtime nodejs20 \
+  --trigger-topic my-topic \
+  --region us-central1
+
+# Deploy Cloud Storage function
+gcloud functions deploy process-uploads \
+  --gen2 \
+  --runtime nodejs20 \
+  --trigger-event-filters="type=google.cloud.storage.object.v1.finalized" \
+  --trigger-event-filters="bucket=my-bucket" \
+  --region us-central1
+```
+
+### Cold Start Optimization Pattern
+
+Minimize cold start latency for Cloud Run
+
+**When to use**: Latency-sensitive applications,User-facing APIs,High-traffic services
+
+
+## 1. Enable Startup CPU Boost
+
+```bash
+gcloud run deploy my-service \
+  --cpu-boost \
+  --region us-central1
+```
+
+
+## 2. Set Minimum Instances
+
+```bash
+gcloud run deploy my-service \
+  --min-instances 1 \
+  --region us-central1
+```
+
+
+## 3. Optimize Container Image
+
+```dockerfile
+# Use distroless for minimal image
+FROM node:20-slim AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+
+FROM gcr.io/distroless/nodejs20-debian12
+WORKDIR /app
+COPY --from=builder /app/node_modules ./node_modules
+COPY src ./src
+CMD ["src/index.js"]
+```
+
+
+## 4. Lazy Initialize Heavy Dependencies
+
+```javascript
+// Lazy load heavy libraries
+let bigQueryClient = null;
+
+function getBigQueryClient() {
+  if (!bigQueryClient) {
+    const { BigQuery } = require('@google-cloud/bigquery');
+    bigQueryClient = new BigQuery();
+  }
+  return bigQueryClient;
+}
+
+// Only initialize when needed
+app.get('/api/analytics', async (req, res) => {
+  const client = getBigQueryClient();
+  const results = await client.query({...});
+  res.json(results);
+});
+```
+
+
+## 5. Increase Memory (More CPU)
+
+```bash
+# Higher memory = more CPU during startup
+gcloud run deploy my-service \
+  --memory 1Gi \
+  --cpu 2 \
+  --region us-central1
+```
+
+### Optimization_impact
+
+- Startup_cpu_boost: 50% faster cold starts
+- Min_instances: Eliminates cold starts for traffic spikes
+- Distroless_image: Smaller attack surface, faster pull
+- Lazy_init: Defers heavy loading to first request
+
+### Concurrency Configuration Pattern
+
+Proper concurrency settings for Cloud Run
+
+**When to use**: Need to optimize instance utilization,Handle traffic spikes efficiently,Reduce cold starts
+
+
+## Understanding Concurrency
+
+```bash
+# Default concurrency is 80
+# Adjust based on your workload
+
+# For I/O-bound workloads (most web apps)
+gcloud run deploy my-service \
+  --concurrency 80 \
+  --cpu 1
+
+# For CPU-bound workloads
+gcloud run deploy my-service \
+  --concurrency 1 \
+  --cpu 1
+
+# For memory-intensive workloads
+gcloud run deploy my-service \
+  --concurrency 10 \
+  --memory 2Gi
+```
+
+
+## Node.js Concurrency
+
+```javascript
+// Node.js is single-threaded but handles I/O concurrently
+// Use async/await for all I/O operations
+
+// GOOD - async I/O
+app.get('/api/data', async (req, res) => {
+  const [users, products] = await Promise.all([
+    fetchUsers(),
+    fetchProducts()
+  ]);
+  res.json({ users, products });
+});
+
+// BAD - blocking operation
+app.get('/api/compute', (req, res) => {
+  const result = heavyCpuOperation(); // Blocks other requests!
+  res.json(result);
+});
+```
+
+
+## Python Concurrency with Gunicorn
+
+```dockerfile
+FROM python:3.11-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY . .
+
+# 4 workers for concurrency
+CMD exec gunicorn --bind :$PORT --workers 4 --threads 2 main:app
+```
+
+```python
+# main.py
+from flask import Flask
+app = Flask(__name__)
+
+@app.route('/api/data')
+def get_data():
+    return {'status': 'ok'}
+```
+
+### Concurrency_guidelines
+
+- Concurrency=1: Only for CPU-bound or unsafe code
+- Concurrency=8 20: Memory-intensive workloads
+- Concurrency=80: Default, good for I/O-bound
+- Concurrency=250: Maximum, for very lightweight handlers
+
+### Pub/Sub Integration Pattern
+
+Event-driven processing with Cloud Pub/Sub
+
+**When to use**: Asynchronous message processing,Decoupled microservices,Event-driven architecture
+
+
+## Push Subscription to Cloud Run
+
+```bash
+# Create topic
+gcloud pubsub topics create orders
+
+# Create push subscription to Cloud Run
+gcloud pubsub subscriptions create orders-push \
+  --topic orders \
+  --push-endpoint https://my-service-xxx.run.app/pubsub \
+  --ack-deadline 600
+```
+
+```javascript
+// Handle Pub/Sub push messages
+const express = require('express');
+const app = express();
+app.use(express.json());
+
+app.post('/pubsub', async (req, res) => {
+  // Verify the request is from Pub/Sub
+  if (!req.body.message) {
+    return res.status(400).send('Invalid Pub/Sub message');
+  }
+
+  try {
+    // Decode message data
+    const message = req.body.message;
+    const data = message.data
+      ? JSON.parse(Buffer.from(message.data, 'base64').toString())
+      : {};
+
+    console.log('Processing order:', data);
+
+    await processOrder(data);
+
+    // Return 200 to acknowledge
+    res.status(200).send('OK');
+  } catch (error) {
+    console.error('Processing failed:', error);
+    // Return 500 to trigger retry
+    res.status(500).send('Processing failed');
+  }
+});
+```
+
+
+## Publishing Messages
+
+```javascript
+const { PubSub } = require('@google-cloud/pubsub');
+const pubsub = new PubSub();
+
+async function publishOrder(order) {
+  const topic = pubsub.topic('orders');
+  const messageBuffer = Buffer.from(JSON.stringify(order));
+
+  const messageId = await topic.publishMessage({
+    data: messageBuffer,
+    attributes: {
+      type: 'order_created',
+      priority: 'high'
+    }
+  });
+
+  console.log(`Published message ${messageId}`);
+  return messageId;
+}
+```
+
+
+## Dead Letter Queue
+
+```bash
+# Create DLQ topic
+gcloud pubsub topics create orders-dlq
+
+# Update subscription with DLQ
+gcloud pubsub subscriptions update orders-push \
+  --dead-letter-topic orders-dlq \
+  --max-delivery-attempts 5
+```
+
+### Cloud SQL Connection Pattern
+
+Connect Cloud Run to Cloud SQL securely
+
+**When to use**: Need relational database,Migrating existing applications,Complex queries and transactions
+
+```bash
+# Deploy with Cloud SQL connection
+gcloud run deploy my-service \
+  --add-cloudsql-instances PROJECT:REGION:INSTANCE \
+  --set-env-vars INSTANCE_CONNECTION_NAME="PROJECT:REGION:INSTANCE" \
+  --set-env-vars DB_NAME="mydb" \
+  --set-env-vars DB_USER="myuser"
+```
+
+```javascript
+// Using Unix socket connection
+const { Pool } = require('pg');
+
+const pool = new Pool({
+  user: process.env.DB_USER,
+  password: process.env.DB_PASS,
+  database: process.env.DB_NAME,
+  // Cloud SQL connector uses Unix socket
+  host: `/cloudsql/${process.env.INSTANCE_CONNECTION_NAME}`,
+  max: 5,  // Connection pool size
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 10000,
+});
+
+app.get('/api/users', async (req, res) => {
+  const client = await pool.connect();
+  try {
+    const result = await client.query('SELECT * FROM users LIMIT 100');
+    res.json(result.rows);
+  } finally {
+    client.release();
+  }
+});
+```
+
+```python
+# Python with SQLAlchemy
+import os
+from sqlalchemy import create_engine
+
+def get_engine():
+    instance_connection_name = os.environ["INSTANCE_CONNECTION_NAME"]
+    db_user = os.environ["DB_USER"]
+    db_pass = os.environ["DB_PASS"]
+    db_name = os.environ["DB_NAME"]
+
+    engine = create_engine(
+        f"postgresql+pg8000://{db_user}:{db_pass}@/{db_name}",
+        connect_args={
+            "unix_sock": f"/cloudsql/{instance_connection_name}/.s.PGSQL.5432"
+        },
+        pool_size=5,
+        max_overflow=2,
+        pool_timeout=30,
+        pool_recycle=1800,
+    )
+    return engine
+```
+
+### Best_practices
+
+- Use connection pooling (max 5-10 per instance)
+- Set appropriate idle timeouts
+- Handle connection errors gracefully
+- Consider Cloud SQL Proxy for local development
+
+### Secret Manager Integration
+
+Securely manage secrets in Cloud Run
+
+**When to use**: API keys, database passwords,Service account keys,Any sensitive configuration
+
+```bash
+# Create secret
+echo -n "my-secret-value" | gcloud secrets create my-secret --data-file=-
+
+# Mount as environment variable
+gcloud run deploy my-service \
+  --update-secrets=API_KEY=my-secret:latest
+
+# Mount as file volume
+gcloud run deploy my-service \
+  --update-secrets=/secrets/api-key=my-secret:latest
+```
+
+```javascript
+// Access mounted as environment variable
+const apiKey = process.env.API_KEY;
+
+// Access mounted as file
+const fs = require('fs');
+const apiKey = fs.readFileSync('/secrets/api-key', 'utf8');
+
+// Access via Secret Manager API (when not mounted)
+const { SecretManagerServiceClient } = require('@google-cloud/secret-manager');
+const client = new SecretManagerServiceClient();
+
+async function getSecret(name) {
+  const [version] = await client.accessSecretVersion({
+    name: `projects/${projectId}/secrets/${name}/versions/latest`
+  });
+  return version.payload.data.toString();
+}
+```
+
+
+## Sharp Edges
+
+### /tmp Filesystem Counts Against Memory
+
+Severity: HIGH
+
+Situation: Writing files to /tmp directory in Cloud Run
+
+Symptoms:
+Container killed with OOM error.
+Memory usage spikes unexpectedly.
+File operations cause container restarts.
+"Container memory limit exceeded" in logs.
+
+Why this breaks:
+Cloud Run uses an in-memory filesystem for /tmp. Any files written
+to /tmp consume memory from your container's allocation.
+
+Common scenarios:
+- Downloading files temporarily
+- Creating temp processing files
+- Libraries caching to /tmp
+- Large log buffers
+
+A 512MB container that downloads a 200MB file to /tmp only has
+~300MB left for the application.
+
+Recommended fix:
+
+
+## Stream instead of buffering
+
+```python
+# BAD - buffers entire file in /tmp
+def process_large_file(bucket_name, blob_name):
+    blob = bucket.blob(blob_name)
+    blob.download_to_filename('/tmp/large_file')
+    with open('/tmp/large_file', 'rb') as f:
+        process(f.read())
+
+# GOOD - stream processing
+def process_large_file(bucket_name, blob_name):
+    blob = bucket.blob(blob_name)
+    with blob.open('rb') as f:
+        for chunk in iter(lambda: f.read(8192), b''):
+            process_chunk(chunk)
+```
+
+
+## Use Cloud Storage for large files
+
+```python
+from google.cloud import storage
+
+def process_with_gcs(bucket_name, input_blob, output_blob):
+    client = storage.Client()
+    bucket = client.bucket(bucket_name)
+
+    # Process directly to/from GCS
+    input_blob = bucket.blob(input_blob)
+    output_blob = bucket.blob(output_blob)
+
+    with input_blob.open('rb') as reader:
+        with output_blob.open('wb') as writer:
+            for chunk in iter(lambda: reader.read(65536), b''):
+                processed = transform(chunk)
+                writer.write(processed)
+```
+
+
+## Set appropriate concurrency
+
+```bash
+# For I/O-bound workloads (most web apps)
+gcloud run deploy my-service \
+  --concurrency=80 \
+  --max-instances=100
+
+# For CPU-bound workloads
+gcloud run deploy my-service \
+  --concurrency=4 \
+  --cpu=2
+
+# Only use 1 when absolutely necessary
+gcloud run deploy my-service \
+  --concurrency=1 \
+  --max-instances=1000  # Be prepared for many instances
+```
+
+
+## Node.js - use async properly
+
+```javascript
+// With high concurrency, ensure async operations
+const express = require('express');
+const app = express();
+
+app.get('/api/data', async (req, res) => {
+  // All I/O should be async
+  const data = await fetchFromDatabase();
+  const enriched = await enrichData(data);
+  res.json(enriched);
+});
+
+// Concurrency 80+ is safe for async I/O workloads
+```
+
+
+## Python - use async framework
+
+```python
+from fastapi import FastAPI
+import asyncio
+import httpx
+
+app = FastAPI()
+
+@app.get("/api/data")
+async def get_data():
+    # Async I/O allows high concurrency
+    async with httpx.AsyncClient() as client:
+        response = await client.get("https://api.example.com/data")
+        return response.json()
+
+# Concurrency 80+ safe with async framework
+```
+
+
+## Calculate concurrency
+
+```
+concurrency = memory_limit / per_request_memory
+
+Example:
+- 512MB container
+- 20MB per request overhead
+- Safe concurrency: ~25
+```
+
+### CPU Throttled When Not Handling Requests
+
+Severity: HIGH
+
+Situation: Running background tasks or processing between requests
+
+Symptoms:
+Background tasks run extremely slowly.
+Scheduled work doesn't complete.
+Metrics collection fails.
+Connection keep-alive breaks.
+
+Why this breaks:
+By default, Cloud Run throttles CPU to near-zero when not actively
+handling a request. This is "CPU only during requests" mode.
+
+Affected operations:
+- Background threads
+- Connection pool maintenance
+- Metrics/telemetry emission
+- Scheduled tasks within container
+- Cleanup operations after response
+
+Recommended fix:
+
+
+## Enable CPU always allocated
+
+```bash
+# CPU allocated even outside requests
+gcloud run deploy my-service \
+  --cpu-throttling=false \
+  --min-instances=1
+
+# Note: This increases costs but enables background work
+```
+
+
+## Use startup CPU boost for initialization
+
+```bash
+# Boost CPU during cold start only
+gcloud run deploy my-service \
+  --cpu-boost \
+  --cpu-throttling=true  # Default, throttle after request
+```
+
+
+## Move background work to Cloud Tasks
+
+```python
+from google.cloud import tasks_v2
+import json
+
+def create_background_task(payload):
+    client = tasks_v2.CloudTasksClient()
+    parent = client.queue_path(
+        "my-project", "us-central1", "my-queue"
+    )
+
+    task = {
+        "http_request": {
+            "http_method": tasks_v2.HttpMethod.POST,
+            "url": "https://my-service.run.app/process",
+            "body": json.dumps(payload).encode(),
+            "headers": {"Content-Type": "application/json"}
+        }
+    }
+
+    client.create_task(parent=parent, task=task)
+
+# Handle response immediately, background via Cloud Tasks
+@app.post("/api/order")
+async def create_order(order: Order):
+    order_id = await save_order(order)
+
+    # Queue background processing
+    create_background_task({"order_id": order_id})
+
+    return {"order_id": order_id, "status": "processing"}
+```
+
+
+## Use Pub/Sub for async processing
+
+```yaml
+# Move heavy processing to separate service
+steps:
+  # Main service - responds quickly
+  - name: 'gcr.io/cloud-builders/gcloud'
+    args: ['run', 'deploy', 'api-service',
+           '--cpu-throttling=true']
+
+  # Worker service - processes messages
+  - name: 'gcr.io/cloud-builders/gcloud'
+    args: ['run', 'deploy', 'worker-service',
+           '--cpu-throttling=false',
+           '--min-instances=1']
+```
+
+### VPC Connector 10-Minute Idle Timeout
+
+Severity: MEDIUM
+
+Situation: Cloud Run service connecting to VPC resources
+
+Symptoms:
+Connection errors after period of inactivity.
+"Connection reset" or "Connection refused" errors.
+Sporadic failures to VPC resources.
+Database connections drop unexpectedly.
+
+Why this breaks:
+Cloud Run's VPC connector has a 10-minute idle timeout on connections.
+If a connection is idle for 10 minutes, it's silently closed.
+
+Affects:
+- Database connection pools
+- Redis connections
+- Internal API connections
+- Any persistent VPC connection
+
+Recommended fix:
+
+
+## Configure connection pool with keep-alive
+
+```python
+# SQLAlchemy with connection recycling
+from sqlalchemy import create_engine
+
+engine = create_engine(
+    DATABASE_URL,
+    pool_size=5,
+    max_overflow=2,
+    pool_recycle=300,  # Recycle connections every 5 minutes
+    pool_pre_ping=True  # Validate connection before use
+)
+```
+
+
+## TCP keep-alive for custom connections
+
+```python
+import socket
+
+sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+sock.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
+sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPIDLE, 60)
+sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPINTVL, 60)
+sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPCNT, 5)
+```
+
+
+## Redis with connection validation
+
+```python
+import redis
+
+pool = redis.ConnectionPool(
+    host=REDIS_HOST,
+    port=6379,
+    socket_keepalive=True,
+    socket_keepalive_options={
+        socket.TCP_KEEPIDLE: 60,
+        socket.TCP_KEEPINTVL: 60,
+        socket.TCP_KEEPCNT: 5
+    },
+    health_check_interval=30
+)
+client = redis.Redis(connection_pool=pool)
+```
+
+
+## Use Cloud SQL Proxy sidecar
+
+```yaml
+# Use Cloud SQL connector which handles reconnection
+# requirements.txt
+cloud-sql-python-connector[pg8000]
+```
+
+```python
+import os
+from google.cloud.sql.connector import Connector
+import sqlalchemy
+
+connector = Connector()
+
+def getconn():
+    return connector.connect(
+        "project:region:instance",
+        "pg8000",
+        user="user",
+        password=os.environ["DB_PASSWORD"],
+        db="database"
+    )
+
+engine = sqlalchemy.create_engine(
+    "postgresql+pg8000://",
+    creator=getconn
+)
+```
+
+### Container Startup Timeout (4 minutes max)
+
+Severity: HIGH
+
+Situation: Deploying containers with slow initialization
+
+Symptoms:
+Deployment fails with "Container failed to start".
+Service never becomes healthy.
+"Revision failed to become ready" errors.
+Works locally but fails on Cloud Run.
+
+Why this breaks:
+Cloud Run expects your container to start listening on PORT within
+4 minutes (240 seconds). If it doesn't, the instance is killed.
+
+Common causes:
+- Heavy framework initialization (ML models, etc.)
+- Waiting for external dependencies at startup
+- Large dependency loading
+- Database migrations on startup
+
+Recommended fix:
+
+
+## Enable startup CPU boost
+
+```bash
+gcloud run deploy my-service \
+  --cpu-boost \
+  --startup-cpu-boost
+```
+
+
+## Lazy initialization
+
+```python
+from functools import lru_cache
+from fastapi import FastAPI
+
+app = FastAPI()
+
+# Don't load at import time
+model = None
+
+@lru_cache()
+def get_model():
+    global model
+    if model is None:
+        # Load on first request, not at startup
+        model = load_heavy_model()
+    return model
+
+@app.get("/predict")
+async def predict(data: dict):
+    model = get_model()  # Loads on first call only
+    return model.predict(data)
+
+# Startup is fast - model loads on first request
+```
+
+
+## Start listening immediately
+
+```python
+import asyncio
+from fastapi import FastAPI
+import uvicorn
+
+app = FastAPI()
+
+# Global state for async initialization
+initialized = asyncio.Event()
+
+@app.on_event("startup")
+async def startup():
+    # Start background initialization
+    asyncio.create_task(async_init())
+
+async def async_init():
+    # Heavy initialization happens after server starts
+    await load_models()
+    await warm_up_connections()
+    initialized.set()
+
+@app.get("/ready")
+async def ready():
+    if not initialized.is_set():
+        raise HTTPException(503, "Still initializing")
+    return {"status": "ready"}
+
+@app.get("/health")
+async def health():
+    # Always respond - health check passes
+    return {"status": "healthy"}
+```
+
+
+## Use multi-stage builds
+
+```dockerfile
+# Build stage - slow
+FROM python:3.11 as builder
+WORKDIR /app
+COPY requirements.txt .
+RUN pip wheel --no-cache-dir --wheel-dir /wheels -r requirements.txt
+
+# Runtime stage - fast startup
+FROM python:3.11-slim
+WORKDIR /app
+COPY --from=builder /wheels /wheels
+RUN pip install --no-cache /wheels/* && rm -rf /wheels
+COPY . .
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]
+```
+
+
+## Run migrations separately
+
+```bash
+# Don't migrate on startup - use Cloud Build
+steps:
+  # Run migrations first
+  - name: 'gcr.io/cloud-builders/gcloud'
+    entrypoint: 'bash'
+    args:
+      - '-c'
+      - |
+        gcloud run jobs execute migrate-job --wait
+
+  # Then deploy
+  - name: 'gcr.io/cloud-builders/gcloud'
+    args: ['run', 'deploy', 'my-service', ...]
+```
+
+### Second Generation Execution Environment Differences
+
+Severity: MEDIUM
+
+Situation: Migrating to or using Cloud Run second-gen execution environment
+
+Symptoms:
+Network behavior changes.
+Different syscall support.
+File system behavior differences.
+Container behaves differently than in first-gen.
+
+Why this breaks:
+Cloud Run's second-generation execution environment uses a different
+sandbox (gVisor) with different characteristics:
+
+- More Linux syscalls supported
+- Full /proc and /sys access
+- Different network stack
+- No automatic HTTPS redirect
+- Different tmp filesystem behavior
+
+Recommended fix:
+
+
+## Explicitly set execution environment
+
+```bash
+# First generation (legacy)
+gcloud run deploy my-service \
+  --execution-environment=gen1
+
+# Second generation (recommended for most)
+gcloud run deploy my-service \
+  --execution-environment=gen2
+```
+
+
+## Handle network differences
+
+```python
+# Second-gen doesn't auto-redirect HTTP to HTTPS
+from fastapi import FastAPI, Request
+from fastapi.responses import RedirectResponse
+
+app = FastAPI()
+
+@app.middleware("http")
+async def redirect_https(request: Request, call_next):
+    # Check X-Forwarded-Proto header
+    if request.headers.get("X-Forwarded-Proto") == "http":
+        url = request.url.replace(scheme="https")
+        return RedirectResponse(url, status_code=301)
+    return await call_next(request)
+```
+
+
+## GPU access (second-gen only)
+
+```bash
+# GPUs only available in second-gen
+gcloud run deploy ml-service \
+  --execution-environment=gen2 \
+  --gpu=1 \
+  --gpu-type=nvidia-l4
+```
+
+
+## Check execution environment
+
+```python
+import os
+
+def get_execution_environment():
+    # Second-gen has different /proc structure
+    try:
+        with open('/proc/version', 'r') as f:
+            version = f.read()
+            if 'gVisor' in version:
+                return 'gen2'
+    except:
+        pass
+    return 'gen1'
+```
+
+### Request Timeout Configuration Mismatch
+
+Severity: MEDIUM
+
+Situation: Long-running requests or background processing
+
+Symptoms:
+Requests terminated before completion.
+504 Gateway Timeout errors.
+Processing stops unexpectedly.
+Inconsistent timeout behavior.
+
+Why this breaks:
+Cloud Run has multiple timeout configurations that must align:
+- Request timeout (default 300s, max 3600s for HTTP, 60m for gRPC)
+- Client timeout
+- Downstream service timeouts
+- Load balancer timeout (for external access)
+
+Recommended fix:
+
+
+## Set consistent timeouts
+
+```bash
+# Increase request timeout (max 3600s for HTTP)
+gcloud run deploy my-service \
+  --timeout=900  # 15 minutes
+```
+
+
+## Handle long-running with webhooks
+
+```python
+from fastapi import FastAPI, BackgroundTasks
+import httpx
+
+app = FastAPI()
+
+@app.post("/process")
+async def process(data: dict, background_tasks: BackgroundTasks):
+    task_id = create_task_id()
+
+    # Start background processing
+    background_tasks.add_task(
+        long_running_process,
+        task_id,
+        data,
+        data.get("callback_url")
+    )
+
+    # Return immediately
+    return {"task_id": task_id, "status": "processing"}
+
+async def long_running_process(task_id, data, callback_url):
+    result = await heavy_computation(data)
+
+    # Callback when done
+    if callback_url:
+        async with httpx.AsyncClient() as client:
+            await client.post(callback_url, json={
+                "task_id": task_id,
+                "result": result
+            })
+```
+
+
+## Use Cloud Tasks for reliable long-running
+
+```python
+from google.cloud import tasks_v2
+
+def create_long_running_task(data):
+    client = tasks_v2.CloudTasksClient()
+    parent = client.queue_path(PROJECT, REGION, "long-tasks")
+
+    task = {
+        "http_request": {
+            "http_method": tasks_v2.HttpMethod.POST,
+            "url": "https://worker.run.app/process",
+            "body": json.dumps(data).encode(),
+            "headers": {"Content-Type": "application/json"}
+        },
+        "dispatch_deadline": {"seconds": 1800}  # 30 min
+    }
+
+    return client.create_task(parent=parent, task=task)
+```
+
+
+## Streaming for long responses
+
+```python
+from fastapi import FastAPI
+from fastapi.responses import StreamingResponse
+
+@app.get("/large-report")
+async def large_report():
+    async def generate():
+        for chunk in process_large_data():
+            yield chunk
+
+    return StreamingResponse(generate(), media_type="text/plain")
+```
+
+
+## Validation Checks
+
+### Hardcoded GCP Credentials
+
+Severity: ERROR
+
+GCP credentials must never be hardcoded in source code
+
+Message: Hardcoded GCP service account credentials. Use Secret Manager or Workload Identity.
+
+### GCP API Key in Source Code
+
+Severity: ERROR
+
+API keys should use Secret Manager
+
+Message: Hardcoded GCP API key. Use Secret Manager.
+
+### Credentials JSON File in Repository
+
+Severity: ERROR
+
+Service account JSON files should not be in source control
+
+Message: Credentials file detected. Add to .gitignore and use Secret Manager.
+
+### Running as Root User
+
+Severity: WARNING
+
+Containers should not run as root for security
+
+Message: Dockerfile runs as root. Add USER directive for security.
+
+### Missing Health Check in Dockerfile
+
+Severity: INFO
+
+Cloud Run uses HTTP health checks, Dockerfile HEALTHCHECK is optional
+
+Message: No HEALTHCHECK in Dockerfile. Cloud Run uses its own health checks.
+
+### Hardcoded Port in Application
+
+Severity: WARNING
+
+Port should come from PORT environment variable
+
+Message: Hardcoded port. Use PORT environment variable for Cloud Run.
+
+### Large File Writes to /tmp
+
+Severity: WARNING
+
+/tmp uses container memory, large writes can cause OOM
+
+Message: /tmp writes consume memory. Consider Cloud Storage for large files.
+
+### Synchronous File Operations
+
+Severity: WARNING
+
+Sync file ops block the event loop in async apps
+
+Message: Synchronous file operations. Use async versions for better concurrency.
+
+### Global Mutable State
+
+Severity: WARNING
+
+Global state issues with concurrent requests
+
+Message: Global mutable state may cause issues with concurrent requests.
+
+### Thread-Unsafe Singleton Pattern
+
+Severity: WARNING
+
+Singletons need thread safety for concurrency > 1
+
+Message: Singleton pattern - ensure thread safety if using concurrency > 1.
+
+
+## Collaboration
+
+### Delegation Triggers
+
+- user needs AWS serverless -> aws-serverless (Lambda, API Gateway, SAM)
+- user needs Azure containers -> azure-functions (Azure Container Apps, Functions)
+- user needs database design -> postgres-wizard (Cloud SQL design, AlloyDB)
+- user needs authentication -> auth-specialist (Firebase Auth, Identity Platform)
+- user needs AI integration -> llm-architect (Vertex AI, Cloud Run + LLM)
+- user needs workflow orchestration -> workflow-automation (Cloud Workflows, Eventarc)