rsc-universal 0.1.1

package/skills/gcp-essentials/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: gcp-essentials
+description: "Use when running a small product on the core of Google Cloud with the gcloud CLI: creating a project, deploying a container to Cloud Run, standing up a Cloud Storage bucket, a managed Cloud SQL Postgres/MySQL, and wiring them together with least-privilege IAM. Triggers: 'deploy to Cloud Run', 'gcloud run deploy', 'set up a GCP project', 'crear bucket en GCP', 'desplegar a Cloud Run', 'service account sin claves JSON', 'why is my Cloud Run running as the default service account', 'connect Cloud Run to Cloud SQL', 'turn off the bucket public access'. NOT AWS (that is aws-essentials)."
+tags: [gcp, cloud-run, cloud-sql, cloud-storage, iam, gcloud, serverless, devops]
+recommends: [aws-essentials, docker, github-actions, secure-coding, postgresdb, deployment, monitoring, backups]
+origin: risco
+---
+
+# 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`. Building/shipping the image
+itself -> `docker` / `github-actions` / [`../deployment/SKILL.md`](../deployment/SKILL.md).
+Postgres schema/index/query tuning -> [`../postgresdb/SKILL.md`](../postgresdb/SKILL.md).
+App-level injection/secret-handling review -> [`../secure-coding/SKILL.md`](../secure-coding/SKILL.md).
+Logging/alerting/SLOs as a practice -> `monitoring`. Backup strategy as a discipline
+-> `backups`. One-click PaaS where you never touch IAM/VPC -> [`../vercel/SKILL.md`](../vercel/SKILL.md)
+/ [`../railway/SKILL.md`](../railway/SKILL.md) / [`../render/SKILL.md`](../render/SKILL.md)
+/ [`../fly-io/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.
+
+```bash
+# 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):
+
+```bash
+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).
+   ```bash
+   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.
+
+WIF for keyless CI, SA impersonation, IAM Recommender and Conditions live in
+[`references/iam-and-auth.md`](references/iam-and-auth.md).
+
+## 2. Cloud Run
+
+Minimal *safe* deploy: dedicated runtime SA, explicit region, no anonymous ingress.
+
+```bash
+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:
+
+```bash
+# 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:
+
+```bash
+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.
+
+```bash
+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:
+
+```bash
+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`:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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.
+
+```bash
+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:
+
+```bash
+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**:
+
+```bash
+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. Private IP, PSC
+and proxy invocation are in [`references/networking-and-sql.md`](references/networking-and-sql.md).
+
+## 5. Wire it together
+
+One service, one dedicated SA, exactly the roles it needs — and nothing else.
+
+```bash
+# 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.
+
+## 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`](references/deploy-recipes.md)):
+  ```bash
+  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:
+  ```bash
+  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
+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).
+
+## References
+
+- [`references/iam-and-auth.md`](references/iam-and-auth.md) — predefined-role catalog,
+  Workload Identity Federation for GitHub Actions, SA impersonation, IAM Recommender,
+  Conditions.
+- [`references/networking-and-sql.md`](references/networking-and-sql.md) — Direct VPC
+  egress vs legacy connectors, Cloud SQL private IP / PSC, Auth Proxy, pooling.
+- [`references/deploy-recipes.md`](references/deploy-recipes.md) — copy-paste runbooks:
+  container deploy, attach SQL, mount a secret, budget alert, full teardown.

package/skills/gcp-essentials/evals/README.md

@@ -0,0 +1,12 @@
+# Evals — gcp-essentials
+
+`cases.yaml` drives two checks through the repo's standard eval harness. The
+`should_trigger` / `should_not_trigger` prompts verify routing: each negative case
+names the real sibling skill it should defer to (`aws-essentials`, `docker`,
+`postgresdb`, `secure-coding`, `vercel`) so the boundary is graded, not assumed. The
+`capability` case is graded by an LLM judge against its `must_include` rubric — there
+are no live GCP calls and nothing is deployed; the judge reads the produced gcloud
+commands and checks that they are least-privilege, keyless, private-by-default, and
+include a cost/teardown note. Run it the same way as every other skill in this repo
+(point the harness at this directory); inspect any rubric miss by hand before trusting
+the score.

package/skills/gcp-essentials/evals/cases.yaml

