GCP Cloud Run

1---
2name: gcp-cloud-run
3description: "Specialized skill for building production-ready serverless applications on GCP. Covers Cloud Run services (containerized), Cloud Run Functions (event-driven), cold start optimization, and event-driven architecture with Pub/Sub."
4source: vibeship-spawner-skills (Apache 2.0)
5---
6 
7# GCP Cloud Run
8 
9## Patterns
10 
11### Cloud Run Service Pattern
12 
13Containerized web service on Cloud Run
14 
15**When to use**: ['Web applications and APIs', 'Need any runtime or library', 'Complex services with multiple endpoints', 'Stateless containerized workloads']
16 
17```javascript
18```dockerfile
19# Dockerfile - Multi-stage build for smaller image
20FROM node:20-slim AS builder
21WORKDIR /app
22COPY package*.json ./
23RUN npm ci --only=production
24 
25FROM node:20-slim
26WORKDIR /app
27 
28# Copy only production dependencies
29COPY --from=builder /app/node_modules ./node_modules
30COPY src ./src
31COPY package.json ./
32 
33# Cloud Run uses PORT env variable
34ENV PORT=8080
35EXPOSE 8080
36 
37# Run as non-root user
38USER node
39 
40CMD ["node", "src/index.js"]
41```
42 
43```javascript
44// src/index.js
45const express = require('express');
46const app = express();
47 
48app.use(express.json());
49 
50// Health check endpoint
51app.get('/health', (req, res) => {
52  res.status(200).send('OK');
53});
54 
55// API routes
56app.get('/api/items/:id', async (req, res) => {
57  try {
58    const item = await getItem(req.params.id);
59    res.json(item);
60  } catch (error) {
61    console.error('Error:', error);
62    res.status(500).json({ error: 'Internal server error' });
63  }
64});
65 
66// Graceful shutdown
67process.on('SIGTERM', () => {
68  console.log('SIGTERM received, shutting down gracefully');
69  server.close(() => {
70    console.log('Server closed');
71    process.exit(0);
72  });
73});
74 
75const PORT = process.env.PORT || 8080;
76const server = app.listen(PORT, () => {
77  console.log(`Server listening on port ${PORT}`);
78});
79```
80 
81```yaml
82# cloudbuild.yaml
83steps:
84  # Build the container image
85  - name: 'gcr.io/cloud-builders/docker'
86    args: ['build', '-t', 'gcr.io/$PROJECT_ID/my-service:$COMMIT_SHA', '.']
87 
88  # Push the container image
89  - name: 'gcr.io/cloud-builders/docker'
90    args: ['push', 'gcr.io/$PROJECT_ID/my-service:$COMMIT_SHA']
91 
92  # Deploy to Cloud Run
93  - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
94    entrypoint: gcloud
95    args:
96      - 'run'
97      - 'deploy'
98      - 'my-service'
99      - '--image=gcr.io/$PROJECT_ID/my-service:$COMMIT_SHA'
100      - '--region=us-central1'
101      - '--platform=managed'
102      - '--allow-unauthenticated'
103      - '--memory=512Mi'
104      - '--cpu=1'
105      - '--min-instances=1'
106      - '--max-instances=100'
107     
108```
109 
110### Cloud Run Functions Pattern
111 
112Event-driven functions (formerly Cloud Functions)
113 
114**When to use**: ['Simple event handlers', 'Pub/Sub message processing', 'Cloud Storage triggers', 'HTTP webhooks']
115 
116```javascript
117```javascript
118// HTTP Function
119// index.js
120const functions = require('@google-cloud/functions-framework');
121 
122functions.http('helloHttp', (req, res) => {
123  const name = req.query.name || req.body.name || 'World';
124  res.send(`Hello, ${name}!`);
125});
126```
127 
128```javascript
129// Pub/Sub Function
130const functions = require('@google-cloud/functions-framework');
131 
132functions.cloudEvent('processPubSub', (cloudEvent) => {
133  // Decode Pub/Sub message
134  const message = cloudEvent.data.message;
135  const data = message.data
136    ? JSON.parse(Buffer.from(message.data, 'base64').toString())
137    : {};
138 
139  console.log('Received message:', data);
140 
141  // Process message
142  processMessage(data);
143});
144```
145 
146```javascript
147// Cloud Storage Function
148const functions = require('@google-cloud/functions-framework');
149 
150functions.cloudEvent('processStorageEvent', async (cloudEvent) => {
151  const file = cloudEvent.data;
152 
153  console.log(`Event: ${cloudEvent.type}`);
154  console.log(`Bucket: ${file.bucket}`);
155  console.log(`File: ${file.name}`);
156 
157  if (cloudEvent.type === 'google.cloud.storage.object.v1.finalized') {
158    await processUploadedFile(file.bucket, file.name);
159  }
160});
161```
162 
163```bash
164# Deploy HTTP function
165gcloud functions deploy hello-http \
166  --gen2 \
167  --runtime nodejs20 \
168  --trigger-http \
169  --allow-unauthenticated \
170  --region us-central1
171 
172# Deploy Pub/Sub function
173gcloud functions deploy process-messages \
174  --gen2 \
175  --runtime nodejs20 \
176  --trigger-topic my-topic \
177  --region us-central1
178 
179# Deploy Cloud Storage function
180gcloud functions deploy process-uploads \
181  --gen2 \
182  --runtime nodejs20 \
183  --trigger-event-filters="type=google.cloud.storage.object.v1.finalized" \
184  --trigger-event-filters="bucket=my-bucket" \
185  --region us-central1
186```
187```
188 
189### Cold Start Optimization Pattern
190 
191Minimize cold start latency for Cloud Run
192 
193**When to use**: ['Latency-sensitive applications', 'User-facing APIs', 'High-traffic services']
194 
195```javascript
196## 1. Enable Startup CPU Boost
197 
198```bash
199gcloud run deploy my-service \
200  --cpu-boost \
201  --region us-central1
202```
203 
204## 2. Set Minimum Instances
205 
206```bash
207gcloud run deploy my-service \
208  --min-instances 1 \
209  --region us-central1
210```
211 
212## 3. Optimize Container Image
213 
214```dockerfile
215# Use distroless for minimal image
216FROM node:20-slim AS builder
217WORKDIR /app
218COPY package*.json ./
219RUN npm ci --only=production
220 
221FROM gcr.io/distroless/nodejs20-debian12
222WORKDIR /app
223COPY --from=builder /app/node_modules ./node_modules
224COPY src ./src
225CMD ["src/index.js"]
226```
227 
228## 4. Lazy Initialize Heavy Dependencies
229 
230```javascript
231// Lazy load heavy libraries
232let bigQueryClient = null;
233 
234function getBigQueryClient() {
235  if (!bigQueryClient) {
236    const { BigQuery } = require('@google-cloud/bigquery');
237    bigQueryClient = new BigQuery();
238  }
239  return bigQueryClient;
240}
241 
242// Only initialize when needed
243app.get('/api/analytics', async (req, res) => {
244  const client = getBigQueryClient();
245  const results = await client.query({...});
246  res.json(results);
247});
248```
249 
250## 5. Increase Memory (More CPU)
251 
252```bash
253# Higher memory = more CPU during startup
254gcloud run deploy my-service \
255  --memory 1Gi \
256  --cpu 2 \
257  --region us-central1
258```
259```
260 
261## Anti-Patterns
262 
263### ❌ CPU-Intensive Work Without Concurrency=1
264 
265**Why bad**: CPU is shared across concurrent requests. CPU-bound work
266will starve other requests, causing timeouts.
267 
268### ❌ Writing Large Files to /tmp
269 
270**Why bad**: /tmp is an in-memory filesystem. Large files consume
271your memory allocation and can cause OOM errors.
272 
273### ❌ Long-Running Background Tasks
274 
275**Why bad**: Cloud Run throttles CPU to near-zero when not handling
276requests. Background tasks will be extremely slow or stall.
277 
278## ⚠️ Sharp Edges
279 
280| Issue | Severity | Solution |
281|-------|----------|----------|
282| Issue | high | ## Calculate memory including /tmp usage |
283| Issue | high | ## Set appropriate concurrency |
284| Issue | high | ## Enable CPU always allocated |
285| Issue | medium | ## Configure connection pool with keep-alive |
286| Issue | high | ## Enable startup CPU boost |
287| Issue | medium | ## Explicitly set execution environment |
288| Issue | medium | ## Set consistent timeouts |
289