Manage programmatic budget alert notifications

Overview

The typical behavior of a budget is to send alert emails when the budget alert threshold rules trigger an email notification.

Diagram of budget alert notifications
Figure 1: Illustrates the default email functionality for budget alert notifications and the optional method to automate cost control responses using Pub/Sub for programmatic notifications.

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:

If you have set organization policies to limit resource sharing by domain, you might encounter an error when attempting to set up Pub/Sub topics or connect them to a Cloud Billing budget.

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 billing-budget-alert@system.gserviceaccount.com service account to the group and grant the group the Pub/Sub Publisher role.

For more information about Google Cloud permissions, see:

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.

  1. Go to the Google Cloud Console Pub/Sub page.

    Sign in to Cloud Console Pub/Sub

  2. Select a project.

  3. Click Create topic.

  4. 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:

  1. Sign in to the Google Cloud Console.

    Sign in to Cloud Console

  2. 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.
  3. In the Billing navigation menu, select Budgets & alerts.

  4. If necessary, create a budget. Or, to edit an existing budget and alert rules, click a budget name.

  5. In the Actions section, under Manage notifications, select Connect a Pub/Sub topic to this budget.

  6. 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.

  7. 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.
  8. Click Save.

Notification format

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

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.

Attribute name Example Description
billingAccountId 01D4EE-079462-DFD6EC The identifier for the Cloud Billing account owning the budget.
budgetId de72f49d-779b-4945-a127-4d6ce8def0bb The identifier for the budget alert within the Cloud Billing account.
schemaVersion 1.0 The notifications schema version.

Data

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:

Data Example Description
budgetDisplayName "My Personal Budget" The human-readable name assigned to the budget.
costAmount 140.321 The amount of costs accrued. The type of costs tracked depends on budget filters & settings.
costIntervalStart "2018-02-01T08:00:00Z" 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.
budgetAmount 152.557 The amount allocated in the budget.
budgetAmountType "SPECIFIED_AMOUNT" The budget amount type. This can be either "SPECIFIED_AMOUNT" (a fixed amount) or "LAST_MONTH_COST" (last month's costs).
alertThresholdExceeded 0.9 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.
forecastThresholdExceeded 0.2 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.
currencyCode "USD" 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.