@@ -0,0 +1,38 @@
+skill: gcp-essentials
+
+should_trigger:
+  - prompt: "Deploy this container to Cloud Run with the gcloud CLI and keep it private."
+    why: "Cloud Run deployment with gcloud is the core GCP runtime path this skill owns."
+  - prompt: "Set up a small GCP project with Cloud SQL Postgres and a storage bucket."
+    why: "Project bootstrap plus Cloud SQL and Cloud Storage are core primitives in the skill."
+  - prompt: "Why is my Cloud Run service using the default compute service account?"
+    why: "Avoiding the default compute service account is a named IAM footgun this skill handles."
+  - prompt: "Connect Cloud Run to Cloud SQL without exposing the database publicly."
+    why: "Cloud Run to Cloud SQL with private/safe connectivity is a central workflow."
+  - prompt: "Crear un bucket en GCP bloqueando acceso publico y usando IAM correctamente."
+    why: "Spanish GCP bucket setup with public access prevention and IAM maps directly to Cloud Storage guidance."
+
+should_not_trigger:
+  - prompt: "Deploy this app to AWS Lambda with S3 and RDS."
+    route_to: "aws-essentials"
+    why: "AWS services belong to the AWS cloud skill, not GCP."
+  - prompt: "Tune this Postgres query and choose indexes after EXPLAIN ANALYZE."
+    route_to: "postgresdb"
+    why: "Postgres schema/query tuning is the database skill; GCP only owns Cloud SQL operations."
+  - prompt: "Create a Dockerfile and GitHub Actions workflow to build my image."
+    route_to: "deployment"
+    why: "Container build and CI/CD mechanics are deployment work, not GCP service setup."
+  - prompt: "Review this authentication code for injection and broken authorization."
+    route_to: "secure-coding"
+    why: "Application security review belongs to secure-coding."
+
+capability:
+  - scenario: "A developer says: 'I need a private Cloud Run API connected to Cloud SQL and a bucket, with least-privilege IAM. Give me the safe gcloud shape.'"
+    must_include:
+      - "Creates or selects a GCP project and enables only required APIs."
+      - "Creates a dedicated runtime service account and explicitly avoids the default compute service account."
+      - "Deploys Cloud Run with --service-account and --no-allow-unauthenticated unless a public endpoint is intentional."
+      - "Creates Cloud Storage with uniform bucket-level access and public access prevention."
+      - "Uses Secret Manager for DB password/secrets, not plaintext env vars."
+      - "Connects Cloud Run to Cloud SQL with the proper instance attachment/socket guidance."
+      - "Keeps IAM grants narrow and uses predefined roles instead of Owner/Editor."

package/skills/gcp-essentials/references/deploy-recipes.md

@@ -0,0 +1,81 @@
+# Deploy recipes
+
+Copy-paste runbooks. Replace `acme-prod`, region, image tag, and the billing account
+id. Every block assumes `gcloud config set project acme-prod` and
+`gcloud config set run/region europe-west1` are done.
+
+## Build & push an image to Artifact Registry
+
+```bash
+gcloud artifacts repositories create app \
+  --repository-format=docker --location=europe-west1
+gcloud auth configure-docker europe-west1-docker.pkg.dev
+docker build -t europe-west1-docker.pkg.dev/acme-prod/app/api:1.4.0 .
+docker push europe-west1-docker.pkg.dev/acme-prod/app/api:1.4.0
+```
+
+## Deploy a private container with a dedicated SA
+
+```bash
+gcloud iam service-accounts create api-sa --display-name="api runtime"
+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
+```
+
+## Attach Cloud SQL to the service
+
+```bash
+gcloud projects add-iam-policy-binding acme-prod \
+  --member="serviceAccount:api-sa@acme-prod.iam.gserviceaccount.com" \
+  --role="roles/cloudsql.client"
+gcloud run services update api --region=europe-west1 \
+  --add-cloudsql-instances=acme-prod:europe-west1:acme-db
+# App connects via host=/cloudsql/acme-prod:europe-west1:acme-db
+```
+
+## Mount a Secret Manager secret
+
+```bash
+printf '%s' "$(openssl rand -base64 24)" | gcloud secrets create db-password --data-file=-
+gcloud secrets add-iam-policy-binding db-password \
+  --member="serviceAccount:api-sa@acme-prod.iam.gserviceaccount.com" \
+  --role="roles/secretmanager.secretAccessor"
+gcloud run services update api --region=europe-west1 \
+  --set-secrets="DB_PASSWORD=db-password:latest"
+```
+
+To rotate: add a new version, then redeploy (or rely on `:latest`):
+
+```bash
+printf '%s' "$NEW" | gcloud secrets versions add db-password --data-file=-
+```
+
+## Budget alert
+
+```bash
+gcloud billing budgets create \
+  --billing-account=0X0X0X-0X0X0X-0X0X0X \
+  --display-name="acme-prod monthly" \
+  --budget-amount=50 \
+  --threshold-rule=percent=0.5 \
+  --threshold-rule=percent=0.9 \
+  --threshold-rule=percent=1.0
+```
+
+A budget alert notifies; it does **not** cap spend. To actually stop spend, wire the
+Pub/Sub budget notification to a function that disables billing on the project.
+
+## Full teardown (dependency order)
+
+```bash
+gcloud run services delete api --region=europe-west1 --quiet
+gcloud sql instances delete acme-db --quiet
+gcloud storage rm --recursive gs://acme-prod-uploads
+gcloud secrets delete db-password --quiet
+gcloud iam service-accounts delete api-sa@acme-prod.iam.gserviceaccount.com --quiet
+# Optional: shut the whole project (30-day recoverable window)
+gcloud projects delete acme-prod
+```

