tessl/pypi-google-cloud-billing-budgets

Google Cloud Billing Budgets API client library for creating and managing cloud billing budgets

—

Pending

Overview

Eval results

Files

Notifications and Alerts

Name: tessl/pypi-google-cloud-billing-budgets
Author: tessl

Configuration for budget notifications and threshold-based alerts. Supports Pub/Sub integration and Cloud Monitoring channels with different capabilities between v1 and v1beta1 APIs.

Capabilities

Notification Rules (v1 API)

The v1 API uses NotificationsRule for configuring budget notifications with Pub/Sub topics and monitoring channels.

class NotificationsRule:
    """
    NotificationsRule defines recipients for budget alerts.

    Attributes:
        pubsub_topic (str): Optional. Pub/Sub topic where budget related
            messages will be published. Must be in the format
            projects/{project_id}/topics/{topic_id}
        schema_version (str): Optional. Schema version of the notification.
            Only "1.0" is supported
        monitoring_notification_channels (List[str]): Optional. Targets
            to send notifications to when a threshold is exceeded. Must be
            in the format projects/{project_id}/notificationChannels/{channel_id}
        disable_default_iam_recipients (bool): Optional. When true, disables
            default notifications sent when budget thresholds are exceeded
        enable_project_level_recipients (bool): Optional. When true, enables
            notifications to be sent to users with IAM roles on the project
    """
    pubsub_topic: str
    schema_version: str
    monitoring_notification_channels: List[str]
    disable_default_iam_recipients: bool
    enable_project_level_recipients: bool

Enhanced Notification Rules (v1beta1 API)

The v1beta1 API uses AllUpdatesRule which provides enhanced notification capabilities.

class AllUpdatesRule:
    """
    AllUpdatesRule defines recipients for all budget notifications.

    Attributes:
        pubsub_topic (str): Optional. Pub/Sub topic where budget notifications
            will be published. Must be in the format
            projects/{project_id}/topics/{topic_id}
        schema_version (str): Optional. Schema version of the notification.
            Only "1.0" is supported
        monitoring_notification_channels (List[str]): Optional. Cloud Monitoring
            notification channels to send budget alerts. Must be in the format
            projects/{project_id}/notificationChannels/{channel_id}
        disable_default_iam_recipients (bool): Optional. When true, disables
            default notifications sent when budget thresholds are exceeded
        enable_project_level_recipients (bool): Optional. When true, enables
            notifications to be sent to users with IAM roles on the project
    """
    pubsub_topic: str
    schema_version: str  # Only "1.0" supported
    monitoring_notification_channels: List[str]
    disable_default_iam_recipients: bool
    enable_project_level_recipients: bool

Threshold Configuration

Threshold rules define when alerts should be triggered based on spending patterns.

class ThresholdRule:
    """
    ThresholdRule contains a definition of a threshold for a budget.

    Attributes:
        threshold_percent (float): Required. Send a notification when this
            threshold is exceeded. Must be between 0.0 and 1.0
        spend_basis (Basis): Optional. The type of basis used to calculate
            threshold (current or forecasted spend)
    """
    threshold_percent: float  # Non-negative number (0.5 = 50%)
    spend_basis: Basis

    class Basis(Enum):
        \"\"\"The type of basis used to determine if spend has passed the threshold.\"\"\"
        BASIS_UNSPECIFIED = 0
        CURRENT_SPEND = 1  # Use current spend as basis for comparison
        FORECASTED_SPEND = 2  # Use forecasted spend (only with calendar periods)

Usage Examples

Setting Up Pub/Sub Notifications (v1)

from google.cloud.billing import budgets

# Create a budget with Pub/Sub notifications
budget = budgets.Budget(
    display_name="Production Budget with Notifications",
    amount=budgets.BudgetAmount(
        specified_amount={"currency_code": "USD", "units": 2000}
    ),
    budget_filter=budgets.Filter(
        projects=["projects/my-production-project"],
        calendar_period=budgets.CalendarPeriod.MONTH
    ),
    threshold_rules=[
        budgets.ThresholdRule(
            threshold_percent=0.8,  # Alert at 80%
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
        ),
        budgets.ThresholdRule(
            threshold_percent=1.0,  # Alert at 100%
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
        )
    ],
    notifications_rule=budgets.NotificationsRule(
        pubsub_topic="projects/my-project/topics/budget-alerts",
        schema_version="1.0",
        monitoring_notification_channels=[
            "projects/my-project/notificationChannels/channel-123",
            "projects/my-project/notificationChannels/channel-456"
        ],
        disable_default_iam_recipients=False,
        enable_project_level_recipients=True
    )
)

Setting Up Enhanced Notifications (v1beta1)

from google.cloud.billing import budgets_v1beta1

# Create a budget with enhanced v1beta1 notifications
budget = budgets_v1beta1.Budget(
    display_name="Enhanced Notification Budget",
    amount=budgets_v1beta1.BudgetAmount(
        specified_amount={"currency_code": "USD", "units": 5000}
    ),
    budget_filter=budgets_v1beta1.Filter(
        resource_ancestors=["organizations/123456789"],
        calendar_period=budgets_v1beta1.CalendarPeriod.QUARTER
    ),
    threshold_rules=[
        budgets_v1beta1.ThresholdRule(
            threshold_percent=0.5,  # Alert at 50%
            spend_basis=budgets_v1beta1.ThresholdRule.Basis.FORECASTED_SPEND
        ),
        budgets_v1beta1.ThresholdRule(
            threshold_percent=0.9,  # Alert at 90%
            spend_basis=budgets_v1beta1.ThresholdRule.Basis.CURRENT_SPEND
        )
    ],
    all_updates_rule=budgets_v1beta1.AllUpdatesRule(
        pubsub_topic="projects/my-project/topics/enhanced-budget-alerts",
        schema_version="1.0",
        monitoring_notification_channels=[
            "projects/my-project/notificationChannels/ops-team",
            "projects/my-project/notificationChannels/finance-team"
        ]
    )
)

