gcp-cloud-run - Agent Skills

GCP Cloud Run

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'

### 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}!); });
// 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); });
// 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); } });
# 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']
javascript
1. Enable Startup CPU Boost
gcloud run deploy my-service \ --cpu-boost \ --region us-central1
2. Set Minimum Instances
gcloud run deploy my-service \ --min-instances 1 \ --region us-central1
3. Optimize Container Image

# 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

// 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)

# Higher memory = more CPU during startup
gcloud run deploy my-service \
  --memory 1Gi \
  --cpu 2 \
  --region us-central1

```

Anti-Patterns

❌ CPU-Intensive Work Without Concurrency=1

Why bad: CPU is shared across concurrent requests. CPU-bound work
will starve other requests, causing timeouts.

❌ Writing Large Files to /tmp

Why bad: /tmp is an in-memory filesystem. Large files consume
your memory allocation and can cause OOM errors.

❌ Long-Running Background Tasks

Why bad: Cloud Run throttles CPU to near-zero when not handling
requests. Background tasks will be extremely slow or stall.

⚠️ Sharp Edges

Issue	Severity	Solution
Issue	high	## Calculate memory including /tmp usage
Issue	high	## Set appropriate concurrency
Issue	high	## Enable CPU always allocated
Issue	medium	## Configure connection pool with keep-alive
Issue	high	## Enable startup CPU boost
Issue	medium	## Explicitly set execution environment
Issue	medium	## Set consistent timeouts