x-alarms

Syntax reference
x-alarms:
  alarm-01:
    Properties: {}
    MacroParameters: {}
    Settings: {}
    Services: {}
    Topics: []

Define AWS CloudWatch alarms on the different resources, services, and define actions.

Note

You can only create new alarms.

Properties

ECS Compose-X will automatically detect whether your properties define an Alarm or a Composite Alarm.

See AWS CW Alarms definition and AWS CW Composite Alarms definition

Attention

When linking to Services and/or Topics, the OKActions, AlarmActions will be overridden accordingly.

Attention

You can only create new alarms. To use existing alarms with new services would required to modify the actions of that alarm to be useful, which would be an external change to any IaC.

Services

x-alarms:
  kafka-scaling-01:
    Properties: {}
    Services:
      <service_name>:
        Scaling: {} # Service scaling definition

Scaling

Allows to define the Scaling of an ECS Service based on that alarm. See Scaling for more details.

See autoscaling_on_custom_alarm for an example.

Topics

Topics syntax
x-alarms:
  alarms-01:
    Properties: {}
    Topics:
      - TopicArn: <str>
        NotifyOn: okay
      - x-sns: <str>
        NotifyOn: all

TopicArn

A string representing the topic ARN. The topic ARN must be valid (will be validated).

x-sns

Allows you to define a SNS topic that was defined in compose-x files already. Supports new created topics and topics found via Lookup.

NotifyOn

This allows you to determine whether the messages should be published based on the alarm status. Default is alarm

Value

Alarm actions

all

OKActions

AlarmActions

alarm

AlarmActions

okay

OKActions

Linking to x-resources properties

Hint

This feature only works for Dimensions and Namespace at the moment. Future versions will add support for alarms defined using Metrics (mutually exclusive to Namespace )

When defining new alarms, you probably want to create these alarms for resources in the compose file, i.e, x-elbv2.

So from the Namespace, x-alarms will then scan resources which were defined in the compose definitions and for the dimensions you wish to import the value from, interpolate and modify the final CloudFormation template to link automatically to that resource.

Supported x-resources

  • x-elbv2 (requires AWS/ApplicationELB or AWS/NetworkELB as value for Namespace)

x-elbv2

Marker for LB: x-elbv2::<lb_name> Marker for Target Group: x-elbv2::<lb_name>::<service>::<port>

Hint

The port is required as you might have multiple targets for the same given service family.

Example test file (truncated) use-cases/elbv2/create_only_with_alarms.yml
      timeout_seconds: 60
      desync_mitigation_mode: defensive
      drop_invalid_header_fields: True
      http2: False
      cross_zone: True
    Settings: {}
    Listeners:
      - Port: 8080
        TargetGroupAttributes:
          deregistration_delay.timeout_seconds: "30"
          proxy_protocol_v2.enabled: "true"
          preserve_client_ip.enabled: "true"
#          - Key: deregistration_delay.timeout_seconds
      AlarmDescription: Alarm for Healthy hosts < 2  within a period of 1 minute
      ComparisonOperator: LessThanThreshold
      DatapointsToAlarm: 1
      Dimensions:
        - Name: LoadBalancer
          Value: x-elbv2::lbC
        - Name: TargetGroup
          Value: x-elbv2::lbC::app03::5000
      EvaluationPeriods: 1
      MetricName: HealthyHostCount
      Namespace: AWS/NetworkELB
      Period: 60
      Statistic: Maximum
      Threshold: 2.0
      TreatMissingData: notBreaching

  lba-only-issues:
    Properties:
      AlarmName: unheathy_hosts_alb
      ActionsEnabled: True
      AlarmDescription: Alarm for Healthy hosts < 2  within a period of 1 minute
      ComparisonOperator: LessThanThreshold
      DatapointsToAlarm: 1
      Dimensions:
        - Name: LoadBalancer
          Value: x-elbv2::lbA
      EvaluationPeriods: 1
      MetricName: HTTPCode_ELB_5XX_Count
      Namespace: AWS/ApplicationELB
      Period: 60
      Statistic: Maximum
      Threshold: 2.0
      TreatMissingData: notBreaching

MacroParameters

For x-alarms, MacroParameters is here to help define in a simpler way a composite alarm. More specifically, all you have to define is the Alarm expression

MacroParameters:
  CompositeExpression: <str>

ServiceName

Allows to set the service name or family defined in the compose file, and automatically fills in the Cluster and ServiceName Dimensions.

Note

If you did set Dimensions in the Properties, these will be overriden.

CompositeExpression

String with a logical high level expression of the composite alarm.

