Skip to content

Add CloudWatch Alarm for Cerberus execution failure #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gregsienkiewicz merged 1 commit into from
Dec 11, 2025
Merged

Add CloudWatch Alarm for Cerberus execution failure #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 19 additions & 2 deletions cerberus/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,23 @@ The following parameters are defined in the `template.yaml` file and can be cust
- **Allowed Pattern**: `^$|^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$`
- **Constraint Description**: Must be a valid email address or left empty.

### NotificationEmail

- **Type**: String
- **Description**: Email address to receive notifications when the Cerberus state machine execution fails.
- **Allowed Pattern**: `^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$`
- **Constraint Description**: Must be a valid email address.

## Monitoring and Alerts

Cerberus includes built-in monitoring capabilities:

- **CloudWatch Alarm**: Automatically monitors the state machine for execution failures
- **SNS Notifications**: Sends email notifications to the specified address when failures occur
- **Failure Detection**: Triggers alerts when any state machine execution fails

The monitoring system helps ensure quick response to any issues with the Cerberus state machine execution.

## Build and Deploy

### Build
Expand Down Expand Up @@ -89,13 +106,13 @@ This parameter enables removal of the default User assignment that will have adm
Deploy the application with the following command:

```bash
sam deploy --region us-east-1 --parameter-overrides ManagementAccountId=012345678901 LogGroupName=/cerberus
sam deploy --region us-east-1 --parameter-overrides ManagementAccountId=012345678901 LogGroupName=/cerberus NotificationEmail=your-email@company.com
```

To include RegEx patterns for permissions and principals, use:

```bash
sam deploy --region us-east-1 --parameter-overrides ManagementAccountId=012345678901 LogGroupName=/cerberus PermissionSetNamePattern='^AWS(?:OrganizationsFullAccess|ReadOnlyAccess|ServiceCatalogEndUserAccess|ServiceCatalogAdminFullAccess|PowerUserAccess|AdministratorAccess)$' PrincipalNamePattern='^AWS(?:LogArchiveViewers|LogArchiveAdmins|ControlTowerAdmins|AccountFactory|AuditAccountAdmins|SecurityAuditors|ServiceCatalogAdmins|SecurityAuditPowerUsers)$' PrincipalUserNameEmail='devops+control-tower-account-factory@company.xyz'
sam deploy --region us-east-1 --parameter-overrides ManagementAccountId=012345678901 LogGroupName=/cerberus PermissionSetNamePattern='^AWS(?:OrganizationsFullAccess|ReadOnlyAccess|ServiceCatalogEndUserAccess|ServiceCatalogAdminFullAccess|PowerUserAccess|AdministratorAccess)$' PrincipalNamePattern='^AWS(?:LogArchiveViewers|LogArchiveAdmins|ControlTowerAdmins|AccountFactory|AuditAccountAdmins|SecurityAuditors|ServiceCatalogAdmins|SecurityAuditPowerUsers)$' PrincipalUserNameEmail='devops+control-tower-account-factory@company.xyz' NotificationEmail=your-email@company.com
```

## Testing
Expand Down
32 changes: 32 additions & 0 deletions cerberus/template.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,12 @@ Parameters:
AllowedPattern: "^$|^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
ConstraintDescription: "Must be a valid email address or left empty."

NotificationEmail:
Type: String
Description: "Email address to receive notifications when the Cerberus state machine execution fails"
AllowedPattern: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
ConstraintDescription: "Must be a valid email address"

Resources:
SfnToCerberusFunctionConnector:
Type: AWS::Serverless::Connector
Expand Down Expand Up @@ -188,6 +194,32 @@ Resources:
LogGroupName: !Ref LogGroupName
RetentionInDays: !Ref LogGroupRetentionDays

CerberusExecutionFailureAlarm:
Type: AWS::CloudWatch::Alarm
Properties:
AlarmDescription: "Cerberus State Machine execution failed"
ComparisonOperator: GreaterThanThreshold
EvaluationPeriods: 1
MetricName: ExecutionsFailed
Namespace: AWS/States
Period: 60
Statistic: Sum
Threshold: 0
Dimensions:
- Name: StateMachineArn
Value: !Ref CerberusStateMachine
AlarmActions:
- !Ref CerberusFailureNotificationTopic

CerberusFailureNotificationTopic:
Type: AWS::SNS::Topic
Properties:
TopicName: "cerberus-failure-notifications"
DisplayName: "Cerberus State Machine Failure Notifications"
Subscription:
- Endpoint: !Ref NotificationEmail
Protocol: email

Outputs:
EventBusArn:
Description: "The ARN of the custom EventBridge event bus for Cerberus"
Expand Down