AWS Billing BudgetThresholdTrigger

AWS Billing BudgetThresholdTrigger

Certified

Trigger a flow when an AWS Budget crosses a spend threshold

Polls one budget with the AWS Budgets DescribeBudget API and starts a flow when its actual or forecasted spend reaches thresholdPercent of the budget limit. The trigger fires once per budget period: after it fires, it stays quiet until the budget's next period (next day, month, quarter or year, depending on the budget's time unit), even if the spend keeps growing or the forecast goes down and up again. It does not fire during the first periodStartGrace of a period (default 12 hours, at most a quarter of the period), while AWS may still report the previous period's spend. The period it fired for is persisted in the namespace KV store, so restarts and new trigger instances do not fire again. Use one trigger per threshold, for example one at 80% FORECASTED and one at 100% ACTUAL. The Budgets API is free, and AWS refreshes budget spend a few times a day, so polling more often than every hour does not bring fresher data.

yaml
type: io.kestra.plugin.aws.billing.BudgetThresholdTrigger

Log a warning when the monthly budget's forecasted spend reaches 80% of its limit.

yaml
id: aws_budget_forecast_alert
namespace: company.finops

tasks:
  - id: alert
    type: io.kestra.plugin.core.log.Log
    level: WARN
    message: >-
      Budget {{ trigger.budget.budgetName }} is forecasted at {{ trigger.spendPercent }}% of its limit
      ({{ trigger.spendAmount }} of {{ trigger.budget.limitAmount }} {{ trigger.budget.limitUnit }}) for {{ trigger.period }}

triggers:
  - id: budget_80_percent_forecast
    type: io.kestra.plugin.aws.billing.BudgetThresholdTrigger
    region: us-east-1
    accessKeyId: "{{ secret('AWS_ACCESS_KEY_ID') }}"
    secretKeyId: "{{ secret('AWS_SECRET_ACCESS_KEY') }}"
    accountId: "{{ secret('AWS_ACCOUNT_ID') }}"
    budgetName: monthly-total
    thresholdType: FORECASTED
    thresholdPercent: 80
    interval: PT1H
Properties

AWS account ID

The 12-digit ID of the account that owns the budget.

Budget name

Name of the budget to watch.

Threshold (percent of the budget limit)

The trigger fires when the spend selected by thresholdType is greater than or equal to this percentage of the budget limit, for example 80 for 80%. Values above 100 alert on overspend, for example 120.

AWS access key ID

Optional static credential. If omitted, the default credentials provider chain is used.

Defaultfalse

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

Endpoint override

Override the default AWS endpoint URL.

DefaultPT1H
Formatduration

Poll interval

How often to read the budget. Default PT1H; AWS refreshes budget spend a few times a day.

DefaultPT12H

Period start grace

How long after a new budget period starts the trigger waits before it can fire. AWS refreshes budget spend only a few times a day, so just after a period rolls over (for example on the 1st of the month for a monthly budget), DescribeBudget can still return the previous period's spend. Without this wait, the trigger could fire on that stale spend, remember the new period as alerted, and then stay quiet when the real crossing happens. A crossing during the wait is not lost: the trigger fires on the first poll after it. Default PT12H; must not be negative. The wait is capped at a quarter of the budget period, so it never blocks a whole period: daily budgets wait at most 6 hours, monthly budgets about a week, and custom budgets a quarter of their own time period.

AWS region

Cost Explorer and AWS Budgets are global services served from us-east-1.

AWS secret access key

Pairs with accessKeyId for static credentials.

AWS session token

Session token for temporary credentials.

State key

Namespace KV key under which the trigger remembers the budget period it last fired for. Defaults to a key derived from the namespace, flow and trigger IDs. Set it to keep that memory when you rename the flow or the trigger.

SubTypestring
Possible Values
CREATEDSUBMITTEDRUNNINGPAUSEDRESTARTEDKILLINGSUCCESSWARNINGFAILEDKILLEDCANCELLEDQUEUEDRETRYINGRETRIEDSKIPPEDBREAKPOINTRESUBMITTED

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

STS endpoint override

Override the default STS endpoint URL.

STS role ARN

IAM role ARN to assume via STS before making API calls.

STS role external ID

External ID to pass when assuming the STS role.

DefaultPT15M

STS role session duration

Duration of the assumed role session. Default PT15M.

STS role session name

Session name to use when assuming the STS role.

DefaultACTUAL
Possible Values
ACTUALFORECASTED

Threshold type

ACTUAL compares the spend so far in the current period, FORECASTED the spend AWS forecasts for the whole period, like the notification types of AWS Budgets. AWS does not forecast every budget (for example daily budgets or new accounts); without a forecast a FORECASTED trigger does not fire. Default ACTUAL.

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.

Budget

The budget as returned by DescribeBudget, with budgetName, budgetType, timeUnit, limitAmount/limitUnit, actualSpendAmount/actualSpendUnit, forecastedSpendAmount/forecastedSpendUnit, timePeriodStart/timePeriodEnd and lastUpdatedTime.

Budget period

The budget period the trigger fired for: yyyy-MM-dd for daily budgets, yyyy-MM for monthly, yyyy-Qn for quarterly, yyyy for annual budgets, and start/end for custom budgets.

Spend amount

The actual or forecasted spend that crossed the threshold, in the budget's unit.

Spend percent

The spend as a percentage of the budget limit, rounded to 2 decimals.

Threshold (percent)

The configured thresholdPercent.

Possible Values
ACTUALFORECASTED

Threshold type

Whether the actual or the forecasted spend crossed the threshold.

More Plugins in this Category

Firecrawl
Firecrawl

Tasks that scrape and crawl websites into clean, LLM-ready content with Firecrawl.

Data

2 tasks

Canonical (EE)
Canonical
Enterprise

Tasks to interact with Canonical services, enabling automation and infrastructure management through API-driven workflows.

CloudInfrastructure

5 tasks