How velikodniy/gcp-spending-guard works
1. What this repo is
- This is not an application backend or UI; it is an infrastructure module that enforces a hard spending limit on a GCP project.
- The module’s purpose is to automate a “kill switch” for billing once a budget threshold is exceeded.
2. Top-level architecture
- The repo is split into two clear parts:
- Terraform/OpenTofu module at the root: main.tf, variables.tf, outputs.tf, versions.tf
- Node.js Cloud Function in function/
- Terraform provisions the Google Cloud resources; the Node.js code runs the enforcement action when an alert arrives.
3. Primary data flow
- GCP Budget Monitoring detects spend exceeding the configured threshold.
- The budget system publishes an alert to a Pub/Sub topic created by this module.
- A Cloud Function subscribed to that topic receives the alert.
- The function calls Google Cloud billing/project APIs to disable billing on the project.
4. Core GCP resources
- Budget resource: configured with a target amount, currency, and display name.
- Pub/Sub topic: acts as the event transport for budget notifications.
- Cloud Function: event-driven handler that performs the billing shutdown action.
- IAM/service account wiring: grants the function permission to interact with billing and project resources.
5. Runtime boundary
- The module has a strong split between:
- Provisioning time: Terraform creates and wires resources together.
- Alert handling time: the function runs only when a budget notification is published.
- This means the enforcement logic is event-driven, not continuously running.
6. Cloud Function deployment model
- The listed required APIs include cloudfunctions, cloudbuild, eventarc, and run, which strongly suggests the function is deployed as Cloud Functions Gen 2.
- In that model, Cloud Build packages/deploys the function, and the runtime sits on Cloud Run with Eventarc/Pub/Sub integration underneath.
7. External dependencies and required APIs
- The module depends on several GCP control-plane services being enabled:
- Budgeting and billing APIs
- Pub/Sub
- Cloud Functions / Cloud Build / Eventarc / Cloud Run
- Cloud Resource Manager
- These are not incidental; they are required for both alert delivery and the enforcement action.
8. Configuration surface
- The main inputs are:
- project_id
- billing_account_id
- budget_amount
- optional region
- optional currency_code
- optional naming inputs for the budget, topic, and function
- The currency must align with the billing account’s currency.
9. Operational behavior
- When triggered by an over-budget event, the function disables billing for the project.
- The README notes that restoring service requires manually reattaching billing; the module is designed to be disruptive by intent.
10. Repository layout significance
- function/package.json and function/index.js indicate the runtime logic is packaged independently from the Terraform code.
- main.tf likely stitches together the topic, budget, function, and IAM.
- variables.tf and outputs.tf define the module contract and expose the created infrastructure to callers.
11. Diagram-worthy subsystems
- A useful architecture diagram should show:
- the GCP project and billing account as external inputs,
- the budget/notification pipeline,
- the Pub/Sub event channel,
- the Cloud Function enforcement worker,
- and the billing disablement action back against the project.
12. Key architectural takeaway
- This module is a governance control: it uses cloud-native eventing to convert a budget breach into an automated billing shutdown.
- The important design pattern is “budget alert as event, function as enforcement, billing API as actuator.”
Main entry points: main.tf Wiring · package.json Deploy function · index.js Handler · variables.tf Inputs
Components 14
Terraform module
Provisioning layer that declares and wires the GCP resources.
- Inputs · Module parameters for project, billing, budget, region, and naming.
variables.tf - Wiring · Creates the budget, Pub/Sub topic, Cloud Function, and IAM connections.
main.tf - Outputs · Exposes created resource identifiers to module callers.
outputs.tf - Versions · Pins Terraform and provider/runtime compatibility.
versions.tf - Budget · Configured spending threshold and notification target.
- Alert topic · Transport for budget breach notifications.
- IAM access · Grants the function permission to manage billing-related actions.
- Target project · Project whose billing is protected by the guard.
- Billing account · Source of truth for the attached billing relationship and currency.
- Budget alerts · Detects threshold breaches and emits notifications.
Function runtime
Event-driven enforcement code packaged and deployed separately from Terraform.
- Deploy function · Cloud Function Gen 2 deployment entrypoint managed by Terraform.
function/package.json - Handler · Processes budget alerts and invokes the shutdown action.
function/index.js - Gen2 platform · Underlying deployment and eventing substrate used by the function.
- Disable billing · Acts on the target project to stop further charges.
Connections 17
- Inputs → Wiring: configures · Inputs feed the Terraform resource graph.
- Wiring → Budget: creates · Defines the spend limit and notification rules.
- Wiring → Alert topic: creates · Provisioned as the alert transport.
- Wiring → IAM access: grants · Wires permissions for the enforcement worker.
- Wiring → Deploy function: deploys · Packages and registers the Cloud Function.
- Budget → Budget alerts: feeds · Budget monitoring evaluates spend against the configured threshold.
- Budget alerts → Alert topic: publishes · Over-budget events are sent to the topic.
- Alert topic → Deploy function: triggers · Event delivery invokes the function.
- Deploy function → Gen2 platform: runs on · Cloud Functions Gen 2 uses Cloud Build, Eventarc, and Cloud Run underneath.
- Deploy function → Handler: executes · Runtime entrypoint is the Node.js handler.
- Handler → Disable billing: calls · Handler invokes billing/project control APIs.
- Disable billing → Target project: disables billing on · Kills further spending for the target project.
- Billing account → Budget: sets currency and scope · Budget is tied to the billing account and its currency.
- Outputs → Wiring: exposes · Surfaces resource identifiers created by the module.
- Versions → Wiring: constrains · Provider and runtime compatibility for the module.
- IAM access → Handler: authorizes · Allows the function to perform the shutdown action.
- Target project → Budget: is monitored by · The budget applies to the target project's spend.