██████╗  ██████╗  ██████╗  ██████╗ ██╗     ███████╗     ██████╗██╗      ██████╗ ██╗   ██╗██████╗
██╔════╝ ██╔═══██╗██╔═══██╗██╔════╝ ██║     ██╔════╝    ██╔════╝██║     ██╔═══██╗██║   ██║██╔══██╗
██║  ███╗██║   ██║██║   ██║██║  ███╗██║     █████╗      ██║     ██║     ██║   ██║██║   ██║██║  ██║
██║   ██║██║   ██║██║   ██║██║   ██║██║     ██╔══╝      ██║     ██║     ██║   ██║██║   ██║██║  ██║
╚██████╔╝╚██████╔╝╚██████╔╝╚██████╔╝███████╗███████╗    ╚██████╗███████╗╚██████╔╝╚██████╔╝██████╔╝
 ╚═════╝  ╚═════╝  ╚═════╝  ╚═════╝ ╚══════╝╚══════╝     ╚═════╝╚══════╝ ╚═════╝  ╚═════╝ ╚═════╝

Google Cloud Developer Training & Resource Guide

Focus: A developer's working map of Google Cloud — what each service is for, how to implement it (gcloud + SDK), what it costs (officially-sourced list prices + free tier), and where it bites. Sourced from cloud.google.com and docs.cloud.google.com; pricing reviewed 2026-06-07. Pricing changes — always confirm on the Pricing Calculator.

How to use this guide

This is a training resource, not just an integration cheat-sheet. Read it in three passes:

1. Mental model → The GCP spine and the compute decision tree. Internalise these and 80% of "which service?" questions answer themselves.
2. Service-by-service → each section below gives Use case · Implement · Cost · Gotcha. Skim the table, dive where you need.
3. Hands-on → the interactive learn module above this page (Cloud Run cost explorer), the official learning paths, and the codeAmani notes for East-Africa-specific guidance.

💡 Per the codeAmani docs policy: when you implement against any of these APIs, pull current docs via the Context7 MCP (resolve-library-id → query-docs) or the official URL in each section — don't code from memory. GCP ships fast.

The GCP spine (a mental model)

Google Cloud is the same infrastructure Google runs Search, Gmail, and YouTube on, rented out. Ignore the 200-product catalogue; a product developer reaches for ~30 services across eight layers:

Two cross-cutting ideas hold it together:

• IAM is the unifier. Every API call is a permission check resolved as a (principal, role, resource) binding. Get IAM right and everything else composes.
• Pricing has two shapes. Serverless (Cloud Run, Functions, BigQuery on-demand, Firestore) bills per use and scales to zero with a genuine always-free tier. Provisioned (Compute Engine, GKE nodes, Cloud SQL, Memorystore) bills for allocated capacity 24/7 whether or not it's busy. Choosing between them is cost optimisation.

Official Documentation

Getting started: SDK, auth, and your first project

Install the Google Cloud SDK (gcloud)

# macOS
brew install --cask google-cloud-sdk

# Linux / WSL
curl https://sdk.cloud.google.com | bash
exec -l $SHELL

# Windows — download the installer:
# https://cloud.google.com/sdk/docs/install

gcloud init          # interactive: pick account + project + region
gcloud components install gke-gcloud-auth-plugin   # if you'll use GKE

No install at all? Open Cloud Shell — a pre-authed gcloud terminal in the browser.

The three ways to authenticate

# 1. You, interactively (local dev, console-style work)
gcloud auth login

# 2. Application Default Credentials — what the SDKs/libraries pick up
gcloud auth application-default login

# 3. A service account (CI/CD, servers). Prefer Workload Identity Federation
#    (below) over downloading a JSON key whenever you can.
gcloud auth activate-service-account --key-file=service-account.json

gcloud config set project my-project-id
gcloud config set run/region africa-south1     # set a default region

★ Why ADC matters — Google's client libraries don't take a key argument; they walk the Application Default Credentials chain (env var GOOGLE_APPLICATION_CREDENTIALS → gcloud user creds → attached service account on GCP). Authenticate once with gcloud auth application-default login and every SDK call "just works" locally with your identity. On Cloud Run/GKE/Compute Engine, the attached service account is the identity — no key files in production.

Enable an API before you call it

Nearly every "permission/404" on a fresh project is a disabled API:

gcloud services enable run.googleapis.com bigquery.googleapis.com \
  secretmanager.googleapis.com aiplatform.googleapis.com
