Create an AWS Budget Alert With AWS SDK v3

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadBudget",
      "Effect": "Allow",
      "Action": "budgets:ViewBudget",
      "Resource": "arn:aws:budgets::123456789012:budget/monthly-cost-budget"
    },
    {
      "Sid": "CreateBudgetAndAlerts",
      "Effect": "Allow",
      "Action": "budgets:ModifyBudget",
      "Resource": "arn:aws:budgets::123456789012:budget/monthly-cost-budget"
    }
  ]
}

{
  "Sid": "AWSBudgetsSNSPublishingPermissions",
  "Effect": "Allow",
  "Principal": { "Service": "budgets.amazonaws.com" },
  "Action": "SNS:Publish",
  "Resource": "arn:aws:sns:us-east-1:123456789012:budget-alerts",
  "Condition": {
    "StringEquals": { "aws:SourceAccount": "123456789012" },
    "ArnLike": { "aws:SourceArn": "arn:aws:budgets::123456789012:*" }
  }
}

// create-budget-alert.ts
// Creates a monthly AWS cost budget with ACTUAL and FORECASTED alerts to email and/or SNS.
// Safe to re-run: an existing budget is left alone and only missing notifications are added.
// Dry run by default (reads only). Pass --apply to create anything.
// Usage: npx tsx create-budget-alert.ts --amount 500 --email [email protected][,[email protected]]
//          [--sns arn:aws:sns:us-east-1:123456789012:budget-alerts] [--name monthly-cost-budget]
//          [--actual 80,100] [--forecast 100] [--apply]
import {
  BudgetsClient,
  CreateBudgetCommand,
  CreateNotificationCommand,
  DescribeBudgetCommand,
  NotFoundException,
  paginateDescribeNotificationsForBudget,
  type Budget,
  type Notification,
  type NotificationWithSubscribers,
  type Subscriber,
} from "@aws-sdk/client-budgets";
import { STSClient, GetCallerIdentityCommand } from "@aws-sdk/client-sts";

const args = process.argv.slice(2);
const flag = (name: string): string | undefined => {
  const i = args.indexOf(name);
  return i >= 0 ? args[i + 1] : undefined;
};
const list = (v: string | undefined): string[] => (v ?? "").split(",").map((s) => s.trim()).filter(Boolean);

const APPLY = args.includes("--apply");
const budgetName = flag("--name") ?? "monthly-cost-budget";
const amount = Number(flag("--amount"));
const emails = list(flag("--email"));
const snsTopicArn = flag("--sns");
const actual = list(flag("--actual") ?? "80,100").map(Number);
const forecast = list(flag("--forecast") ?? "100").map(Number);

if (!Number.isFinite(amount) || amount <= 0) throw new Error("--amount must be a positive number of USD, e.g. --amount 500");
if (!emails.length && !snsTopicArn) throw new Error("Give at least one --email or an --sns topic ARN");
if (emails.length > 10) throw new Error("A notification can have at most 10 email subscribers");
if (actual.length + forecast.length > 5) throw new Error("A budget can have at most 5 notifications");
if ([...actual, ...forecast].some((t) => !Number.isFinite(t) || t <= 0)) throw new Error("Thresholds must be positive percentages");

// AWS Budgets has one global endpoint in the aws partition, signed for us-east-1.
const budgets = new BudgetsClient({ region: "us-east-1" });

const subscribers: Subscriber[] = [
  ...emails.map((Address): Subscriber => ({ SubscriptionType: "EMAIL", Address })),
  ...(snsTopicArn ? [{ SubscriptionType: "SNS", Address: snsTopicArn } satisfies Subscriber] : []),
];

const wanted: Notification[] = [
  ...actual.map((Threshold): Notification => ({ NotificationType: "ACTUAL", ComparisonOperator: "GREATER_THAN", Threshold, ThresholdType: "PERCENTAGE" })),
  ...forecast.map((Threshold): Notification => ({ NotificationType: "FORECASTED", ComparisonOperator: "GREATER_THAN", Threshold, ThresholdType: "PERCENTAGE" })),
];

const budget: Budget = {
  BudgetName: budgetName,
  BudgetType: "COST",
  TimeUnit: "MONTHLY", // no TimePeriod: starts at the current month and renews every month
  BudgetLimit: { Amount: amount.toFixed(2), Unit: "USD" },
};

const same = (a: Notification, b: Notification): boolean =>
  a.NotificationType === b.NotificationType &&
  a.ComparisonOperator === b.ComparisonOperator &&
  a.Threshold === b.Threshold &&
  (a.ThresholdType ?? "PERCENTAGE") === (b.ThresholdType ?? "PERCENTAGE");
