AWS.Budgets reference

Budget

Source: src/AWS/Budgets/Budget.ts

An AWS Budget — tracks cost or usage against a defined limit over a time period and notifies subscribers when configured thresholds are crossed.

Budgets are a global (account-level) resource; they are free and take effect immediately.

Budget: Creating a Budget

Monthly cost budget with an email alert at 80%

import * as Budgets from "alchemy/AWS/Budgets";

const budget = yield* Budgets.Budget("MonthlyCost", {
  budgetType: "COST",
  timeUnit: "MONTHLY",
  budgetLimit: { amount: "100", unit: "USD" },
  notifications: [
    {
      notificationType: "ACTUAL",
      comparisonOperator: "GREATER_THAN",
      threshold: 80,
      thresholdType: "PERCENTAGE",
      subscribers: [{ subscriptionType: "EMAIL", address: "team@example.com" }],
    },
  ],
});

Budget scoped to a single service

const budget = yield* Budgets.Budget("EC2Spend", {
  budgetLimit: { amount: "500", unit: "USD" },
  costFilters: {
    Service: ["Amazon Elastic Compute Cloud - Compute"],
  },
});

BudgetAction

Source: src/AWS/Budgets/BudgetAction.ts

An AWS Budgets action — runs an IAM policy attachment, SCP attachment, or SSM stop-instances document when a budget threshold is crossed, either automatically or after manual approval.

The execution role must trust budgets.amazonaws.com and carry the permissions the action needs (the AWS managed policy AWSBudgetsActionsWithAWSResourceControlAccess covers all three kinds).

BudgetAction: Creating a Budget Action

Apply a Deny-All Policy at 100% of the Budget

import * as AWS from "alchemy/AWS";

const budget = yield* AWS.Budgets.Budget("MonthlyCost", {
  budgetLimit: { amount: "100", unit: "USD" },
});

const action = yield* AWS.Budgets.BudgetAction("FreezeSpend", {
  budgetName: budget.budgetName,
  notificationType: "ACTUAL",
  actionType: "APPLY_IAM_POLICY",
  actionThreshold: {
    actionThresholdValue: 100,
    actionThresholdType: "PERCENTAGE",
  },
  definition: {
    iamActionDefinition: {
      policyArn: "arn:aws:iam::aws:policy/AWSDenyAll",
      roles: [devRole.roleName],
    },
  },
  executionRoleArn: executionRole.roleArn,
  approvalModel: "MANUAL",
  subscribers: [{ subscriptionType: "EMAIL", address: "team@example.com" }],
});

Stop EC2 Instances Automatically

const action = yield* AWS.Budgets.BudgetAction("StopDevInstances", {
  budgetName: budget.budgetName,
  notificationType: "ACTUAL",
  actionType: "RUN_SSM_DOCUMENTS",
  actionThreshold: {
    actionThresholdValue: 100,
    actionThresholdType: "PERCENTAGE",
  },
  definition: {
    ssmActionDefinition: {
      actionSubType: "STOP_EC2_INSTANCES",
      region: "us-east-1",
      instanceIds: [instance.instanceId],
    },
  },
  executionRoleArn: executionRole.roleArn,
  approvalModel: "AUTOMATIC",
  subscribers: [{ subscriptionType: "EMAIL", address: "team@example.com" }],
});

DescribeBudget

Source: src/AWS/Budgets/DescribeBudget.ts

Runtime binding for budgets:ViewBudget via DescribeBudget.

Bind this operation to a Budget to read its definition and — most usefully at runtime — its CalculatedSpend (actual and forecasted spend so far in the period), e.g. for a cost kill-switch or a spend dashboard. Provide the implementation with Effect.provide(AWS.Budgets.DescribeBudgetHttp).

DescribeBudget: Reading Budget Spend

// init — bind the operation to the budget
const describeBudget = yield* AWS.Budgets.DescribeBudget(budget);

// runtime
const { Budget: b } = yield* describeBudget();
const actual = Number(b?.CalculatedSpend?.ActualSpend?.Amount ?? "0");
const limit = Number(b?.BudgetLimit?.Amount ?? "0");
const overBudget = limit > 0 && actual >= limit;

DescribeBudgetActionHistories

Source: src/AWS/Budgets/DescribeBudgetActionHistories.ts

Runtime binding for budgets:DescribeBudgetActionHistories.

Bind this operation to a BudgetAction to read its event history — creations, updates, and executions with their statuses — e.g. to audit when a kill-switch fired and whether it succeeded. Provide the implementation with Effect.provide(AWS.Budgets.DescribeBudgetActionHistoriesHttp).