gcloud services list --enabled

Cost & billing model (the part that bites)

All figures below are us-central1 / Tier-1 list prices, reviewed 2026-06-07, from cloud.google.com. Regional pricing varies; cold-tier storage adds retrieval + egress fees. Treat the Pricing Calculator as canonical.

Always-Free tier (per billing account, every month — not the trial)

Source: Free cloud features.

⚠️ The Cloud Run pricing page lists the free tier as 240,000 vCPU-s + 450,000 GiB-s (applied as a spend-based discount at Tier-1 rates), while the free-tier doc lists 180,000 / 360,000. They're published in two places — reconcile on the Calculator for your region.

Headline rates (us-central1, Tier-1 list)

Discount levers (provisioned services)

• Spot VMs — 60–91% off on-demand, can be reclaimed in ~30s. Batch/fault-tolerant only.
• Committed Use Discounts (CUDs) — up to ~55% for 1- or 3-year spend/resource commitments. E2 is eligible.
• Sustained Use Discounts — automatic on some families (E2 has none, but its on-demand list is already low).
• Serverless scale-to-zero — the biggest lever for spiky/low-traffic workloads: an idle Cloud Run service costs ~nothing; an idle VM still bills.

Don't get surprised

# Set a budget + alert (do this on day one)
gcloud billing budgets create --billing-account=BILLING_ID \
  --display-name="codeamani-monthly" \
  --budget-amount=50USD \
  --threshold-rule=percent=0.5 --threshold-rule=percent=0.9

# Egress (data leaving Google) is the silent cost — same-region traffic
# between your services is usually free; cross-region and internet egress are not.

Compute

Pick the right compute primitive in one decision — start at the top and follow the arrows:

Choosing compute: the decision tree

Is it a stateless container that responds to requests/events?
├─ Yes → does a single function/endpoint cover it?
│        ├─ Yes → Cloud Run functions   (smallest unit, event triggers)
│        └─ No  → Cloud Run             (any container, scale-to-zero, websockets, jobs)
└─ No  → do you need Kubernetes / multi-container orchestration / service mesh?
         ├─ Yes → GKE  (Autopilot first; Standard for node-level control)
         └─ No  → need a full OS, GPU, long-running daemon, or custom kernel?
                  ├─ Yes → Compute Engine (VMs; Spot for batch)
                  └─ Legacy/managed PaaS → App Engine

Rule of thumb for codeAmani: start every service on Cloud Run. Graduate to GKE only when you genuinely need Kubernetes primitives, and to Compute Engine only for stateful/GPU/long-running work. Most M-Pesa + Next.js products never leave Cloud Run.

Cloud Run — serverless containers (start here)

• Use case: APIs, full-stack apps (Next.js), webhook/callback receivers, background jobs. The default for codeAmani services.
• Implement:

# Deploy straight from source — Cloud Build builds the container for you
gcloud run deploy my-api --source . --region africa-south1 --allow-unauthenticated

# …or from a prebuilt image
gcloud run deploy my-api --image gcr.io/PROJECT/my-image --region africa-south1

gcloud run services logs tail my-api --region africa-south1
gcloud run jobs create nightly-recon --image gcr.io/PROJECT/recon && \
gcloud run jobs execute nightly-recon

• Cost: vCPU $0.000018/vCPU-s, memory $0.000002/GiB-s (Tier-1 instance-based); requests $0.40/M in request-based mode. Free tier: 2M requests + the vCPU-s/GiB-s allowances above. Scale-to-zero means an idle service ≈ free.
• Gotcha: cold starts. For latency-sensitive endpoints (M-Pesa STK callback), set --min-instances=1. Request-based billing only charges CPU during a request (cheapest for spiky traffic); instance-based keeps CPU "always allocated" (needed for background work / websockets) at lower per-second rates but bills the whole instance lifetime. Pick deliberately — see the cost explorer above.

Cloud Run functions — event-driven snippets

• Use case: "when X happens, run this" — a Storage upload, a Pub/Sub message, an HTTP hook. Smallest deployable unit.
• Implement:

gcloud functions deploy thumb-maker \
  --gen2 --runtime=nodejs22 --region=africa-south1 \
  --trigger-bucket=codeamani-uploads --entry-point=makeThumb

• Cost: 2nd-gen runs on Cloud Run, so it uses Cloud Run pricing + a per-invocation charge; free tier 2M invocations/mo.
• Gotcha: "Cloud Functions (2nd gen)" is now branded Cloud Run functions and shares Cloud Run's runtime/limits. New work → --gen2.