Forecast-Based Alerting

from google.cloud.billing import budgets

# Create a budget with forecast-based threshold alerting
budget = budgets.Budget(
    display_name="Forecast Alert Budget",
    amount=budgets.BudgetAmount(
        specified_amount={"currency_code": "USD", "units": 10000}
    ),
    budget_filter=budgets.Filter(
        projects=["projects/ml-training-project"],
        services=["services/compute.googleapis.com"],
        calendar_period=budgets.CalendarPeriod.MONTH
    ),
    threshold_rules=[
        # Alert when forecasted spend hits 80%
        budgets.ThresholdRule(
            threshold_percent=0.8,
            spend_basis=budgets.ThresholdRule.Basis.FORECASTED_SPEND
        ),
        # Alert when current spend hits 100%
        budgets.ThresholdRule(
            threshold_percent=1.0,
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
        )
    ],
    notifications_rule=budgets.NotificationsRule(
        pubsub_topic="projects/my-project/topics/ml-budget-alerts",
        schema_version="1.0",
        disable_default_iam_recipients=False
    )
)

Multiple Threshold Configuration

from google.cloud.billing import budgets

# Create a budget with multiple threshold levels
budget = budgets.Budget(
    display_name="Multi-Threshold Budget",
    amount=budgets.BudgetAmount(
        specified_amount={"currency_code": "USD", "units": 3000}
    ),
    budget_filter=budgets.Filter(
        projects=["projects/web-app-project"],
        calendar_period=budgets.CalendarPeriod.MONTH
    ),
    threshold_rules=[
        # Early warning at 25%
        budgets.ThresholdRule(
            threshold_percent=0.25,
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
        ),
        # Mid-month check at 50%
        budgets.ThresholdRule(
            threshold_percent=0.5,
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
        ),
        # Alert at 75%
        budgets.ThresholdRule(
            threshold_percent=0.75,
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
        ),
        # Critical alert at 90%
        budgets.ThresholdRule(
            threshold_percent=0.9,
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
        ),
        # Overspend alert at 100%
        budgets.ThresholdRule(
            threshold_percent=1.0,
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
        )
    ],
    notifications_rule=budgets.NotificationsRule(
        pubsub_topic="projects/my-project/topics/web-app-budget",
        schema_version="1.0",
        monitoring_notification_channels=[
            "projects/my-project/notificationChannels/dev-team",
            "projects/my-project/notificationChannels/finance-alerts"
        ]
    )
)

Monitoring Channel Integration

from google.cloud.billing import budgets

# Budget with Cloud Monitoring integration
budget = budgets.Budget(
    display_name="Monitoring Integration Budget",
    amount=budgets.BudgetAmount(
        specified_amount={"currency_code": "USD", "units": 1500}
    ),
    budget_filter=budgets.Filter(
        projects=["projects/microservices-project"],
        calendar_period=budgets.CalendarPeriod.MONTH,
        services=[
            "services/compute.googleapis.com",
            "services/storage.googleapis.com",
            "services/bigquery.googleapis.com"
        ]
    ),
    threshold_rules=[
        budgets.ThresholdRule(
            threshold_percent=0.8,
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
        )
    ],
    notifications_rule=budgets.NotificationsRule(
        pubsub_topic="projects/my-project/topics/microservices-budget",
        schema_version="1.0",
        monitoring_notification_channels=[
            # Email notification channel
            "projects/my-project/notificationChannels/email-devops",
            # Slack notification channel  
            "projects/my-project/notificationChannels/slack-alerts",
            # PagerDuty notification channel
            "projects/my-project/notificationChannels/pagerduty-critical"
        ],
        disable_default_iam_recipients=True,  # Only use specified channels
        enable_project_level_recipients=False
    )
)

Notification Message Format

When budget thresholds are exceeded, notifications are sent with a structured format containing budget and spending information.

Pub/Sub Message Schema

Budget notifications published to Pub/Sub topics follow this structure:

{
    "budgetDisplayName": "My Budget Name",
    "alertThresholdExceeded": 0.8,  # Threshold that was exceeded (0.0-1.0)
    "costAmount": 850.00,  # Current spend amount
    "costIntervalStart": "2024-01-01T00:00:00Z",
    "costIntervalEnd": "2024-01-15T23:59:59Z", 
    "budgetAmount": 1000.00,  # Total budget amount
    "budgetAmountType": "SPECIFIED_AMOUNT",  # or "LAST_PERIOD_AMOUNT"
    "currencyCode": "USD",
    "schemaVersion": "1.0"
}

Message Attributes

Pub/Sub messages include these attributes:

billingAccountId: The billing account ID
budgetId: The budget ID that triggered the alert
schemaVersion: Always "1.0"

API Version Differences

v1 API Features

Uses NotificationsRule class
Supports disable_default_iam_recipients flag
Supports enable_project_level_recipients flag
REST transport available

v1beta1 API Features

Uses AllUpdatesRule class (enhanced notifications)
Simplified notification configuration
Enhanced Pub/Sub integration
Only gRPC transports (no REST)
More flexible notification channel management

Install with Tessl CLI

npx tessl i tessl/pypi-google-cloud-billing-budgets

docs

budget-data-models.md

budget-service-clients.md

index.md

notifications-alerts.md

request-response-types.md

tile.json