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.