Google Cloud Billing BudgetAlertTrigger

Google Cloud Billing BudgetAlertTrigger
Certified
Trigger on GCP Cloud Billing Budget Alerts

Consumes budget notifications published to a Google Cloud Pub/Sub topic and starts a Flow when the cost crosses the configured threshold. State is deduplicated per budget and billing interval in the namespace KV store. In the event of a KV store failure, a warning is logged and the trigger proceeds with execution to avoid missing critical budget alerts.

yaml
type: io.kestra.plugin.gcp.billing.BudgetAlertTrigger

Examples

Trigger a flow when a budget exceeds 85% of its allocation

yaml
id: gcp_budget_alert_listener
namespace: company.finops

tasks:
  - id: notify_slack
    type: io.kestra.plugin.core.log.Log
    message: "ALERT: Budget '{{ trigger.budgetAlert.budgetDisplayName }}' reached {{ trigger.budgetAlert.usageRatio * 100 }}% (Cost: {{ trigger.budgetAlert.costAmount }} {{ trigger.budgetAlert.currencyCode }})"

triggers:
  - id: budget_alert
    type: io.kestra.plugin.gcp.billing.BudgetAlertTrigger
    serviceAccount: "{{ secret('GCP_SA') }}"
    topic: "gcp-budget-alerts"
    subscription: "kestra-budget-alerts-sub"
    thresholdRatio: 0.85

Properties

subscription *string

Subscription ID

The Pub/Sub subscription name to pull budget notifications from.

topic *string

Topic ID

The Pub/Sub topic name receiving Cloud Billing budget notifications.

allowConcurrent boolean

Defaultfalse

Specifies whether a trigger is allowed to start a new execution even if a previous run is still in progress.

autoCreateSubscription booleanstring

Defaulttrue

Auto-create subscription

Whether to create the subscription if it does not already exist.

impersonatedServiceAccount string

The GCP service account to impersonate

interval string

DefaultPT1M

Formatduration

The interval between polling iterations

maxDuration string

DefaultPT30S

Max duration

Duration limit for a polling run; defaults to PT30S (30 seconds). Should stay below the polling interval.

maxRecords integerstring

Default10

Max records per poll

Maximum number of messages to consume per polling run (between 1 and 1000). Defaults to 10. Out-of-range values cause the trigger to fail during evaluation.

projectId string

The GCP project ID

scopes array

SubTypestring

Default["https://www.googleapis.com/auth/cloud-platform"]

The GCP scopes to be used

serviceAccount string

The GCP service account key

stopAfter array

SubTypestring

Possible Values

CREATEDSUBMITTEDRUNNINGPAUSEDRESTARTEDKILLINGSUCCESSWARNINGFAILEDKILLEDCANCELLEDQUEUEDRETRYINGRETRIEDSKIPPEDBREAKPOINTRESUBMITTED

List of execution states after which a trigger should be stopped (a.k.a. disabled).

thresholdAmount numberstring

Threshold amount

Minimum absolute cost amount in the budget's currency required to trigger the flow. When both thresholdRatio and thresholdAmount are specified, both conditions must be met (logical AND). Out-of-range values cause the trigger to fail during evaluation.

thresholdRatio numberstring

Threshold ratio (between 0.0 and 1.0+)

Minimum budget usage ratio required to trigger the flow (e.g. 0.9 for 90%, 1.0 for 100%). If unset, any notification that crosses a Google budget threshold will trigger. Out-of-range values cause the trigger to fail during evaluation.

when string

Defaulttrue

A condition that determines whether the trigger should run.

A Pebble expression evaluated at trigger time. The trigger fires only when the expression evaluates to a truthy value (true, a non-empty string, a non-zero number). Use this to gate trigger execution on dynamic runtime values such as execution labels, flow variables, or environment conditions.

Outputs

budgetAlert

The primary or first matched budget alert

Convenience shortcut for budgetAlerts.getFirst().

Definitions

io.kestra.plugin.gcp.billing.models.BudgetAlert

alertThresholdExceedednumber

The percentage threshold exceeded that triggered this notification (from Google payload)

billingAccountIdstring

The billing account ID associated with the budget alert

budgetAmountnumber

The total budget amount

budgetAmountTypestring

The type of budget amount (e.g. SPECIFIED_AMOUNT)

budgetDisplayNamestring

The display name of the budget that generated this alert

budgetIdstring

The budget ID associated with the alert

costAmountnumber

The current cost amount in the budget period

costIntervalStartstring

The start timestamp of the budget interval

currencyCodestring

The currency code for the cost and budget amounts

forecastThresholdExceedednumber

The forecast threshold exceeded that triggered this notification (from Google payload)

usageRationumber

The ratio of current cost to total budget amount (costAmount / budgetAmount)

budgetAlerts array

All budget alerts that matched in this polling run