GKE — managed Kubernetes

• Use case: you already speak Kubernetes, need multi-container orchestration, service mesh, or fine pod scheduling.
• Implement:

gcloud container clusters create-auto my-cluster --region africa-south1   # Autopilot
gcloud container clusters get-credentials my-cluster --region africa-south1
kubectl apply -f deployment.yaml

• Cost: $0.10/cluster/hour management fee on every cluster (~$73/mo). Autopilot bills per-second for the vCPU/memory/ephemeral-storage your Pods request (no idle-node waste); Standard bills the underlying nodes regardless of utilisation.
• Gotcha: that flat cluster fee makes a single-service GKE deployment far pricier than Cloud Run. Don't reach for GKE until orchestration genuinely earns its $73/mo.

Compute Engine — virtual machines (the escape hatch)

• Use case: long-running daemons, GPU/TPU jobs, stateful processes, custom kernels — anything the request model can't hold.
• Implement:

gcloud compute instances create dev-box \
  --zone=africa-south1-a --machine-type=e2-small \
  --image-family=debian-12 --image-project=debian-cloud --tags=http-server
gcloud compute ssh dev-box --zone=africa-south1-a
gcloud compute instances stop dev-box --zone=africa-south1-a   # stop to save $$

• Cost: billed 24/7 while running. Spot VMs 60–91% off (reclaimable); CUDs up to ~55%. Persistent disk billed per GB-month even when the VM is stopped.
• Gotcha: open SSH explicitly on non-default networks: gcloud compute firewall-rules create allow-ssh --allow tcp:22. africa-south1 (Johannesburg) is closest to Nairobi; europe-west1 next.

Databases

Cloud SQL — managed relational (default OLTP)

• Implement:

gcloud sql instances create app-db --database-version=POSTGRES_16 \
  --tier=db-f1-micro --region=africa-south1
gcloud sql databases create app --instance=app-db
# From Cloud Run, connect via the built-in Cloud SQL connector (no public IP needed):
gcloud run deploy my-api --add-cloudsql-instances PROJECT:africa-south1:app-db

• Cost: provisioned — you pay for vCPU + RAM + storage 24/7 (and HA doubles it). No scale-to-zero. Gotcha: for low-traffic apps, a small Cloud SQL instance can dwarf your Cloud Run bill — consider Firestore (serverless) if the data model allows.

Firestore — serverless document DB

• Implement:

import { Firestore } from "@google-cloud/firestore";
const db = new Firestore();
await db.collection("payments").doc(checkoutRequestId).set({ status: "PENDING" });

• Cost: per-operation — reads / writes / deletes + stored GiB + egress. Free tier: 50k reads / 20k writes / 20k deletes per day. Gotcha: costs scale with operation count, not data size — a chatty real-time listener can rack up reads. Model for fewer, denormalised documents.

codeAmani pattern: store the M-Pesa CheckoutRequestID as a Firestore doc ID on STK Push, then dedupe on callback — idempotency for free, and it scales to zero between transactions.

Storage

Cloud Storage — object store

• Use case: user uploads, build artefacts, ML data, backups, and the staging bucket for Cloud Build / Agent Engine deploys.
• Implement:

gcloud storage buckets create gs://codeamani-uploads --location=africa-south1
gcloud storage cp ./file.pdf gs://codeamani-uploads/
# Signed URL for a time-limited client upload (no creds on the client):
gcloud storage sign-url gs://codeamani-uploads/file.pdf --duration=15m

• Cost: Standard ~$0.020/GB-mo (US regional). Lifecycle rules auto-tier cold data to Nearline → Coldline → Archive (cheaper at-rest, but add retrieval fees). Egress to the internet is billed.
• Gotcha: cold classes are cheap to store, expensive to read — only tier data you won't touch. Use signed URLs for client up/downloads so you never ship credentials to the browser.

AI / ML

Vertex AI + Gemini

• Use case: Gemini text/multimodal generation with enterprise IAM + regional pinning + data-residency controls; Model Garden; fine-tuning; Vector Search for RAG.
• Implement:

import vertexai
from vertexai.generative_models import GenerativeModel

vertexai.init(project="PROJECT", location="us-central1")
model = GenerativeModel("gemini-2.5-flash")
resp = model.generate_content("Andika salamu fupi kwa Kiswahili.")
print(resp.text)

