AWS Billing AnomalyTrigger

AWS Billing AnomalyTrigger
Certified
Trigger a flow on new AWS cost anomalies

Polls the Cost Explorer GetAnomalies API and starts one flow execution with all the anomalies it has not reported before, optionally only for one monitor and above minImpactUsd. Each poll reads the anomalies of the last lookback days, because Cost Anomaly Detection often reports an anomaly a day or more after it started, and an ongoing anomaly keeps growing. The watermark of the anomalies already reported (their ID and last observed date) is persisted in the namespace KV store only after the execution is created, so an anomaly is reported once, even after a restart. An anomaly below minImpactUsd is not remembered, so it fires later if its impact grows above the threshold. Cost Explorer is a paid API: each poll costs $0.01 per page, so the default interval is PT6H; Cost Anomaly Detection itself runs about three times a day.

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

Examples

Log each new cost anomaly with a total impact of at least 100 USD.

yaml
id: aws_cost_anomaly_alert
namespace: company.finops

tasks:
  - id: each_anomaly
    type: io.kestra.plugin.core.flow.ForEach
    values: "{{ trigger.anomalies }}"
    tasks:
      - id: log_anomaly
        type: io.kestra.plugin.core.log.Log
        level: WARN
        message: >-
          Cost anomaly {{ fromJson(taskrun.value).anomalyId }} on {{ fromJson(taskrun.value).dimensionValue }}:
          {{ fromJson(taskrun.value).totalImpact }} USD since {{ fromJson(taskrun.value).anomalyStartDate }}

triggers:
  - id: on_anomaly
    type: io.kestra.plugin.aws.billing.AnomalyTrigger
    region: us-east-1
    accessKeyId: "{{ secret('AWS_ACCESS_KEY_ID') }}"
    secretKeyId: "{{ secret('AWS_SECRET_ACCESS_KEY') }}"
    minImpactUsd: 100
    interval: PT6H

Properties

accessKeyId string

AWS access key ID

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

allowConcurrent boolean

Defaultfalse

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

endpointOverride string

Endpoint override

Override the default AWS endpoint URL.

interval string

DefaultPT6H

Formatduration

Poll interval

How often to call GetAnomalies. Default PT6H: every poll is a paid Cost Explorer request ($0.01 per page), and Cost Anomaly Detection runs about three times a day.

lookback string

DefaultPT168H

Lookback

How far back each poll reads anomalies, in whole days. Covers anomalies that AWS reports a few days after they started, and is also how far back the first poll goes. Anomalies older than this are never reported. Default P7D.

maxPages integerstring

Default10

Maximum number of pages

Stops after this many GetAnomalies requests per poll, each one costing $0.01. Anomalies on the pages not read are reported by a later poll. Default 10, between 1 and 1000.

minImpactUsd numberstring

Minimum total impact (USD)

Only report anomalies whose total impact is greater than or equal to this amount. The filter is sent to AWS and checked again on each anomaly. An anomaly below the threshold is not remembered, so it is reported once its impact grows above it. All anomalies when not set.

monitorArn string

Monitor ARN

Only report anomalies detected by this anomaly monitor. All monitors when not set.

region string

AWS region

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

secretKeyId string

AWS secret access key

Pairs with accessKeyId for static credentials.

sessionToken string

AWS session token

Session token for temporary credentials.

stateKey string

State key

Namespace KV key under which the trigger persists its watermark of reported anomalies. Defaults to a key derived from the namespace, flow and trigger IDs. Set it to keep the watermark when you rename the flow or the trigger.

stopAfter array

SubTypestring

Possible Values

CREATEDSUBMITTEDRUNNINGPAUSEDRESTARTEDKILLINGSUCCESSWARNINGFAILEDKILLEDCANCELLEDQUEUEDRETRYINGRETRIEDSKIPPEDBREAKPOINTRESUBMITTED

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

stsEndpointOverride string

STS endpoint override

Override the default STS endpoint URL.

stsRoleArn string

STS role ARN

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

stsRoleExternalId string

STS role external ID

External ID to pass when assuming the STS role.

stsRoleSessionDuration string

DefaultPT15M

STS role session duration

Duration of the assumed role session. Default PT15M.

stsRoleSessionName string

STS role session name

Session name to use when assuming the STS role.

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

anomalies array

SubTypeobject

New anomalies

The anomalies not reported before, oldest first, each with anomalyId, anomalyStartDate, anomalyEndDate, dimensionValue, monitorArn, impact amounts in USD (totalImpact, maxImpact, totalActualSpend, totalExpectedSpend), scores and rootCauses, as returned by GetAnomalies.