In your expression, use the alarm name as defined in the compose file, not using the AlarmName property! ECS Compose-X will automatically map to the CFN Alarm being created.

For example

Example CompositeAlarm with MacroParameters
x-alarms:
  alarm-01:
    Properties {}

  alarm-02:
    Properties: {}

  composite-alarm:
    MacroParameters:
      CompositeExpression: ALARM(alarm-01) and ALARM(alarm-02)

Examples

Alarm with scaling actions for service
x-alarms:
  alarm-01:
    Properties:
      ActionsEnabled: true
      AlarmDescription: A simple CW alarm
      ComparisonOperator: GreaterThanOrEqualToThreshold
      DatapointsToAlarm: 1
      Dimensions:
        - Name: Cluster
          Value: DEV
        - Name: Topic
          Value: topic01
        - Name: ConsumerGroup
          Value: consumer01
      EvaluationPeriods: 5
      MetricName: TotalLagForTopicAndConsumerGroup
      Namespace: lag-metrics-v4
      Period: 60
      Statistic: Sum
      Threshold: 1.0
      TreatMissingData: notBreaching
    Services:
      app03:
        Access: NA
        Scaling:
          ScaleInCooldown: 60
          Steps:
            - Count: 1
              LowerBound: 0
              UpperBound: 1000
            - Count: 3
              LowerBound: 1000
              UpperBound: 10000
    Topics:
      - TopicArn: arn:aws:sns:eu-west-1:012346578900:topic/sometopic
      - x-sns: topic-01
x-sns:
  topic-01:
    Properties: {}

Hint

When the alarms is only for the service, the alarm gets created in the same stack as the service(s). When the alarm has both services and topics, the alarms are created in a separate stack.

Hint

When defining a composite alarm, the actions defined in Services or Topics are ignored.

JSON Schema

Model

x-alarms

x-alarms.spec.json

x-alarms

type

object

properties

  • Properties

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-alarms-bucket.html

type

object

  • Settings

x-resources.common.spec.json#/definitions/Settings

  • MacroParameters

type

object

properties

  • CompositeExpression

type

string

  • ServiceName

Name of the service/family the alarm is for. Automatically sets Dimensions.

type

string

  • Services

x-resources.common.spec.json#/definitions/Services

  • Topics

List of SNS Topics to use for notifications

type

array

items

#/definitions/TopicDef

additionalProperties

False

definitions

  • TopicDef

SNS Topic definition for x-alarms.Topics[]

type

object

properties

  • TopicArn

The SNS Topic full ARN

type

string

format

arn:aws(?:-[a-z]+)?:sns:[a-z0-9A-Z-]+:d{12}:[a-z0-9A-Z-._]+$

  • x-sns

The name of a topic defined in x-sns.Topic.

type

string

  • NotifyOn

The status to trigger the SNS action on.

type

array

default

all

items

type

string

enum

all, alarm, okay

Definition

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "id": "x-alarms.spec.json",
  "$id": "x-alarms.spec.json",
  "title": "x-alarms",
  "description": "x-alarms",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "Properties": {
      "type": "object",
      "description": "https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-alarms-bucket.html"
    },
    "Settings": {
      "$ref": "x-resources.common.spec.json#/definitions/Settings"
    },
    "MacroParameters": {
      "type": "object",
      "properties": {
        "CompositeExpression": {
          "type": "string"
        },
        "ServiceName": {
          "type": "string",
          "description": "Name of the service/family the alarm is for. Automatically sets Dimensions."
        }
      }
    },
    "Services": {
      "$ref": "x-resources.common.spec.json#/definitions/Services"
    },
    "Topics": {
      "description": "List of SNS Topics to use for notifications",
      "type": "array",
      "items": {
        "$ref": "#/definitions/TopicDef"
      }
    }
  },
  "definitions": {
    "TopicDef": {
      "description": "SNS Topic definition for x-alarms.Topics[]",
      "type": "object",
      "properties": {
        "TopicArn": {
          "type": "string",
          "description": "The SNS Topic full ARN",
          "format": "arn:aws(?:-[a-z]+)?:sns:[a-z0-9A-Z-]+:\\d{12}:[a-z0-9A-Z-._]+$"
        },
        "x-sns": {
          "type": "string",
          "description": "The name of a topic defined in x-sns.Topic."
        },
        "NotifyOn": {
          "description": "The status to trigger the SNS action on.",
          "type": "array",
          "default": "all",
          "items": {
            "type": "string",
            "enum": [
              "all",
              "alarm",
              "okay"
            ]
          }
        }
      }
    }
  }
}

Test files

You can find the test files here to use as reference for your use-case.