AWS Billing DescribeBudgets

AWS Billing DescribeBudgets

Certified

List AWS Budgets of an account

Calls the AWS Budgets DescribeBudgets API and returns each budget with its limit, actual and forecasted spend.

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

List the budgets of an account and log how many there are.

yaml
id: aws_list_budgets
namespace: company.finops

tasks:
  - id: budgets
    type: io.kestra.plugin.aws.billing.DescribeBudgets
    region: us-east-1
    accessKeyId: "{{ secret('AWS_ACCESS_KEY_ID') }}"
    secretKeyId: "{{ secret('AWS_SECRET_ACCESS_KEY') }}"
    accountId: "{{ secret('AWS_ACCOUNT_ID') }}"
    fetchType: FETCH

  - id: log_budgets
    type: io.kestra.plugin.core.log.Log
    message: "{{ outputs.budgets.size }} budgets found"
Installation

Our standard Docker images already include this plugin. If you use a -slim image or another setup, install it with the following command:

kestractl plugins get io.kestra.plugin:plugin-aws --compatible-for $KESTRA_VERSION

For kestractl, use your Kestra version with --compatible-for, or specify an exact plugin version.

Properties

AWS account ID

The 12-digit ID of the account that owns the budgets. Required by the AWS Budgets API.

Access Key Id in order to connect to AWS

If no credentials are defined, we will use the default credentials provider chain to fetch credentials.

Assets this task consumes as inputs or produces as outputs, for lineage tracking and the asset graph (Enterprise Edition). A flow declaring this property on a task is rejected in the open-source edition.

Definitions
assetFailureBehaviorstring
Possible Values
IGNOREFAILWARN

Asset failure behavior

Behavior applied to the task state when a declared asset fails to render, emit, or be persisted (e.g. a lock conflict): FAIL escalates it to FAILED, WARN (default) warns it if it would otherwise succeed, IGNORE leaves the state untouched.

enableAutobooleanstring

Whether to auto-register assets referenced dynamically at runtime that are not statically declared in inputs or outputs.

inputsarray

The assets consumed as inputs.

id*string
Min length1
typestring
outputs

The assets produced as outputs.

id*string
Min length1
Max length150
type*object
descriptionstring
displayNamestring
metadataobject
Default{}
namespacestring
Min length1
Max length150
id*string
Min length1
Max length150
type*object
descriptionstring
displayNamestring
metadataobject
Default{}
namespacestring
Min length1
Max length150
id*string
Min length1
Max length150
type*object
descriptionstring
displayNamestring
metadataobject
Default{}
namespacestring
Min length1
Max length150
id*string
Min length1
Max length150
type*object
descriptionstring
displayNamestring
metadataobject
Default{}
namespacestring
Min length1
Max length150
id*string
Min length1
Max length150
type*object
descriptionstring
displayNamestring
metadataobject
Default{}
namespacestring
Min length1
Max length150
id*string
Min length1
Max length150
type*string
Min length1

Custom asset type

descriptionstring
displayNamestring
metadataobject
Default{}
namespacestring
Min length1
Max length150

The endpoint with which the SDK should communicate

This property allows you to use a different S3 compatible storage backend.

DefaultSTORE
Possible Values
STOREFETCHFETCH_ONENONE

Fetch strategy

Default STORE writes all budgets to internal storage. FETCH returns all budgets, FETCH_ONE the first one, NONE only the count.

Default10

Maximum number of pages

Stops after this many DescribeBudgets requests of 100 budgets each, and logs a warning if more budgets were available. Default 10, between 1 and 1000.

AWS region with which the SDK should communicate

Secret Key Id in order to connect to AWS

If no credentials are defined, we will use the default credentials provider chain to fetch credentials.

AWS session token, retrieved from an AWS token service, used for authenticating that this user has received temporary permissions to access a given resource

If no credentials are defined, we will use the default credentials provider chain to fetch credentials.

The AWS STS endpoint with which the SDKClient should communicate

AWS STS Role

The Amazon Resource Name (ARN) of the role to assume. If set the task will use the StsAssumeRoleCredentialsProvider. If no credentials are defined, we will use the default credentials provider chain to fetch credentials.

AWS STS External Id

A unique identifier that might be required when you assume a role in another account. This property is only used when an stsRoleArn is defined.

DefaultPT15M

AWS STS Session duration

The duration of the role session (default: 15 minutes, i.e., PT15M). This property is only used when an stsRoleArn is defined.

AWS STS Session name

This property is only used when an stsRoleArn is defined.

OIDC token to assume the STS role with

When set together with stsRoleArn, the role is assumed through AssumeRoleWithWebIdentity and no AWS credentials are needed at all: AWS verifies the token against the identity provider that issued it. Use {{ oidcToken(audience='sts.amazonaws.com') }} to have Kestra Enterprise mint one for the running execution. The resulting credentials last stsRoleSessionDuration; the token expression is rendered again at every refresh, so a short-lived token keeps working for a long task.

First budget

Single budget when fetchType is FETCH_ONE.

SubTypeobject

Budgets

All budgets when fetchType is FETCH, each with budgetName, budgetType, timeUnit, limitAmount/limitUnit, actualSpendAmount/actualSpendUnit, forecastedSpendAmount/forecastedSpendUnit, timePeriodStart/timePeriodEnd and lastUpdatedTime.

Budget count

Number of budgets in the output: all budgets read for FETCH, STORE and NONE, 1 or 0 for FETCH_ONE.

Truncated

True when maxPages was reached before all budgets were read.

Formaturi

Stored data URI

Internal storage URI of an ION file with all budgets when fetchType is STORE.

Unitrows

Number of budgets fetched or stored.