Add support for Metrics Insights Alarms

Author: henkka

.changelog/28547.txt

@@ -0,0 +1,3 @@
+```release-note:enhancement
+resource/aws_cloudwatch_metric_alarm: Add `period` attribute to `metric_query` in order to support AWS CloudWatch Metrics Insights Alarms.
+```

internal/service/cloudwatch/metric_alarm.go

@@ -82,6 +82,13 @@ func ResourceMetricAlarm() *schema.Resource {
 							Optional:     true,
 							ValidateFunc: validation.StringLenBetween(1, 1024),
 						},
+						"period": {
+							Type:     schema.TypeInt,
+							Optional: true,
+							ValidateFunc: validation.Any(
+								validation.IntDivisibleBy(60),
+								validation.IntInSlice([]int{10, 30})),
+						},
 						"metric": {
 							Type:     schema.TypeList,
 							MaxItems: 1,
@@ -598,6 +605,7 @@ func flattenMetricAlarmMetrics(metrics []*cloudwatch.MetricDataQuery) []map[stri
 			"id":          aws.StringValue(mq.Id),
 			"label":       aws.StringValue(mq.Label),
 			"return_data": aws.BoolValue(mq.ReturnData),
+			"period":      int(aws.Int64Value(mq.Period)),
 		}
 		if mq.MetricStat != nil {
 			metric := flattenMetricAlarmMetricsMetricStat(mq.MetricStat)
@@ -638,6 +646,9 @@ func expandMetricAlarmMetrics(v *schema.Set) []*cloudwatch.MetricDataQuery {
 		if v, ok := metricQueryResource["expression"]; ok && v.(string) != "" {
 			metricQuery.Expression = aws.String(v.(string))
 		}
+		if v, ok := metricQueryResource["period"]; ok && v.(int) > 0 {
+			metricQuery.Period = aws.Int64(int64(v.(int)))
+		}
 		if v, ok := metricQueryResource["label"]; ok && v.(string) != "" {
 			metricQuery.Label = aws.String(v.(string))
 		}

internal/service/cloudwatch/metric_alarm_test.go

@@ -459,6 +459,13 @@ func TestAccCloudWatchMetricAlarm_expression(t *testing.T) {
 					resource.TestCheckResourceAttr(resourceName, "metric_query.#", "2"),
 				),
 			},
+			{
+				Config: testAccMetricAlarmConfig_metricsInsightsQueryExpression(rName),
+				Check: resource.ComposeTestCheckFunc(
+					testAccCheckMetricAlarmExists(resourceName, &alarm),
+					resource.TestCheckResourceAttr(resourceName, "metric_query.#", "1"),
+					resource.TestCheckResourceAttr(resourceName, "metric_query.0.period", "300")),
+			},
 			{
 				ResourceName:      resourceName,
 				ImportState:       true,
@@ -1000,6 +1007,27 @@ resource "aws_cloudwatch_metric_alarm" "test" {
 `, rName)
 }
 
+func testAccMetricAlarmConfig_metricsInsightsQueryExpression(rName string) string {
+	expression := "SELECT AVG(CPUUtilization) FROM SCHEMA(\\\"AWS/EC2\\\", InstanceId)"
+	return fmt.Sprintf(`
+resource "aws_cloudwatch_metric_alarm" "test" {
+  alarm_name                = "%s"
+  comparison_operator       = "GreaterThanOrEqualToThreshold"
+  evaluation_periods        = "2"
+  threshold                 = "80"
+  alarm_description         = "This metric monitors ec2 cpu utilization"
+  insufficient_data_actions = []
+
+  metric_query {
+    id          = "e1"
+    expression  = "%s"
+    period      = 300
+    return_data = true
+  }
+}
+`, rName, expression)
+}
+
 // EC2 Automate requires a valid EC2 instance
 // ValidationError: Invalid use of EC2 'Recover' action. i-abc123 is not a valid EC2 instance.
 func testAccMetricAlarmConfig_actionsEC2Automate(rName, action string) string {

website/docs/r/cloudwatch_metric_alarm.html.markdown

@@ -166,6 +166,27 @@ resource "aws_cloudwatch_metric_alarm" "nlb_healthyhosts" {
 }
 ```
 
+## Example with AWS Metric Insights Alarm
+
+```terraform
+resource "aws_cloudwatch_metric_alarm" "this" {
+  alarm_name          = "alarmname"
+  alarm_description   = "Alarm if any of the EC2 instances go above 50% in CPU utilization."
+  comparison_operator = "GreaterThanThreshold"
+  evaluation_periods  = 1
+  datapoints_to_alarm = 1
+  threshold           = 50
+  ok_actions          = [aws_sns_topic.sns.arn]
+  alarm_actions       = [aws_sns_topic.sns.arn]
+  metric_query {
+    id          = "m1"
+    return_data = true
+    period      = 60
+    expression  = "SELECT AVG(CPUUtilization) FROM SCHEMA(\"AWS/EC2\", InstanceId)"
+  }
+}
+```
+
 ~> **NOTE:**  You cannot create a metric alarm consisting of both `statistic` and `extended_statistic` parameters.
 You must choose one or the other
 
@@ -215,9 +236,10 @@ The following values are supported: `ignore`, and `evaluate`.
 
 * `id` - (Required) A short name used to tie this object to the results in the response. If you are performing math expressions on this set of data, this name represents that data and can serve as a variable in the mathematical expression. The valid characters are letters, numbers, and underscore. The first character must be a lowercase letter.
 * `account_id` - (Optional) The ID of the account where the metrics are located, if this is a cross-account alarm.
-* `expression` - (Optional) The math expression to be performed on the returned data, if this object is performing a math expression. This expression can use the id of the other metrics to refer to those metrics, and can also use the id of other expressions to use the result of those expressions. For more information about metric math expressions, see Metric Math Syntax and Functions in the [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/using-metric-math.html#metric-math-syntax).
+* `expression` - (Optional) The math expression or Metric Insights query to be performed on the returned data, if this object is performing a math expression. This expression can use the id of the other metrics to refer to those metrics, and can also use the id of other expressions to use the result of those expressions. For more information about metric math expressions, see Metric Math Syntax and Functions in the [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/using-metric-math.html#metric-math-syntax).
 * `label` - (Optional) A human-readable label for this metric or expression. This is especially useful if this is an expression, so that you know what the value represents.
 * `return_data` (Optional) Specify exactly one `metric_query` to be `true` to use that `metric_query` result as the alarm.
+* `period` (Optional) The period in seconds over which the specified AWS Metric Insights query in `expression` is applied. Should only be used when `expression` is AWS Metric Insights query. For metrics with regular resolution, the value must be a multiple of 60. For high-resolution metrics that are collected at intervals of less than one minute, the period can be 1, 5, 10, 30, 60, or any multiple of 60.
 * `metric` (Optional) The metric to be returned, along with statistics, period, and units. Use this parameter only if this object is retrieving a metric and not performing a math expression on returned data.
 
 ~> **NOTE:**  You must specify either `metric` or `expression`. Not both.