gcp-spend-cap-setup

GCP Spend-Cap Setup (GUIDED)

Overview

Google's spend caps on budgets (Public Preview since 2026-07-29) actually pause a service when a monthly threshold is hit — but creation is console-only: the Billing Budget API v1 has no enforcement field and gcloud billing budgets create has no cap flag. This skill is therefore GUIDED: it runs only read-only commands itself; you perform the single mutation in the console; the skill prepares everything before and verifies everything after.

A tripped cap returns permission errors (403) to ALL callers of that service, including production. Choosing to cap is a human decision — that is by design.

When to Use

• Standalone, whenever you want hard caps on AI/serverless spend.
• After a gcp-ironclad run: the final report's recommend_spend_cap flags point here.
• During an active incident. Unlike the APPLY skills, there is no bleeding-halt gate — a spend cap is precisely the emergency brake, so this skill must work while a project is bleeding.

Inputs

• SESSION_DIR env var — session directory; create /tmp/gcp-ironclad/<iso-ts>/ if unset (same convention as the other skills).
• MODE env var — unset for a full run; verify to skip to Step 4 using a prior ${SESSION_DIR}/spend-caps.json.
• No DRY_RUN: the skill never mutates, so there is nothing to dry-run.

Outputs

• ${SESSION_DIR}/spend-caps.json — matches output.schema.json, self-validated at the end.
• ${SESSION_DIR}/spend-cap-runbook.md — the console runbook, kept for audit trail.

Execution

Step 0 — Preflight + API-surface probe

1. Print the active CLI and ADC identities so a mismatch is visible before anything silently 403s:

   gcloud auth list --filter=status:ACTIVE --format="value(account)"
   gcloud auth application-default print-access-token >/dev/null 2>&1 || echo "WARN: no ADC credentials — run: gcloud auth application-default login"
   

   If the ADC identity is known to differ from the CLI identity, warn: ADC is a separate login; a mismatch produces silent PERMISSION_DENIED on API calls.
2. Probe the Budget API surface for future enforcement support:

   curl -s "https://billingbudgets.googleapis.com/\$discovery/rest?version=v1" \
     | jq -r '.schemas.GoogleCloudBillingBudgetsV1Budget.properties | keys[]' \
     | grep -iE "enforce|cap|pause" || true
   

   • No match (today's state) → apiSurfaceDetected: false.
   • Any match → apiSurfaceDetected: true; print: "Budget API now exposes an enforcement-like field — Google may have shipped API support for spend caps. This skill predates that; check the docs and consider upgrading it. Continuing in guided mode." Do NOT attempt to use the field.