DescribeBudgetActionHistories: Reading Budget Actions

// init — bind the operation to the action
const histories = yield* AWS.Budgets.DescribeBudgetActionHistories(action);

// runtime
const result = yield* histories({});
const executions = result.ActionHistories.filter(
  (h) => h.EventType === "EXECUTE_ACTION",
);

DescribeBudgetActionsForBudget

Source: src/AWS/Budgets/DescribeBudgetActionsForBudget.ts

Runtime binding for budgets:DescribeBudgetActionsForBudget.

Bind this operation to a Budget to list its budget actions and their execution status — e.g. to check whether a cost kill-switch has fired. Provide the implementation with Effect.provide(AWS.Budgets.DescribeBudgetActionsForBudgetHttp).

DescribeBudgetActionsForBudget: Reading Budget Actions

// init — bind the operation to the budget
const listActions = yield* AWS.Budgets.DescribeBudgetActionsForBudget(budget);

// runtime
const result = yield* listActions();
const statuses = (result.Actions ?? []).map((a) => a.Status);

DescribeBudgetPerformanceHistory

Source: src/AWS/Budgets/DescribeBudgetPerformanceHistory.ts

Runtime binding for budgets:ViewBudget via DescribeBudgetPerformanceHistory.

Bind this operation to a Budget to read its budgeted-vs-actual amounts for past periods — e.g. to render a spend trend or detect consistently blown budgets. Provide the implementation with Effect.provide(AWS.Budgets.DescribeBudgetPerformanceHistoryHttp).

DescribeBudgetPerformanceHistory: Reading Budget Spend

// init — bind the operation to the budget
const history = yield* AWS.Budgets.DescribeBudgetPerformanceHistory(budget);

// runtime
const result = yield* history();
const periods =
  result.BudgetPerformanceHistory?.BudgetedAndActualAmountsList ?? [];

DescribeNotificationsForBudget

Source: src/AWS/Budgets/DescribeNotificationsForBudget.ts

Runtime binding for budgets:ViewBudget via DescribeNotificationsForBudget.

Bind this operation to a Budget to list its alert thresholds and their alarm state (NotificationState is ALARM once a threshold has been crossed) — e.g. to gate expensive work on whether any budget alert has fired. Provide the implementation with Effect.provide(AWS.Budgets.DescribeNotificationsForBudgetHttp).

DescribeNotificationsForBudget: Reading Budget Alerts

// init — bind the operation to the budget
const notifications = yield* AWS.Budgets.DescribeNotificationsForBudget(budget);

// runtime
const result = yield* notifications();
const inAlarm = (result.Notifications ?? []).some(
  (n) => n.NotificationState === "ALARM",
);

DescribeSubscribersForNotification

Source: src/AWS/Budgets/DescribeSubscribersForNotification.ts

Runtime binding for budgets:ViewBudget via DescribeSubscribersForNotification.

Bind this operation to a Budget to list who is notified when a given alert threshold is crossed — pair it with DescribeNotificationsForBudget to enumerate a budget’s full alerting fan-out (each subscriber’s Address comes back Redacted). Provide the implementation with Effect.provide(AWS.Budgets.DescribeSubscribersForNotificationHttp).

DescribeSubscribersForNotification: Reading Budget Alerts

// init — bind both operations to the budget
const notifications = yield* AWS.Budgets.DescribeNotificationsForBudget(budget);
const subscribers = yield* AWS.Budgets.DescribeSubscribersForNotification(budget);

// runtime
const { Notifications = [] } = yield* notifications();
for (const notification of Notifications) {
  const result = yield* subscribers({ Notification: notification });
  const recipients = (result.Subscribers ?? []).map((s) => s.SubscriptionType);
}

ExecuteBudgetAction

Source: src/AWS/Budgets/ExecuteBudgetAction.ts

Runtime binding for budgets:ExecuteBudgetAction.

Bind this operation to a BudgetAction to approve, retry, reverse, or reset it from inside a function runtime — e.g. an approval workflow that approves a pending kill-switch, or an automated recovery that reverses it at the start of a new period. Provide the implementation with Effect.provide(AWS.Budgets.ExecuteBudgetActionHttp).

ExecuteBudgetAction: Executing Budget Actions

Approve a Pending Action

// init — bind the operation to the action
const execute = yield* AWS.Budgets.ExecuteBudgetAction(action);

// runtime
yield* execute({ ExecutionType: "APPROVE_BUDGET_ACTION" });

Reverse an Executed Action

yield* execute({ ExecutionType: "REVERSE_BUDGET_ACTION" });