const label = (n: Notification): string => `${n.NotificationType} > ${n.Threshold}%`;

async function existingBudget(accountId: string): Promise<Budget | undefined> {
  try {
    const res = await budgets.send(new DescribeBudgetCommand({ AccountId: accountId, BudgetName: budgetName }));
    return res.Budget;
  } catch (err) {
    if (err instanceof NotFoundException) return undefined;
    throw err;
  }
}

async function existingNotifications(accountId: string): Promise<Notification[]> {
  const found: Notification[] = [];
  const pages = paginateDescribeNotificationsForBudget({ client: budgets }, { AccountId: accountId, BudgetName: budgetName });
  for await (const page of pages) found.push(...(page.Notifications ?? []));
  return found;
}

async function main(): Promise<void> {
  const { Account: accountId } = await new STSClient({ region: "us-east-1" }).send(new GetCallerIdentityCommand({}));
  if (!accountId) throw new Error("Could not resolve the AWS account ID");
  console.log(`Account ${accountId}, budget "${budgetName}": ${budget.BudgetLimit?.Amount} USD per month`);
  console.log(`Alerts: ${wanted.map(label).join(", ")} -> ${subscribers.map((s) => s.Address).join(", ")}`);

  const current = await existingBudget(accountId);
  if (!current) {
    console.log(APPLY ? "Creating budget with notifications..." : "Would create the budget with these notifications.");
    if (APPLY) {
      const notifications: NotificationWithSubscribers[] = wanted.map((Notification) => ({ Notification, Subscribers: subscribers }));
      await budgets.send(new CreateBudgetCommand({ AccountId: accountId, Budget: budget, NotificationsWithSubscribers: notifications }));
      console.log("Created. Email subscribers must confirm; SNS topics need a policy that lets budgets.amazonaws.com publish.");
    }
  } else {
    const limit = current.BudgetLimit;
    console.log(`Budget exists: ${limit?.Amount} ${limit?.Unit}, ${current.TimeUnit}.`);
    if (Number(limit?.Amount) !== amount) console.log(`Note: limit differs from --amount ${amount}; change it in the console or with UpdateBudget.`);
    const have = await existingNotifications(accountId);
    const missing = wanted.filter((w) => !have.some((h) => same(h, w)));
    if (!missing.length) console.log("All requested notifications already exist. Nothing to do.");
    for (const n of missing) {
      console.log(`${APPLY ? "Adding" : "Would add"} notification ${label(n)}`);
      if (APPLY) await budgets.send(new CreateNotificationCommand({ AccountId: accountId, BudgetName: budgetName, Notification: n, Subscribers: subscribers }));
    }
  }
  if (!APPLY) console.log("Dry run: nothing was created. Re-run with --apply.");
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

npm install @aws-sdk/client-budgets @aws-sdk/client-sts
npm install --save-dev tsx typescript

# Plan: shows what would be created (read-only)
AWS_PROFILE=billing npx tsx create-budget-alert.ts --amount 500 --email [email protected],[email protected] \
  --sns arn:aws:sns:us-east-1:123456789012:budget-alerts

# Create it
AWS_PROFILE=billing npx tsx create-budget-alert.ts --amount 500 --email [email protected],[email protected] \
  --sns arn:aws:sns:us-east-1:123456789012:budget-alerts --apply

# Later: add a 50% early warning to the same budget
AWS_PROFILE=billing npx tsx create-budget-alert.ts --amount 500 --email [email protected],[email protected] \
  --actual 50,80,100 --apply

$ npx tsx create-budget-alert.ts --amount 500 --email [email protected],[email protected] --sns arn:aws:sns:us-east-1:123456789012:budget-alerts
Account 123456789012, budget "monthly-cost-budget": 500.00 USD per month
Alerts: ACTUAL > 80%, ACTUAL > 100%, FORECASTED > 100% -> [email protected], [email protected], arn:aws:sns:us-east-1:123456789012:budget-alerts
Would create the budget with these notifications.
Dry run: nothing was created. Re-run with --apply.

$ npx tsx create-budget-alert.ts ... --apply
Creating budget with notifications...
Created. Email subscribers must confirm; SNS topics need a policy that lets budgets.amazonaws.com publish.

$ npx tsx create-budget-alert.ts --amount 500 --email [email protected],[email protected] --actual 50,80,100 --apply
Account 123456789012, budget "monthly-cost-budget": 500.00 USD per month
Alerts: ACTUAL > 50%, ACTUAL > 80%, ACTUAL > 100%, FORECASTED > 100% -> [email protected], [email protected]
Budget exists: 500.0 USD, MONTHLY.
Adding notification ACTUAL > 50%