Multi-account CDK construct to monitor estimated billing charges with alerts and notifications for a AWS Organization. It gives you the capability to monitor specific AWS Service charges, by a linked AWS account in a master/payer account. It can create customizable billing alarms for multiple linked AWS accounts within AWS Organization. It can subscribe multiple email address endpoints to an SNS Topic created by the package or it can use an existing SNS Topic Arn within the master/payer account.
For single AWS account billing alarm requirements, see @spacecomx/cdk-billing-alarm
⚠️ Before you can create a billing alarm, you must enable billing alerts in your master/payer account when using consolidated billing. For more information, see Enabling Billing Alerts.
TypeScript/JavaScript:
npm i @spacecomx/cdk-organization-billing-alarmor:
yarn add @spacecomx/cdk-organization-billing-alarmPython:
pip install spacecomx.cdk-organization-billing-alarmThis type of billing alarm configuration will provide estimated charges for every AWS Service that you use, in addition to the estimated overall total of your AWS charges within your AWS master/payer account e.g (AWS Organization).
- It creates a new SNS Topic in your AWS master/payer account.
- It then subscribes the email address endpoint to the topic.
- It then creates the Cloudwach estimate billing alarm.
- It then associates the SNS topic with the newly created billing alarm.
🔸 The
emailAddressis an endpoint that subscribes to a SNS topic. ThethresholdAmountis the amount in USD, that will trigger the alarm when AWS charges exceed the threshold.
import { Stack, StackProps } from '@aws-cdk/core';
import {
MasterAccountAlarm,
MasterAccountAlarmProps,
} from '@spacecomx/cdk-organization-billing-alarm';
export class OrganizationBillingAlarmStack extends Stack {
constructor(scope: Construct, id: string, props: StackProps) {
super(scope, id, props);
const config: MasterAccountAlarmProps = {
alarmConfiguration: {
topicDescription: 'Organization Billing Alarm Topic',
emailAddress: ['billing@example.org', 'admin@example.org'],
alarmDescription: 'Consolidated Billing Alarm: All AWS Services',
thresholdAmount: 140,
},
};
new MasterAccountAlarm(this, 'MasterAccountAlarm', config);
}
}This type of billing alarm configuration simliar to example 1, with the exception that the billing alarm is now linked to an existing SNS Topic in the master/payer account.
- It uses an existing SNS Topic within the AWS master/payer account.
- It imports a secret by secret name that was created in master/payer account using AWS Secrets Manager e.g (prod/billing/topicArn).
- It then subscribes the email address endpoint to the retrieved SNS Topic's Arn.
- It then creates the Cloudwach estimate billing alarm.
- It then associates the SNS topic with the newly created billing alarm.
🔸 The
secretNameoption is required and used to retrieve the existing SNS Topic's Arn from AWS Secrets Manager. The secret name must exist in the same account and region as the master/payer AWS account.
import { Stack, StackProps } from '@aws-cdk/core';
import {
MasterAccountAlarm,
MasterAccountAlarmProps,
} from '@spacecomx/cdk-organization-billing-alarm';
export class OrganizationBillingAlarmStack extends Stack {
constructor(scope: Construct, id: string, props: StackProps) {
super(scope, id, props);
const config: MasterAccountAlarmProps = {
secretName: 'prod/billing/topicArn', // existing sns topic arn
alarmConfiguration: {
emailAddress: ['john@example.org'],
alarmDescription: 'Consolidated Billing Alarm: All AWS Services',
thresholdAmount: 140,
},
};
new MasterAccountAlarm(this, 'MasterAccountAlarm', config);
}
}This type of billing alarm configuration provides customizable options for linked AWS accounts within the master/payer account. The packages accountConfiguration required option allows for multiple AWS accounts to link to a single SNS Topic using the required secretName option.
- It uses an existing SNS Topic's Arn within the AWS master/payer account.
- It imports a secret by secret name that was created in master/payer account using AWS Secrets Manager e.g (prod/billing/topicArn).
- It then creates the Cloudwach estimate billing alarm associated to the linked AWS account.
- It then associates the SNS topic with the newly created billing alarm.
🔸 The
secretNameoption is required and used to retrieve the existing SNS Topic's Arn from AWS Secrets Manager. The secret name must exist in the same account and region as the master/payer AWS account.
import { Stack, StackProps } from '@aws-cdk/core';
import {
LinkedAccountAlarm,
LinkedAccountAlarmProps,
} from '@spacecomx/cdk-organization-billing-alarm';
export class OrganizationBillingAlarmStack extends Stack {
constructor(scope: Construct, id: string, props: StackProps) {
super(scope, id, props);
const config: LinkedAccountAlarmProps = {
secretName: 'prod/billing/topicArn',
accountConfiguration: [
{
account: '444455556666',
alarmName: 'Billing Alarm (Acc: 444455556666)', // named by aws-cdk (recommended)
alarmDescription:
'Billing Alarm: All AWS Services (Acc: 444455556666)',
thresholdAmount: 50,
},
],
};
new LinkedAccountAlarm(this, 'LinkedAccountAlarm', config);
}
}-OR-
You can manage multiple linked AWS accounts each with its own billing alarm configuration, with a single implementation of the LinkedAccountAlarm construct. The code example below uses a single SNS Topic to manage alerts and notifications for all linked accounts within the master/payer account. Each linked account can send alerts and notifications to either a single email address or multiple email addresses, subscribed to the SNS Topic within the master/payer account
🔸 Should you need more that one SNS topic e.g. you want seperate out linked accounts by department or business unit, each having its own SNS Topic. One option would be to, firstly create an SNS Topic in the master/payer account for each department or business unit. Remember to create a new secret with that SNS Topic's Arn in AWS Secrets Manager. Then simply, new up
LinkedAccountAlarmconstructs that group those linked accounts by department or business unit, each with its own SNS Topic.
const config: LinkedAccountAlarmProps = {
secretName: 'prod/billing/other/topicArn', // single topic used by multiple accounts
accountConfiguration: [
{
account: '444455556666',
alarmDescription: 'Billing Alarm: All AWS Services (Acc: 444455556666)',
thresholdAmount: 50,
},
{
account: '123456789000',
alarmDescription: 'Billing Alarm: All AWS Services (Acc: 123456789000)',
thresholdAmount: 120,
},
],
};🔸 You can also link the alarm to a specific AWS Service, per linked AWS account. Use the
awsServiceoption. See the code example below.
const config: LinkedAccountAlarmProps = {
secretName: 'prod/billing/topicArn',
accountConfiguration: [
{
account: '444455556666',
alarmDescription: 'Billing Alarm: All AWS Services (Acc: 444455556666)',
thresholdAmount: 50,
},
{
account: '123456789000',
alarmDescription: 'Billing Alarm: Amazon DynamoDB (Acc: 123456789000)',
thresholdAmount: 120,
awsService: 'AmazonDynamoDB', // alert on Amazon DynamoDB charges
},
],
};🔸 Should you need to remove a
awsServicesubscribed to a specific linked account, simply remove theawsServiceoption.
When would you use this option?
- When an existing SNS topic that already has an email address endpoint subscribed to it,
- or you dont require any additional email address endpoints to be added to the existing topic,
- or you want to add your own email address endpoints manually to the SNS topic (not recommended),
- or you want to remove an email address endpoints from the SNS topic created with the package,
- or you want to add or update email address endpoints for the SNS topic using the package.
🔸 To manage adding and removing endpoints for the SNS topic, use the packages
emailAddressoption. You can simply set theemailAddress: ['john@example.org']option toemailAddress: []. Please note that email endpoint subscriptions created manually via AWS SNS Console will not be removed by the package.
const config: MasterAccountAlarmProps = {
alarmConfiguration: {
emailAddress: [], // required
...
},
};Adding and removing endpoints means you will need to again confirm the subscription of each email address you specified with emailAddress option or those added manually by you e.g AWS SNS console (not recommended). See post deployment for details.
⚠️ Please be cautious. Without an endpoint been provided i.e. (email address been subscribed to the SNS topic), the billing alarm will still trigger when exceeding the alarm threshold. However you will not recieve any email alarm notifications via email.
Once the Billing Alarm Stack resources has been successfully created in your AWS account, you will need to confirm the subscription of each email address you specified with the emailAddress configuration option. Clicking on the "Confirm Subscription" link for that email, will automatically activate billing alarm notifications for that email address.
If you did not receive the email, you can process a "Request Confirmation" for the subscription from the Simple Notification Service (SNS) console within your AWS account.
⚠️ Without confirming the email subscription you will not recieve any email alarm notifications via email. The billing alarm will trigger when exceeding the alarm threshold, but you will not be notified via email.
For more detail, see API documentation
Contributions of all kinds are welcome! Check out our contributor's guide and our code of conduct
- @spacecomx/cdk-billing-alarm - used for single account billing alarm requirements and some.
@spacecomx/cdk-organization-billing-alarm is distributed under the MIT license.