How to Create a Google Cloud Budget with gcloud

Google Cloud budgets live on the Cloud Billing account, not on a project, so the person creating one needs billing-account access even when the budget only watches one project. This guide creates a monthly budget with gcloud billing budgets create, scopes it, and wires the alert to Pub/Sub so something other than an inbox can react.

Access you need

• On the Cloud Billing account: the Billing Account Costs Manager or Billing Account Administrator role. They carry billing.budgets.create, billing.budgets.get, billing.budgets.list and billing.accounts.getSpendingInformation.
• For Pub/Sub notifications: Pub/Sub Admin on the project that holds the topic.
• Your billing account ID: gcloud billing accounts list.

1. Pick the scope

A budget can watch the whole billing account, specific projects, folders or organizations, specific services, or resources that carry one label. Two scope rules matter in practice:

• Label scope is only available on billing-account-level budgets, and only one label per budget.
• Labels applied to a project itself cannot be used as a budget scope. The label has to be on the resources.

If a team owns whole projects, scope by project. If teams share projects, label the resources and scope by label.

2. Create the budget

gcloud billing budgets create \
  --billing-account=0X0X0X-0X0X0X-0X0X0X \
  --display-name="payments-team-monthly" \
  --budget-amount=4000USD \
  --calendar-period=month \
  --filter-projects=projects/payments-prod,projects/payments-dev \
  --threshold-rule=percent=0.50 \
  --threshold-rule=percent=0.90 \
  --threshold-rule=percent=1.0,basis=forecasted-spend \
  --notifications-rule-pubsub-topic=projects/finops-tools/topics/budget-alerts

Swap --filter-projects for --filter-labels=team=payments to scope by label instead. --last-period-amount in place of --budget-amount sets the limit to whatever last period cost, which suits a “tell me if we grow” budget. Each --threshold-rule is a fraction of the amount; basis=forecasted-spend fires on the projection rather than the actual.

3. Confirm it exists

gcloud billing budgets list --billing-account=0X0X0X-0X0X0X-0X0X0X

The new budget appears with its displayName, amount and thresholdRules. In the console it is under Billing › Budgets & alerts, where the chart shows spend against the line.

4. Act on the Pub/Sub message

Cloud Billing publishes to the topic several times a day with the budget’s current status, including costAmount (spend so far in the period) and budgetAmount, even when nothing has changed, and delivery is at-least-once, so make the consumer idempotent. Google documents consumers that post to Slack, cap usage, or disable billing on a project. Disabling billing stops the project’s services, so keep that for sandboxes.

What this budget does and does not do

What you created is an alerts-only budget. It emails holders of the Billing Account Administrator and Billing Account User roles by default (turn that off with --disable-default-iam-recipients) and messages to Pub/Sub. It does not stop or scale anything. Delete it with gcloud billing budgets delete BUDGET_ID --billing-account=....

Scoping by label only works if the labels are on the resources in the first place; activating tags and labels for cost attribution covers that, and cloud budget planning covers choosing the amount.

Doing the same in ZopNight

In ZopNight a GCP project is a cloud account, so a budget can target the project as a whole, one resource, or a resource group that mixes resources from several projects or clouds. Spend is computed live from cost data rather than a stored counter, each budget has its own alert threshold, and the Budgets page shows remaining amount and percent used per target.