mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
hanzoskills.com/llms.txt now opens with the install line, the API reference index and the company index, so an agent that lands on any one of the three can find the rest. robots.txt claimed 537 documents while llms.txt counts 920. The number is gone from robots.txt; llms.txt derives it. public/ is regenerated from scripts/site.py, which it had fallen behind: the copy-prompt menu and agent bar were in the generator and not in the committed pages. tests/site.mjs passes against the result. Co-authored-by: Hanzo Dev <[email protected]>
727 lines
34 KiB
HTML
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="alternate" type="text/markdown" href="/cloud-gcp-serverless.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/cloud-gcp-serverless">
|
|
</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('name', 'World')
|
|
return f'Hello, {name}!'
|
|
|
|
# Pub/Sub trigger
|
|
@functions_framework.cloud_event
|
|
def process_message(cloud_event):
|
|
import base64
|
|
message = base64.b64decode(cloud_event.data["message"]["data"]).decode()
|
|
print(f"Processing message: {message}")
|
|
|
|
# Cloud Storage trigger
|
|
@functions_framework.cloud_event
|
|
def process_file(cloud_event):
|
|
bucket = cloud_event.data["bucket"]
|
|
name = cloud_event.data["name"]
|
|
print(f"File uploaded: gs://{bucket}/{name}")
|
|
|
|
# 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="DATABASE_URL=postgresql://host/db" \
|
|
--set-secrets="API_KEY=api-key:latest"</code></pre>
|
|
<pre><code class="lang-python"># Cloud Run service example (FastAPI)
|
|
from fastapi import FastAPI
|
|
import os
|
|
|
|
app = FastAPI()
|
|
|
|
@app.get("/")
|
|
def read_root():
|
|
return {"message": "Hello from Cloud Run"}
|
|
|
|
@app.get("/health")
|
|
def health_check():
|
|
return {"status": "healthy"}
|
|
|
|
if __name__ == "__main__":
|
|
import uvicorn
|
|
port = int(os.environ.get("PORT", 8080))
|
|
uvicorn.run(app, host="0.0.0.0", 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: "postgresql://host/db"
|
|
|
|
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: "postgresql://host/db"</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 | <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['video_url']
|
|
# This takes 5 minutes, function times out!
|
|
processed_video = expensive_video_processing(video_url)
|
|
return {"status": "done"}
|
|
|
|
# ✅ Good: Publish to Pub/Sub, process asynchronously
|
|
from google.cloud import pubsub_v1
|
|
|
|
@functions_framework.http
|
|
def submit_video(request):
|
|
video_url = request.json['video_url']
|
|
|
|
# Publish to Pub/Sub (fast)
|
|
publisher = pubsub_v1.PublisherClient()
|
|
topic_path = publisher.topic_path('my-project', 'video-processing')
|
|
publisher.publish(topic_path, video_url.encode())
|
|
|
|
return {"status": "queued"}, 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["message"]["data"]).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="type=google.cloud.storage.object.v1.finalized" \
|
|
--event-filters="bucket=upload-bucket"
|
|
|
|
# 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="type=google.cloud.pubsub.topic.v1.messagePublished" \
|
|
--transport-topic=message-queue
|
|
|
|
# Cloud Run service receives CloudEvents
|
|
from flask import Flask, request
|
|
import json
|
|
|
|
app = Flask(__name__)
|
|
|
|
@app.post("/")
|
|
def handle_event():
|
|
event = request.get_json()
|
|
print(f"Event type: {event['type']}")
|
|
print(f"Event data: {event['data']}")
|
|
|
|
# Process event based on type
|
|
if event['type'] == 'google.cloud.storage.object.v1.finalized':
|
|
bucket = event['data']['bucket']
|
|
name = event['data']['name']
|
|
# Process uploaded file
|
|
elif event['type'] == 'google.cloud.pubsub.topic.v1.messagePublished':
|
|
message = event['data']['message']['data']
|
|
# Process message
|
|
|
|
return "", 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('model.h5') # 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('model.h5')
|
|
|
|
@functions_framework.http
|
|
def api_endpoint(request):
|
|
# Model already loaded, fast response
|
|
result = MODEL.predict(request.json['data'])
|
|
return {"prediction": 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="0 * * * *" \
|
|
--uri="https://api-service-xxx.run.app/cleanup" \
|
|
--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="0 9 * * *" \
|
|
--topic=report-generation \
|
|
--message-body='{"report_type": "daily"}' \
|
|
--time-zone="America/Los_Angeles"</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 = {
|
|
"http_request": {
|
|
"http_method": tasks_v2.HttpMethod.POST,
|
|
"url": url,
|
|
"headers": {"Content-Type": "application/json"},
|
|
"body": json.dumps(payload).encode()
|
|
}
|
|
}
|
|
|
|
# Schedule task for future execution
|
|
if delay_seconds:
|
|
import datetime
|
|
timestamp = datetime.datetime.utcnow() + datetime.timedelta(seconds=delay_seconds)
|
|
task["schedule_time"] = timestamp
|
|
|
|
response = client.create_task(request={"parent": parent, "task": task})
|
|
return response
|
|
|
|
# Example: Send notification email in 1 hour
|
|
enqueue_task(
|
|
'my-project',
|
|
'us-central1',
|
|
'email-queue',
|
|
'https://api-service-xxx.run.app/send-email',
|
|
{'to': '[email protected]', 'subject': 'Reminder'},
|
|
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="DB_PASSWORD=super_secret" # Visible in UI!
|
|
|
|
# ✅ Good: Secret Manager integration
|
|
# Create secret
|
|
echo -n "super_secret" | 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['DB_PASSWORD'] # Automatically injected</code></pre>
|
|
<hr>
|
|
<h2>Quick Reference</h2>
|
|
<h3>Serverless Service Selection</h3>
|
|
<pre><code>Use Case | Best Choice | Why
|
|
--------------------------|--------------------|---------------------------------
|
|
Event handler (<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="CRON" --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 | <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'T: Use Cloud Functions for long-running tasks (use Cloud Run)
|
|
❌ DON'T: Store secrets in environment variables
|
|
❌ DON'T: Set max-instances too high without testing backend capacity
|
|
❌ DON'T: Use App Engine Flexible when Standard suffices (higher cost)
|
|
❌ DON'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['items']: # 10,000 items!
|
|
process_item(item) # Takes 10 minutes total
|
|
return "Done"
|
|
# 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('my-project', 'batch-processing')
|
|
|
|
# Enqueue each item
|
|
for item in request.json['items']:
|
|
publisher.publish(topic_path, json.dumps(item).encode())
|
|
|
|
return {"status": "queued", "count": len(request.json['items'])}
|
|
|
|
# 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't: Store secrets in environment variables
|
|
gcloud run deploy api-service \
|
|
--set-env-vars="API_KEY=sk_live_abc123,DB_PASSWORD=secret"
|
|
# Secrets visible in console, logs, error messages
|
|
|
|
# ✅ Correct: Use Secret Manager
|
|
gcloud secrets create api-key --data-file=- <<< "sk_live_abc123"
|
|
gcloud secrets create db-password --data-file=- <<< "secret"
|
|
|
|
gcloud run deploy api-service \
|
|
--set-secrets="API_KEY=api-key:latest,DB_PASSWORD=db-password:latest"</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't: Set unbounded concurrency without testing
|
|
# gcloud run deploy api-service --concurrency=1000
|
|
# Each instance handles 1000 concurrent requests!
|
|
|
|
@app.get("/query")
|
|
def query_database():
|
|
# Database has connection pool of 10
|
|
result = db.execute("SELECT * FROM large_table")
|
|
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'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('model.h5')
|
|
# Process request...
|
|
|
|
# ✅ Correct: Import at module level (once per instance)
|
|
import tensorflow as tf
|
|
|
|
MODEL = tf.keras.models.load_model('model.h5') # Load once
|
|
|
|
@functions_framework.http
|
|
def predict(request):
|
|
result = MODEL.predict(request.json['data'])
|
|
return {"prediction": 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> |