• Cost: token-based (per 1M input/output tokens), per-model — confirm current rates on the Vertex AI pricing page. Flash tiers are markedly cheaper than Pro.
• Gotcha: Vertex Gemini ≠ AI Studio Gemini. Vertex is the IAM/residency/enterprise path; AI Studio is cheaper and faster to wire for prototypes. Per codeAmani's AI routing, Vertex is for compliance-bound (KDPA) or region-pinned workloads.

Agent Builder / Agent Engine — managed agent runtime

• Use case: production agents needing managed sessions + long-term Memory Bank.
• Implement:

pip install "google-cloud-aiplatform[agent_engines,adk]"
gsutil mb -l us-central1 gs://codeamani-agents-staging   # staging bucket first

import vertexai
from google.adk.agents import Agent
from vertexai.agent_engines import AdkApp

client = vertexai.Client(project="PROJECT", location="us-central1")
agent = Agent(name="support_bot", model="gemini-2.5-pro",
              instruction="Swahili-fluent support agent for codeAmani M-Pesa flows.", tools=[])
engine = client.agent_engines.create(agent_engine=AdkApp(agent=agent), config={
    "staging_bucket": "gs://codeamani-agents-staging",
    "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
})
print(engine.api_resource.name)

• Cost: per request + per session-second. For low-volume agents, Cloud Run + raw Gemini calls is often cheaper.
• Gotcha: staging bucket must exist and be in the same region as the Agent Engine instance. africa-south1 does not host Agent Engine yet → pin to europe-west1 or us-central1.

Eventing, scheduling & orchestration

• Cost: Pub/Sub free tier 10 GiB/mo, then per-GiB; Scheduler is a few cents per job/month; Tasks per-operation.
• Gotcha: Pub/Sub guarantees at-least-once delivery — make subscribers idempotent (the same dedup discipline as M-Pesa callbacks).

DevOps: build, registry, deploy, CI/CD

• Cloud Build — CI/CD (gcloud builds submit --tag …); free 2,500 build-min/mo.
• Artifact Registry — the modern container + package registry (successor to Container Registry). *-docker.pkg.dev.
• Cloud Deploy — managed progressive delivery (dev → staging → prod) for Cloud Run / GKE.

# cloudbuild.yaml — build, test, push, deploy to Cloud Run
steps:
  - { name: node:22, entrypoint: npm, args: [ci] }
  - { name: node:22, entrypoint: npm, args: [test] }
  - { name: gcr.io/cloud-builders/docker,
      args: [build, -t, "$_REGION-docker.pkg.dev/$PROJECT_ID/app/$_SVC:$COMMIT_SHA", .] }
  - { name: gcr.io/cloud-builders/docker,
      args: [push, "$_REGION-docker.pkg.dev/$PROJECT_ID/app/$_SVC:$COMMIT_SHA"] }
  - { name: gcr.io/google.com/cloudsdktool/cloud-sdk, entrypoint: gcloud,
      args: [run, deploy, "$_SVC", "--image=$_REGION-docker.pkg.dev/$PROJECT_ID/app/$_SVC:$COMMIT_SHA",
             "--region=$_REGION"] }
substitutions: { _SVC: my-api, _REGION: africa-south1 }
options: { logging: CLOUD_LOGGING_ONLY }

Networking (the essentials)

• Gotcha: egress is the silent cost. Same-region service-to-service traffic is typically free; cross-region and internet egress bill per GB. Keep your DB, cache, and compute in the same region.

Security & Identity

IAM — every call is a permission check

gcloud projects get-iam-policy PROJECT_ID
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:claude-bot@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/run.developer"

Least-privilege rules of thumb: predefined roles over roles/owner; bind at the narrowest scope (one bucket / one service, not the whole project); one service account per service.

Secret Manager — runtime secrets

gcloud secrets create DARAJA_KEY --data-file=./key.txt
gcloud secrets versions access latest --secret=DARAJA_KEY
# Mount straight into Cloud Run (never bake secrets into env vars/images):
gcloud run deploy my-api --update-secrets=DARAJA_KEY=DARAJA_KEY:latest

Workload Identity Federation — kill the JSON key

For GitHub Actions and other external CI, federate instead of downloading a service-account key:

# GitHub Actions — short-lived token, no long-lived secret to leak
- uses: google-github-actions/auth@v2
  with:
    workload_identity_provider: projects/123/locations/global/workloadIdentityPools/gh/providers/gh
    service_account: deployer@PROJECT.iam.gserviceaccount.com

