GCP essentials

Get a small product running on the core of Google Cloud — safely and cheaply — with the gcloud CLI as the source of truth. The console is fine for reading; the CLI is what you commit, review, and reproduce. Bias toward secure-by-default and near-zero bill, not "every GCP service".

Four primitives carry most products, plus the project/billing scaffold under them:

• IAM — who can do what. Get this wrong and nothing else matters.
• Cloud Run — serverless containers, scale to zero.
• Cloud Storage — object storage (buckets).
• Cloud SQL — managed Postgres/MySQL.

Out of scope, route elsewhere: AWS -> ../aws-essentials/SKILL.md. Building/shipping the image itself -> ../docker/SKILL.md / ../github-actions/SKILL.md / ../deployment/SKILL.md. Postgres schema/index/query tuning -> ../postgresdb/SKILL.md. App-level injection/secret-handling review -> ../secure-coding/SKILL.md. Logging/alerting/SLOs as a practice -> ../monitoring/SKILL.md. Backup strategy as a discipline -> ../backups/SKILL.md. One-click PaaS where you never touch IAM/VPC -> ../vercel/SKILL.md / ../railway/SKILL.md / ../render/SKILL.md / ../fly-io/SKILL.md.

0. Bootstrap a project

One project per environment (e.g. acme-prod, acme-staging). Projects are the IAM and billing boundary; mixing prod and dev in one project is how a staging credential deletes prod data.

# Create the project and point gcloud at it
gcloud projects create acme-prod --name="Acme prod"
gcloud config set project acme-prod
gcloud config set run/region europe-west1   # set once; every run command inherits it

# Link billing (no billing = APIs 403). Find your account id first:
gcloud billing accounts list
gcloud billing projects link acme-prod --billing-account=0X0X0X-0X0X0X-0X0X0X

# Enable ONLY the APIs this product needs. Why: every enabled API widens the
# attack surface and some bill the moment they are on.
gcloud services enable \
  run.googleapis.com \
  sqladmin.googleapis.com \
  storage.googleapis.com \
  secretmanager.googleapis.com \
  iam.googleapis.com

1. IAM without footguns

A binding is member + role on a resource. Members come in three flavours you will actually type:

Member type	Syntax	Use for
User	user:alice@acme.com	a human
Group	group:eng@acme.com	a team (manage in Workspace)
Service account	serviceAccount:NAME@PROJ.iam.gserviceaccount.com	a workload identity

Grant grammar — bind at the smallest resource that works (project here, but prefer bucket/instance scope when the role supports it):

gcloud projects add-iam-policy-binding acme-prod \
  --member="serviceAccount:api@acme-prod.iam.gserviceaccount.com" \
  --role="roles/cloudsql.client"

Choosing a role:

Role kind	Example	When
Primitive	roles/owner, roles/editor	Almost never on a workload — project-wide, far too broad.
Predefined	roles/storage.objectAdmin	Default. Google-maintained, scoped to one service.
Custom	your own permission list	Only when no predefined role fits — you now own the upkeep.

Two hard rules, each with teeth:

1. Never run a workload as the default compute service account. It carries Editor on the whole project, so a single RCE in your container = full project takeover. Mint a dedicated SA per service and pass it explicitly (see Cloud Run).

   gcloud iam service-accounts create api-sa --display-name="api runtime"
   

2. Never create service-account JSON keys. A leaked key is a long-lived, un-rotated credential. Use the attached SA on Cloud Run/Compute, and Workload Identity Federation for external/CI auth (GitHub Actions). If ... keys create is in your runbook, the runbook is wrong.

The predefined-role catalog, WIF for keyless CI, SA impersonation, IAM Recommender and Conditions live in references/iam-and-auth.md.

2. Cloud Run

Minimal safe deploy: dedicated runtime SA, explicit region, no anonymous ingress.

gcloud run deploy api \
  --image=europe-west1-docker.pkg.dev/acme-prod/app/api:1.4.0 \
  --region=europe-west1 \
  --service-account=api-sa@acme-prod.iam.gserviceaccount.com \
  --no-allow-unauthenticated

• --service-account sets the runtime identity. Omit it and the revision runs as the over-privileged default compute SA — the rule-1 footgun. Always pass it.
• --no-allow-unauthenticated keeps the service private (callers need roles/run.invoker). Flip to --allow-unauthenticated only for a genuinely public endpoint. Open by accident and you have shipped an unauthenticated API.