package/skills/gcp-essentials/references/iam-and-auth.md

@@ -0,0 +1,94 @@
+# IAM & auth
+
+Depth for the IAM section of SKILL.md. Predefined roles, keyless CI, impersonation,
+drift detection.
+
+## Predefined roles for a typical product
+
+Prefer these Google-maintained roles over primitives or custom roles. Bind them to the
+service's dedicated SA at the narrowest resource scope the role supports.
+
+| Need | Role | Scope it to |
+|------|------|-------------|
+| Connect to Cloud SQL from the workload | `roles/cloudsql.client` | project |
+| Read/write objects in one bucket | `roles/storage.objectAdmin` | the bucket |
+| Read object content only | `roles/storage.objectViewer` | the bucket |
+| Read one secret's value | `roles/secretmanager.secretAccessor` | the secret |
+| Invoke a private Cloud Run service | `roles/run.invoker` | the service |
+| Push/pull container images | `roles/artifactregistry.writer` | the repo |
+| Write logs/metrics from the app | usually implicit on Cloud Run runtime SA | — |
+
+Bind at resource scope when possible — e.g. a secret, not the project:
+
+```bash
+gcloud secrets add-iam-policy-binding db-password \
+  --member="serviceAccount:api-sa@acme-prod.iam.gserviceaccount.com" \
+  --role="roles/secretmanager.secretAccessor"
+```
+
+## Workload Identity Federation for GitHub Actions (keyless)
+
+No JSON key downloaded, ever. GitHub's OIDC token is exchanged for short-lived GCP
+credentials.
+
+```bash
+# 1. A pool + an OIDC provider that trusts GitHub's issuer
+gcloud iam workload-identity-pools create github \
+  --location=global --display-name="GitHub Actions"
+
+gcloud iam workload-identity-pools providers create-oidc github-oidc \
+  --location=global --workload-identity-pool=github \
+  --display-name="GitHub OIDC" \
+  --issuer-uri="https://token.actions.githubusercontent.com" \
+  --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository" \
+  --attribute-condition="assertion.repository=='acme/api'"
+
+# 2. Let the deploy SA be impersonated only from that repo
+PROJECT_NUM=$(gcloud projects describe acme-prod --format='value(projectNumber)')
+gcloud iam service-accounts add-iam-policy-binding \
+  deployer@acme-prod.iam.gserviceaccount.com \
+  --role="roles/iam.workloadIdentityUser" \
+  --member="principalSet://iam.googleapis.com/projects/${PROJECT_NUM}/locations/global/workloadIdentityPools/github/attribute.repository/acme/api"
+```
+
+In the workflow, use `google-github-actions/auth` with the provider resource name and
+`service_account` — never a `credentials_json` secret. The `attribute-condition`
+pinning the exact repo is the security boundary; without it any repo could mint
+credentials.
+
+## Service account impersonation
+
+Run a one-off command *as* a service account without holding its key. The caller needs
+`roles/iam.serviceAccountTokenCreator` on the target SA.
+
+```bash
+gcloud storage ls gs://acme-prod-uploads \
+  --impersonate-service-account=api-sa@acme-prod.iam.gserviceaccount.com
+```
+
+Use this to test that an SA actually has the access you think it does — least surprise
+before deploy.
+
+## IAM Recommender (catch drift)
+
+The Recommender flags roles a member has not used in 90 days, so you can prune
+over-grants. Review it on a schedule.
+
+```bash
+gcloud recommender recommendations list \
+  --project=acme-prod --location=global \
+  --recommender=google.iam.policy.Recommender \
+  --format="table(content.overview)"
+```
+
+## IAM Conditions
+
+Attach a condition to narrow a binding by time or resource attribute — e.g. access to
+objects under one prefix only.
+
+```bash
+gcloud projects add-iam-policy-binding acme-prod \
+  --member="serviceAccount:api-sa@acme-prod.iam.gserviceaccount.com" \
+  --role="roles/storage.objectViewer" \
+  --condition='expression=resource.name.startsWith("projects/_/buckets/acme-prod-uploads/objects/public/"),title=public-prefix-only'
+```