See https://cloud.google.com/iam/docs/workload-identity-federation. Service-account JSON keys are radioactive — never commit, never ship to a client.

Cloud KMS — managed encryption keys

Customer-managed encryption keys (CMEK) for data you must control at rest — relevant for KDPA/compliance workloads.

Observability

• Cloud Logging — centralised logs (gcloud run services logs tail …); free 50 GiB/project/mo.
• Cloud Monitoring — metrics, dashboards, uptime checks, alerting policies.
• Cloud Trace / Error Reporting — distributed traces + automatic exception grouping.

gcloud logging read 'resource.type=cloud_run_revision severity>=ERROR' --limit 20 --freshness=1h

Cloud Shell (the browser terminal)

A free, pre-authed Debian VM at shell.cloud.google.com: gcloud, gsutil, bq, kubectl, docker, Node, Python; 5 GB persistent $HOME; web preview on port 8080.

gcloud cloud-shell ssh                                   # connect from your terminal
gcloud cloud-shell ssh --command "gcloud run deploy my-api --source ."   # deploy from an iPad

• When to reach for it: onboarding (no local SDK), demos/pairing (share a URL), one-off bq/gcloud from a phone.
• Gotcha: only $HOME persists. gcloud config lives in a temp dir — persist anything you care about under $HOME.

Claude Code integration

gcloud via the Bash tool (most reliable)

// .claude/settings.json
{ "permissions": { "allow": ["Bash(gcloud:*)", "Bash(gsutil:*)", "Bash(bq:*)"] } }

Community MCP server

GCP has no first-party MCP server; community servers wrap the SDK:

{ "mcpServers": { "gcp": { "command": "npx", "args": ["-y", "gcp-mcp"],
  "env": { "GOOGLE_APPLICATION_CREDENTIALS": "${GOOGLE_APPLICATION_CREDENTIALS}",
           "GOOGLE_CLOUD_PROJECT": "${GOOGLE_CLOUD_PROJECT}" } } } }

Slash command: analyze Cloud Run logs

<!-- .claude/commands/gcp-logs.md -->
Analyze recent Cloud Run logs for $ARGUMENTS.
Run: gcloud run services logs tail $ARGUMENTS --region africa-south1 --limit 50
Summarise errors, high-latency requests, and crash loops with root causes + fixes.

Environment variables

GOOGLE_CLOUD_PROJECT=my-project-id
GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa.json   # local only; use ADC/WIF where possible
GOOGLE_CLOUD_REGION=africa-south1

Official learning resources

Train, don't guess. All first-party:

Suggested path for a codeAmani dev: Free Tier sign-up → deploy a container to Cloud Run (Codelab) → wire Firestore + Secret Manager → add a Cloud Build pipeline → layer Vertex/Gemini → read the cost + security pillars of the Well-Architected Framework.

Troubleshooting

codeAmani notes

• Secrets stay server-side. Service-account JSON keys are radioactive — never commit, never ship to a client. Prefer Workload Identity Federation for GitHub Actions and ADC locally. Mount Secret Manager versions into Cloud Run (--update-secrets=DARAJA_KEY=DARAJA_KEY:latest) rather than baking values into env vars or images.
• AI routing. Vertex AI is the Gemini path when you need region pinning or enterprise IAM (KDPA/HIPAA-style workloads). For plain Gemini calls without residency constraints, AI Studio is cheaper and faster. Reserve Agent Engine for production agents needing Memory Bank + managed sessions; one-shot agentic flows are leaner on Cloud Run + raw Gemini.
• African market. africa-south1 (Johannesburg) is the closest GCP region to Kenya — use it for Cloud Run, Compute Engine, Cloud Storage, Cloud SQL, and Firestore where possible. Agent Engine and some Vertex features aren't there yet; fall back to europe-west1 (Belgium), which still beats us-central1 on RTT to Nairobi.
• M-Pesa callbacks. Host the Daraja callback on Cloud Run with --min-instances=1 so the first STK Push of the day doesn't time out on a cold start. Store the CheckoutRequestID in Firestore (serverless, scales to zero between transactions) as the idempotency/dedup key — never in memory.
• Cost for a lean SaaS. Cloud Run (scale-to-zero) + Firestore (per-op, free daily tier) + Cloud Storage + Secret Manager keeps a low-traffic East-African product comfortably inside or near the always-free tier. Avoid an always-on Cloud SQL or a GKE cluster until traffic justifies the 24/7 spend.