The typical behavior of a budget is to send alert emails when the budget alert threshold rules trigger an email notification.
However, if you are using budgets as a cost control tool, email notifications might not be the best notification method to use to ensure timely action to control your Google Cloud costs. Beyond email notifications, you can use programmatic notifications to automate cost control responses. Examples of cost control responses include:
- Capping your Google Cloud spend by automatically disabling billing or terminating resources.
- Forwarding your budget messages to other mediums (such as Slack).
- Throttling your resource usage by adjusting quotas.
For more information, see Examples of automated cost control responses.
Permissions required for this task
To set Pub/Sub topics and link them to a Cloud Billing budget, you need the following roles:
- To create or modify a budget for your Cloud Billing account, you need the Billing Account Administrator role on the Cloud Billing account.
To set or modify Pub/Sub topics, you need the Pub/Sub Editor role on the target project that contains the Pub/Sub topics.
Specifically, you must have the following permissions:
billing.budgets.createon the Cloud Billing account, to create a new budget.
billing.budgets.liston the Cloud Billing account, to view all budgets for the Cloud Billing account.
billing.budgets.updateon the Cloud Billing account, to modify an existing budget.
roles/pubsub.editoron the target project that contains the Pub/Sub topics.
To edit an existing Cloud Billing budget to connect it to an existing Pub/Sub topic, you need these specific permissions:
Permissions related to a domain restriction constraint
In this situation, you might need to force account access to successfully connect a Pub/Sub topic to a budget.
If you choose to set up a Google Group to grant permissions within the allowed
domain, add the
account to the group and grant the group the
Pub/Sub Publisher role.
For more information about Google Cloud permissions, see:
- Overview of Cloud Billing access control
- Create custom roles for Cloud Billing
- Understanding predefined Identity and Access Management roles
How to setup and enable Pub/Sub programmatic notifications
To enable programmatic notifications to receive Pub/Sub messages with the current status of your budget, connect a Pub/Sub topic to your Cloud Billing budget.
To connect, edit, or remove a Pub/Sub topic linked to your budget, do the following:
1. Create a Pub/Sub topic
Configure a Pub/Sub topic for Cloud Billing to publish your budget alerts to. If you already have a Cloud Billing budgets Pub/Sub topic configured, you can reuse it for all budgets, or you can create a unique topic per budget.
Go to the Google Cloud Console Pub/Sub page.
Select a project.
In the Topic ID field, provide a topic name, and click CREATE TOPIC.
2. Connect a Cloud Billing budget to a Pub/Sub topic
To connect a Cloud Billing budget to a Pub/Sub topic, do the following:
Sign in to the Google Cloud Console.
Open the console Navigation menu, and then select Billing.
If you have more than one Cloud Billing account, do one of the following:
- To manage Cloud Billing for the current project, select Go to linked billing account.
- To locate a different Cloud Billing account, select Manage billing accounts and choose the account for which you'd like to manage a budget.
In the Billing navigation menu, select Budgets & alerts.
If necessary, create a budget. Or, to edit an existing budget and alert rules, click a budget name.
In the Actions section, under Manage notifications, select Connect a Pub/Sub topic to this budget.
In the Project field, click Select a project and choose the project that contains the Pub/Sub topics you've set up. If you followed the recommendation in the previous section, this is your billing administration Google Cloud project.
Under Select a Pub/Sub topic, select an existing topic, or create a new topic by selecting Create a topic.
- If creating a new topic, in the Topic ID field, provide a topic name, and click CREATE TOPIC.
- After it's created, the topic will be selected.
Notifications sent to the Pub/Sub topic consist of two parts:
- Attributes: A set of key-value pairs describing the event.
- Data: A string containing a JSON object that describes the budget alert details.
Attributes are key-value pairs contained in all notifications sent by Cloud Billing to your Pub/Sub topic. Notifications always contain the following set of key-value pairs, regardless of the notification payload.
||The identifier for the Cloud Billing account owning the budget.|
||The identifier for the budget alert within the Cloud Billing account.|
||The notifications schema version.|
For schema version 1.x, budget alert details are returned in a base64-encoded UTF-8 string containing a JSON object with the following properties:
||The human-readable name assigned to the budget.|
||The amount of costs accrued. The type of costs tracked depends on budget filters & settings.|
||The start of the budget alert period. Cost reported includes costs for usage starting at this time. Currently, this is the first day of the month during which the budget usage occurred.|
||The amount allocated in the budget.|
||The budget amount type. This can be either
||The highest configured actual cost alert threshold exceeded. Value is a percent in decimal format (for example, 0.9 is 90%). This key is not present if the actual cost doesn't exceed any threshold.|
||The highest forecasted cost alert threshold exceeded. Value is a percent in decimal format (for example, 0.2 is 20%). This key is not present if the forecasted cost doesn't exceed any threshold.|
||The budget alert currency. All costs and budget alert amounts are in this currency.|
Delivery guarantees for notifications to Pub/Sub
After you create a budget and connect it to a Pub/Sub topic, you can expect to receive programmatic notifications as described here:
- Budget notifications are sent to the Pub/Sub topic multiple times per day with the current status of your budget. This is a different cadence than the budget alert emails, which are only sent when a budget threshold is met.
- Pub/Sub notifications are sent even if the Cloud Billing account has no usage.
- It may take several hours before receiving the first Pub/Sub notification.
- Pub/Sub only guarantees at-least-once delivery. You might receive a message multiple times, and messages might arrive out of order.
If delivery fails due to Pub/Sub topic misconfiguration, you will not be notified.
Delivery might fail for one of the following reasons:
- The Pub/Sub topic no longer exists.
- The Cloud Billing no longer has permission to publish to the Pub/Sub topic.
- You have exceeded your notification quota.