AWS Metric Alarm Terraform module

Terraform module that creates a Massdriver-integrated AWS CloudWatch metric alarm. Supports both simple metric alarms and metric math expression-based alarms in a single module.

This module is designed to be used alongside terraform-massdriver-aws-alarm-channel, which creates the SNS topic that alarm notifications are published to.

Features

• Creates a CloudWatch metric alarm with SNS actions for alarm and OK states
• Supports simple single-metric alarms (metric_name, namespace, period, statistic)
• Supports metric math expression alarms (metric_queries) for complex multi-metric conditions
• Validates inputs at plan time to enforce mutual exclusivity between the two modes
• Registers the alarm with Massdriver for UI visibility via massdriver_package_alarm

Usage

Simple metric alarm

module "alarm_channel" {
  source = "massdriver-cloud/aws-alarm-channel/massdriver"

  md_metadata = var.md_metadata
}

module "cpu_alarm" {
  source = "massdriver-cloud/aws-metric-alarm/massdriver"

  alarm_name   = "${var.md_metadata.name_prefix}-cpu-high"
  display_name = "CPU High"
  message      = "CPU utilization exceeded threshold"

  sns_topic_arn = module.alarm_channel.arn
  md_metadata   = var.md_metadata

  comparison_operator = "GreaterThanOrEqualToThreshold"
  evaluation_periods  = 3
  threshold           = 80

  metric_name = "CPUUtilization"
  namespace   = "AWS/EC2"
  period      = 300
  statistic   = "Average"
  dimensions  = { InstanceId = "i-0123456789abcdef0" }
}

Expression-based alarm

module "error_rate_alarm" {
  source = "massdriver-cloud/aws-metric-alarm/massdriver"

  alarm_name   = "${var.md_metadata.name_prefix}-error-rate"
  display_name = "Error Rate"
  message      = "Error rate exceeded threshold"

  sns_topic_arn = module.alarm_channel.arn
  md_metadata   = var.md_metadata

  comparison_operator = "GreaterThanThreshold"
  evaluation_periods  = 3
  threshold           = 5

  display_metric_key = "errors"
  metric_queries = {
    errors = {
      expression  = "(error_count / request_count) * 100"
      label       = "Error Rate"
      return_data = true
    }
    error_count = {
      label = "Errors"
      metric = {
        metric_name = "5XXError"
        namespace   = "AWS/ApiGateway"
        period      = 300
        stat        = "Sum"
        dimensions  = { ApiName = "my-api" }
      }
    }
    request_count = {
      label = "Requests"
      metric = {
        metric_name = "Count"
        namespace   = "AWS/ApiGateway"
        period      = 300
        stat        = "Sum"
        dimensions  = { ApiName = "my-api" }
      }
    }
  }
}

Requirements

No requirements.

Providers

Name	Version
aws	6.40.0
massdriver	1.3.4

Modules

No modules.

Resources

Name	Type
aws_cloudwatch_metric_alarm.alarm	resource
massdriver_package_alarm.package_alarm	resource

Inputs

Name	Description	Type	Default	Required
alarm_name	The descriptive name for the alarm. Must be unique within the AWS account.	string	n/a	yes
comparison_operator	The arithmetic operation to use when comparing the specified statistic and threshold. Valid values: GreaterThanOrEqualToThreshold, GreaterThanThreshold, LessThanThreshold, LessThanOrEqualToThreshold.	string	n/a	yes
dimensions	The dimensions for the alarm's associated metric.	map(string)	null	no
display_metric_key	Required when using metric_queries. The key in metric_queries whose metric should be displayed in the Massdriver UI.	string	null	no
display_name	Short name to display in the Massdriver UI.	string	n/a	yes
evaluation_periods	The number of periods over which data is compared to the specified threshold.	number	n/a	yes
md_metadata	Massdriver metadata object, must include name_prefix.	any	n/a	yes
message	Message to include in the alarm description.	string	n/a	yes
metric_name	The name for the alarm's associated metric. Required for simple metric alarms, conflicts with metric_queries.	string	null	no
metric_queries	Map of metric query ID to metric query config for expression-based alarms. Conflicts with metric_name, namespace, period, and statistic. See the aws_cloudwatch_metric_alarm docs for the metric_query structure.	map(object({ expression = optional(string) label = optional(string) return_data = optional(bool) metric = optional(object({ metric_name = string namespace = string period = number stat = string unit = optional(string) dimensions = optional(map(string)) })) }))	null	no
namespace	The namespace for the alarm's associated metric. Required when metric_name is set.	string	null	no
period	The period in seconds over which the specified statistic is applied. Required when metric_name is set.	number	null	no
sns_topic_arn	Massdriver alarm channel SNS topic ARN.	string	n/a	yes
statistic	The statistic to apply to the alarm's associated metric. Valid values: SampleCount, Average, Sum, Minimum, Maximum. Required when metric_name is set, conflicts with extended_statistic.	string	null	no
threshold	The value against which the specified statistic is compared.	number	n/a	yes

Outputs

Name	Description
arn	The ARN of the CloudWatch metric alarm.

Authors

Module is maintained by Massdriver, Inc.

License

Apache 2 Licensed. See LICENSE for full details.