Files
skills/public/cloud-gcp-serverless.html
zeekay 747dafba10 Register WebMCP tools on every page, and name each page's twin from site.py
Every page now loads /webmcp.js, scripts/webmcp.ts with its types
stripped (npm run webmcp). Where the browser has document.modelContext
it registers two read-only tools: search_skills over the published
skills index, and get_skill, which returns a skill's markdown checked
against the index digest. The markdown alternate link moves from
build.py to site.py, so CI holds every page to it.

The API catalog gains the site itself (llms.txt and the skills index)
and hanzo.ai/agents; the live discovery check now fetches every
catalog link. tests/site.mjs drives the tools through a recording
modelContext, and checks a browser without one loads clean.
2026-10-26 20:57:05 -07:00

727 lines
34 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>cloud-gcp-serverless</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/cloud-gcp-serverless">
<link rel="alternate" type="text/markdown" href="/cloud-gcp-serverless.md">
<script type="module" src="/webmcp.js"></script>
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/cloud-gcp-serverless.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>cloud-gcp-serverless</h1><p class="lede">Google Cloud serverless services including Cloud Functions, Cloud Run, and App Engine</p><h1>GCP Serverless Computing</h1>
<p><strong>Scope</strong>: Cloud Functions event-driven functions, Cloud Run containers, App Engine applications, and serverless patterns <strong>Lines</strong>: ~360 <strong>Last Updated</strong>: 2025-10-25 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<hr>
<h2>When to Use This Skill</h2>
<p>Activate this skill when:</p>
<ul><li>Building event-driven applications with Cloud Functions</li><li>Deploying stateless containerized services with Cloud Run</li><li>Running web applications and APIs on App Engine</li><li>Choosing between serverless compute options</li><li>Configuring triggers and event routing with Eventarc</li><li>Scheduling tasks with Cloud Scheduler and Cloud Tasks</li><li>Optimizing cold start performance and concurrency</li><li>Managing secrets and environment variables in serverless environments</li></ul>
<h2>Core Concepts</h2>
<h3>Concept 1: Cloud Functions Triggers</h3>
<p><strong>Trigger types</strong>:</p>
<ul><li><strong>HTTP</strong>: Direct HTTP requests (synchronous)</li><li><strong>Cloud Pub/Sub</strong>: Message queue (asynchronous)</li><li><strong>Cloud Storage</strong>: Object lifecycle events</li><li><strong>Firestore</strong>: Document changes</li><li><strong>Firebase Auth</strong>: User authentication events</li></ul>
<pre><code class="lang-python">import functions_framework
from google.cloud import storage
# HTTP trigger
@functions_framework.http
def hello_http(request):
name = request.args.get(&#x27;name&#x27;, &#x27;World&#x27;)
return f&#x27;Hello, {name}!&#x27;
# Pub/Sub trigger
@functions_framework.cloud_event
def process_message(cloud_event):
import base64
message = base64.b64decode(cloud_event.data[&quot;message&quot;][&quot;data&quot;]).decode()
print(f&quot;Processing message: {message}&quot;)
# Cloud Storage trigger
@functions_framework.cloud_event
def process_file(cloud_event):
bucket = cloud_event.data[&quot;bucket&quot;]
name = cloud_event.data[&quot;name&quot;]
print(f&quot;File uploaded: gs://{bucket}/{name}&quot;)
# Process file
storage_client = storage.Client()
blob = storage_client.bucket(bucket).blob(name)
content = blob.download_as_text()
# Process content...</code></pre>
<pre><code class="lang-bash"># Deploy HTTP function
gcloud functions deploy hello-http \
--runtime=python311 \
--trigger-http \
--allow-unauthenticated \
--region=us-central1
# Deploy Pub/Sub function
gcloud functions deploy process-message \
--runtime=python311 \
--trigger-topic=message-queue \
--region=us-central1
# Deploy Cloud Storage function
gcloud functions deploy process-file \
--runtime=python311 \
--trigger-event=google.storage.object.finalize \
--trigger-resource=upload-bucket \
--region=us-central1</code></pre>
<h3>Concept 2: Cloud Run Service Configuration</h3>
<p><strong>Key features</strong>:</p>
<ul><li>Deploy any container (not limited to specific runtimes)</li><li>Automatic HTTPS endpoints</li><li>Traffic splitting for gradual rollouts</li><li>Concurrency control (requests per container)</li></ul>
<pre><code class="lang-bash"># Build container with Cloud Build
gcloud builds submit --tag gcr.io/my-project/api-service
# Deploy to Cloud Run
gcloud run deploy api-service \
--image=gcr.io/my-project/api-service \
--region=us-central1 \
--platform=managed \
--allow-unauthenticated \
--memory=512Mi \
--cpu=1 \
--min-instances=0 \
--max-instances=100 \
--concurrency=80 \
--timeout=300 \
--set-env-vars=&quot;DATABASE_URL=postgresql://host/db&quot; \
--set-secrets=&quot;API_KEY=api-key:latest&quot;</code></pre>
<pre><code class="lang-python"># Cloud Run service example (FastAPI)
from fastapi import FastAPI
import os
app = FastAPI()
@app.get(&quot;/&quot;)
def read_root():
return {&quot;message&quot;: &quot;Hello from Cloud Run&quot;}
@app.get(&quot;/health&quot;)
def health_check():
return {&quot;status&quot;: &quot;healthy&quot;}
if __name__ == &quot;__main__&quot;:
import uvicorn
port = int(os.environ.get(&quot;PORT&quot;, 8080))
uvicorn.run(app, host=&quot;0.0.0.0&quot;, port=port)</code></pre>
<h3>Concept 3: App Engine Environments</h3>
<p><strong>Standard vs Flexible</strong>:</p>
<ul><li><strong>Standard</strong>: Fast scaling, language-specific runtimes, free tier</li><li><strong>Flexible</strong>: Custom containers, more control, no free tier</li></ul>
<pre><code class="lang-yaml"># app.yaml for App Engine Standard (Python 3.11)
runtime: python311
instance_class: F2
env_variables:
DATABASE_URL: &quot;postgresql://host/db&quot;
handlers:
- url: /static
static_dir: static
- url: /.*
script: auto
secure: always
automatic_scaling:
target_cpu_utilization: 0.65
min_instances: 1
max_instances: 10
min_pending_latency: 30ms
max_pending_latency: 100ms</code></pre>
<pre><code class="lang-yaml"># app.yaml for App Engine Flexible (custom runtime)
runtime: custom
env: flex
automatic_scaling:
min_num_instances: 1
max_num_instances: 10
cpu_utilization:
target_utilization: 0.65
resources:
cpu: 1
memory_gb: 2
disk_size_gb: 10
env_variables:
DATABASE_URL: &quot;postgresql://host/db&quot;</code></pre>
<h3>Concept 4: Serverless Comparison Matrix</h3>
<p><strong>When to use each service</strong>:</p>
<pre><code>Feature | Cloud Functions | Cloud Run | App Engine Std | App Engine Flex
--------------------|-----------------|----------------|----------------|----------------
Container support | No | Yes (any) | No | Yes (any)
Max request timeout | 9 min | 60 min | 10 min | 60 min
Concurrency/instance| 1 | Up to 1000 | Up to 80 | Up to 80
Cold start | ~1-2s | ~1-3s | &lt;1s | Minutes
Scaling to zero | Yes | Yes | Yes | No (min 1)
Free tier | 2M invocations | 2M requests | 28 hrs/day | No
Best for | Event handlers | APIs, websites | Web apps | Docker apps</code></pre>
<hr>
<h2>Patterns</h2>
<h3>Pattern 1: Cloud Functions with Pub/Sub for Async Processing</h3>
<p><strong>When to use</strong>:</p>
<ul><li>Decouple long-running tasks from HTTP requests</li><li>Retry failed operations automatically</li></ul>
<pre><code class="lang-python"># ❌ Bad: Long-running task in HTTP function (times out)
@functions_framework.http
def process_video(request):
video_url = request.json[&#x27;video_url&#x27;]
# This takes 5 minutes, function times out!
processed_video = expensive_video_processing(video_url)
return {&quot;status&quot;: &quot;done&quot;}
# ✅ Good: Publish to Pub/Sub, process asynchronously
from google.cloud import pubsub_v1
@functions_framework.http
def submit_video(request):
video_url = request.json[&#x27;video_url&#x27;]
# Publish to Pub/Sub (fast)
publisher = pubsub_v1.PublisherClient()
topic_path = publisher.topic_path(&#x27;my-project&#x27;, &#x27;video-processing&#x27;)
publisher.publish(topic_path, video_url.encode())
return {&quot;status&quot;: &quot;queued&quot;}, 202
# Separate function processes videos asynchronously
@functions_framework.cloud_event
def process_video_async(cloud_event):
import base64
video_url = base64.b64decode(cloud_event.data[&quot;message&quot;][&quot;data&quot;]).decode()
# Process for as long as needed (up to 9 minutes)
processed_video = expensive_video_processing(video_url)
# Pub/Sub automatically retries on failure</code></pre>
<p><strong>Benefits</strong>:</p>
<ul><li>HTTP endpoint responds immediately</li><li>Automatic retries on failure</li><li>Scale processing independently from API</li></ul>
<h3>Pattern 2: Cloud Run Traffic Splitting</h3>
<p><strong>Use case</strong>: Canary deployment with gradual rollout</p>
<pre><code class="lang-bash"># Deploy baseline version
gcloud run deploy api-service \
--image=gcr.io/my-project/api:v1 \
--region=us-central1 \
--tag=v1
# Deploy new version with tag (no traffic)
gcloud run deploy api-service \
--image=gcr.io/my-project/api:v2 \
--region=us-central1 \
--tag=v2 \
--no-traffic
# Test new version directly via tagged URL
curl https://v2---api-service-xxx-uc.a.run.app
# Send 10% traffic to new version
gcloud run services update-traffic api-service \
--region=us-central1 \
--to-revisions=v1=90,v2=10
# Monitor metrics, then gradually increase
gcloud run services update-traffic api-service \
--region=us-central1 \
--to-revisions=v1=50,v2=50
# Fully cutover to new version
gcloud run services update-traffic api-service \
--region=us-central1 \
--to-latest</code></pre>
<h3>Pattern 3: Eventarc for Event-Driven Architecture</h3>
<p><strong>Use case</strong>: React to events from multiple sources with unified routing</p>
<pre><code class="lang-bash"># Create Eventarc trigger for Cloud Storage events
gcloud eventarc triggers create storage-trigger \
--location=us-central1 \
--destination-run-service=process-uploads \
--destination-run-region=us-central1 \
--event-filters=&quot;type=google.cloud.storage.object.v1.finalized&quot; \
--event-filters=&quot;bucket=upload-bucket&quot;
# Create trigger for Pub/Sub messages
gcloud eventarc triggers create pubsub-trigger \
--location=us-central1 \
--destination-run-service=process-messages \
--destination-run-region=us-central1 \
--event-filters=&quot;type=google.cloud.pubsub.topic.v1.messagePublished&quot; \
--transport-topic=message-queue
# Cloud Run service receives CloudEvents
from flask import Flask, request
import json
app = Flask(__name__)
@app.post(&quot;/&quot;)
def handle_event():
event = request.get_json()
print(f&quot;Event type: {event[&#x27;type&#x27;]}&quot;)
print(f&quot;Event data: {event[&#x27;data&#x27;]}&quot;)
# Process event based on type
if event[&#x27;type&#x27;] == &#x27;google.cloud.storage.object.v1.finalized&#x27;:
bucket = event[&#x27;data&#x27;][&#x27;bucket&#x27;]
name = event[&#x27;data&#x27;][&#x27;name&#x27;]
# Process uploaded file
elif event[&#x27;type&#x27;] == &#x27;google.cloud.pubsub.topic.v1.messagePublished&#x27;:
message = event[&#x27;data&#x27;][&#x27;message&#x27;][&#x27;data&#x27;]
# Process message
return &quot;&quot;, 204</code></pre>
<h3>Pattern 4: Cold Start Optimization</h3>
<p><strong>Use case</strong>: Reduce latency for first requests after scaling to zero</p>
<pre><code class="lang-python"># ❌ Bad: Load heavy dependencies in request handler
@functions_framework.http
def api_endpoint(request):
import tensorflow as tf # 2 second import!
import numpy as np
model = tf.keras.models.load_model(&#x27;model.h5&#x27;) # 5 second load!
# Process request...
# ✅ Good: Load dependencies at module level (once per instance)
import tensorflow as tf
import numpy as np
# Load model once when instance starts
MODEL = tf.keras.models.load_model(&#x27;model.h5&#x27;)
@functions_framework.http
def api_endpoint(request):
# Model already loaded, fast response
result = MODEL.predict(request.json[&#x27;data&#x27;])
return {&quot;prediction&quot;: result.tolist()}
# For Cloud Run, also use min-instances to keep warm
# gcloud run deploy service --min-instances=1</code></pre>
<h3>Pattern 5: Cloud Scheduler for Cron Jobs</h3>
<p><strong>Use case</strong>: Run periodic tasks on schedule</p>
<pre><code class="lang-bash"># Create job to call HTTP endpoint every hour
gcloud scheduler jobs create http hourly-cleanup \
--location=us-central1 \
--schedule=&quot;0 * * * *&quot; \
--uri=&quot;https://api-service-xxx.run.app/cleanup&quot; \
--http-method=POST \
--oidc-service-account-email=scheduler@my-project.iam.gserviceaccount.com
# Create job to publish Pub/Sub message daily
gcloud scheduler jobs create pubsub daily-report \
--location=us-central1 \
--schedule=&quot;0 9 * * *&quot; \
--topic=report-generation \
--message-body=&#x27;{&quot;report_type&quot;: &quot;daily&quot;}&#x27; \
--time-zone=&quot;America/Los_Angeles&quot;</code></pre>
<h3>Pattern 6: Cloud Tasks for Task Queues</h3>
<p><strong>Use case</strong>: Schedule tasks for specific times or rate-limit processing</p>
<pre><code class="lang-python">from google.cloud import tasks_v2
import json
def enqueue_task(project_id, location, queue_name, url, payload, delay_seconds=0):
client = tasks_v2.CloudTasksClient()
parent = client.queue_path(project_id, location, queue_name)
task = {
&quot;http_request&quot;: {
&quot;http_method&quot;: tasks_v2.HttpMethod.POST,
&quot;url&quot;: url,
&quot;headers&quot;: {&quot;Content-Type&quot;: &quot;application/json&quot;},
&quot;body&quot;: json.dumps(payload).encode()
}
}
# Schedule task for future execution
if delay_seconds:
import datetime
timestamp = datetime.datetime.utcnow() + datetime.timedelta(seconds=delay_seconds)
task[&quot;schedule_time&quot;] = timestamp
response = client.create_task(request={&quot;parent&quot;: parent, &quot;task&quot;: task})
return response
# Example: Send notification email in 1 hour
enqueue_task(
&#x27;my-project&#x27;,
&#x27;us-central1&#x27;,
&#x27;email-queue&#x27;,
&#x27;https://api-service-xxx.run.app/send-email&#x27;,
{&#x27;to&#x27;: &#x27;[email protected]&#x27;, &#x27;subject&#x27;: &#x27;Reminder&#x27;},
delay_seconds=3600
)</code></pre>
<h3>Pattern 7: VPC Connector for Private Resources</h3>
<p><strong>Use case</strong>: Access Cloud SQL, Memorystore, or internal services from serverless</p>
<pre><code class="lang-bash"># Create Serverless VPC Access connector
gcloud compute networks vpc-access connectors create serverless-connector \
--region=us-central1 \
--subnet=default \
--subnet-project=my-project \
--min-instances=2 \
--max-instances=10
# Deploy Cloud Run with VPC connector
gcloud run deploy api-service \
--image=gcr.io/my-project/api \
--region=us-central1 \
--vpc-connector=serverless-connector \
--vpc-egress=private-ranges-only
# Now service can access Cloud SQL via private IP
# DATABASE_URL=postgresql://10.0.0.3:5432/db</code></pre>
<h3>Pattern 8: Secrets Management</h3>
<p><strong>Use case</strong>: Securely inject database passwords and API keys</p>
<pre><code class="lang-bash"># ❌ Bad: Environment variables for secrets (visible in console)
gcloud run deploy api-service \
--set-env-vars=&quot;DB_PASSWORD=super_secret&quot; # Visible in UI!
# ✅ Good: Secret Manager integration
# Create secret
echo -n &quot;super_secret&quot; | gcloud secrets create db-password --data-file=-
# Grant Cloud Run service account access
gcloud secrets add-iam-policy-binding db-password \
--member=serviceAccount:SERVICE_ACCOUNT_EMAIL \
--role=roles/secretmanager.secretAccessor
# Deploy with secret
gcloud run deploy api-service \
--set-secrets=DB_PASSWORD=db-password:latest
# Access in code
import os
db_password = os.environ[&#x27;DB_PASSWORD&#x27;] # Automatically injected</code></pre>
<hr>
<h2>Quick Reference</h2>
<h3>Serverless Service Selection</h3>
<pre><code>Use Case | Best Choice | Why
--------------------------|--------------------|---------------------------------
Event handler (&lt;9 min) | Cloud Functions | Simple, event-driven
HTTP API | Cloud Run | Any language/framework
Web application | App Engine Std | Integrated services, free tier
Custom Docker app | Cloud Run | Full container control
Long-running tasks | Cloud Run Jobs | Up to 24 hours
Legacy app migration | App Engine Flex | Docker, gradual migration</code></pre>
<h3>Key gcloud Commands</h3>
<pre><code class="lang-bash"># Cloud Functions
gcloud functions deploy NAME --runtime=RUNTIME --trigger-http
gcloud functions logs read NAME --limit=50
gcloud functions delete NAME
# Cloud Run
gcloud run deploy SERVICE --image=IMAGE --region=REGION
gcloud run services list
gcloud run services delete SERVICE --region=REGION
# App Engine
gcloud app deploy
gcloud app browse
gcloud app logs tail
# Cloud Scheduler
gcloud scheduler jobs create http JOB --schedule=&quot;CRON&quot; --uri=URL
gcloud scheduler jobs run JOB
# Cloud Tasks
gcloud tasks queues create QUEUE --location=LOCATION
gcloud tasks queues describe QUEUE --location=LOCATION</code></pre>
<h3>Concurrency and Scaling</h3>
<pre><code>Service | Max Concurrency | Scale to Zero | Cold Start
----------------|-----------------|---------------|------------
Cloud Functions | 1 | Yes | ~1-2s
Cloud Run | 1-1000 | Yes | ~1-3s
App Engine Std | 1-80 | Yes | &lt;1s
App Engine Flex | 1-80 | No (min 1) | Minutes</code></pre>
<h3>Key Guidelines</h3>
<pre><code>✅ DO: Load dependencies at module level to reduce cold starts
✅ DO: Use Pub/Sub for async processing in Cloud Functions
✅ DO: Set min-instances for latency-sensitive services
✅ DO: Use Secret Manager for credentials (not env vars)
✅ DO: Implement proper health check endpoints
✅ DO: Configure appropriate concurrency based on backend capacity
❌ DON&#x27;T: Use Cloud Functions for long-running tasks (use Cloud Run)
❌ DON&#x27;T: Store secrets in environment variables
❌ DON&#x27;T: Set max-instances too high without testing backend capacity
❌ DON&#x27;T: Use App Engine Flexible when Standard suffices (higher cost)
❌ DON&#x27;T: Ignore cold start optimization for user-facing APIs</code></pre>
<hr>
<h2>Anti-Patterns</h2>
<h3>Critical Violations</h3>
<pre><code class="lang-python"># ❌ NEVER: Perform long-running task synchronously in HTTP function
@functions_framework.http
def process_batch(request):
for item in request.json[&#x27;items&#x27;]: # 10,000 items!
process_item(item) # Takes 10 minutes total
return &quot;Done&quot;
# Function times out at 9 minutes!
# ✅ CORRECT: Use Pub/Sub or Cloud Run for long tasks
@functions_framework.http
def submit_batch(request):
from google.cloud import pubsub_v1
publisher = pubsub_v1.PublisherClient()
topic_path = publisher.topic_path(&#x27;my-project&#x27;, &#x27;batch-processing&#x27;)
# Enqueue each item
for item in request.json[&#x27;items&#x27;]:
publisher.publish(topic_path, json.dumps(item).encode())
return {&quot;status&quot;: &quot;queued&quot;, &quot;count&quot;: len(request.json[&#x27;items&#x27;])}
# Or use Cloud Run with higher timeout
# gcloud run deploy batch-processor --timeout=3600 # 1 hour</code></pre>
<p>❌ <strong>Synchronous long tasks</strong>: Cloud Functions have 9-minute max timeout. Long-running tasks cause failures. ✅ <strong>Correct approach</strong>: Use Pub/Sub for async processing or Cloud Run for longer timeout (up to 60 minutes).</p>
<h3>Common Mistakes</h3>
<pre><code class="lang-bash"># ❌ Don&#x27;t: Store secrets in environment variables
gcloud run deploy api-service \
--set-env-vars=&quot;API_KEY=sk_live_abc123,DB_PASSWORD=secret&quot;
# Secrets visible in console, logs, error messages
# ✅ Correct: Use Secret Manager
gcloud secrets create api-key --data-file=- &lt;&lt;&lt; &quot;sk_live_abc123&quot;
gcloud secrets create db-password --data-file=- &lt;&lt;&lt; &quot;secret&quot;
gcloud run deploy api-service \
--set-secrets=&quot;API_KEY=api-key:latest,DB_PASSWORD=db-password:latest&quot;</code></pre>
<p>❌ <strong>Env vars for secrets</strong>: Environment variables are visible in console, logs, and error messages. ✅ <strong>Better</strong>: Use Secret Manager integration for secure secret injection.</p>
<pre><code class="lang-python"># ❌ Don&#x27;t: Set unbounded concurrency without testing
# gcloud run deploy api-service --concurrency=1000
# Each instance handles 1000 concurrent requests!
@app.get(&quot;/query&quot;)
def query_database():
# Database has connection pool of 10
result = db.execute(&quot;SELECT * FROM large_table&quot;)
return result
# Database connection pool exhausted, queries fail!
# ✅ Correct: Set concurrency based on backend capacity
# gcloud run deploy api-service --concurrency=5
# Each instance handles max 5 requests (within connection pool limit)</code></pre>
<p>❌ <strong>Unbounded concurrency</strong>: Default Cloud Run concurrency of 80 can overwhelm databases and external APIs. ✅ <strong>Better</strong>: Set max concurrency based on backend capacity (e.g., database connection pool size).</p>
<pre><code class="lang-python"># ❌ Don&#x27;t: Import heavy dependencies in request handler
@functions_framework.http
def predict(request):
import tensorflow as tf # 2 second import on every cold start!
model = tf.keras.models.load_model(&#x27;model.h5&#x27;)
# Process request...
# ✅ Correct: Import at module level (once per instance)
import tensorflow as tf
MODEL = tf.keras.models.load_model(&#x27;model.h5&#x27;) # Load once
@functions_framework.http
def predict(request):
result = MODEL.predict(request.json[&#x27;data&#x27;])
return {&quot;prediction&quot;: result.tolist()}</code></pre>
<p>❌ <strong>Request-level imports</strong>: Importing heavy libraries in request handler increases cold start latency. ✅ <strong>Better</strong>: Import at module level so libraries load once per instance, not per request.</p>
<hr>
<h2>Related Skills</h2>
<ul><li><code>gcp-compute.md</code> - Comparing serverless with VM-based compute</li><li><code>gcp-storage.md</code> - Cloud Functions triggers for Cloud Storage events</li><li><code>gcp-databases.md</code> - Connecting serverless to Cloud SQL and Firestore</li><li><code>gcp-iam-security.md</code> - Service accounts for serverless workloads</li><li><code>gcp-networking.md</code> - VPC connectors for private resource access</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2025-10-25 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/cloud-gcp-serverless.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>