package/skills/gcp-essentials/references/networking-and-sql.md

@@ -0,0 +1,74 @@
+# Networking & Cloud SQL
+
+Depth for the Cloud SQL and VPC parts of SKILL.md.
+
+## Cloud Run egress: Direct VPC egress, not the legacy connector
+
+To reach private IPs (a Cloud SQL private instance, an internal service) from Cloud
+Run, prefer **Direct VPC egress** over the older Serverless VPC Access connector —
+fewer moving parts, lower latency, no connector VM to size or pay for.
+
+```bash
+gcloud run deploy api --region=europe-west1 \
+  --service-account=api-sa@acme-prod.iam.gserviceaccount.com \
+  --network=projects/acme-prod/global/networks/default \
+  --subnet=projects/acme-prod/regions/europe-west1/subnetworks/default \
+  --vpc-egress=all-traffic
+```
+
+- `--vpc-egress=all-traffic` routes all outbound through the VPC. The older explicit
+  Direct-VPC-egress value is deprecated in favour of `all-traffic`.
+- `--vpc-egress=private-ranges-only` sends only RFC-1918 traffic through the VPC and
+  lets public traffic exit directly — use it when only the DB is private.
+
+The legacy `--vpc-connector` still works but is no longer the default recommendation;
+do not provision a new connector for greenfield work.
+
+## Cloud SQL private IP
+
+Disable the public IP and give the instance a private address on your VPC. This is the
+single biggest attack-surface reduction for a database.
+
+```bash
+# One-time: allocate a range and peer it (Service Networking)
+gcloud compute addresses create google-managed-services-default \
+  --global --purpose=VPC_PEERING --prefix-length=16 \
+  --network=projects/acme-prod/global/networks/default
+gcloud services vpc-peerings connect \
+  --service=servicenetworking.googleapis.com \
+  --ranges=google-managed-services-default \
+  --network=default --project=acme-prod
+
+# Create the instance with private IP, no public IP.
+# --edition=ENTERPRISE is required: POSTGRES_16+ defaults to Enterprise Plus, which
+# cannot run the shared-core db-f1-micro tier, so the create fails without it.
+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
+```
+
+PSC (Private Service Connect) is the alternative when you need the instance reachable
+from multiple VPCs or projects; enable it with `--enable-private-service-connect` and
+allow the consumer projects.
+
+## Cloud SQL Auth Proxy (for outside-VPC connections)
+
+The proxy gives short-lived client certs and TLS 1.3 without managing certificates. Use
+it for **local dev** or any non-serverless host — Cloud Run does **not** need it (it
+uses the `/cloudsql/...` socket via `--add-cloudsql-instances`).
+
+```bash
+# Local dev against a private-IP instance over the proxy
+./cloud-sql-proxy --private-ip acme-prod:europe-west1:acme-db
+# then connect your client to 127.0.0.1:5432
+```
+
+## Connection pooling
+
+Cloud SQL has a hard `max_connections` ceiling and Cloud Run can fan out to many
+instances, each opening its own pool — you will exhaust connections under load. Keep
+each instance's pool small (e.g. a few connections) and, for high concurrency, front
+the database with a pooler (PgBouncer / a managed proxy) rather than raising
+`max_connections`. Schema and query tuning beyond this is `postgresdb` territory.