Production knobs:

# Cold starts hurt: pin a warm instance and boost CPU on startup.
# Default min-instances is 0 (scales to zero); default max is 100 (your cost ceiling).
gcloud run services update api --region=europe-west1 \
  --min-instances=1 --cpu-boost --max-instances=20

Config vs secrets — secrets never go in --set-env-vars, because env vars show up in plaintext in describe, logs and the console. Mount them from Secret Manager:

gcloud run deploy api --region=europe-west1 \
  --service-account=api-sa@acme-prod.iam.gserviceaccount.com \
  --set-env-vars="LOG_LEVEL=info" \
  --set-secrets="DB_PASSWORD=db-password:latest"

3. Cloud Storage

Create buckets locked down; loosen deliberately, never the reverse.

gcloud storage buckets create gs://acme-prod-uploads \
  --location=europe-west1 \
  --uniform-bucket-level-access \
  --public-access-prevention

• --uniform-bucket-level-access (UBLA) turns off per-object ACLs so access is only IAM — one place to reason about, one place to audit. There is a 90-day window to revert UBLA; after that it is permanent, so set it at creation.
• --public-access-prevention makes a public grant impossible even by mistake.

Grant access to the workload, not the world:

gcloud storage buckets add-iam-policy-binding gs://acme-prod-uploads \
  --member="serviceAccount:api-sa@acme-prod.iam.gserviceaccount.com" \
  --role="roles/storage.objectAdmin"

Need to hand a file to an anonymous browser? Use a signed URL (time-limited), never allUsers:

gcloud storage sign-url gs://acme-prod-uploads/report.pdf --duration=15m \
  --impersonate-service-account=api-sa@acme-prod.iam.gserviceaccount.com

--impersonate-service-account is not decoration. Signing needs a private key, and the keyless model this skill mandates (attached SA, no JSON keys) hands you an ADC token, not a key. The flag tells gcloud to sign via the IAM signBlob API instead — so the caller must hold roles/iam.serviceAccountTokenCreator (which grants iam.serviceAccounts.signBlob) on api-sa. Without it, the command fails or silently wants a key file, which would reopen the rule-2 footgun. Grant it once:

gcloud iam service-accounts add-iam-policy-binding \
  api-sa@acme-prod.iam.gserviceaccount.com \
  --member="serviceAccount:api-sa@acme-prod.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountTokenCreator"

Durability one-liners:

gcloud storage buckets update gs://acme-prod-uploads --versioning      # keep old versions
gcloud storage buckets update gs://acme-prod-uploads \
  --lifecycle-file=lifecycle.json                                      # auto-expire/age out

4. Cloud SQL

Create a managed Postgres with a private IP and no public IP — the public IP is the part that gets scanned and brute-forced.

gcloud sql instances create acme-db \
  --database-version=POSTGRES_16 \
  --edition=ENTERPRISE \
  --region=europe-west1 \
  --tier=db-f1-micro \
  --no-assign-ip \
  --network=projects/acme-prod/global/networks/default

--edition=ENTERPRISE is mandatory here, not optional. From POSTGRES_16 up the default edition is Enterprise Plus, which only runs on N2/C4A/N4 machine series — the shared-core db-f1-micro is an Enterprise-only tier, so the create fails without this flag. Want the cheapest box? Stay on Enterprise. Reach for Enterprise Plus only when you actually need its dedicated cores and faster failover, and drop --tier for a --cpu/--memory pair then.

Put the password in Secret Manager, not in a flag or a file:

gcloud sql users create app --instance=acme-db --password="$(openssl rand -base64 24)"
printf '%s' "$(openssl rand -base64 24)" | \
  gcloud secrets create db-password --data-file=-

Attach the instance to Cloud Run — serverless connects over a Unix socket, no Auth Proxy sidecar needed:

gcloud run deploy api --region=europe-west1 \
  --service-account=api-sa@acme-prod.iam.gserviceaccount.com \
  --add-cloudsql-instances=acme-prod:europe-west1:acme-db \
  --set-secrets="DB_PASSWORD=db-password:latest"
# In the app, connect via the socket:
#   host=/cloudsql/acme-prod:europe-west1:acme-db

The Cloud SQL Auth Proxy (short-lived certs, TLS 1.3) is for connecting from outside — local dev or a non-serverless host — not for Cloud Run. Direct VPC egress vs legacy connectors, private IP / PSC, proxy invocation and pooling are in references/networking-and-sql.md.

5. Wire it together

One service, one dedicated SA, exactly the roles it needs — and nothing else.

# Identity
gcloud iam service-accounts create api-sa --display-name="api runtime"
SA=api-sa@acme-prod.iam.gserviceaccount.com

# Exactly four predefined roles. No Editor, no Owner.
gcloud projects add-iam-policy-binding acme-prod \
  --member="serviceAccount:$SA" --role="roles/cloudsql.client"
gcloud secrets add-iam-policy-binding db-password \
  --member="serviceAccount:$SA" --role="roles/secretmanager.secretAccessor"
gcloud storage buckets add-iam-policy-binding gs://acme-prod-uploads \
  --member="serviceAccount:$SA" --role="roles/storage.objectAdmin"

# Deploy with all three wired in
gcloud run deploy api --region=europe-west1 \
  --image=europe-west1-docker.pkg.dev/acme-prod/app/api:1.4.0 \
  --service-account="$SA" \
  --no-allow-unauthenticated \
  --add-cloudsql-instances=acme-prod:europe-west1:acme-db \
  --set-secrets="DB_PASSWORD=db-password:latest" \
  --set-env-vars="BUCKET=acme-prod-uploads"

Note the scoping: cloudsql.client is project-wide (the role needs it), but the storage and secret grants are bound to the specific bucket and secret, not the project. Grant narrow.

Copy-paste runbooks for each piece — image build and push, private container deploy, attach SQL, mount a secret, full teardown — are in references/deploy-recipes.md.

6. Cost & teardown

• Cloud Run scales to zero by default — an idle service costs ~nothing. Keep --min-instances=0 on staging.
• Cap blast radius with --max-instances and a budget alert (full command in references/deploy-recipes.md):

  gcloud billing budgets create --billing-account=0X0X0X-0X0X0X-0X0X0X \
    --display-name="acme-prod" --budget-amount=50 \
    --threshold-rule=percent=0.9
  

• Tear down in dependency order so nothing dangles:

  gcloud run services delete api --region=europe-west1
  gcloud sql instances delete acme-db
  gcloud storage rm --recursive gs://acme-prod-uploads
  

Anti-patterns

Bad	Good	Why
Deploy with no --service-account	Pass a dedicated per-service SA	Default compute SA has Editor; an RCE becomes project takeover
gcloud iam service-accounts keys create key.json	Attached SA + Workload Identity Federation	JSON keys are long-lived, leak, and are rarely rotated
--role=roles/editor on a workload SA	Scoped predefined roles (cloudsql.client, …)	Primitive roles grant far more than the service needs
Bucket public via allUsers	Signed URL via --impersonate-service-account (+ Token Creator)	A public bucket is a data leak; keyless signing needs signBlob, not a key file
Bucket created without UBLA/PAP	--uniform-bucket-level-access --public-access-prevention at create	ACLs sprawl; PAP blocks accidental public grants
Cloud SQL with public IP open to 0.0.0.0/0	--no-assign-ip + private IP / Auth Proxy	Public DB IPs get scanned and brute-forced
Secrets in --set-env-vars	--set-secrets from Secret Manager	Env vars are plaintext in describe, logs, console
gcloud services enable everything	Enable only the APIs you use	Each API widens attack surface; some bill on enable
No --min-instances on prod, then blame cold starts	--min-instances=1 --cpu-boost on prod	Scale-to-zero is the cause; pin a warm instance
Auth Proxy sidecar on Cloud Run	--add-cloudsql-instances + /cloudsql/... socket	Serverless connects natively; the proxy is for outside-VPC

Verify

scripts/verify.sh is an offline static linter (no GCP calls, no network) over files that contain gcloud command blocks. It flags the unsafe patterns above: JSON key creation, roles/owner|roles/editor bound to a service account, bucket creates missing UBLA/PAP, Cloud SQL public IP without private IP, and Cloud Run deploys missing --service-account.

bash scripts/verify.sh path/to/runbook.sh        # one file
bash scripts/verify.sh path/to/dir/              # recurse a directory

It prints PASS/FAIL per check and exits nonzero on any FAIL. An empty or clean target passes (exit 0).